From 6b666bff46865d7079a2219ccdcc43c08ecd6c6d Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sun, 25 Jan 2026 15:18:30 -0500 Subject: [PATCH] fix: proactive documentation and sprint planning automation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - doc-guardian: Hook now tracks documentation dependencies and outputs specific files needing updates (e.g., commands → COMMANDS-CHEATSHEET.md) - projman: SessionStart hook now suggests /sprint-plan when open issues exist without milestone, and warns about unreleased CHANGELOG entries - projman: Add /suggest-version command for semantic version recommendations - docs: Update COMMANDS-CHEATSHEET.md with data-platform plugin (was missing) - docs: Update CLAUDE.md with data-platform and version 4.0.0 Fixes documentation drift and lack of proactive workflow suggestions. Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 19 +++++ CLAUDE.md | 18 +++-- docs/COMMANDS-CHEATSHEET.md | 35 +++++++-- plugins/doc-guardian/hooks/notify.sh | 45 ++++++++++-- plugins/projman/commands/suggest-version.md | 78 +++++++++++++++++++++ plugins/projman/hooks/startup-check.sh | 40 ++++++++++- 6 files changed, 219 insertions(+), 16 deletions(-) create mode 100644 plugins/projman/commands/suggest-version.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c03c20b..ceedc06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,25 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## [Unreleased] + +### Added +- **projman:** `/suggest-version` command - Analyzes CHANGELOG and recommends semantic version bump +- **projman:** SessionStart hook now suggests sprint planning when open issues exist without milestone +- **projman:** SessionStart hook now warns about unreleased CHANGELOG entries + +### Changed +- **doc-guardian:** Hook now tracks documentation dependencies and queues specific files needing updates + - Outputs which specific docs need updating (e.g., "commands changed → update needed: docs/COMMANDS-CHEATSHEET.md README.md") + - Maintains queue file (`.doc-guardian-queue`) for batch processing +- **docs:** COMMANDS-CHEATSHEET.md updated with data-platform plugin (7 commands + hook) + +### Fixed +- Documentation drift: COMMANDS-CHEATSHEET.md was missing data-platform plugin added in v4.0.0 +- Proactive sprint planning: projman now suggests `/sprint-plan` at session start when unplanned issues exist + +--- + ## [4.0.0] - 2026-01-25 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 9c3cbae..3e1d326 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,7 +50,7 @@ See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing. ## Project Overview **Repository:** leo-claude-mktplace -**Version:** 3.1.2 +**Version:** 4.0.0 **Status:** Production Ready A plugin marketplace for Claude Code containing: @@ -65,6 +65,7 @@ A plugin marketplace for Claude Code containing: | `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 | | `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 | | `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 | +| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.0.0 | | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 | ## Quick Start @@ -84,10 +85,12 @@ A plugin marketplace for Claude Code containing: | **Setup** | `/initial-setup`, `/project-init`, `/project-sync` | | **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` | | **Quality** | `/review`, `/test-check`, `/test-gen` | +| **Versioning** | `/suggest-version` | | **PR Review** | `/pr-review:initial-setup`, `/pr-review:project-init` | | **Docs** | `/doc-audit`, `/doc-sync` | | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` | | **Config** | `/config-analyze`, `/config-optimize` | +| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run` | | **Debug** | `/debug-report`, `/debug-review` | ## Repository Structure @@ -104,8 +107,8 @@ leo-claude-mktplace/ │ │ ├── .claude-plugin/plugin.json │ │ ├── .mcp.json │ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK -│ │ ├── commands/ # 13 commands (incl. setup, debug) -│ │ ├── hooks/ # SessionStart mismatch detection +│ │ ├── commands/ # 14 commands (incl. setup, debug, suggest-version) +│ │ ├── hooks/ # SessionStart: mismatch detection + sprint suggestions │ │ ├── agents/ # 4 agents │ │ └── skills/label-taxonomy/ │ ├── git-flow/ # Git workflow automation @@ -119,10 +122,17 @@ leo-claude-mktplace/ │ │ ├── commands/ # 6 commands (incl. setup) │ │ ├── hooks/ # SessionStart mismatch detection │ │ └── agents/ # 5 agents -│ ├── clarity-assist/ # Prompt optimization (NEW v3.0.0) +│ ├── clarity-assist/ # Prompt optimization │ │ ├── .claude-plugin/plugin.json │ │ ├── commands/ # 2 commands │ │ └── agents/ +│ ├── data-platform/ # Data engineering (NEW v4.0.0) +│ │ ├── .claude-plugin/plugin.json +│ │ ├── .mcp.json +│ │ ├── mcp-servers/ # pandas, postgresql, dbt MCPs +│ │ ├── commands/ # 7 commands +│ │ ├── hooks/ # SessionStart PostgreSQL check +│ │ └── agents/ # 2 agents │ ├── doc-guardian/ # Documentation drift detection │ ├── code-sentinel/ # Security scanning & refactoring │ ├── claude-config-maintainer/ diff --git a/docs/COMMANDS-CHEATSHEET.md b/docs/COMMANDS-CHEATSHEET.md index e1baa9b..cdf7577 100644 --- a/docs/COMMANDS-CHEATSHEET.md +++ b/docs/COMMANDS-CHEATSHEET.md @@ -22,6 +22,7 @@ Quick reference for all commands in the Leo Claude Marketplace. | **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code | | **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace | | **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates | +| **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump | | **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message | | **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation | | **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch | @@ -55,6 +56,14 @@ Quick reference for all commands in the Leo Claude Marketplace. | **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes | | **cmdb-assistant** | `/cmdb-site` | | X | Manage sites, locations, racks, and regions | | **project-hygiene** | *PostToolUse hook* | X | | Removes temp files, warns about unexpected root files | +| **data-platform** | `/ingest` | | X | Load data from CSV, Parquet, JSON into DataFrame | +| **data-platform** | `/profile` | | X | Generate data profiling report with statistics | +| **data-platform** | `/schema` | | X | Explore database schemas, tables, columns | +| **data-platform** | `/explain` | | X | Explain query execution plan | +| **data-platform** | `/lineage` | | X | Show dbt model lineage and dependencies | +| **data-platform** | `/run` | | X | Run dbt models with validation | +| **data-platform** | `/initial-setup` | | X | Setup wizard for data-platform MCP servers | +| **data-platform** | *SessionStart hook* | X | | Checks PostgreSQL connection (non-blocking warning) | --- @@ -62,12 +71,13 @@ Quick reference for all commands in the Leo Claude Marketplace. | Category | Plugins | Primary Use | |----------|---------|-------------| -| **Setup** | projman, pr-review, cmdb-assistant | `/initial-setup`, `/project-init` | +| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/initial-setup`, `/project-init` | | **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification | | **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews | | **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance | | **Git Operations** | git-flow | Commits, branches, workflow automation | | **Infrastructure** | cmdb-assistant | NetBox CMDB management | +| **Data Engineering** | data-platform | pandas, PostgreSQL, dbt operations | | **Maintenance** | project-hygiene | Automatic cleanup | --- @@ -76,11 +86,12 @@ Quick reference for all commands in the Leo Claude Marketplace. | Plugin | Hook Event | Behavior | |--------|------------|----------| -| **projman** | SessionStart | Checks git remote vs .env; warns if mismatch detected | +| **projman** | SessionStart | Checks git remote vs .env; warns if mismatch detected; suggests sprint planning if issues exist | | **pr-review** | SessionStart | Checks git remote vs .env; warns if mismatch detected | -| **doc-guardian** | PostToolUse (Write/Edit) | Silently tracks documentation drift | +| **doc-guardian** | PostToolUse (Write/Edit) | Tracks documentation drift; auto-updates dependent docs | | **code-sentinel** | PreToolUse (Write/Edit) | Scans for security issues; blocks critical vulnerabilities | | **project-hygiene** | PostToolUse (Write/Edit) | Cleans temp files, warns about misplaced files | +| **data-platform** | SessionStart | Checks PostgreSQL connection; non-blocking warning if unavailable | --- @@ -162,6 +173,19 @@ Managing infrastructure with CMDB: 4. /cmdb-site view Y # Check site info ``` +### Example 6b: Data Engineering Workflow + +Working with data pipelines: + +``` +1. /ingest file.csv # Load data into DataFrame +2. /profile # Generate data profiling report +3. /schema # Explore database schemas +4. /lineage model_name # View dbt model dependencies +5. /run model_name # Execute dbt models +6. /explain "SELECT ..." # Analyze query execution plan +``` + ### Example 7: First-Time Setup (New Machine) Setting up the marketplace for the first time: @@ -209,9 +233,10 @@ Some plugins require MCP server connectivity: | projman | Gitea | Issues, PRs, wiki, labels, milestones | | pr-review | Gitea | PR operations and reviews | | cmdb-assistant | NetBox | Infrastructure CMDB | +| data-platform | pandas, PostgreSQL, dbt | DataFrames, database queries, dbt builds | -Ensure credentials are configured in `~/.config/claude/gitea.env` or `~/.config/claude/netbox.env`. +Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/claude/netbox.env`, or `~/.config/claude/postgres.env`. --- -*Last Updated: 2026-01-22* +*Last Updated: 2026-01-25* diff --git a/plugins/doc-guardian/hooks/notify.sh b/plugins/doc-guardian/hooks/notify.sh index f7c1bbc..8511fb8 100755 --- a/plugins/doc-guardian/hooks/notify.sh +++ b/plugins/doc-guardian/hooks/notify.sh @@ -1,6 +1,6 @@ #!/bin/bash # doc-guardian notification hook -# Outputs a single notification for config file changes, nothing otherwise +# Tracks documentation dependencies and queues updates # This is a command hook - guaranteed not to block workflow # Read tool input from stdin (JSON with file_path) @@ -14,10 +14,45 @@ if [ -z "$FILE_PATH" ]; then exit 0 fi -# Check if file is in a config directory (commands/, agents/, skills/, hooks/) -if echo "$FILE_PATH" | grep -qE '/(commands|agents|skills|hooks)/'; then - echo "[doc-guardian] Config file modified. Run /doc-sync when ready." +# Define documentation dependency mappings +# When these directories change, these docs need updating +declare -A DOC_DEPS +DOC_DEPS["commands"]="docs/COMMANDS-CHEATSHEET.md README.md" +DOC_DEPS["agents"]="README.md CLAUDE.md" +DOC_DEPS["hooks"]="docs/COMMANDS-CHEATSHEET.md README.md" +DOC_DEPS["skills"]="README.md" +DOC_DEPS[".claude-plugin"]="CLAUDE.md .claude-plugin/marketplace.json" +DOC_DEPS["mcp-servers"]="docs/COMMANDS-CHEATSHEET.md CLAUDE.md" + +# Check which config directory was modified +MODIFIED_TYPE="" +for dir in commands agents hooks skills .claude-plugin mcp-servers; do + if echo "$FILE_PATH" | grep -qE "/${dir}/|^${dir}/"; then + MODIFIED_TYPE="$dir" + break + fi +done + +# Exit silently if not a tracked config directory +if [ -z "$MODIFIED_TYPE" ]; then + exit 0 fi -# Exit silently for all other files (no output = no blocking) +# Get the dependent docs +DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}" + +# Queue file for tracking pending updates +QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue" + +# Add to queue (create if doesn't exist, append if does) +{ + echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS" +} >> "$QUEUE_FILE" 2>/dev/null || true + +# Count pending updates +PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1") + +# Output notification with specific docs that need updating +echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)" + exit 0 diff --git a/plugins/projman/commands/suggest-version.md b/plugins/projman/commands/suggest-version.md new file mode 100644 index 0000000..4253969 --- /dev/null +++ b/plugins/projman/commands/suggest-version.md @@ -0,0 +1,78 @@ +# /suggest-version + +Analyze CHANGELOG.md and suggest appropriate semantic version bump. + +## Behavior + +1. **Read current state**: + - Read `CHANGELOG.md` to find current version and [Unreleased] content + - Read `.claude-plugin/marketplace.json` for current marketplace version + - Check individual plugin versions in `plugins/*/. claude-plugin/plugin.json` + +2. **Analyze [Unreleased] section**: + - Extract all entries under `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated` + - Categorize changes by impact + +3. **Apply SemVer rules**: + + | Change Type | Version Bump | Indicators | + |-------------|--------------|------------| + | **MAJOR** (X.0.0) | Breaking changes | `### Removed`, `### Changed` with "BREAKING:", renamed/removed APIs | + | **MINOR** (x.Y.0) | New features, backwards compatible | `### Added` with new commands/plugins/features | + | **PATCH** (x.y.Z) | Bug fixes only | `### Fixed` only, `### Changed` for non-breaking tweaks | + +4. **Output recommendation**: + ``` + ## Version Analysis + + **Current version:** X.Y.Z + **[Unreleased] summary:** + - Added: N entries (new features/plugins) + - Changed: N entries (M breaking) + - Fixed: N entries + - Removed: N entries + + **Recommendation:** MINOR bump → X.(Y+1).0 + **Reason:** New features added without breaking changes + + **To release:** ./scripts/release.sh X.Y.Z + ``` + +5. **Check version sync**: + - Compare marketplace version with individual plugin versions + - Warn if plugins are out of sync (e.g., marketplace 4.0.0 but projman 3.1.0) + +## Examples + +**Output when MINOR bump needed:** +``` +## Version Analysis + +**Current version:** 4.0.0 +**[Unreleased] summary:** +- Added: 3 entries (new command, hook improvement, workflow example) +- Changed: 1 entry (0 breaking) +- Fixed: 2 entries + +**Recommendation:** MINOR bump → 4.1.0 +**Reason:** New features (Added section) without breaking changes + +**To release:** ./scripts/release.sh 4.1.0 +``` + +**Output when nothing to release:** +``` +## Version Analysis + +**Current version:** 4.0.0 +**[Unreleased] summary:** Empty - no pending changes + +**Recommendation:** No release needed +``` + +## Integration + +This command helps maintain proper versioning workflow: +- Run after completing a sprint to determine version bump +- Run before `/sprint-close` to ensure version is updated +- Integrates with `./scripts/release.sh` for actual release execution diff --git a/plugins/projman/hooks/startup-check.sh b/plugins/projman/hooks/startup-check.sh index 3c795b5..82fca59 100755 --- a/plugins/projman/hooks/startup-check.sh +++ b/plugins/projman/hooks/startup-check.sh @@ -1,6 +1,6 @@ #!/bin/bash # projman startup check hook -# Checks for common issues at session start +# Checks for common issues AND suggests sprint planning proactively # All output MUST have [projman] prefix PREFIX="[projman]" @@ -26,5 +26,41 @@ if [[ -f ".env" ]]; then fi fi -# All checks passed - say nothing +# Check for open issues (suggests sprint planning) +# Only if .env exists with valid GITEA config +if [[ -f ".env" ]]; then + GITEA_API_URL=$(grep -E "^GITEA_API_URL=" ~/.config/claude/gitea.env 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true) + GITEA_API_TOKEN=$(grep -E "^GITEA_API_TOKEN=" ~/.config/claude/gitea.env 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true) + GITEA_REPO=$(grep -E "^GITEA_REPO=" .env 2>/dev/null | cut -d'=' -f2 | tr -d '"' || true) + + if [[ -n "$GITEA_API_URL" && -n "$GITEA_API_TOKEN" && -n "$GITEA_REPO" ]]; then + # Quick check for open issues without milestone (unplanned work) + OPEN_ISSUES=$(curl -s -m 5 \ + -H "Authorization: token $GITEA_API_TOKEN" \ + "${GITEA_API_URL}/repos/${GITEA_REPO}/issues?state=open&milestone=none&limit=1" 2>/dev/null | \ + grep -c '"number"' || echo "0") + + if [[ "$OPEN_ISSUES" -gt 0 ]]; then + # Count total unplanned issues + TOTAL_UNPLANNED=$(curl -s -m 5 \ + -H "Authorization: token $GITEA_API_TOKEN" \ + "${GITEA_API_URL}/repos/${GITEA_REPO}/issues?state=open&milestone=none" 2>/dev/null | \ + grep -c '"number"' || echo "?") + echo "$PREFIX ${TOTAL_UNPLANNED} open issues without milestone - consider /sprint-plan" + fi + fi +fi + +# Check for CHANGELOG.md [Unreleased] content (version management) +if [[ -f "CHANGELOG.md" ]]; then + # Check if there's content under [Unreleased] that hasn't been released + UNRELEASED_CONTENT=$(sed -n '/## \[Unreleased\]/,/## \[/p' CHANGELOG.md 2>/dev/null | grep -E '^### (Added|Changed|Fixed|Removed|Deprecated)' | head -1 || true) + if [[ -n "$UNRELEASED_CONTENT" ]]; then + UNRELEASED_LINES=$(sed -n '/## \[Unreleased\]/,/## \[/p' CHANGELOG.md 2>/dev/null | grep -E '^- ' | wc -l | tr -d ' ') + if [[ "$UNRELEASED_LINES" -gt 0 ]]; then + echo "$PREFIX ${UNRELEASED_LINES} unreleased changes in CHANGELOG - consider version bump" + fi + fi +fi + exit 0