personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'fix: proactive documentation and sprint planning automation' (#153) from fix/proactive-automation-docs into development

Browse Source 
Reviewed-on: #153
This commit was merged in pull request #153.
This commit is contained in:
Leo Miranda
2026-01-25 20:23:56 +00:00
parent a77b8ee123 6b666bff46
commit 69bbffd9cc
6 changed files with 219 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
CHANGELOG.md
View File

@@ -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

18
CLAUDE.md
View File

@@ -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/

35
docs/COMMANDS-CHEATSHEET.md
View File

@@ -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*

45
plugins/doc-guardian/hooks/notify.sh
View File

@@ -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

78
plugins/projman/commands/suggest-version.md Normal file
View File

@@ -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

40
plugins/projman/hooks/startup-check.sh
View File

@@ -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