diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 37e81af..00d014d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Project management plugins with Gitea and NetBox integrations", - "version": "5.7.1" + "version": "5.8.0" }, "plugins": [ { diff --git a/.claude/backups/CLAUDE.md.2026-01-22_132037 b/.claude/backups/CLAUDE.md.2026-01-22_132037 new file mode 100644 index 0000000..30779ea --- /dev/null +++ b/.claude/backups/CLAUDE.md.2026-01-22_132037 @@ -0,0 +1,249 @@ +# CLAUDE.md + +This file provides guidance to Claude Code when working with code in this repository. + +## Project Overview + +**Repository:** leo-claude-mktplace +**Version:** 3.0.1 +**Status:** Production Ready + +A plugin marketplace for Claude Code containing: + +| Plugin | Description | Version | +|--------|-------------|---------| +| `projman` | Sprint planning and project management with Gitea integration | 3.0.0 | +| `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 | +| `pr-review` | Multi-agent PR review with confidence scoring | 1.0.0 | +| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 | +| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 | +| `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 | +| `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 | + +## Quick Start + +```bash +# Validate marketplace compliance +./scripts/validate-marketplace.sh + +# Setup commands (in a target project with plugin installed) +/initial-setup # First time: full setup wizard +/project-init # New project: quick config +/project-sync # After repo move: sync config + +# Run projman commands +/sprint-plan # Start sprint planning +/sprint-status # Check progress +/review # Pre-close code quality review +/test-check # Verify tests before close +/sprint-close # Complete sprint +``` + +## Repository Structure + +``` +leo-claude-mktplace/ +├── .claude-plugin/ +│ └── marketplace.json # Marketplace manifest +├── mcp-servers/ # SHARED MCP servers (v3.0.0+) +│ ├── gitea/ # Gitea MCP (issues, PRs, wiki) +│ └── netbox/ # NetBox MCP (CMDB) +├── plugins/ +│ ├── projman/ # Sprint management +│ │ ├── .claude-plugin/plugin.json +│ │ ├── .mcp.json +│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK +│ │ ├── commands/ # 12 commands (incl. setup) +│ │ ├── hooks/ # SessionStart mismatch detection +│ │ ├── agents/ # 4 agents +│ │ └── skills/label-taxonomy/ +│ ├── git-flow/ # Git workflow automation +│ │ ├── .claude-plugin/plugin.json +│ │ ├── commands/ # 8 commands +│ │ └── agents/ +│ ├── pr-review/ # Multi-agent PR review +│ │ ├── .claude-plugin/plugin.json +│ │ ├── .mcp.json +│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK +│ │ ├── commands/ # 6 commands (incl. setup) +│ │ ├── hooks/ # SessionStart mismatch detection +│ │ └── agents/ # 5 agents +│ ├── clarity-assist/ # Prompt optimization (NEW v3.0.0) +│ │ ├── .claude-plugin/plugin.json +│ │ ├── commands/ # 2 commands +│ │ └── agents/ +│ ├── doc-guardian/ # Documentation drift detection +│ ├── code-sentinel/ # Security scanning & refactoring +│ ├── claude-config-maintainer/ +│ ├── cmdb-assistant/ +│ └── project-hygiene/ +├── scripts/ +│ ├── setup.sh, post-update.sh +│ └── validate-marketplace.sh # Marketplace compliance validation +└── docs/ + ├── CANONICAL-PATHS.md # Single source of truth for paths + └── CONFIGURATION.md # Centralized configuration guide +``` + +## CRITICAL: Rules You MUST Follow + +### File Operations +- **NEVER** create files in repository root unless listed in "Allowed Root Files" +- **NEVER** modify `.gitignore` without explicit permission +- **ALWAYS** use `.scratch/` for temporary/exploratory work +- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files + +### Plugin Development +- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root) +- **Every plugin MUST be listed in marketplace.json** +- **MCP servers are SHARED at root** with symlinks from plugins +- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python` +- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.) + +### Hooks (Valid Events Only) +`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact` + +**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed` + +### Allowed Root Files +`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` + +### Allowed Root Directories +`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/` + +## Architecture + +### Four-Agent Model (projman) + +| Agent | Personality | Responsibilities | +|-------|-------------|------------------| +| **Planner** | Thoughtful, methodical | Sprint planning, architecture analysis, issue creation, lesson search | +| **Orchestrator** | Concise, action-oriented | Sprint execution, parallel batching, Git operations, lesson capture | +| **Executor** | Implementation-focused | Code implementation, branch management, MR creation | +| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification | + +### MCP Server Tools (Gitea) + +| Category | Tools | +|----------|-------| +| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` | +| Labels | `get_labels`, `suggest_labels`, `create_label` | +| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` | +| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` | +| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` | +| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW v3.0.0)* | +| Validation | `validate_repo_org`, `get_branch_protection` | + +### Hybrid Configuration + +| Level | Location | Purpose | +|-------|----------|---------| +| System | `~/.config/claude/gitea.env` | Credentials (GITEA_API_URL, GITEA_API_TOKEN) | +| Project | `.env` in project root | Repository specification (GITEA_ORG, GITEA_REPO) | + +**Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations. + +### Branch-Aware Security + +| Branch Pattern | Mode | Capabilities | +|----------------|------|--------------| +| `development`, `feat/*` | Development | Full access | +| `staging` | Staging | Read-only code, can create issues | +| `main`, `master` | Production | Read-only, emergency only | + +## Label Taxonomy + +43 labels total: 27 organization + 16 repository + +**Organization:** Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6 +**Repository:** Component/9, Tech/7 + +Sync with `/labels-sync` command. + +## Lessons Learned System + +Stored in Gitea Wiki under `lessons-learned/sprints/`. + +**Workflow:** +1. Orchestrator captures at sprint close via MCP tools +2. Planner searches at sprint start using `search_lessons` +3. Tags enable cross-project discovery + +## Common Operations + +### Adding a New Plugin + +1. Create `plugins/{name}/.claude-plugin/plugin.json` +2. Add entry to `.claude-plugin/marketplace.json` with category, tags, license +3. Create `README.md` and `claude-md-integration.md` +4. If using MCP server, create symlink: `ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}` +5. Run `./scripts/validate-marketplace.sh` +6. Update `CHANGELOG.md` + +### Adding a Command to projman + +1. Create `plugins/projman/commands/{name}.md` +2. Update `plugins/projman/README.md` +3. Update marketplace description if significant + +### Validation + +```bash +./scripts/validate-marketplace.sh # Validates all manifests +``` + +## Path Verification Protocol + +**Before creating any file:** + +1. Read `docs/CANONICAL-PATHS.md` +2. List all paths to be created/modified +3. Verify each against canonical paths +4. If not in canonical paths, STOP and ask + +## Documentation Index + +| Document | Purpose | +|----------|---------| +| `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths | +| `docs/COMMANDS-CHEATSHEET.md` | All commands quick reference with workflow examples | +| `docs/CONFIGURATION.md` | Centralized setup guide | +| `docs/UPDATING.md` | Update guide for the marketplace | +| `plugins/projman/CONFIGURATION.md` | Quick reference (links to central) | +| `plugins/projman/README.md` | Projman full documentation | + +## Versioning and Changelog Rules + +### Version Display +**The marketplace version is displayed ONLY in the main `README.md` title.** + +- Format: `# Leo Claude Marketplace - vX.Y.Z` +- Do NOT add version numbers to individual plugin documentation titles +- Do NOT add version numbers to configuration guides +- Do NOT add version numbers to CLAUDE.md or other docs + +### Changelog Maintenance (MANDATORY) +**`CHANGELOG.md` is the authoritative source for version history.** + +When releasing a new version: +1. Update main `README.md` title with new version +2. Update `CHANGELOG.md` with: + - Version number and date: `## [X.Y.Z] - YYYY-MM-DD` + - **Added**: New features, commands, files + - **Changed**: Modifications to existing functionality + - **Fixed**: Bug fixes + - **Removed**: Deleted features, files, deprecated items +3. Update `marketplace.json` metadata version +4. Update plugin `plugin.json` versions if plugin-specific changes + +### Version Format +- Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH +- MAJOR: Breaking changes +- MINOR: New features, backward compatible +- PATCH: Bug fixes, minor improvements + +--- + +**Last Updated:** 2026-01-20 diff --git a/.doc-guardian-queue b/.doc-guardian-queue new file mode 100644 index 0000000..0be6d98 --- /dev/null +++ b/.doc-guardian-queue @@ -0,0 +1,27 @@ +# Doc Guardian Queue - cleared after sync on 2026-02-02 +2026-02-02T11:41:00 | .claude-plugin | /home/lmiranda/claude-plugins-work/.claude-plugin/marketplace.json | CLAUDE.md .claude-plugin/marketplace.json +2026-02-02T13:35:48 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-approval.md | README.md +2026-02-02T13:36:03 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-start.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:36:16 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/orchestrator.md | README.md CLAUDE.md +2026-02-02T13:39:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/rfc.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:39:15 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/setup.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:39:32 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-workflow.md | README.md +2026-02-02T13:43:14 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-templates.md | README.md +2026-02-02T13:44:55 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-lifecycle.md | README.md +2026-02-02T13:45:04 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/label-taxonomy/labels-reference.md | README.md +2026-02-02T13:45:14 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-plan.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:45:48 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/review.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:46:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-close.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:46:21 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-status.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:46:38 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md +2026-02-02T13:46:57 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md +2026-02-02T13:49:13 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/design-gate.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:49:24 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-gate.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:49:35 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/domain-consultation.md | README.md +2026-02-02T13:50:04 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-02-02T13:50:59 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/server.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-02-02T13:51:32 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-02-02T13:51:49 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/validation-rules.md | README.md +2026-02-02T13:52:07 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/mcp-tools-reference.md | README.md +2026-02-02T13:59:09 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/progress-tracking.md | README.md +2026-02-02T14:01:34 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/test.md | docs/COMMANDS-CHEATSHEET.md README.md diff --git a/.env b/.env new file mode 100644 index 0000000..dbefba5 --- /dev/null +++ b/.env @@ -0,0 +1 @@ +GITEA_REPO=personal-projects/leo-claude-mktplace diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bd8942..664b496 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,64 @@ 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/). +## [5.8.0] - 2026-02-02 + +### Added + +#### Projman Hardening Sprint +Targeted improvements to safety gates, command structure, lifecycle tracking, and cross-plugin contracts. + +**Sprint Lifecycle State Machine:** +- New `skills/sprint-lifecycle.md` - defines valid states and transitions via milestone metadata +- States: idle -> Sprint/Planning -> Sprint/Executing -> Sprint/Reviewing -> idle +- All sprint commands check and set lifecycle state on entry/exit +- Out-of-order calls produce warnings with guidance, `--force` override available + +**Sprint Dispatch Log:** +- Orchestrator now maintains a structured dispatch log during execution +- Records task dispatch, completion, failure, gate checks, and resume events +- Enables timeline reconstruction after interrupted sessions + +**Gate Contract Versioning:** +- Gate commands (`/design-gate`, `/data-gate`) declare `gate_contract: v1` in frontmatter +- `domain-consultation.md` Gate Command Reference includes expected contract version +- `validate_workflow_integration` now checks contract version compatibility +- Mismatch produces WARNING, missing contract produces INFO suggestion + +**Shared Visual Output Skill:** +- New `skills/visual-output.md` - single source of truth for projman visual headers +- All 4 agent files reference the skill instead of inline templates +- Phase Registry maps agents to emoji and phase names + +### Changed + +**Sprint Approval Gate Hardened:** +- Approval is now a hard block, not a warning (was "recommended", now required) +- `--force` flag added to bypass in emergencies (logged to milestone) +- Consistent language across sprint-approval.md, sprint-start.md, and orchestrator.md + +**RFC Commands Normalized:** +- 5 individual commands (`/rfc-create`, `/rfc-list`, `/rfc-review`, `/rfc-approve`, `/rfc-reject`) consolidated into `/rfc create|list|review|approve|reject` +- `/clear-cache` absorbed into `/setup --clear-cache` +- Command count reduced from 17 to 12 + +**`/test` Command Documentation Expanded:** +- Sprint integration section (pre-close verification workflow) +- Concrete usage examples for all modes +- Edge cases table +- DO NOT rules for both modes + +### Removed + +- `plugins/projman/commands/rfc-create.md` (replaced by `/rfc create`) +- `plugins/projman/commands/rfc-list.md` (replaced by `/rfc list`) +- `plugins/projman/commands/rfc-review.md` (replaced by `/rfc review`) +- `plugins/projman/commands/rfc-approve.md` (replaced by `/rfc approve`) +- `plugins/projman/commands/rfc-reject.md` (replaced by `/rfc reject`) +- `plugins/projman/commands/clear-cache.md` (replaced by `/setup --clear-cache`) + +--- + ## [5.7.1] - 2026-02-02 ### Added diff --git a/README.md b/README.md index 0e1bdd0..dfbf32a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Leo Claude Marketplace - v5.7.1 +# Leo Claude Marketplace - v5.8.0 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. @@ -19,7 +19,7 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp - Branch-aware security (development/staging/production) - Pre-sprint-close code quality review and test verification -**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/setup`, `/review`, `/test`, `/debug`, `/suggest-version`, `/proposal-status`, `/clear-cache`, `/rfc-create`, `/rfc-list`, `/rfc-review`, `/rfc-approve`, `/rfc-reject` +**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/setup`, `/review`, `/test`, `/debug`, `/suggest-version`, `/proposal-status`, `/rfc` #### [git-flow](./plugins/git-flow) *NEW in v3.0.0* **Git Workflow Automation** diff --git a/docs/COMMANDS-CHEATSHEET.md b/docs/COMMANDS-CHEATSHEET.md index e3c706d..1f0e4a3 100644 --- a/docs/COMMANDS-CHEATSHEET.md +++ b/docs/COMMANDS-CHEATSHEET.md @@ -9,23 +9,18 @@ Quick reference for all commands in the Leo Claude Marketplace. | Plugin | Command | Auto | Manual | Description | |--------|---------|:----:|:------:|-------------| | **projman** | `/sprint-plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation | -| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination | +| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination (requires approval or `--force`) | | **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) | | **projman** | `/review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) | | **projman** | `/test` | | X | Run tests (`/test run`) or generate tests (`/test gen `) | | **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki | | **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea | -| **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync` | +| **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` | | **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/setup --sync` | | **projman** | `/debug` | | X | Diagnostics (`/debug report`) or investigate (`/debug review`) | | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump | | **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status | -| **projman** | `/clear-cache` | | X | Clear plugin cache to force fresh configuration reload | -| **projman** | `/rfc-create` | | X | Create new RFC from conversation or clarified spec | -| **projman** | `/rfc-list` | | X | List all RFCs grouped by status | -| **projman** | `/rfc-review` | | X | Submit Draft RFC for review | -| **projman** | `/rfc-approve` | | X | Approve RFC in Review status for sprint planning | -| **projman** | `/rfc-reject` | | X | Reject RFC with documented reason | +| **projman** | `/rfc` | | X | RFC lifecycle management (`/rfc create\|list\|review\|approve\|reject`) | | **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 | @@ -144,11 +139,11 @@ Full workflow from idea to implementation using RFCs: ``` 1. /clarify # Clarify the feature idea -2. /rfc-create # Create RFC from clarified spec +2. /rfc create # Create RFC from clarified spec ... refine RFC content ... -3. /rfc-review 0001 # Submit RFC for review +3. /rfc review 0001 # Submit RFC for review ... review discussion ... -4. /rfc-approve 0001 # Approve RFC for implementation +4. /rfc approve 0001 # Approve RFC for implementation 5. /sprint-plan # Select approved RFC for sprint ... implement feature ... 6. /sprint-close # Complete sprint, RFC marked Implemented diff --git a/mcp-servers/contract-validator/.doc-guardian-queue b/mcp-servers/contract-validator/.doc-guardian-queue new file mode 100644 index 0000000..bd8da40 --- /dev/null +++ b/mcp-servers/contract-validator/.doc-guardian-queue @@ -0,0 +1,20 @@ +2026-01-26T14:36:42 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T14:37:38 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T14:37:48 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T14:38:05 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T14:38:55 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T14:39:35 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T14:40:19 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T15:02:30 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T15:02:37 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T15:03:41 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_report_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-02-02T10:56:19 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-02-02T10:57:49 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-02-02T10:58:22 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/mcp-tools-reference.md | README.md +2026-02-02T10:58:38 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/validation-rules.md | README.md +2026-02-02T10:59:13 | .claude-plugin | /home/lmiranda/claude-plugins-work/.claude-plugin/marketplace.json | CLAUDE.md .claude-plugin/marketplace.json +2026-02-02T13:55:33 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/visual-output.md | README.md +2026-02-02T13:55:41 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md +2026-02-02T13:55:55 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/orchestrator.md | README.md CLAUDE.md +2026-02-02T13:56:14 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/executor.md | README.md CLAUDE.md +2026-02-02T13:56:34 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md diff --git a/mcp-servers/contract-validator/mcp_server/server.py b/mcp-servers/contract-validator/mcp_server/server.py index 3891576..1d3c504 100644 --- a/mcp-servers/contract-validator/mcp_server/server.py +++ b/mcp-servers/contract-validator/mcp_server/server.py @@ -133,7 +133,7 @@ class ContractValidatorMCPServer: ), Tool( name="validate_workflow_integration", - description="Validate that a domain plugin exposes the required advisory interfaces (gate command, review command, advisory agent) expected by projman's domain-consultation skill", + description="Validate that a domain plugin exposes the required advisory interfaces (gate command, review command, advisory agent) expected by projman's domain-consultation skill. Also checks gate contract version compatibility.", inputSchema={ "type": "object", "properties": { @@ -144,6 +144,10 @@ class ContractValidatorMCPServer: "domain_label": { "type": "string", "description": "The Domain/* label it claims to handle, e.g. Domain/Viz" + }, + "expected_contract": { + "type": "string", + "description": "Expected contract version (e.g., 'v1'). If provided, validates the gate command's contract matches." } }, "required": ["plugin_path", "domain_label"] @@ -261,9 +265,16 @@ class ContractValidatorMCPServer: """Validate agent data flow""" return await self.validation_tools.validate_data_flow(agent_name, claude_md_path) - async def _validate_workflow_integration(self, plugin_path: str, domain_label: str) -> dict: + async def _validate_workflow_integration( + self, + plugin_path: str, + domain_label: str, + expected_contract: str = None + ) -> dict: """Validate domain plugin exposes required advisory interfaces""" - return await self.validation_tools.validate_workflow_integration(plugin_path, domain_label) + return await self.validation_tools.validate_workflow_integration( + plugin_path, domain_label, expected_contract + ) # Report tool implementations (Issue #188) diff --git a/mcp-servers/contract-validator/mcp_server/validation_tools.py b/mcp-servers/contract-validator/mcp_server/validation_tools.py index 1aa550a..585dadb 100644 --- a/mcp-servers/contract-validator/mcp_server/validation_tools.py +++ b/mcp-servers/contract-validator/mcp_server/validation_tools.py @@ -72,6 +72,7 @@ class WorkflowIntegrationResult(BaseModel): domain_label: str valid: bool gate_command_found: bool + gate_contract: Optional[str] = None # Contract version declared by gate command review_command_found: bool advisory_agent_found: bool issues: list[ValidationIssue] = [] @@ -349,22 +350,32 @@ class ValidationTools: return result.model_dump() - async def validate_workflow_integration(self, plugin_path: str, domain_label: str) -> dict: + async def validate_workflow_integration( + self, + plugin_path: str, + domain_label: str, + expected_contract: Optional[str] = None + ) -> dict: """ Validate that a domain plugin exposes required advisory interfaces. Checks for: - Gate command (e.g., /design-gate, /data-gate) - REQUIRED + - Gate contract version (gate_contract in frontmatter) - INFO if missing - Review command (e.g., /design-review, /data-review) - recommended - Advisory agent referencing the domain label - recommended Args: plugin_path: Path to the domain plugin directory domain_label: The Domain/* label it claims to handle (e.g., Domain/Viz) + expected_contract: Expected contract version (e.g., 'v1'). If provided, + validates the gate command's contract matches. Returns: Validation result with found interfaces and issues """ + import re + plugin_path_obj = Path(plugin_path) issues = [] @@ -383,6 +394,7 @@ class ValidationTools: # Check for gate command commands_dir = plugin_path_obj / "commands" gate_command_found = False + gate_contract = None gate_patterns = ["pass", "fail", "PASS", "FAIL", "Binary pass/fail", "gate"] if commands_dir.exists(): @@ -392,6 +404,13 @@ class ValidationTools: content = cmd_file.read_text() if any(pattern in content for pattern in gate_patterns): gate_command_found = True + # Parse frontmatter for gate_contract + frontmatter_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) + if frontmatter_match: + frontmatter = frontmatter_match.group(1) + contract_match = re.search(r'gate_contract:\s*(\S+)', frontmatter) + if contract_match: + gate_contract = contract_match.group(1) break if not gate_command_found: @@ -441,11 +460,31 @@ class ValidationTools: suggestion=f"Create agents/{domain_short}-advisor.md referencing '{domain_label}'" )) + # Check gate contract version + if gate_command_found: + if not gate_contract: + issues.append(ValidationIssue( + severity=IssueSeverity.INFO, + issue_type=IssueType.MISSING_INTEGRATION, + message=f"Gate command does not declare a contract version", + location=str(commands_dir), + suggestion="Consider adding `gate_contract: v1` to frontmatter for version tracking" + )) + elif expected_contract and gate_contract != expected_contract: + issues.append(ValidationIssue( + severity=IssueSeverity.WARNING, + issue_type=IssueType.INTERFACE_MISMATCH, + message=f"Contract version mismatch: gate declares {gate_contract}, projman expects {expected_contract}", + location=str(commands_dir), + suggestion=f"Update domain-consultation.md Gate Command Reference table to {gate_contract}, or update gate command to {expected_contract}" + )) + result = WorkflowIntegrationResult( plugin_name=plugin_name, domain_label=domain_label, valid=gate_command_found, # Only gate is required for validity gate_command_found=gate_command_found, + gate_contract=gate_contract, review_command_found=review_command_found, advisory_agent_found=advisory_agent_found, issues=issues diff --git a/mcp-servers/contract-validator/tests/test_validation_tools.py b/mcp-servers/contract-validator/tests/test_validation_tools.py index 2ebfacd..aae08a1 100644 --- a/mcp-servers/contract-validator/tests/test_validation_tools.py +++ b/mcp-servers/contract-validator/tests/test_validation_tools.py @@ -350,7 +350,10 @@ async def test_validate_workflow_integration_complete(validation_tools, domain_p assert result["gate_command_found"] is True assert result["review_command_found"] is True assert result["advisory_agent_found"] is True - assert len(result["issues"]) == 0 + # May have INFO issue about missing contract version (not an error/warning) + error_or_warning = [i for i in result["issues"] + if i["severity"].value in ("error", "warning")] + assert len(error_or_warning) == 0 @pytest.mark.asyncio @@ -404,3 +407,108 @@ async def test_validate_workflow_integration_nonexistent_plugin(validation_tools assert "error" in result assert "not found" in result["error"].lower() + + +# --- Gate Contract Version Tests --- + +@pytest.fixture +def domain_plugin_with_contract(tmp_path): + """Create domain plugin with gate_contract: v1 in frontmatter""" + plugin_dir = tmp_path / "viz-platform-versioned" + plugin_dir.mkdir() + (plugin_dir / ".claude-plugin").mkdir() + (plugin_dir / "commands").mkdir() + (plugin_dir / "agents").mkdir() + + # Gate command with gate_contract in frontmatter + gate_cmd = plugin_dir / "commands" / "design-gate.md" + gate_cmd.write_text("""--- +description: Design system compliance gate (pass/fail) +gate_contract: v1 +--- + +# /design-gate + +Binary pass/fail validation gate for design system compliance. + +## Output + +- **PASS**: All design system checks passed +- **FAIL**: Design system violations detected +""") + + # Review command + review_cmd = plugin_dir / "commands" / "design-review.md" + review_cmd.write_text("""# /design-review + +Comprehensive design system audit. +""") + + # Advisory agent + agent = plugin_dir / "agents" / "design-reviewer.md" + agent.write_text("""# design-reviewer + +Design system compliance auditor for Domain/Viz issues. +""") + + return str(plugin_dir) + + +@pytest.mark.asyncio +async def test_validate_workflow_contract_match(validation_tools, domain_plugin_with_contract): + """Test that matching expected_contract produces no warning""" + result = await validation_tools.validate_workflow_integration( + domain_plugin_with_contract, + "Domain/Viz", + expected_contract="v1" + ) + + assert "error" not in result + assert result["valid"] is True + assert result["gate_contract"] == "v1" + + # Should have no warnings about contract mismatch + warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"] + contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()] + assert len(contract_warnings) == 0 + + +@pytest.mark.asyncio +async def test_validate_workflow_contract_mismatch(validation_tools, domain_plugin_with_contract): + """Test that mismatched expected_contract produces WARNING""" + result = await validation_tools.validate_workflow_integration( + domain_plugin_with_contract, + "Domain/Viz", + expected_contract="v2" # Gate has v1 + ) + + assert "error" not in result + assert result["valid"] is True # Contract mismatch doesn't affect validity + assert result["gate_contract"] == "v1" + + # Should have warning about contract mismatch + warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"] + contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()] + assert len(contract_warnings) == 1 + assert "mismatch" in contract_warnings[0]["message"].lower() + assert "v1" in contract_warnings[0]["message"] + assert "v2" in contract_warnings[0]["message"] + + +@pytest.mark.asyncio +async def test_validate_workflow_no_contract(validation_tools, domain_plugin_complete): + """Test that missing gate_contract produces INFO suggestion""" + result = await validation_tools.validate_workflow_integration( + domain_plugin_complete, + "Domain/Viz" + ) + + assert "error" not in result + assert result["valid"] is True + assert result["gate_contract"] is None + + # Should have info issue about missing contract + info_issues = [i for i in result["issues"] if i["severity"].value == "info"] + contract_info = [i for i in info_issues if "contract" in i["message"].lower()] + assert len(contract_info) == 1 + assert "does not declare" in contract_info[0]["message"].lower() diff --git a/mcp-servers/viz-platform/.doc-guardian-queue b/mcp-servers/viz-platform/.doc-guardian-queue new file mode 100644 index 0000000..f5eb1d3 --- /dev/null +++ b/mcp-servers/viz-platform/.doc-guardian-queue @@ -0,0 +1,5 @@ +2026-01-26T11:40:11 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/registry/dmc_2_5.json | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T13:46:31 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_chart_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T13:46:32 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T13:46:34 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md +2026-01-26T13:46:35 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md diff --git a/plugins/contract-validator/skills/mcp-tools-reference.md b/plugins/contract-validator/skills/mcp-tools-reference.md index 1f36dd2..df8d352 100644 --- a/plugins/contract-validator/skills/mcp-tools-reference.md +++ b/plugins/contract-validator/skills/mcp-tools-reference.md @@ -16,7 +16,7 @@ Available MCP tools for contract-validator operations. | `validate_compatibility` | Check two plugins for conflicts | | `validate_agent_refs` | Check agent tool references exist | | `validate_data_flow` | Verify data flow through agent sequence | -| `validate_workflow_integration` | Check domain plugin exposes required advisory interfaces | +| `validate_workflow_integration` | Check domain plugin exposes required advisory interfaces and gate contract version | ### Report Tools | Tool | Description | @@ -57,8 +57,9 @@ Available MCP tools for contract-validator operations. ### Workflow Integration Check ``` 1. validate_workflow_integration(plugin_path, domain_label) # Check single domain plugin -2. For each domain in domain-consultation.md detection rules: - validate_workflow_integration(domain_plugin_path, domain_label) +2. validate_workflow_integration(plugin_path, domain_label, expected_contract="v1") # With contract version check +3. For each domain in domain-consultation.md detection rules: + validate_workflow_integration(domain_plugin_path, domain_label, expected_contract) ``` ## Error Handling diff --git a/plugins/contract-validator/skills/validation-rules.md b/plugins/contract-validator/skills/validation-rules.md index 1c92f25..db7faa7 100644 --- a/plugins/contract-validator/skills/validation-rules.md +++ b/plugins/contract-validator/skills/validation-rules.md @@ -35,7 +35,9 @@ Rules for validating plugin compatibility and agent definitions. 2. Gate command produces binary PASS/FAIL output 3. Review command exists (WARNING if missing, not ERROR) 4. Advisory agent exists referencing the domain label -- Severity: ERROR for missing gate, WARNING for missing review/agent +5. Gate command declares `gate_contract` version in frontmatter +6. If expected version provided, gate contract version matches expected +- Severity: ERROR for missing gate, WARNING for missing review/agent or contract mismatch, INFO for missing contract ## Severity Levels diff --git a/plugins/data-platform/commands/data-gate.md b/plugins/data-platform/commands/data-gate.md index 527cf53..5014c25 100644 --- a/plugins/data-platform/commands/data-gate.md +++ b/plugins/data-platform/commands/data-gate.md @@ -1,5 +1,6 @@ --- description: Data integrity compliance gate (pass/fail) for sprint execution +gate_contract: v1 arguments: - name: path description: File or directory to validate diff --git a/plugins/projman/.doc-guardian-queue b/plugins/projman/.doc-guardian-queue new file mode 100644 index 0000000..8228a4e --- /dev/null +++ b/plugins/projman/.doc-guardian-queue @@ -0,0 +1,5 @@ +2026-01-30T14:32:53 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/setup-workflows.md | README.md +2026-01-30T14:32:53 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/setup.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-01-30T14:32:54 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/debug.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-01-30T14:32:54 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/test.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-01-30T14:33:13 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-status.md | docs/COMMANDS-CHEATSHEET.md README.md diff --git a/plugins/projman/agents/code-reviewer.md b/plugins/projman/agents/code-reviewer.md index d5fc1f0..f2e808a 100644 --- a/plugins/projman/agents/code-reviewer.md +++ b/plugins/projman/agents/code-reviewer.md @@ -11,6 +11,8 @@ You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures - skills/review-checklist.md - skills/test-standards.md +- skills/sprint-lifecycle.md +- skills/visual-output.md ## Your Personality @@ -28,14 +30,10 @@ You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures ## Visual Output -Display header at start of every response: -``` -╔══════════════════════════════════════════════════════════════════╗ -║ 📋 PROJMAN ║ -║ 🏁 CLOSING ║ -║ Code Review ║ -╚══════════════════════════════════════════════════════════════════╝ -``` +See `skills/visual-output.md` for header templates. Use the **Code Reviewer** row from the Phase Registry: +- Phase Emoji: Magnifier +- Phase Name: REVIEW +- Context: Sprint Name ## Your Responsibilities diff --git a/plugins/projman/agents/executor.md b/plugins/projman/agents/executor.md index 32f1557..165438c 100644 --- a/plugins/projman/agents/executor.md +++ b/plugins/projman/agents/executor.md @@ -15,6 +15,7 @@ You are the **Executor Agent** - an implementation-focused specialist who writes - skills/progress-tracking.md - skills/runaway-detection.md - skills/lessons-learned.md +- skills/visual-output.md ## Your Personality @@ -32,14 +33,10 @@ You are the **Executor Agent** - an implementation-focused specialist who writes ## Visual Output -Display header at start of every response: -``` -╔══════════════════════════════════════════════════════════════════╗ -║ 📋 PROJMAN ║ -║ ⚡ EXECUTION ║ -║ [Issue Title] ║ -╚══════════════════════════════════════════════════════════════════╝ -``` +See `skills/visual-output.md` for header templates. Use the **Executor** row from the Phase Registry: +- Phase Emoji: Wrench +- Phase Name: IMPLEMENTING +- Context: Issue Title ## Your Responsibilities diff --git a/plugins/projman/agents/orchestrator.md b/plugins/projman/agents/orchestrator.md index 62eb17c..9f48f2e 100644 --- a/plugins/projman/agents/orchestrator.md +++ b/plugins/projman/agents/orchestrator.md @@ -19,6 +19,8 @@ You are the **Orchestrator Agent** - a concise, action-oriented coordinator who - skills/runaway-detection.md - skills/wiki-conventions.md - skills/domain-consultation.md +- skills/sprint-lifecycle.md +- skills/visual-output.md ## Your Personality @@ -36,28 +38,17 @@ You are the **Orchestrator Agent** - a concise, action-oriented coordinator who ## Visual Output -Display header at start of every response: -``` -╔══════════════════════════════════════════════════════════════════╗ -║ 📋 PROJMAN ║ -║ ⚡ EXECUTION ║ -║ [Sprint Name] ║ -╚══════════════════════════════════════════════════════════════════╝ -``` +See `skills/visual-output.md` for header templates. Use the **Orchestrator** row from the Phase Registry: +- Phase Emoji: Lightning +- Phase Name: EXECUTION +- Context: Sprint Name -Progress block format: -``` -┌─ Sprint Progress ────────────────────────────────────────────────┐ -│ [Sprint Name] │ -│ ████████████░░░░░░░░░░░░░░░░░░ 40% complete │ -│ ✅ Done: 4 ⏳ Active: 2 ⬚ Pending: 4 │ -└──────────────────────────────────────────────────────────────────┘ -``` +Also use the Progress Block format from `skills/visual-output.md` during sprint execution. ## Your Responsibilities ### 1. Verify Approval (Sprint Start) -Execute `skills/sprint-approval.md` - Check milestone for approval record. +Execute `skills/sprint-approval.md` - Check milestone for approval record. **STOP execution if approval is missing** unless user provided `--force` flag. ### 2. Detect Checkpoints (Sprint Start) Check for resume points from interrupted sessions. @@ -105,6 +96,13 @@ Execute `skills/wiki-conventions.md` - Update implementation status. ### 10. Git Operations (Sprint Close) Execute `skills/git-workflow.md` - Merge, tag, clean up branches. +### 11. Maintain Dispatch Log +Execute `skills/progress-tracking.md` (Sprint Dispatch Log section): +- Create dispatch log header at sprint start +- Append row on every task dispatch, completion, failure, and domain gate check +- On sprint resume: add "Resumed" row with checkpoint context +- Log is posted as comments, one `add_comment` per event + ## Critical Reminders 1. **NEVER use CLI tools** - Use MCP tools exclusively (see `skills/mcp-tools-reference.md`) diff --git a/plugins/projman/agents/planner.md b/plugins/projman/agents/planner.md index 7224a6c..6094891 100644 --- a/plugins/projman/agents/planner.md +++ b/plugins/projman/agents/planner.md @@ -21,6 +21,8 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r - skills/planning-workflow.md - skills/label-taxonomy/labels-reference.md - skills/domain-consultation.md +- skills/sprint-lifecycle.md +- skills/visual-output.md ## Your Personality @@ -38,14 +40,10 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r ## Visual Output -Display header at start of every response: -``` -╔══════════════════════════════════════════════════════════════════╗ -║ 📋 PROJMAN ║ -║ 🎯 PLANNING ║ -║ [Sprint Name or Goal] ║ -╚══════════════════════════════════════════════════════════════════╝ -``` +See `skills/visual-output.md` for header templates. Use the **Planner** row from the Phase Registry: +- Phase Emoji: Target +- Phase Name: PLANNING +- Context: Sprint Name or Goal ## Your Responsibilities diff --git a/plugins/projman/claude-md-integration.md b/plugins/projman/claude-md-integration.md index 048fb7f..9d1d40b 100644 --- a/plugins/projman/claude-md-integration.md +++ b/plugins/projman/claude-md-integration.md @@ -12,11 +12,11 @@ This project uses the **projman** plugin for sprint planning and project managem | `/sprint-close` | Complete sprint and capture lessons learned to Gitea Wiki | | `/labels-sync` | Synchronize label taxonomy from Gitea | | `/initial-setup` | Run initial setup for projman plugin | -| `/rfc-create` | Create new RFC from conversation or clarified spec | -| `/rfc-list` | List all RFCs grouped by status | -| `/rfc-review` | Submit Draft RFC for review | -| `/rfc-approve` | Approve RFC for sprint planning | -| `/rfc-reject` | Reject RFC with documented reason | +| `/rfc create` | Create new RFC from conversation or clarified spec | +| `/rfc list` | List all RFCs grouped by status | +| `/rfc review` | Submit Draft RFC for review | +| `/rfc approve` | Approve RFC for sprint planning | +| `/rfc reject` | Reject RFC with documented reason | ### MCP Tools Available diff --git a/plugins/projman/commands/clear-cache.md b/plugins/projman/commands/clear-cache.md deleted file mode 100644 index cd68699..0000000 --- a/plugins/projman/commands/clear-cache.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: Clear plugin cache to force fresh configuration reload after marketplace updates ---- - -# Clear Cache - -## Purpose - -Clear plugin cache to force fresh configuration reload after marketplace updates. - -## When to Use - -- After updating the marketplace (`git pull` or reinstall) -- When MCP servers show stale configuration -- When plugin changes don't take effect - -## Workflow - -Execute cache clear: - -```bash -rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/ -``` - -Then inform user: "Cache cleared. Restart Claude Code for changes to take effect." - -## Visual Output - -``` -╔══════════════════════════════════════════════════════════════════╗ -║ 📋 PROJMAN ║ -║ Clear Cache ║ -╚══════════════════════════════════════════════════════════════════╝ -``` diff --git a/plugins/projman/commands/review.md b/plugins/projman/commands/review.md index 11102b8..fac445c 100644 --- a/plugins/projman/commands/review.md +++ b/plugins/projman/commands/review.md @@ -8,6 +8,7 @@ agent: code-reviewer ## Skills Required - skills/review-checklist.md +- skills/sprint-lifecycle.md ## Purpose @@ -19,6 +20,7 @@ Run `/review` before `/sprint-close` to catch issues. ## Workflow +0. **Check Lifecycle State** - Execute `skills/sprint-lifecycle.md` check protocol. Expect `Sprint/Executing`. Set `Sprint/Reviewing` after review begins. Warn if in wrong state (allow with `--force`). 1. **Determine Scope** - Sprint files or recent commits (`git diff --name-only HEAD~5`) 2. **Read Files** - Use Read tool for each file in scope 3. **Scan for Patterns** - Check each category from review checklist diff --git a/plugins/projman/commands/rfc-approve.md b/plugins/projman/commands/rfc-approve.md deleted file mode 100644 index 409c35a..0000000 --- a/plugins/projman/commands/rfc-approve.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: Approve an RFC in Review status, making it ready for sprint planning -agent: planner ---- - -# Approve RFC - -## Skills Required - -- skills/mcp-tools-reference.md -- skills/rfc-workflow.md -- skills/rfc-templates.md - -## Purpose - -Transition an RFC from Review to Approved status, indicating the proposal has been accepted and is ready for implementation in an upcoming sprint. - -## Invocation - -Run `/rfc-approve ` where number is the RFC number: -- `/rfc-approve 0003` -- `/rfc-approve 3` (leading zeros optional) - -## Workflow - -1. **Validate RFC Number** - - Normalize input (add leading zeros if needed) - - Fetch RFC page: `RFC-NNNN: *` - -2. **Check Current Status** - - Parse frontmatter to get current status - - **STOP** if status is not "Review" - - Error: "RFC-NNNN is in [status] status. Only RFCs in Review can be approved." - -3. **Gather Decision Details** - - Prompt: "Please provide the approval rationale (why is this RFC being approved?):" - - This becomes the Decision section content - -4. **Update RFC Page** - - Change status: Review → Approved - - Update "Updated" date - - Add/update Decision section: - ```markdown - ## Decision - - **Decision:** Approved - **Date:** YYYY-MM-DD - **Decided By:** @[current user or maintainer] - - **Rationale:** - - [User-provided rationale] - ``` - -5. **Update RFC-Index** - - Remove entry from "## In Review" section - - Add entry to "## Approved" section - -6. **Confirm Approval** - - Display updated status - - Note that RFC is now available for `/sprint-plan` - -## Visual Output - -``` -+----------------------------------------------------------------------+ -| PROJMAN - RFC Approval | -+----------------------------------------------------------------------+ - -RFC-0003: Feature X has been approved! - -Status: Review → Approved -Decision recorded in RFC page. - -This RFC is now available for sprint planning. -Use /sprint-plan and select this RFC when prompted. -``` - -## Validation Errors - -- **RFC not found**: "RFC-NNNN not found. Check the number with /rfc-list" -- **Wrong status**: "RFC-NNNN is [status]. Only RFCs in Review can be approved." -- **No rationale provided**: "Approval rationale is required. Please explain why this RFC is being approved." diff --git a/plugins/projman/commands/rfc-create.md b/plugins/projman/commands/rfc-create.md deleted file mode 100644 index 4545e8e..0000000 --- a/plugins/projman/commands/rfc-create.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -description: Create a new RFC (Request for Comments) from conversation or clarified specification -agent: planner ---- - -# Create RFC - -## Skills Required - -- skills/mcp-tools-reference.md -- skills/rfc-workflow.md -- skills/rfc-templates.md - -## Purpose - -Create a new RFC wiki page to track a feature idea, proposal, or enhancement through the review lifecycle. RFCs provide a structured way to document, discuss, and approve changes before implementation. - -## Invocation - -Run `/rfc-create` with optional context: -- After `/clarify` to convert clarified spec to RFC -- With description of feature idea -- From conversation context - -## Workflow - -1. **Gather Input** - - Check if conversation has clarified specification (from `/clarify`) - - If no context: prompt for Summary, Motivation, and initial Design - - Extract author from context or prompt - -2. **Allocate RFC Number** - - Call `allocate_rfc_number` MCP tool - - Get next sequential 4-digit number - -3. **Create RFC Page** - - Use template from `skills/rfc-templates.md` - - Fill in frontmatter (number, title, status=Draft, author, dates) - - Populate Summary, Motivation, Detailed Design sections - - Create wiki page: `RFC-NNNN: Title` - -4. **Update RFC-Index** - - Fetch RFC-Index (create if doesn't exist) - - Add entry to "## Draft" section - - Update wiki page - -5. **Confirm Creation** - - Display RFC number and wiki link - - Remind about next steps (refine → `/rfc-review`) - -## Visual Output - -``` -+----------------------------------------------------------------------+ -| PROJMAN - RFC Creation | -+----------------------------------------------------------------------+ - -RFC-0001: [Title] created successfully! - -Status: Draft -Wiki: [link to RFC page] - -Next steps: -- Refine the RFC with additional details -- When ready: /rfc-review 0001 to submit for review -``` - -## Input Mapping - -When converting from `/clarify` output: - -| Clarify Section | RFC Section | -|-----------------|-------------| -| Problem/Context | Motivation > Problem Statement | -| Goals/Outcomes | Motivation > Goals | -| Scope/Requirements | Detailed Design > Overview | -| Constraints | Non-Goals or Detailed Design | -| Success Criteria | Testing Strategy | - -## Edge Cases - -- **No RFC-Index exists**: Create it with empty sections -- **User provides minimal input**: Create minimal RFC template, note sections to fill -- **Duplicate title**: Proceed (RFC numbers are unique, titles don't need to be) diff --git a/plugins/projman/commands/rfc-list.md b/plugins/projman/commands/rfc-list.md deleted file mode 100644 index 10a57c5..0000000 --- a/plugins/projman/commands/rfc-list.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -description: List all RFCs grouped by status from RFC-Index wiki page -agent: planner ---- - -# List RFCs - -## Skills Required - -- skills/mcp-tools-reference.md -- skills/rfc-workflow.md - -## Purpose - -Display all RFCs grouped by their lifecycle status. Highlights "Approved" RFCs that are ready for sprint planning. - -## Invocation - -Run `/rfc-list` to see all RFCs. - -Optional filters: -- `/rfc-list approved` - Show only approved RFCs -- `/rfc-list draft` - Show only draft RFCs -- `/rfc-list review` - Show only RFCs in review - -## Workflow - -1. **Fetch RFC-Index** - - Call `get_wiki_page` for "RFC-Index" - - Handle missing index gracefully - -2. **Parse Sections** - - Extract tables from each status section - - Parse RFC number, title, and metadata from each row - -3. **Display Results** - - Group by status - - Highlight Approved section (ready for planning) - - Show counts per status - -## Visual Output - -``` -+----------------------------------------------------------------------+ -| PROJMAN - RFC Index | -+----------------------------------------------------------------------+ - -## Approved (Ready for Sprint Planning) - -| RFC | Title | Champion | Created | -|-----|-------|----------|---------| -| RFC-0003 | Feature X | @user | 2026-01-15 | -| RFC-0007 | Enhancement Y | @user | 2026-01-28 | - -## In Review (2) - -| RFC | Title | Author | Created | -|-----|-------|--------|---------| -| RFC-0004 | Feature Y | @user | 2026-01-20 | -| RFC-0008 | Idea Z | @user | 2026-01-29 | - -## Draft (3) - -| RFC | Title | Author | Created | -|-----|-------|--------|---------| -| RFC-0005 | Concept A | @user | 2026-01-22 | -| RFC-0009 | Proposal B | @user | 2026-01-30 | -| RFC-0010 | Sketch C | @user | 2026-01-30 | - -## Implementing (1) - -| RFC | Title | Sprint | Started | -|-----|-------|--------|---------| -| RFC-0002 | Feature W | Sprint 18 | 2026-01-22 | - -## Implemented (1) - -| RFC | Title | Completed | Release | -|-----|-------|-----------|---------| -| RFC-0001 | Initial Feature | 2026-01-10 | v5.0.0 | - -## Rejected (0) - -(none) - -## Stale (0) - -(none) - ---- -Total: 10 RFCs | 2 Approved | 1 Implementing -``` - -## Edge Cases - -- **No RFC-Index**: Display message "No RFCs yet. Create one with /rfc-create" -- **Empty sections**: Show "(none)" for empty status categories -- **Filter applied**: Only show matching section, still show total counts diff --git a/plugins/projman/commands/rfc-reject.md b/plugins/projman/commands/rfc-reject.md deleted file mode 100644 index 9cee144..0000000 --- a/plugins/projman/commands/rfc-reject.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -description: Reject an RFC with documented reason, marking it as declined -agent: planner ---- - -# Reject RFC - -## Skills Required - -- skills/mcp-tools-reference.md -- skills/rfc-workflow.md -- skills/rfc-templates.md - -## Purpose - -Transition an RFC to Rejected status with a documented reason. Rejected RFCs remain in the wiki for historical reference but are marked as declined. - -## Invocation - -Run `/rfc-reject ` where number is the RFC number: -- `/rfc-reject 0006` -- `/rfc-reject 6` (leading zeros optional) - -## Workflow - -1. **Validate RFC Number** - - Normalize input (add leading zeros if needed) - - Fetch RFC page: `RFC-NNNN: *` - -2. **Check Current Status** - - Parse frontmatter to get current status - - **STOP** if status is not "Draft" or "Review" - - Error: "RFC-NNNN is in [status] status. Only Draft or Review RFCs can be rejected." - -3. **Require Rejection Reason** - - Prompt: "Please provide the rejection reason (required):" - - **STOP** if no reason provided - - Error: "Rejection reason is required to document why this RFC was declined." - -4. **Update RFC Page** - - Change status: [current] → Rejected - - Update "Updated" date - - Add/update Decision section: - ```markdown - ## Decision - - **Decision:** Rejected - **Date:** YYYY-MM-DD - **Decided By:** @[current user or maintainer] - - **Reason:** - - [User-provided rejection reason] - ``` - -5. **Update RFC-Index** - - Remove entry from current section ("## Draft" or "## In Review") - - Add entry to "## Rejected" section with reason summary - -6. **Confirm Rejection** - - Display updated status - - Note that RFC remains in wiki for reference - -## Visual Output - -``` -+----------------------------------------------------------------------+ -| PROJMAN - RFC Rejection | -+----------------------------------------------------------------------+ - -RFC-0006: Proposed Feature has been rejected. - -Status: Review → Rejected -Reason: Out of scope for current project direction - -The RFC remains in the wiki for historical reference. -If circumstances change, a new RFC can be created. -``` - -## Validation Errors - -- **RFC not found**: "RFC-NNNN not found. Check the number with /rfc-list" -- **Wrong status**: "RFC-NNNN is [status]. Only Draft or Review RFCs can be rejected." -- **No reason provided**: "Rejection reason is required. Please document why this RFC is being declined." - -## Notes - -- Rejected is a terminal state -- To reconsider, create a new RFC that references the rejected one -- Rejection reasons help future contributors understand project direction diff --git a/plugins/projman/commands/rfc-review.md b/plugins/projman/commands/rfc-review.md deleted file mode 100644 index f706541..0000000 --- a/plugins/projman/commands/rfc-review.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -description: Submit a Draft RFC for review, transitioning status to Review -agent: planner ---- - -# Submit RFC for Review - -## Skills Required - -- skills/mcp-tools-reference.md -- skills/rfc-workflow.md -- skills/rfc-templates.md - -## Purpose - -Transition an RFC from Draft to Review status, indicating it's ready for maintainer evaluation. Optionally assign a champion to shepherd the RFC through review. - -## Invocation - -Run `/rfc-review ` where number is the RFC number: -- `/rfc-review 0001` -- `/rfc-review 1` (leading zeros optional) - -## Workflow - -1. **Validate RFC Number** - - Normalize input (add leading zeros if needed) - - Fetch RFC page: `RFC-NNNN: *` - -2. **Check Current Status** - - Parse frontmatter to get current status - - **STOP** if status is not "Draft" - - Error: "RFC-NNNN is in [status] status. Only Draft RFCs can be submitted for review." - -3. **Validate Minimum Content** - - Check for Summary section (required) - - Check for Motivation section (required) - - Check for Detailed Design > Overview (required) - - Warn if Alternatives Considered is empty - -4. **Optional: Assign Champion** - - Ask: "Would you like to assign a champion? (Enter username or skip)" - - Champion is responsible for driving the RFC through review - -5. **Update RFC Page** - - Change status: Draft → Review - - Update "Updated" date - - Set Champion if provided - - Add Review Notes section if not present - -6. **Update RFC-Index** - - Remove entry from "## Draft" section - - Add entry to "## In Review" section - -7. **Confirm Transition** - - Display updated status - - Note next steps (review discussion, then /rfc-approve or /rfc-reject) - -## Visual Output - -``` -+----------------------------------------------------------------------+ -| PROJMAN - RFC Review Submission | -+----------------------------------------------------------------------+ - -RFC-0005: Feature Idea submitted for review - -Status: Draft → Review -Champion: @assigned_user (or: unassigned) -Updated: RFC-Index - -Next steps: -- Discuss in RFC wiki page comments or meetings -- When decision reached: /rfc-approve 0005 or /rfc-reject 0005 -``` - -## Validation Errors - -- **RFC not found**: "RFC-NNNN not found. Check the number with /rfc-list" -- **Wrong status**: "RFC-NNNN is [status]. Only Draft RFCs can be reviewed." -- **Missing sections**: "RFC-NNNN is missing required sections: [list]. Please complete before review." diff --git a/plugins/projman/commands/rfc.md b/plugins/projman/commands/rfc.md new file mode 100644 index 0000000..75dcedc --- /dev/null +++ b/plugins/projman/commands/rfc.md @@ -0,0 +1,144 @@ +--- +description: RFC lifecycle management - create, list, review, approve, reject +agent: planner +--- + +# RFC Management + +## Skills Required + +- skills/mcp-tools-reference.md +- skills/rfc-workflow.md +- skills/rfc-templates.md + +## Purpose + +Manage the full RFC lifecycle through sub-commands. RFCs provide a structured way to document, discuss, and approve changes before implementation. + +## Invocation + +``` +/rfc [arguments] +``` + +### Sub-Commands + +| Sub-Command | Usage | Description | +|-------------|-------|-------------| +| `create` | `/rfc create` | Create new RFC from conversation or clarified spec | +| `list` | `/rfc list [filter]` | List all RFCs grouped by status | +| `review` | `/rfc review ` | Submit Draft RFC for review | +| `approve` | `/rfc approve ` | Approve RFC in Review status | +| `reject` | `/rfc reject ` | Reject RFC with documented reason | + +--- + +## Sub-Command: create + +Create a new RFC wiki page to track a feature idea through the review lifecycle. + +**Workflow:** +1. Check if conversation has clarified specification (from `/clarify`) +2. If no context: prompt for Summary, Motivation, and initial Design +3. Call `allocate_rfc_number` MCP tool for next sequential number +4. Create RFC page using template from `skills/rfc-templates.md` +5. Update RFC-Index wiki page (create if doesn't exist) +6. Display RFC number, wiki link, and next steps + +**Input Mapping (from /clarify):** + +| Clarify Section | RFC Section | +|-----------------|-------------| +| Problem/Context | Motivation > Problem Statement | +| Goals/Outcomes | Motivation > Goals | +| Scope/Requirements | Detailed Design > Overview | +| Constraints | Non-Goals or Detailed Design | +| Success Criteria | Testing Strategy | + +**Edge cases:** +- No RFC-Index exists: Create it with empty sections +- User provides minimal input: Create minimal RFC template, note sections to fill +- Duplicate title: Proceed (RFC numbers are unique, titles don't need to be) + +--- + +## Sub-Command: list + +Display all RFCs grouped by lifecycle status. + +**Filters:** `/rfc list approved`, `/rfc list draft`, `/rfc list review` + +**Workflow:** +1. Fetch RFC-Index wiki page via `get_wiki_page` +2. Parse tables from each status section +3. Display grouped by status, highlight Approved section +4. Show counts per status + +**Edge cases:** +- No RFC-Index: "No RFCs yet. Create one with `/rfc create`" +- Empty sections: Show "(none)" + +--- + +## Sub-Command: review + +Submit a Draft RFC for review, transitioning status to Review. + +**Usage:** `/rfc review ` (leading zeros optional) + +**Workflow:** +1. Validate RFC number, fetch page +2. Check status is Draft - STOP if not +3. Validate minimum content (Summary, Motivation, Detailed Design > Overview required) +4. Optionally assign champion +5. Update RFC page: status Draft -> Review, update date +6. Update RFC-Index: move from Draft to In Review section + +--- + +## Sub-Command: approve + +Approve an RFC in Review status for sprint planning. + +**Usage:** `/rfc approve ` (leading zeros optional) + +**Workflow:** +1. Validate RFC number, fetch page +2. Check status is Review - STOP if not +3. Gather approval rationale (required) +4. Update RFC page: status Review -> Approved, add Decision section +5. Update RFC-Index: move from In Review to Approved section + +--- + +## Sub-Command: reject + +Reject an RFC with documented reason. + +**Usage:** `/rfc reject ` (leading zeros optional) + +**Workflow:** +1. Validate RFC number, fetch page +2. Check status is Draft or Review - STOP if not +3. Require rejection reason (mandatory) +4. Update RFC page: status -> Rejected, add Decision section +5. Update RFC-Index: move to Rejected section + +--- + +## Visual Output + +``` ++----------------------------------------------------------------------+ +| PROJMAN - RFC [Sub-Command] | ++----------------------------------------------------------------------+ +``` + +--- + +## Validation Errors (All Sub-Commands) + +- **RFC not found**: "RFC-NNNN not found. Check the number with `/rfc list`" +- **Wrong status**: "RFC-NNNN is in [status] status. [Specific allowed statuses for this action]." +- **Missing required input**: Specific message per sub-command +- **No sub-command provided**: Display sub-command reference table diff --git a/plugins/projman/commands/setup.md b/plugins/projman/commands/setup.md index 77322cf..ac70dd4 100644 --- a/plugins/projman/commands/setup.md +++ b/plugins/projman/commands/setup.md @@ -26,6 +26,7 @@ Unified setup command for all configuration needs. /setup --full # Full wizard (MCP + system + project) /setup --quick # Project-only setup /setup --sync # Update after repo move +/setup --clear-cache # Clear plugin cache (between sessions only) ``` ## Mode Detection @@ -79,6 +80,21 @@ Steps: 6. Update `.env` 7. Confirm +## Mode: Clear Cache (--clear-cache) + +Clear plugin cache to force fresh configuration reload. + +**WARNING:** Only run between sessions, never mid-session. Clearing cache mid-session destroys MCP tool venv paths and breaks all MCP operations. + +Steps: +1. Execute: `rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/` +2. Inform user: "Cache cleared. Restart Claude Code for changes to take effect." + +When to use: +- After updating the marketplace (`git pull` or reinstall) +- When MCP servers show stale configuration +- When plugin changes don't take effect + ## Visual Output ``` diff --git a/plugins/projman/commands/sprint-close.md b/plugins/projman/commands/sprint-close.md index dbb25c7..b8d4f30 100644 --- a/plugins/projman/commands/sprint-close.md +++ b/plugins/projman/commands/sprint-close.md @@ -13,6 +13,7 @@ agent: orchestrator - skills/rfc-workflow.md - skills/progress-tracking.md - skills/git-workflow.md +- skills/sprint-lifecycle.md ## Purpose @@ -26,6 +27,7 @@ Run `/sprint-close` when sprint work is complete. Execute the sprint close workflow: +0. **Check Lifecycle State** - Execute `skills/sprint-lifecycle.md` check protocol. Expect `Sprint/Reviewing`. Clear all Sprint/* labels (return to idle) at the END of close workflow, after all other steps. Warn if in wrong state (allow with `--force`). 1. **Review Sprint Completion** - Verify issues closed or moved to backlog 2. **Capture Lessons Learned** - Interview user about challenges and insights 3. **Tag for Discoverability** - Apply technology, component, and pattern tags diff --git a/plugins/projman/commands/sprint-plan.md b/plugins/projman/commands/sprint-plan.md index 9bda12d..31e1ffd 100644 --- a/plugins/projman/commands/sprint-plan.md +++ b/plugins/projman/commands/sprint-plan.md @@ -18,6 +18,7 @@ agent: planner - skills/sprint-approval.md - skills/planning-workflow.md - skills/label-taxonomy/labels-reference.md +- skills/sprint-lifecycle.md ## Purpose @@ -35,6 +36,7 @@ Provide sprint goals as natural language input, or prepare input via: Execute the planning workflow as defined in `skills/planning-workflow.md`. **Key steps:** +0. **Check Lifecycle State** - Execute `skills/sprint-lifecycle.md` check protocol. Expect idle state. Set `Sprint/Planning` after planning completes. Warn and stop if sprint is in another active state (unless `--force`). 1. Run pre-planning validations (branch, repo org, labels) 2. Detect input source (file, wiki, or conversation) 3. Search relevant lessons learned diff --git a/plugins/projman/commands/sprint-start.md b/plugins/projman/commands/sprint-start.md index 4e0a37a..6af22ac 100644 --- a/plugins/projman/commands/sprint-start.md +++ b/plugins/projman/commands/sprint-start.md @@ -15,6 +15,7 @@ agent: orchestrator - skills/git-workflow.md - skills/progress-tracking.md - skills/runaway-detection.md +- skills/sprint-lifecycle.md ## Purpose @@ -24,11 +25,14 @@ Initiate sprint execution. The orchestrator agent verifies approval, analyzes de Run `/sprint-start` when ready to begin executing a planned sprint. +**Flags:** +- `--force` — Bypass approval gate (emergency only, logged to milestone) + ## Workflow Execute the sprint start workflow: -1. **Verify Sprint Approval** (recommended) - Check milestone for approval record +1. **Verify Sprint Approval & Lifecycle State** (required) - Check milestone for approval record. STOP if missing unless `--force` flag provided. Also verify lifecycle state is `Sprint/Planning` per `skills/sprint-lifecycle.md`. Set `Sprint/Executing` after verification passes. 2. **Detect Checkpoints** - Check for resume points from interrupted sessions 3. **Fetch Sprint Issues** - Get open issues from milestone 4. **Analyze Dependencies** - Use `get_execution_order` for parallel batches diff --git a/plugins/projman/commands/sprint-status.md b/plugins/projman/commands/sprint-status.md index c409eb9..e55525e 100644 --- a/plugins/projman/commands/sprint-status.md +++ b/plugins/projman/commands/sprint-status.md @@ -9,6 +9,7 @@ description: Check current sprint progress, identify blockers, optionally genera - skills/mcp-tools-reference.md - skills/progress-tracking.md - skills/dependency-management.md +- skills/sprint-lifecycle.md ## Purpose @@ -23,6 +24,7 @@ Check current sprint progress, identify blockers, and show execution status. Opt ## Workflow +0. **Display Lifecycle State** - Read current Sprint/* state from milestone description per `skills/sprint-lifecycle.md` and display in output header. 1. **Fetch Sprint Issues** - Get all issues for current milestone 2. **Calculate Progress** - Count completed vs total issues 3. **Identify Active Tasks** - Find issues with `Status/In-Progress` diff --git a/plugins/projman/commands/test.md b/plugins/projman/commands/test.md index cc5925f..2df4020 100644 --- a/plugins/projman/commands/test.md +++ b/plugins/projman/commands/test.md @@ -93,6 +93,78 @@ Generate comprehensive tests for specified code. See `skills/test-standards.md` for test patterns and structure. +### DO NOT (Generate Mode) + +- Install dependencies without asking first +- Generate tests that import private/internal functions not meant for testing +- Overwrite existing test files without confirmation +- Generate tests with hardcoded values that should be environment-based + +--- + +## Sprint Integration + +The `/test` command plays a critical role in the sprint close workflow: + +1. After `/review` identifies code quality issues +2. Before `/sprint-close` finalizes the sprint +3. The code reviewer and orchestrator reference test results when deciding if a sprint is ready to close + +### Pre-Close Verification + +When running `/test run` before sprint close: + +1. **Identify sprint files** - Files changed in the current sprint (via git diff against development) +2. **Check test coverage** - Report which sprint files have tests and which don't +3. **Flag untested code** - Warn if new code has no corresponding tests +4. **Recommend action** - "READY FOR CLOSE" or "TESTS NEEDED: [list of untested files]" + +--- + +## Examples + +### Run all tests +``` +/test run +``` +Detects framework, runs full test suite, reports results. + +### Run with coverage +``` +/test run --coverage +``` +Same as above plus coverage percentage per file. + +### Generate tests for a specific file +``` +/test gen src/auth/jwt_service.py +``` +Analyzes the file, generates a test file at `tests/test_jwt_service.py`. + +### Generate specific test type +``` +/test gen src/api/routes/auth.py --type=integration +``` +Generates integration tests (request/response patterns) instead of unit tests. + +### Generate with specific framework +``` +/test gen src/components/Card.jsx --framework=vitest +``` +Uses Vitest instead of auto-detected framework. + +--- + +## Edge Cases + +| Scenario | Behavior | +|----------|----------| +| No test framework detected | List what was checked, ask user to specify test command | +| Tests fail | Report failures clearly, recommend "TESTS MUST PASS before sprint close" | +| No tests exist for sprint files | Warn with file list, offer to generate with `/test gen` | +| External services required | Ask for confirmation before running tests that need database/API | +| Mixed framework project | Detect all frameworks, ask which to run or run all | + --- ## Visual Output diff --git a/plugins/projman/skills/domain-consultation.md b/plugins/projman/skills/domain-consultation.md index 4f7c229..2ed817d 100644 --- a/plugins/projman/skills/domain-consultation.md +++ b/plugins/projman/skills/domain-consultation.md @@ -154,10 +154,12 @@ This pattern ensures domain expertise stays in domain plugins while projman orch ## Gate Command Reference -| Domain | Gate Command | Review Command | Advisory Agent | -|--------|--------------|----------------|----------------| -| Viz | `/design-gate ` | `/design-review ` | `design-reviewer` | -| Data | `/data-gate ` | `/data-review ` | `data-advisor` | +| Domain | Gate Command | Contract | Review Command | Advisory Agent | +|--------|--------------|----------|----------------|----------------| +| Viz | `/design-gate ` | v1 | `/design-review ` | `design-reviewer` | +| Data | `/data-gate ` | v1 | `/data-review ` | `data-advisor` | Gate commands return binary PASS/FAIL for automation. Review commands return detailed reports for human review. + +**Contract Version:** Gate commands declare `gate_contract: vN` in their frontmatter. The version in this table is what projman expects. If a gate command bumps its contract version, this table must be updated to match. The `contract-validator` plugin checks this automatically via `validate_workflow_integration`. diff --git a/plugins/projman/skills/label-taxonomy/labels-reference.md b/plugins/projman/skills/label-taxonomy/labels-reference.md index 0c73786..2dbdb4e 100644 --- a/plugins/projman/skills/label-taxonomy/labels-reference.md +++ b/plugins/projman/skills/label-taxonomy/labels-reference.md @@ -90,6 +90,18 @@ Repository-level labels are specific to each project. - `Tech/Vue` (#42b883) - Vue.js frontend framework - `Tech/FastAPI` (#009688) - FastAPI backend framework +### Sprint Lifecycle (Milestone Metadata) + +These are tracked as milestone description metadata, not as Gitea issue labels. They are documented here for completeness. + +| Label | Description | +|-------|-------------| +| `Sprint/Planning` | Sprint planning in progress | +| `Sprint/Executing` | Sprint execution in progress | +| `Sprint/Reviewing` | Code review in progress | + +**Note:** Lifecycle state is stored in milestone description as `**Sprint State:** Sprint/Executing`. See `skills/sprint-lifecycle.md` for state machine rules. + ### Domain (2 labels) Cross-plugin integration labels for domain-specific validation gates. diff --git a/plugins/projman/skills/progress-tracking.md b/plugins/projman/skills/progress-tracking.md index 0e07d85..2d89bf3 100644 --- a/plugins/projman/skills/progress-tracking.md +++ b/plugins/projman/skills/progress-tracking.md @@ -138,6 +138,49 @@ For resume support, save checkpoints after major steps: --- +## Sprint Dispatch Log + +A single structured comment on the sprint milestone that records all task dispatches and completions. This is the first place to look when resuming an interrupted sprint. + +### Format + +Post as a comment on the milestone (via `add_comment` on a pinned tracking issue, or as milestone description appendix): + +```markdown +## Sprint Dispatch Log + +| Time | Issue | Action | Agent | Branch | Notes | +|------|-------|--------|-------|--------|-------| +| 14:30 | #45 | Dispatched | Executor | feat/45-jwt | Parallel batch 1 | +| 14:30 | #46 | Dispatched | Executor | feat/46-login | Parallel batch 1 | +| 14:45 | #45 | Complete | Executor | feat/45-jwt | 47 tool calls, merged | +| 14:52 | #46 | Failed | Executor | feat/46-login | Auth test failure | +| 14:53 | #46 | Re-dispatched | Executor | feat/46-login | After fix | +| 15:10 | #46 | Complete | Executor | feat/46-login | 62 tool calls, merged | +| 15:10 | #47 | Dispatched | Executor | feat/47-tests | Batch 2 (depended on #45, #46) | +``` + +### When to Log + +| Event | Action Column | Required Fields | +|-------|---------------|-----------------| +| Task dispatched to executor | `Dispatched` | Time, Issue, Branch, Batch info | +| Task completed | `Complete` | Time, Issue, Tool call count | +| Task failed | `Failed` | Time, Issue, Error summary | +| Task re-dispatched | `Re-dispatched` | Time, Issue, Reason | +| Domain gate checked | `Gate: PASS` or `Gate: FAIL` | Time, Issue, Domain | +| Sprint resumed | `Resumed` | Time, Notes (from checkpoint) | + +### Implementation + +The orchestrator appends rows to this log via `add_comment` on the first issue in the milestone (or a dedicated tracking issue). Each append is a single `add_comment` call updating the table. + +**On sprint start:** Create the dispatch log header. +**On each event:** Append a row. +**On sprint resume:** Add a "Resumed" row with checkpoint context. + +--- + ## Sprint Progress Display ``` diff --git a/plugins/projman/skills/rfc-templates.md b/plugins/projman/skills/rfc-templates.md index 9c0b1c9..974d4f6 100644 --- a/plugins/projman/skills/rfc-templates.md +++ b/plugins/projman/skills/rfc-templates.md @@ -11,7 +11,7 @@ Provides templates for RFC wiki pages and defines the required/optional sections ## When to Use -- **Commands**: `/rfc-create` when generating new RFC pages +- **Commands**: `/rfc create` when generating new RFC pages - **Integration**: Referenced by `rfc-workflow.md` for page structure --- diff --git a/plugins/projman/skills/rfc-workflow.md b/plugins/projman/skills/rfc-workflow.md index 5cf609d..ea6b570 100644 --- a/plugins/projman/skills/rfc-workflow.md +++ b/plugins/projman/skills/rfc-workflow.md @@ -12,7 +12,7 @@ Defines the Request for Comments (RFC) system for capturing, reviewing, and trac ## When to Use - **Planner agent**: When detecting approved RFCs for sprint planning -- **Commands**: `/rfc-create`, `/rfc-list`, `/rfc-review`, `/rfc-approve`, `/rfc-reject` +- **Commands**: `/rfc create`, `/rfc list`, `/rfc review`, `/rfc approve`, `/rfc reject` - **Integration**: With `/sprint-plan` to select approved RFCs for implementation --- @@ -298,11 +298,11 @@ When RFC status changes: | Component | How It Uses RFC System | |-----------|------------------------| -| `/rfc-create` | Creates RFC page + updates RFC-Index | -| `/rfc-list` | Reads and displays RFC-Index | -| `/rfc-review` | Transitions Draft → Review | -| `/rfc-approve` | Transitions Review → Approved | -| `/rfc-reject` | Transitions Review/Draft → Rejected | +| `/rfc create` | Creates RFC page + updates RFC-Index | +| `/rfc list` | Reads and displays RFC-Index | +| `/rfc review` | Transitions Draft -> Review | +| `/rfc approve` | Transitions Review -> Approved | +| `/rfc reject` | Transitions Review/Draft -> Rejected | | `/sprint-plan` | Detects Approved RFCs, transitions to Implementing | -| `/sprint-close` | Transitions Implementing → Implemented | -| `clarity-assist` | Suggests `/rfc-create` for feature ideas | +| `/sprint-close` | Transitions Implementing -> Implemented | +| `clarity-assist` | Suggests `/rfc create` for feature ideas | diff --git a/plugins/projman/skills/sprint-approval.md b/plugins/projman/skills/sprint-approval.md index 0a886e4..d218123 100644 --- a/plugins/projman/skills/sprint-approval.md +++ b/plugins/projman/skills/sprint-approval.md @@ -84,15 +84,17 @@ get_milestone(repo="org/repo", milestone_id=17) ### If Approval Missing ``` -⚠️ SPRINT APPROVAL NOT FOUND (Warning) +🔴 SPRINT APPROVAL NOT FOUND — BLOCKED Sprint 17 milestone does not contain an approval record. +Execution cannot proceed without approval. -Recommended: Run /sprint-plan first to: +Required: Run /sprint-plan first to: 1. Review the sprint scope -2. Document the approved execution plan +2. Get explicit approval for execution -Proceeding anyway - consider adding approval for audit trail. +To override (emergency only): /sprint-start --force +This bypasses the approval gate and logs a warning to the milestone. ``` ### If Approval Found @@ -134,3 +136,16 @@ Request re-approval when: - Scope expansion needed (new files, new branches) - Dependencies change significantly - Timeline changes require scope adjustment + +--- + +## Force Override + +The `--force` flag bypasses the approval gate for emergency situations. + +When `--force` is used: +1. Log a warning comment on the milestone: "⚠️ Sprint started without approval via --force on [date]" +2. Proceed with execution +3. The sprint close will flag this as an audit concern + +**Do NOT use --force** as standard practice. If you find yourself using it regularly, the planning workflow needs adjustment. diff --git a/plugins/projman/skills/sprint-lifecycle.md b/plugins/projman/skills/sprint-lifecycle.md new file mode 100644 index 0000000..f36f082 --- /dev/null +++ b/plugins/projman/skills/sprint-lifecycle.md @@ -0,0 +1,104 @@ +--- +name: sprint-lifecycle +description: Sprint lifecycle state machine using milestone labels +--- + +# Sprint Lifecycle + +## Purpose + +Defines the valid sprint lifecycle states and transitions, enforced via labels on the sprint milestone. Each projman command checks the current state before executing and updates it on completion. + +## When to Use + +- **All sprint commands**: Check state on entry, update on exit +- **Sprint status**: Display current lifecycle state + +--- + +## State Machine + +``` +idle -> Sprint/Planning -> Sprint/Executing -> Sprint/Reviewing -> idle + (sprint-plan) (sprint-start) (review) (sprint-close) +``` + +## State Labels + +| Label | Set By | Meaning | +|-------|--------|---------| +| *(no Sprint/* label)* | `/sprint-close` or initial state | Idle - no active sprint phase | +| `Sprint/Planning` | `/sprint-plan` | Planning in progress | +| `Sprint/Executing` | `/sprint-start` | Execution in progress | +| `Sprint/Reviewing` | `/review` | Code review in progress | + +**Rule:** Only ONE `Sprint/*` label may exist on a milestone at a time. Setting a new one removes the previous one. + +--- + +## State Transition Rules + +| Command | Expected State | Sets State | On Wrong State | +|---------|---------------|------------|----------------| +| `/sprint-plan` | idle (no Sprint/* label) | `Sprint/Planning` | Warn: "Sprint is in [state]. Run `/sprint-close` first or use `--force` to re-plan." Allow with `--force`. | +| `/sprint-start` | `Sprint/Planning` | `Sprint/Executing` | Warn: "Expected Sprint/Planning state but found [state]. Run `/sprint-plan` first or use `--force`." Allow with `--force`. | +| `/review` | `Sprint/Executing` | `Sprint/Reviewing` | Warn: "Expected Sprint/Executing state but found [state]." Allow with `--force`. | +| `/sprint-close` | `Sprint/Reviewing` | Remove all Sprint/* labels (idle) | Warn: "Expected Sprint/Reviewing state but found [state]. Run `/review` first or use `--force`." Allow with `--force`. | +| `/sprint-status` | Any | No change (read-only) | Display current state in output. | + +--- + +## Checking State (Protocol) + +At command entry, before any other work: + +1. Fetch the active milestone using `get_milestone` +2. Check milestone description for `**Sprint State:**` line +3. Compare against expected state for this command +4. If mismatch: display warning with guidance, STOP unless `--force` provided +5. If match: proceed and update state after command completes its primary work + +**Implementation:** Use milestone description metadata. Add/update a line: +``` +**Sprint State:** Sprint/Executing +``` + +This avoids needing actual Gitea labels on milestones (which may not be supported). Parse this line to check state, update it to set state. + +--- + +## Setting State + +After command completes successfully: + +1. Fetch current milestone description +2. If `**Sprint State:**` line exists, replace it +3. If not, append it to the end of the description +4. Update milestone via `update_milestone` + +**Format:** `**Sprint State:** ` where state is one of: +- `Sprint/Planning` +- `Sprint/Executing` +- `Sprint/Reviewing` +- (empty/removed for idle) + +--- + +## Displaying State + +In `/sprint-status` output, include: + +``` +Sprint Phase: Executing (since 2026-02-01) +``` + +Parse the milestone description for the `**Sprint State:**` line and display it prominently. + +--- + +## Edge Cases + +- **No active milestone**: State is implicitly `idle` +- **Multiple milestones**: Use the open/active milestone. If multiple open, use the most recent. +- **Milestone has no state line**: Treat as `idle` +- **`--force` used**: Log to milestone: "Warning: Lifecycle state override: [command] forced from [actual] state on [date]" diff --git a/plugins/projman/skills/visual-output.md b/plugins/projman/skills/visual-output.md new file mode 100644 index 0000000..80dd16a --- /dev/null +++ b/plugins/projman/skills/visual-output.md @@ -0,0 +1,101 @@ +--- +name: visual-output +description: Standard visual formatting for projman commands and agents +--- + +# Visual Output Standards + +## Purpose + +Single source of truth for all projman visual headers, progress blocks, and verdict formats. All agents and commands reference this skill instead of defining their own templates. + +--- + +## Plugin Header (Double-Line) + +Projman uses the double-line box drawing header style with emoji phase indicators. + +### Agent Headers + +``` ++----------------------------------------------------------------------+ +| PROJMAN | +| [Phase Emoji] [PHASE NAME] | +| [Context Line] | ++----------------------------------------------------------------------+ +``` + +### Phase Registry + +| Agent | Phase Emoji | Phase Name | Context | +|-------|-------------|------------|---------| +| Planner | Target | PLANNING | Sprint Name or Goal | +| Orchestrator | Lightning | EXECUTION | Sprint Name | +| Executor | Wrench | IMPLEMENTING | Issue Title | +| Code Reviewer | Magnifier | REVIEW | Sprint Name | + +### Command Headers (Non-Agent) + +For commands that don't invoke a specific agent phase: + +| Command | Phase Emoji | Phase Name | +|---------|-------------|------------| +| `/sprint-status` | Chart | STATUS | +| `/setup` | Gear | SETUP | +| `/debug` | Bug | DEBUG | +| `/labels-sync` | Label | LABELS | +| `/suggest-version` | Package | VERSION | +| `/proposal-status` | Clipboard | PROPOSALS | +| `/test` | Flask | TEST | +| `/rfc` | Document | RFC [Sub-Command] | + +--- + +## Progress Block + +Used by orchestrator during sprint execution: + +``` ++-- Sprint Progress -------------------------------------------------------+ +| [Sprint Name] | +| [Progress bar] XX% complete | +| Done: X Active: X Pending: X | ++--------------------------------------------------------------------------+ +``` + +--- + +## Sprint Close Summary + +``` ++----------------------------------------------------------------------+ +| PROJMAN | +| Finish Flag CLOSING | +| [Sprint Name] | ++----------------------------------------------------------------------+ +``` + +--- + +## Gate Verdict Format + +For domain gate results displayed by orchestrator: + +``` ++-- Domain Gate: [Viz/Data] -----------------------------------------------+ +| Status: PASS / FAIL | +| [Details if FAIL] | ++--------------------------------------------------------------------------+ +``` + +--- + +## Status Indicators + +| Indicator | Meaning | +|-----------|---------| +| Check | Complete / Pass | +| X | Failed / Blocked | +| Hourglass | In progress | +| Empty box | Pending / Not started | +| Warning | Warning | diff --git a/plugins/viz-platform/commands/design-gate.md b/plugins/viz-platform/commands/design-gate.md index c5cb418..127e737 100644 --- a/plugins/viz-platform/commands/design-gate.md +++ b/plugins/viz-platform/commands/design-gate.md @@ -1,5 +1,6 @@ --- description: Design system compliance gate (pass/fail) for sprint execution +gate_contract: v1 arguments: - name: path description: File or directory to validate