1 Commits

Author SHA1 Message Date
249f8794ad feat(projman): add domain gate checks to orchestrator agent
Add domain-consultation skill and gate check responsibilities to the
orchestrator agent. Before marking issues complete, the orchestrator
now checks for Domain/* labels and invokes the appropriate gate command
(/design-gate for Domain/Viz, /data-gate for Domain/Data).

Includes graceful degradation when gate commands are unavailable.

Closes #362

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-01 18:11:58 -05:00
54 changed files with 555 additions and 3305 deletions

View File

@@ -6,7 +6,7 @@
}, },
"metadata": { "metadata": {
"description": "Project management plugins with Gitea and NetBox integrations", "description": "Project management plugins with Gitea and NetBox integrations",
"version": "5.8.0" "version": "5.5.0"
}, },
"plugins": [ "plugins": [
{ {
@@ -155,7 +155,7 @@
}, },
{ {
"name": "data-platform", "name": "data-platform",
"version": "1.3.0", "version": "1.2.0",
"description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration", "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
"source": "./plugins/data-platform", "source": "./plugins/data-platform",
"author": { "author": {

View File

@@ -1,249 +0,0 @@
# 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

View File

@@ -1,27 +0,0 @@
# 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

1
.env
View File

@@ -1 +0,0 @@
GITEA_REPO=personal-projects/leo-claude-mktplace

View File

@@ -4,109 +4,6 @@ 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/). 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
- **contract-validator**: New `validate_workflow_integration` MCP tool — validates domain plugins expose required advisory interfaces (gate command, review command, advisory agent)
- **contract-validator**: New `MISSING_INTEGRATION` issue type for workflow integration validation
### Fixed
- `scripts/setup.sh` banner version updated from v5.1.0 to v5.7.1
### Reverted
- **marketplace.json**: Removed `integrates_with` field — Claude Code schema does not support custom plugin fields (causes marketplace load failure)
---
## [5.7.0] - 2026-02-02
### Added
- **data-platform**: New `data-advisor` agent for data integrity, schema, and dbt compliance validation
- **data-platform**: New `data-integrity-audit.md` skill defining audit rules, severity levels, and scanning strategies
- **data-platform**: New `/data-gate` command for binary pass/fail data integrity gates (projman integration)
- **data-platform**: New `/data-review` command for comprehensive data integrity audits
### Changed
- Domain Advisory Pattern now fully operational for both Viz and Data domains
- projman orchestrator `Domain/Data` gates now resolve to live `/data-gate` command (previously fell through to "gate unavailable" warning)
---
## [5.6.0] - 2026-02-01
### Added
- **Domain Advisory Pattern**: Cross-plugin integration enabling projman to consult domain-specific plugins during sprint lifecycle
- **projman**: New `domain-consultation.md` skill for domain detection and gate protocols
- **viz-platform**: New `design-reviewer` agent for design system compliance auditing
- **viz-platform**: New `design-system-audit.md` skill defining audit rules and severity levels
- **viz-platform**: New `/design-review` command for detailed design system audits
- **viz-platform**: New `/design-gate` command for binary pass/fail validation gates
- **Labels**: New `Domain/Viz` and `Domain/Data` labels for domain routing
### Changed
- **projman planner**: Now loads domain-consultation skill and performs domain detection during planning
- **projman orchestrator**: Now runs domain gates before marking Domain/* labeled issues as complete
---
## [5.5.0] - 2026-02-01 ## [5.5.0] - 2026-02-01
### Added ### Added

View File

@@ -1,4 +1,4 @@
# Leo Claude Marketplace - v5.8.0 # Leo Claude Marketplace - v5.5.0
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. 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) - Branch-aware security (development/staging/production)
- Pre-sprint-close code quality review and test verification - 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`, `/rfc` **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`
#### [git-flow](./plugins/git-flow) *NEW in v3.0.0* #### [git-flow](./plugins/git-flow) *NEW in v3.0.0*
**Git Workflow Automation** **Git Workflow Automation**
@@ -138,22 +138,7 @@ Visualization toolkit with version-locked component validation and design token
- 5 Page tools for multi-page app structure - 5 Page tools for multi-page app structure
- Dual theme storage: user-level and project-level - Dual theme storage: user-level and project-level
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/design-review`, `/design-gate`, `/initial-setup` **Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/initial-setup`
## Domain Advisory Pattern
The marketplace supports cross-plugin domain advisory integration:
- **Domain Detection**: projman automatically detects when issues involve specialized domains (frontend/viz, data engineering)
- **Acceptance Criteria**: Domain-specific acceptance criteria are added to issues during planning
- **Execution Gates**: Domain validation gates (`/design-gate`, `/data-gate`) run before issue completion
- **Extensible**: New domains can be added by creating advisory agents and gate commands
**Current Domains:**
| Domain | Plugin | Gate Command |
|--------|--------|--------------|
| Visualization | viz-platform | `/design-gate` |
| Data | data-platform | `/data-gate` |
## MCP Servers ## MCP Servers
@@ -215,7 +200,7 @@ Cross-plugin compatibility validation tools.
| Category | Tools | | Category | Tools |
|----------|-------| |----------|-------|
| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | | Parse | `parse_plugin_interface`, `parse_claude_md_agents` |
| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow`, `validate_workflow_integration` | | Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` |
| Report | `generate_compatibility_report`, `list_issues` | | Report | `generate_compatibility_report`, `list_issues` |
## Installation ## Installation

View File

@@ -9,18 +9,23 @@ Quick reference for all commands in the Leo Claude Marketplace.
| Plugin | Command | Auto | Manual | Description | | Plugin | Command | Auto | Manual | Description |
|--------|---------|:----:|:------:|-------------| |--------|---------|:----:|:------:|-------------|
| **projman** | `/sprint-plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation | | **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 (requires approval or `--force`) | | **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination |
| **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) | | **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** | `/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 <target>`) | | **projman** | `/test` | | X | Run tests (`/test run`) or generate tests (`/test gen <target>`) |
| **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki | | **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
| **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea | | **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
| **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` | | **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync` |
| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/setup --sync` | | **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** | `/debug` | | X | Diagnostics (`/debug report`) or investigate (`/debug review`) |
| **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump | | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
| **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status | | **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
| **projman** | `/rfc` | | X | RFC lifecycle management (`/rfc create\|list\|review\|approve\|reject`) | | **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 |
| **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message | | **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-push` | | X | Commit and push to remote in one operation |
| **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch | | **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch |
@@ -87,11 +92,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
| **viz-platform** | `/chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido | | **viz-platform** | `/chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
| **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) | | **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
| **viz-platform** | `/breakpoints` | | X | Configure responsive layout breakpoints | | **viz-platform** | `/breakpoints` | | X | Configure responsive layout breakpoints |
| **viz-platform** | `/design-review` | | X | Detailed design system audits |
| **viz-platform** | `/design-gate` | | X | Binary pass/fail design system validation gates |
| **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) | | **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) |
| **data-platform** | `/data-review` | | X | Comprehensive data integrity audits |
| **data-platform** | `/data-gate` | | X | Binary pass/fail data integrity gates |
| **contract-validator** | `/validate-contracts` | | X | Full marketplace compatibility validation | | **contract-validator** | `/validate-contracts` | | X | Full marketplace compatibility validation |
| **contract-validator** | `/check-agent` | | X | Validate single agent definition | | **contract-validator** | `/check-agent` | | X | Validate single agent definition |
| **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces | | **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces |
@@ -139,11 +140,11 @@ Full workflow from idea to implementation using RFCs:
``` ```
1. /clarify # Clarify the feature idea 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 ... ... refine RFC content ...
3. /rfc review 0001 # Submit RFC for review 3. /rfc-review 0001 # Submit RFC for review
... review discussion ... ... 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 5. /sprint-plan # Select approved RFC for sprint
... implement feature ... ... implement feature ...
6. /sprint-close # Complete sprint, RFC marked Implemented 6. /sprint-close # Complete sprint, RFC marked Implemented
@@ -293,4 +294,4 @@ Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/cl
--- ---
*Last Updated: 2026-02-02* *Last Updated: 2026-01-30*

View File

@@ -398,7 +398,6 @@ PR_REVIEW_AUTO_SUBMIT=false
| **code-sentinel** | None | None | None needed | | **code-sentinel** | None | None | None needed |
| **project-hygiene** | None | None | None needed | | **project-hygiene** | None | None | None needed |
| **claude-config-maintainer** | None | None | None needed | | **claude-config-maintainer** | None | None | None needed |
| **contract-validator** | None | None | `/initial-setup` |
--- ---

View File

@@ -1,20 +0,0 @@
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

View File

@@ -131,28 +131,6 @@ class ContractValidatorMCPServer:
"required": ["agent_name", "claude_md_path"] "required": ["agent_name", "claude_md_path"]
} }
), ),
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. Also checks gate contract version compatibility.",
inputSchema={
"type": "object",
"properties": {
"plugin_path": {
"type": "string",
"description": "Path to the domain plugin directory"
},
"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"]
}
),
# Report tools (to be implemented in #188) # Report tools (to be implemented in #188)
Tool( Tool(
name="generate_compatibility_report", name="generate_compatibility_report",
@@ -220,8 +198,6 @@ class ContractValidatorMCPServer:
result = await self._validate_agent_refs(**arguments) result = await self._validate_agent_refs(**arguments)
elif name == "validate_data_flow": elif name == "validate_data_flow":
result = await self._validate_data_flow(**arguments) result = await self._validate_data_flow(**arguments)
elif name == "validate_workflow_integration":
result = await self._validate_workflow_integration(**arguments)
elif name == "generate_compatibility_report": elif name == "generate_compatibility_report":
result = await self._generate_compatibility_report(**arguments) result = await self._generate_compatibility_report(**arguments)
elif name == "list_issues": elif name == "list_issues":
@@ -265,17 +241,6 @@ class ContractValidatorMCPServer:
"""Validate agent data flow""" """Validate agent data flow"""
return await self.validation_tools.validate_data_flow(agent_name, claude_md_path) 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,
expected_contract: str = None
) -> dict:
"""Validate domain plugin exposes required advisory interfaces"""
return await self.validation_tools.validate_workflow_integration(
plugin_path, domain_label, expected_contract
)
# Report tool implementations (Issue #188) # Report tool implementations (Issue #188)
async def _generate_compatibility_report(self, marketplace_path: str, format: str = "markdown") -> dict: async def _generate_compatibility_report(self, marketplace_path: str, format: str = "markdown") -> dict:

View File

@@ -26,7 +26,6 @@ class IssueType(str, Enum):
OPTIONAL_DEPENDENCY = "optional_dependency" OPTIONAL_DEPENDENCY = "optional_dependency"
UNDECLARED_OUTPUT = "undeclared_output" UNDECLARED_OUTPUT = "undeclared_output"
INVALID_SEQUENCE = "invalid_sequence" INVALID_SEQUENCE = "invalid_sequence"
MISSING_INTEGRATION = "missing_integration"
class ValidationIssue(BaseModel): class ValidationIssue(BaseModel):
@@ -66,18 +65,6 @@ class DataFlowResult(BaseModel):
issues: list[ValidationIssue] = [] issues: list[ValidationIssue] = []
class WorkflowIntegrationResult(BaseModel):
"""Result of workflow integration validation for domain plugins"""
plugin_name: str
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] = []
class ValidationTools: class ValidationTools:
"""Tools for validating plugin compatibility and agent references""" """Tools for validating plugin compatibility and agent references"""
@@ -349,145 +336,3 @@ class ValidationTools:
) )
return result.model_dump() return result.model_dump()
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 = []
# Extract plugin name from path
plugin_name = plugin_path_obj.name
if not plugin_path_obj.exists():
return {
"error": f"Plugin directory not found: {plugin_path}",
"plugin_path": plugin_path,
"domain_label": domain_label
}
# Extract domain short name from label (e.g., "Domain/Viz" -> "viz", "Domain/Data" -> "data")
domain_short = domain_label.split("/")[-1].lower() if "/" in domain_label else domain_label.lower()
# 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():
for cmd_file in commands_dir.glob("*.md"):
if "gate" in cmd_file.name.lower():
# Verify it's actually a gate command by checking content
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:
issues.append(ValidationIssue(
severity=IssueSeverity.ERROR,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Plugin '{plugin_name}' lacks a gate command for domain '{domain_label}'",
location=str(commands_dir),
suggestion=f"Create commands/{domain_short}-gate.md with binary PASS/FAIL output"
))
# Check for review command
review_command_found = False
if commands_dir.exists():
for cmd_file in commands_dir.glob("*.md"):
if "review" in cmd_file.name.lower() and "gate" not in cmd_file.name.lower():
review_command_found = True
break
if not review_command_found:
issues.append(ValidationIssue(
severity=IssueSeverity.WARNING,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Plugin '{plugin_name}' lacks a review command for domain '{domain_label}'",
location=str(commands_dir),
suggestion=f"Create commands/{domain_short}-review.md for detailed audits"
))
# Check for advisory agent
agents_dir = plugin_path_obj / "agents"
advisory_agent_found = False
if agents_dir.exists():
for agent_file in agents_dir.glob("*.md"):
content = agent_file.read_text()
# Check if agent references the domain label or gate command
if domain_label in content or f"{domain_short}-gate" in content.lower() or "advisor" in agent_file.name.lower() or "reviewer" in agent_file.name.lower():
advisory_agent_found = True
break
if not advisory_agent_found:
issues.append(ValidationIssue(
severity=IssueSeverity.WARNING,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Plugin '{plugin_name}' lacks an advisory agent for domain '{domain_label}'",
location=str(agents_dir) if agents_dir.exists() else str(plugin_path_obj),
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
)
return result.model_dump()

View File

@@ -254,261 +254,3 @@ async def test_validate_data_flow_missing_producer(validation_tools, tmp_path):
# Should have warning about missing producer # Should have warning about missing producer
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"] warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
assert len(warning_issues) > 0 assert len(warning_issues) > 0
# --- Workflow Integration Tests ---
@pytest.fixture
def domain_plugin_complete(tmp_path):
"""Create a complete domain plugin with gate, review, and advisory agent"""
plugin_dir = tmp_path / "viz-platform"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
(plugin_dir / "commands").mkdir()
(plugin_dir / "agents").mkdir()
# Gate command with PASS/FAIL pattern
gate_cmd = plugin_dir / "commands" / "design-gate.md"
gate_cmd.write_text("""# /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.
Handles issues with `Domain/Viz` label.
""")
return str(plugin_dir)
@pytest.fixture
def domain_plugin_missing_gate(tmp_path):
"""Create domain plugin with review and agent but no gate command"""
plugin_dir = tmp_path / "data-platform"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
(plugin_dir / "commands").mkdir()
(plugin_dir / "agents").mkdir()
# Review command (but no gate)
review_cmd = plugin_dir / "commands" / "data-review.md"
review_cmd.write_text("""# /data-review
Data integrity audit.
""")
# Advisory agent
agent = plugin_dir / "agents" / "data-advisor.md"
agent.write_text("""# data-advisor
Data integrity advisor for Domain/Data issues.
""")
return str(plugin_dir)
@pytest.fixture
def domain_plugin_minimal(tmp_path):
"""Create minimal plugin with no commands or agents"""
plugin_dir = tmp_path / "minimal-plugin"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
readme = plugin_dir / "README.md"
readme.write_text("# Minimal Plugin\n\nNo commands or agents.")
return str(plugin_dir)
@pytest.mark.asyncio
async def test_validate_workflow_integration_complete(validation_tools, domain_plugin_complete):
"""Test complete domain plugin returns valid with all interfaces found"""
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_command_found"] is True
assert result["review_command_found"] is True
assert result["advisory_agent_found"] is True
# 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
async def test_validate_workflow_integration_missing_gate(validation_tools, domain_plugin_missing_gate):
"""Test plugin missing gate command returns invalid with ERROR"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_missing_gate,
"Domain/Data"
)
assert "error" not in result
assert result["valid"] is False
assert result["gate_command_found"] is False
assert result["review_command_found"] is True
assert result["advisory_agent_found"] is True
# Should have one ERROR for missing gate
error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
assert len(error_issues) == 1
assert "gate" in error_issues[0]["message"].lower()
@pytest.mark.asyncio
async def test_validate_workflow_integration_minimal(validation_tools, domain_plugin_minimal):
"""Test minimal plugin returns invalid with multiple issues"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_minimal,
"Domain/Test"
)
assert "error" not in result
assert result["valid"] is False
assert result["gate_command_found"] is False
assert result["review_command_found"] is False
assert result["advisory_agent_found"] is False
# Should have one ERROR (gate) and two WARNINGs (review, agent)
error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
assert len(error_issues) == 1
assert len(warning_issues) == 2
@pytest.mark.asyncio
async def test_validate_workflow_integration_nonexistent_plugin(validation_tools, tmp_path):
"""Test error when plugin directory doesn't exist"""
result = await validation_tools.validate_workflow_integration(
str(tmp_path / "nonexistent"),
"Domain/Test"
)
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()

View File

@@ -1,5 +0,0 @@
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

View File

@@ -30,7 +30,6 @@
- Use `validate_compatibility` for pairwise checks - Use `validate_compatibility` for pairwise checks
- Use `validate_agent_refs` for CLAUDE.md agents - Use `validate_agent_refs` for CLAUDE.md agents
- Use `validate_data_flow` for data sequences - Use `validate_data_flow` for data sequences
- Use `validate_workflow_integration` for domain plugin advisory interfaces
5. **Generate report**: 5. **Generate report**:
- Use `generate_compatibility_report` for full report - Use `generate_compatibility_report` for full report

View File

@@ -16,7 +16,6 @@ Available MCP tools for contract-validator operations.
| `validate_compatibility` | Check two plugins for conflicts | | `validate_compatibility` | Check two plugins for conflicts |
| `validate_agent_refs` | Check agent tool references exist | | `validate_agent_refs` | Check agent tool references exist |
| `validate_data_flow` | Verify data flow through agent sequence | | `validate_data_flow` | Verify data flow through agent sequence |
| `validate_workflow_integration` | Check domain plugin exposes required advisory interfaces and gate contract version |
### Report Tools ### Report Tools
| Tool | Description | | Tool | Description |
@@ -54,14 +53,6 @@ Available MCP tools for contract-validator operations.
3. Build Mermaid diagram from results 3. Build Mermaid diagram from results
``` ```
### Workflow Integration Check
```
1. validate_workflow_integration(plugin_path, domain_label) # Check single domain plugin
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 ## Error Handling
If MCP tools fail: If MCP tools fail:

View File

@@ -30,15 +30,6 @@ Rules for validating plugin compatibility and agent definitions.
3. Check for orphaned data references 3. Check for orphaned data references
4. Ensure required data is available at each step 4. Ensure required data is available at each step
### Workflow Integration Checks
1. Gate command exists in plugin's commands/ directory
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
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 ## Severity Levels
| Level | Meaning | Action | | Level | Meaning | Action |
@@ -55,8 +46,6 @@ Rules for validating plugin compatibility and agent definitions.
| Data flow gap | Producer not called before consumer | Reorder workflow steps | | Data flow gap | Producer not called before consumer | Reorder workflow steps |
| Name conflict | Two plugins use same command | Rename one command | | Name conflict | Two plugins use same command | Rename one command |
| Orphan reference | Data produced but never consumed | Remove or use the data | | Orphan reference | Data produced but never consumed | Remove or use the data |
| Missing gate command | Domain plugin lacks /X-gate command | Create commands/{domain}-gate.md |
| Missing advisory agent | Domain plugin has no reviewer agent | Create agents/{domain}-advisor.md |
## MCP Tools ## MCP Tools
@@ -65,5 +54,4 @@ Rules for validating plugin compatibility and agent definitions.
| `validate_compatibility` | Check two plugins for conflicts | | `validate_compatibility` | Check two plugins for conflicts |
| `validate_agent_refs` | Check agent tool references | | `validate_agent_refs` | Check agent tool references |
| `validate_data_flow` | Verify data flow sequences | | `validate_data_flow` | Verify data flow sequences |
| `validate_workflow_integration` | Check domain plugin advisory interfaces |
| `list_issues` | Filter issues by severity or type | | `list_issues` | Filter issues by severity or type |

View File

@@ -1,6 +1,6 @@
{ {
"name": "data-platform", "name": "data-platform",
"version": "1.3.0", "version": "1.1.0",
"description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration", "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
"author": { "author": {
"name": "Leo Miranda", "name": "Leo Miranda",

View File

@@ -1,320 +0,0 @@
---
agent: data-advisor
description: Reviews code for data integrity, schema validity, and dbt compliance using data-platform MCP tools
triggers:
- /data-review command
- /data-gate command
- projman orchestrator domain gate
---
# Data Advisor Agent
You are a strict data integrity auditor. Your role is to review code for proper schema usage, dbt compliance, lineage integrity, and data quality standards.
## Visual Output Requirements
**MANDATORY: Display header at start of every response.**
```
+----------------------------------------------------------------------+
| DATA-PLATFORM - Data Advisor |
| [Target Path] |
+----------------------------------------------------------------------+
```
## Trigger Conditions
Activate this agent when:
- User runs `/data-review <path>`
- User runs `/data-gate <path>`
- Projman orchestrator requests data domain gate check
- Code review includes database operations, dbt models, or data pipelines
## Skills to Load
- skills/data-integrity-audit.md
- skills/mcp-tools-reference.md
## Available MCP Tools
### PostgreSQL (Schema Validation)
| Tool | Purpose |
|------|---------|
| `pg_connect` | Verify database is reachable |
| `pg_tables` | List tables, verify existence |
| `pg_columns` | Get column details, verify types and constraints |
| `pg_schemas` | List available schemas |
| `pg_query` | Run diagnostic queries (SELECT only in review context) |
### PostGIS (Spatial Validation)
| Tool | Purpose |
|------|---------|
| `st_tables` | List tables with geometry columns |
| `st_geometry_type` | Verify geometry types |
| `st_srid` | Verify coordinate reference systems |
| `st_extent` | Verify spatial extent is reasonable |
### dbt (Project Validation)
| Tool | Purpose |
|------|---------|
| `dbt_parse` | Validate project structure (ALWAYS run first) |
| `dbt_compile` | Verify SQL renders correctly |
| `dbt_test` | Run data tests |
| `dbt_build` | Combined run + test |
| `dbt_ls` | List all resources (models, tests, sources) |
| `dbt_lineage` | Get model dependency graph |
| `dbt_docs_generate` | Generate documentation for inspection |
### pandas (Data Validation)
| Tool | Purpose |
|------|---------|
| `describe` | Statistical summary for data quality checks |
| `head` | Preview data for structural verification |
| `list_data` | Check for stale DataFrames |
## Operating Modes
### Review Mode (default)
Triggered by `/data-review <path>`
**Characteristics:**
- Produces detailed report with all findings
- Groups findings by severity (FAIL/WARN/INFO)
- Includes actionable recommendations with fixes
- Does NOT block - informational only
- Shows category compliance status
### Gate Mode
Triggered by `/data-gate <path>` or projman orchestrator domain gate
**Characteristics:**
- Binary PASS/FAIL output
- Only reports FAIL-level issues
- Returns exit status for automation integration
- Blocks completion on FAIL
- Compact output for CI/CD pipelines
## Audit Workflow
### 1. Receive Target Path
Accept file or directory path from command invocation.
### 2. Determine Scope
Analyze target to identify what type of data work is present:
| Pattern | Type | Checks to Run |
|---------|------|---------------|
| `dbt_project.yml` present | dbt project | Full dbt validation |
| `*.sql` files in dbt path | dbt models | Model compilation, lineage |
| `*.py` with `pg_query`/`pg_execute` | Database operations | Schema validation |
| `schema.yml` files | dbt schemas | Schema drift detection |
| Migration files (`*_migration.sql`) | Schema changes | Full PostgreSQL + dbt checks |
### 3. Run Database Checks (if applicable)
```
1. pg_connect → verify database reachable
If fails: WARN, continue with file-based checks
2. pg_tables → verify expected tables exist
If missing: FAIL
3. pg_columns on affected tables → verify types
If mismatch: FAIL
```
### 4. Run dbt Checks (if applicable)
```
1. dbt_parse → validate project
If fails: FAIL immediately (project broken)
2. dbt_ls → catalog all resources
Record models, tests, sources
3. dbt_lineage on target models → check integrity
Orphaned refs: FAIL
4. dbt_compile on target models → verify SQL
Compilation errors: FAIL
5. dbt_test --select <targets> → run tests
Test failures: FAIL
6. Cross-reference tests → models without tests
Missing tests: WARN
```
### 5. Run PostGIS Checks (if applicable)
```
1. st_tables → list spatial tables
If none found: skip PostGIS checks
2. st_srid → verify SRID correct
Unexpected SRID: FAIL
3. st_geometry_type → verify expected types
Wrong type: WARN
4. st_extent → sanity check bounding box
Unreasonable extent: FAIL
```
### 6. Scan Python Code (manual patterns)
For Python files with database operations:
| Pattern | Issue | Severity |
|---------|-------|----------|
| `f"SELECT * FROM {table}"` | SQL injection risk | WARN |
| `f"INSERT INTO {table}"` | Unparameterized mutation | WARN |
| `pg_execute` without WHERE in DELETE/UPDATE | Dangerous mutation | WARN |
| Hardcoded connection strings | Credential exposure | WARN |
### 7. Generate Report
Output format depends on operating mode (see templates in `skills/data-integrity-audit.md`).
## Report Formats
### Gate Mode Output
**PASS:**
```
DATA GATE: PASS
No blocking data integrity violations found.
```
**FAIL:**
```
DATA GATE: FAIL
Blocking Issues (2):
1. dbt/models/staging/stg_census.sql - Compilation error: column 'census_yr' not found
Fix: Column was renamed to 'census_year' in source table. Update model.
2. portfolio_app/toronto/loaders/census.py:67 - References table 'census_raw' which does not exist
Fix: Table was renamed to 'census_demographics' in migration 003.
Run /data-review for full audit report.
```
### Review Mode Output
```
+----------------------------------------------------------------------+
| DATA-PLATFORM - Data Integrity Audit |
| /path/to/project |
+----------------------------------------------------------------------+
Target: /path/to/project
Scope: 12 files scanned, 8 models checked, 3 tables verified
FINDINGS
FAIL (2)
1. [dbt/models/staging/stg_census.sql] Compilation error
Error: column 'census_yr' does not exist
Fix: Column was renamed to 'census_year'. Update SELECT clause.
2. [portfolio_app/loaders/census.py:67] Missing table reference
Error: Table 'census_raw' does not exist
Fix: Table renamed to 'census_demographics' in migration 003.
WARN (3)
1. [dbt/models/marts/dim_neighbourhoods.sql] Missing dbt test
Issue: No unique test on neighbourhood_id
Suggestion: Add unique test to schema.yml
2. [portfolio_app/toronto/queries.py:45] Hardcoded SQL
Issue: f"SELECT * FROM {table_name}" without parameterization
Suggestion: Use parameterized queries
3. [dbt/models/staging/stg_legacy.sql] Orphaned model
Issue: No downstream consumers or exposures
Suggestion: Remove if unused or add to exposure
INFO (1)
1. [dbt/models/marts/fct_demographics.sql] Documentation gap
Note: Model description missing in schema.yml
Suggestion: Add description for discoverability
SUMMARY
Schema: 2 issues
Lineage: Intact
dbt: 1 failure
PostGIS: Not applicable
VERDICT: FAIL (2 blocking issues)
```
## Severity Definitions
| Level | Criteria | Action Required |
|-------|----------|-----------------|
| **FAIL** | dbt parse/compile fails, missing tables/columns, type mismatches, broken lineage, invalid SRID | Must fix before completion |
| **WARN** | Missing tests, hardcoded SQL, schema drift, orphaned models | Should fix |
| **INFO** | Documentation gaps, optimization opportunities | Consider for improvement |
## Error Handling
| Error | Response |
|-------|----------|
| Database not reachable | WARN: "PostgreSQL unavailable, skipping schema checks" - continue |
| No dbt_project.yml | Skip dbt checks silently - not an error |
| No PostGIS tables | Skip PostGIS checks silently - not an error |
| MCP tool fails | WARN: "Tool {name} failed: {error}" - continue with remaining |
| Empty path | PASS: "No data artifacts found in target path" |
| Invalid path | Error: "Path not found: {path}" |
## Integration with projman
When called as a domain gate by projman orchestrator:
1. Receive path from orchestrator (changed files for the issue)
2. Determine what type of data work changed
3. Run audit in gate mode
4. Return structured result:
```
Gate: data
Status: PASS | FAIL
Blocking: N issues
Summary: Brief description
```
5. Orchestrator decides whether to proceed based on gate status
## Example Interactions
**User**: `/data-review dbt/models/staging/`
**Agent**:
1. Scans all .sql files in staging/
2. Runs dbt_parse to validate project
3. Runs dbt_compile on each model
4. Checks lineage for orphaned refs
5. Cross-references test coverage
6. Returns detailed report
**User**: `/data-gate portfolio_app/toronto/`
**Agent**:
1. Scans for Python files with pg_query/pg_execute
2. Checks if referenced tables exist
3. Validates column types
4. Returns PASS if clean, FAIL with blocking issues if not
5. Compact output for automation
## Communication Style
Technical and precise. Report findings with exact locations, specific violations, and actionable fixes:
- "Table `census_demographics` column `population` is `varchar(50)` in PostgreSQL but referenced as `integer` in `stg_census.sql` line 14. This will cause a runtime cast error."
- "Model `dim_neighbourhoods` has no `unique` test on `neighbourhood_id`. Add to `schema.yml` to prevent duplicates."
- "Spatial extent for `toronto_boundaries` shows global coordinates (-180 to 180). Expected Toronto bbox (~-79.6 to -79.1 longitude). Likely missing ST_Transform or wrong SRID on import."

View File

@@ -1,105 +0,0 @@
---
description: Data integrity compliance gate (pass/fail) for sprint execution
gate_contract: v1
arguments:
- name: path
description: File or directory to validate
required: true
---
# /data-gate
Binary pass/fail validation for data integrity compliance. Used by projman orchestrator during sprint execution to gate issue completion.
## Usage
```
/data-gate <path>
```
**Examples:**
```
/data-gate ./dbt/models/staging/
/data-gate ./portfolio_app/toronto/parsers/
/data-gate ./dbt/
```
## What It Does
1. **Activates** the `data-advisor` agent in gate mode
2. **Loads** the `skills/data-integrity-audit.md` skill
3. **Determines scope** from target path:
- dbt project directory: full dbt validation (parse, compile, test, lineage)
- Python files with database operations: schema validation
- SQL files: dbt model validation
- Mixed: all applicable checks
4. **Checks only FAIL-level violations:**
- dbt parse failures (project broken)
- dbt compilation errors (SQL invalid)
- Missing tables/columns referenced in code
- Data type mismatches that cause runtime errors
- Broken lineage (orphaned model references)
- PostGIS SRID mismatches
5. **Returns binary result:**
- `PASS` - No blocking violations found
- `FAIL` - One or more blocking violations
## Output
### On PASS
```
DATA GATE: PASS
No blocking data integrity violations found.
```
### On FAIL
```
DATA GATE: FAIL
Blocking Issues (2):
1. dbt/models/staging/stg_census.sql - Compilation error: column 'census_yr' not found
Fix: Column was renamed to 'census_year' in source table. Update model.
2. portfolio_app/toronto/loaders/census.py:67 - References table 'census_raw' which does not exist
Fix: Table was renamed to 'census_demographics' in migration 003.
Run /data-review for full audit report.
```
## Integration with projman
This command is automatically invoked by the projman orchestrator when:
1. An issue has the `Domain/Data` label
2. The orchestrator is about to mark the issue as complete
3. The orchestrator passes the path of changed files
**Gate behavior:**
- PASS: Issue can be marked complete
- FAIL: Issue stays open, blocker comment added with failure details
## Differences from /data-review
| Aspect | /data-gate | /data-review |
|--------|------------|--------------|
| Output | Binary PASS/FAIL | Detailed report with all severities |
| Severity | FAIL only | FAIL + WARN + INFO |
| Purpose | Automation gate | Human review |
| Verbosity | Minimal | Comprehensive |
| Speed | Skips INFO checks | Full scan |
## When to Use
- **Sprint execution**: Automatic quality gates via projman
- **CI/CD pipelines**: Automated data integrity checks
- **Quick validation**: Fast pass/fail without full report
- **Pre-merge checks**: Verify data changes before integration
For detailed findings including warnings and suggestions, use `/data-review` instead.
## Requirements
- data-platform MCP server must be running
- For dbt checks: dbt project must be configured (auto-detected via `dbt_project.yml`)
- For PostgreSQL checks: connection configured in `~/.config/claude/postgres.env`
- If database or dbt unavailable: applicable checks skipped with warning (non-blocking degradation)

View File

@@ -1,149 +0,0 @@
---
description: Audit data integrity, schema validity, and dbt compliance
arguments:
- name: path
description: File, directory, or dbt project to audit
required: true
---
# /data-review
Comprehensive data integrity audit producing a detailed report with findings at all severity levels. For human review and standalone codebase auditing.
## Usage
```
/data-review <path>
```
**Examples:**
```
/data-review ./dbt/
/data-review ./portfolio_app/toronto/
/data-review ./dbt/models/marts/
```
## What It Does
1. **Activates** the `data-advisor` agent in review mode
2. **Scans target path** to determine scope:
- Identifies dbt project files (.sql models, schema.yml, sources.yml)
- Identifies Python files with database operations
- Identifies migration files
- Identifies PostGIS usage
3. **Runs all check categories:**
- Schema validity (PostgreSQL tables, columns, types)
- dbt project health (parse, compile, test, lineage)
- PostGIS compliance (SRID, geometry types, extent)
- Data type consistency
- Code patterns (unsafe SQL, hardcoded queries)
4. **Produces detailed report** with all severity levels (FAIL, WARN, INFO)
5. **Provides actionable recommendations** for each finding
## Output Format
```
+----------------------------------------------------------------------+
| DATA-PLATFORM - Data Integrity Audit |
| /path/to/project |
+----------------------------------------------------------------------+
Target: /path/to/project
Scope: N files scanned, N models checked, N tables verified
FINDINGS
FAIL (N)
1. [location] violation description
Fix: actionable fix
WARN (N)
1. [location] warning description
Suggestion: improvement suggestion
INFO (N)
1. [location] info description
Note: context
SUMMARY
Schema: Valid | N issues
Lineage: Intact | N orphaned
dbt: Passes | N failures
PostGIS: Valid | N issues | Not applicable
VERDICT: PASS | FAIL (N blocking issues)
```
## When to Use
### Before Sprint Planning
Audit data layer health to identify tech debt and inform sprint scope.
```
/data-review ./dbt/
```
### During Code Review
Get detailed data integrity findings alongside code review comments.
```
/data-review ./dbt/models/staging/stg_new_source.sql
```
### After Migrations
Verify schema changes didn't break anything downstream.
```
/data-review ./migrations/
```
### Periodic Health Checks
Regular data infrastructure audits for proactive maintenance.
```
/data-review ./data_pipeline/
```
### New Project Onboarding
Understand the current state of data architecture.
```
/data-review .
```
## Severity Levels
| Level | Meaning | Gate Impact |
|-------|---------|-------------|
| **FAIL** | Blocking issues that will cause runtime errors | Would block `/data-gate` |
| **WARN** | Quality issues that should be addressed | Does not block gate |
| **INFO** | Suggestions for improvement | Does not block gate |
## Differences from /data-gate
`/data-review` gives you the full picture. `/data-gate` gives the orchestrator a yes/no.
| Aspect | /data-gate | /data-review |
|--------|------------|--------------|
| Output | Binary PASS/FAIL | Detailed report |
| Severity | FAIL only | FAIL + WARN + INFO |
| Purpose | Automation | Human review |
| Verbosity | Minimal | Comprehensive |
| Speed | Fast (skips INFO) | Thorough |
Use `/data-review` when you want to understand.
Use `/data-gate` when you want to automate.
## Requirements
- data-platform MCP server must be running
- For dbt checks: dbt project must be configured (auto-detected via `dbt_project.yml`)
- For PostgreSQL checks: connection configured in `~/.config/claude/postgres.env`
**Graceful degradation:** If database or dbt unavailable, applicable checks are skipped with a note in the report rather than failing entirely.
## Skills Used
- `skills/data-integrity-audit.md` - Audit rules and patterns
- `skills/mcp-tools-reference.md` - MCP tool reference
## Related Commands
- `/data-gate` - Binary pass/fail for automation
- `/lineage` - Visualize dbt model dependencies
- `/schema` - Explore database schema

View File

@@ -1,307 +0,0 @@
---
name: data-integrity-audit
description: Rules and patterns for auditing data integrity, schema validity, and dbt compliance
---
# Data Integrity Audit
## Purpose
Defines what "data valid" means for the data-platform domain. This skill is loaded by the `data-advisor` agent for both review and gate modes during sprint execution and standalone audits.
---
## What to Check
| Check Category | What It Validates | MCP Tools Used |
|----------------|-------------------|----------------|
| **Schema Validity** | Tables exist, columns have correct types, constraints present, no orphaned columns | `pg_tables`, `pg_columns`, `pg_schemas` |
| **dbt Project Health** | Project parses without errors, models compile, tests defined for critical models | `dbt_parse`, `dbt_compile`, `dbt_test`, `dbt_ls` |
| **Lineage Integrity** | No orphaned models (referenced but missing), no circular dependencies, upstream sources exist | `dbt_lineage`, `dbt_ls` |
| **Data Type Consistency** | DataFrame dtypes match expected schema, no silent type coercion, date formats consistent | `describe`, `head`, `pg_columns` |
| **PostGIS Compliance** | Spatial tables have correct SRID, geometry types match expectations, extent is reasonable | `st_tables`, `st_geometry_type`, `st_srid`, `st_extent` |
| **Query Safety** | SELECT queries used for reads (not raw SQL for mutations), parameterized patterns | Code review - manual pattern check |
---
## Common Violations
### FAIL-Level Violations (Block Gate)
| Violation | Detection Method | Example |
|-----------|-----------------|---------|
| dbt parse failure | `dbt_parse` returns error | Project YAML invalid, missing ref targets |
| dbt compilation error | `dbt_compile` fails | SQL syntax error, undefined column reference |
| Missing table/column | `pg_tables`, `pg_columns` lookup | Code references `census_raw` but table doesn't exist |
| Type mismatch | Compare `pg_columns` vs dbt schema | Column is `varchar` in DB but model expects `integer` |
| Broken lineage | `dbt_lineage` shows orphaned refs | Model references `stg_old_format` which doesn't exist |
| PostGIS SRID mismatch | `st_srid` returns unexpected value | Geometry column has SRID 0 instead of 4326 |
| Unreasonable spatial extent | `st_extent` returns global bbox | Toronto data shows coordinates in China |
### WARN-Level Violations (Report, Don't Block)
| Violation | Detection Method | Example |
|-----------|-----------------|---------|
| Missing dbt tests | `dbt_ls` shows model without test | `dim_customers` has no `unique` test on `customer_id` |
| Undocumented columns | dbt schema.yml missing descriptions | Model columns have no documentation |
| Schema drift | `pg_columns` vs dbt schema.yml | Column exists in DB but not in dbt YAML |
| Hardcoded SQL | Scan Python for string concatenation | `f"SELECT * FROM {table}"` without parameterization |
| Orphaned model | `dbt_lineage` shows no downstream | `stg_legacy` has no consumers and no exposure |
### INFO-Level Violations (Suggestions Only)
| Violation | Detection Method | Example |
|-----------|-----------------|---------|
| Missing indexes | Query pattern suggests need | Frequent filter on non-indexed column |
| Documentation gaps | dbt docs incomplete | Missing model description |
| Unused models | `dbt_ls` vs actual queries | Model exists but never selected |
| Optimization opportunity | `describe` shows data patterns | Column has low cardinality, could be enum |
---
## Severity Classification
| Severity | When to Apply | Gate Behavior |
|----------|--------------|---------------|
| **FAIL** | Broken lineage, models that won't compile, missing tables/columns, data type mismatches that cause runtime errors, invalid SRID | Blocks issue completion |
| **WARN** | Missing dbt tests, undocumented columns, schema drift, hardcoded SQL, orphaned models | Does NOT block gate, included in review report |
| **INFO** | Optimization opportunities, documentation gaps, unused models | Review report only |
### Severity Decision Tree
```
Is the dbt project broken (parse/compile fails)?
YES -> FAIL
NO -> Does code reference non-existent tables/columns?
YES -> FAIL
NO -> Would this cause a runtime error?
YES -> FAIL
NO -> Does it violate data quality standards?
YES -> WARN
NO -> Is it an optimization/documentation suggestion?
YES -> INFO
NO -> Not a violation
```
---
## Scanning Strategy
### For dbt Projects
1. **Parse validation** (ALWAYS FIRST)
```
dbt_parse → if fails, immediate FAIL (project is broken)
```
2. **Catalog resources**
```
dbt_ls → list all models, tests, sources, exposures
```
3. **Lineage check**
```
dbt_lineage on changed models → check upstream/downstream integrity
```
4. **Compilation check**
```
dbt_compile on changed models → verify SQL renders correctly
```
5. **Test execution**
```
dbt_test --select <changed_models> → verify tests pass
```
6. **Test coverage audit**
```
Cross-reference dbt_ls tests against model list → flag models without tests (WARN)
```
### For PostgreSQL Schema Changes
1. **Table verification**
```
pg_tables → verify expected tables exist
```
2. **Column validation**
```
pg_columns on affected tables → verify types match expectations
```
3. **Schema comparison**
```
Compare pg_columns output against dbt schema.yml → flag drift
```
### For PostGIS/Spatial Data
1. **Spatial table scan**
```
st_tables → list tables with geometry columns
```
2. **SRID validation**
```
st_srid → verify SRID is correct for expected region
Expected: 4326 (WGS84) for GPS data, local projections for regional data
```
3. **Geometry type check**
```
st_geometry_type → verify expected types (Point, Polygon, etc.)
```
4. **Extent sanity check**
```
st_extent → verify bounding box is reasonable for expected region
Toronto data should be ~(-79.6 to -79.1, 43.6 to 43.9)
```
### For DataFrame/pandas Operations
1. **Data quality check**
```
describe → check for unexpected nulls, type issues, outliers
```
2. **Structure verification**
```
head → verify data structure matches expectations
```
3. **Memory management**
```
list_data → verify no stale DataFrames from previous failed runs
```
### For Python Code (Manual Scan)
1. **SQL injection patterns**
- Scan for f-strings with table/column names
- Check for string concatenation in queries
- Look for `.format()` calls with SQL
2. **Mutation safety**
- `pg_execute` usage should be intentional, not accidental
- Verify DELETE/UPDATE have WHERE clauses
3. **Credential exposure**
- No hardcoded connection strings
- No credentials in code (check for `.env` usage)
---
## Report Templates
### Gate Mode (Compact)
```
DATA GATE: PASS
No blocking data integrity violations found.
```
or
```
DATA GATE: FAIL
Blocking Issues (N):
1. <location> - <violation description>
Fix: <actionable fix>
2. <location> - <violation description>
Fix: <actionable fix>
Run /data-review for full audit report.
```
### Review Mode (Detailed)
```
+----------------------------------------------------------------------+
| DATA-PLATFORM - Data Integrity Audit |
| [Target Path] |
+----------------------------------------------------------------------+
Target: <scanned path or project>
Scope: N files scanned, N models checked, N tables verified
FINDINGS
FAIL (N)
1. [location] violation description
Fix: actionable fix
2. [location] violation description
Fix: actionable fix
WARN (N)
1. [location] warning description
Suggestion: improvement suggestion
2. [location] warning description
Suggestion: improvement suggestion
INFO (N)
1. [location] info description
Note: context
SUMMARY
Schema: Valid | N issues
Lineage: Intact | N orphaned
dbt: Passes | N failures
PostGIS: Valid | N issues | Not applicable
VERDICT: PASS | FAIL (N blocking issues)
```
---
## Skip Patterns
Do not flag violations in:
- `**/tests/**` - Test files may have intentional violations
- `**/__pycache__/**` - Compiled files
- `**/fixtures/**` - Test fixtures
- `**/.scratch/**` - Temporary working files
- Files with `# noqa: data-audit` comment
- Migration files marked as historical
---
## Error Handling
| Scenario | Behavior |
|----------|----------|
| Database not reachable (`pg_connect` fails) | WARN, skip PostgreSQL checks, continue with file-based |
| dbt not configured (no `dbt_project.yml`) | Skip dbt checks entirely, not an error |
| No PostGIS tables found | Skip PostGIS checks, not an error |
| MCP tool call fails | Report as WARN with tool name, continue with remaining checks |
| No data files in scanned path | Report "No data artifacts found" - PASS (nothing to fail) |
| Empty directory | Report "No files found in path" - PASS |
---
## Integration Notes
### projman Orchestrator
When called as a domain gate:
1. Orchestrator detects `Domain/Data` label on issue
2. Orchestrator identifies changed files
3. Orchestrator invokes `/data-gate <path>`
4. Agent runs gate mode scan
5. Returns PASS/FAIL to orchestrator
6. Orchestrator decides whether to complete issue
### Standalone Usage
For manual audits:
1. User runs `/data-review <path>`
2. Agent runs full review mode scan
3. Returns detailed report with all severity levels
4. User decides on actions

View File

@@ -1,5 +0,0 @@
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

View File

@@ -11,8 +11,6 @@ You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures
- skills/review-checklist.md - skills/review-checklist.md
- skills/test-standards.md - skills/test-standards.md
- skills/sprint-lifecycle.md
- skills/visual-output.md
## Your Personality ## Your Personality
@@ -30,10 +28,14 @@ You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures
## Visual Output ## Visual Output
See `skills/visual-output.md` for header templates. Use the **Code Reviewer** row from the Phase Registry: Display header at start of every response:
- Phase Emoji: Magnifier ```
- Phase Name: REVIEW ╔══════════════════════════════════════════════════════════════════╗
- Context: Sprint Name ║ 📋 PROJMAN ║
║ 🏁 CLOSING ║
║ Code Review ║
╚══════════════════════════════════════════════════════════════════╝
```
## Your Responsibilities ## Your Responsibilities

View File

@@ -15,7 +15,6 @@ You are the **Executor Agent** - an implementation-focused specialist who writes
- skills/progress-tracking.md - skills/progress-tracking.md
- skills/runaway-detection.md - skills/runaway-detection.md
- skills/lessons-learned.md - skills/lessons-learned.md
- skills/visual-output.md
## Your Personality ## Your Personality
@@ -33,10 +32,14 @@ You are the **Executor Agent** - an implementation-focused specialist who writes
## Visual Output ## Visual Output
See `skills/visual-output.md` for header templates. Use the **Executor** row from the Phase Registry: Display header at start of every response:
- Phase Emoji: Wrench ```
- Phase Name: IMPLEMENTING ╔══════════════════════════════════════════════════════════════════╗
- Context: Issue Title ║ 📋 PROJMAN ║
║ ⚡ EXECUTION ║
║ [Issue Title] ║
╚══════════════════════════════════════════════════════════════════╝
```
## Your Responsibilities ## Your Responsibilities

View File

@@ -19,8 +19,6 @@ You are the **Orchestrator Agent** - a concise, action-oriented coordinator who
- skills/runaway-detection.md - skills/runaway-detection.md
- skills/wiki-conventions.md - skills/wiki-conventions.md
- skills/domain-consultation.md - skills/domain-consultation.md
- skills/sprint-lifecycle.md
- skills/visual-output.md
## Your Personality ## Your Personality
@@ -38,17 +36,28 @@ You are the **Orchestrator Agent** - a concise, action-oriented coordinator who
## Visual Output ## Visual Output
See `skills/visual-output.md` for header templates. Use the **Orchestrator** row from the Phase Registry: Display header at start of every response:
- Phase Emoji: Lightning ```
- Phase Name: EXECUTION ╔══════════════════════════════════════════════════════════════════╗
- Context: Sprint Name ║ 📋 PROJMAN ║
║ ⚡ EXECUTION ║
║ [Sprint Name] ║
╚══════════════════════════════════════════════════════════════════╝
```
Also use the Progress Block format from `skills/visual-output.md` during sprint execution. Progress block format:
```
┌─ Sprint Progress ────────────────────────────────────────────────┐
│ [Sprint Name] │
│ ████████████░░░░░░░░░░░░░░░░░░ 40% complete │
│ ✅ Done: 4 ⏳ Active: 2 ⬚ Pending: 4 │
└──────────────────────────────────────────────────────────────────┘
```
## Your Responsibilities ## Your Responsibilities
### 1. Verify Approval (Sprint Start) ### 1. Verify Approval (Sprint Start)
Execute `skills/sprint-approval.md` - Check milestone for approval record. **STOP execution if approval is missing** unless user provided `--force` flag. Execute `skills/sprint-approval.md` - Check milestone for approval record.
### 2. Detect Checkpoints (Sprint Start) ### 2. Detect Checkpoints (Sprint Start)
Check for resume points from interrupted sessions. Check for resume points from interrupted sessions.
@@ -66,6 +75,7 @@ Execute `skills/dependency-management.md` - Check for file conflicts before para
Execute `skills/progress-tracking.md` - Manage status labels, parse progress comments. Execute `skills/progress-tracking.md` - Manage status labels, parse progress comments.
### 6.5. Domain Gate Checks ### 6.5. Domain Gate Checks
Execute `skills/domain-consultation.md` (Execution Gate Protocol section): Execute `skills/domain-consultation.md` (Execution Gate Protocol section):
1. **Before marking any issue as complete**, check for `Domain/*` labels 1. **Before marking any issue as complete**, check for `Domain/*` labels
@@ -96,13 +106,6 @@ Execute `skills/wiki-conventions.md` - Update implementation status.
### 10. Git Operations (Sprint Close) ### 10. Git Operations (Sprint Close)
Execute `skills/git-workflow.md` - Merge, tag, clean up branches. 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 ## Critical Reminders
1. **NEVER use CLI tools** - Use MCP tools exclusively (see `skills/mcp-tools-reference.md`) 1. **NEVER use CLI tools** - Use MCP tools exclusively (see `skills/mcp-tools-reference.md`)

View File

@@ -20,9 +20,6 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r
- skills/sprint-approval.md - skills/sprint-approval.md
- skills/planning-workflow.md - skills/planning-workflow.md
- skills/label-taxonomy/labels-reference.md - skills/label-taxonomy/labels-reference.md
- skills/domain-consultation.md
- skills/sprint-lifecycle.md
- skills/visual-output.md
## Your Personality ## Your Personality
@@ -40,10 +37,14 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r
## Visual Output ## Visual Output
See `skills/visual-output.md` for header templates. Use the **Planner** row from the Phase Registry: Display header at start of every response:
- Phase Emoji: Target ```
- Phase Name: PLANNING ╔══════════════════════════════════════════════════════════════════╗
- Context: Sprint Name or Goal ║ 📋 PROJMAN ║
║ 🎯 PLANNING ║
║ [Sprint Name or Goal] ║
╚══════════════════════════════════════════════════════════════════╝
```
## Your Responsibilities ## Your Responsibilities
@@ -65,25 +66,10 @@ Execute `skills/wiki-conventions.md` - Create proposal and implementation pages.
### 6. Task Sizing ### 6. Task Sizing
Execute `skills/task-sizing.md` - **REFUSE to create L/XL tasks without breakdown.** Execute `skills/task-sizing.md` - **REFUSE to create L/XL tasks without breakdown.**
### 7. Domain Consultation ### 7. Issue Creation
Execute `skills/domain-consultation.md` (Planning Protocol section):
1. **After drafting issues but BEFORE creating them in Gitea**
2. **Analyze each issue for domain signals:**
- Check planned labels for `Component/Frontend`, `Component/UI` -> Domain/Viz
- Check planned labels for `Component/Database`, `Component/Data` -> Domain/Data
- Scan issue description for domain keywords (see skill for full list)
3. **For detected domains, append acceptance criteria:**
- Domain/Viz: Design System Compliance checklist
- Domain/Data: Data Integrity checklist
4. **Add corresponding `Domain/*` label** to the issue's label set
5. **Document in planning summary** which issues have domain gates active
### 8. Issue Creation
Execute `skills/issue-conventions.md` - Use proper format with wiki references. Execute `skills/issue-conventions.md` - Use proper format with wiki references.
### 9. Request Approval ### 8. Request Approval
Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permission. Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permission.
## Critical Reminders ## Critical Reminders
@@ -95,7 +81,6 @@ Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permissi
5. **ALWAYS search lessons** - Past experience informs better planning 5. **ALWAYS search lessons** - Past experience informs better planning
6. **ALWAYS include wiki reference** - Every issue links to implementation wiki page 6. **ALWAYS include wiki reference** - Every issue links to implementation wiki page
7. **ALWAYS use proper title format** - `[Sprint XX] <type>: <description>` 7. **ALWAYS use proper title format** - `[Sprint XX] <type>: <description>`
8. **ALWAYS check domain signals** - Every issue gets checked for viz/data domain applicability before creation
## Your Mission ## Your Mission

View File

@@ -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 | | `/sprint-close` | Complete sprint and capture lessons learned to Gitea Wiki |
| `/labels-sync` | Synchronize label taxonomy from Gitea | | `/labels-sync` | Synchronize label taxonomy from Gitea |
| `/initial-setup` | Run initial setup for projman plugin | | `/initial-setup` | Run initial setup for projman plugin |
| `/rfc create` | Create new RFC from conversation or clarified spec | | `/rfc-create` | Create new RFC from conversation or clarified spec |
| `/rfc list` | List all RFCs grouped by status | | `/rfc-list` | List all RFCs grouped by status |
| `/rfc review` | Submit Draft RFC for review | | `/rfc-review` | Submit Draft RFC for review |
| `/rfc approve` | Approve RFC for sprint planning | | `/rfc-approve` | Approve RFC for sprint planning |
| `/rfc reject` | Reject RFC with documented reason | | `/rfc-reject` | Reject RFC with documented reason |
### MCP Tools Available ### MCP Tools Available

View File

@@ -0,0 +1,34 @@
---
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 ║
╚══════════════════════════════════════════════════════════════════╝
```

View File

@@ -8,7 +8,6 @@ agent: code-reviewer
## Skills Required ## Skills Required
- skills/review-checklist.md - skills/review-checklist.md
- skills/sprint-lifecycle.md
## Purpose ## Purpose
@@ -20,7 +19,6 @@ Run `/review` before `/sprint-close` to catch issues.
## Workflow ## 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`) 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 2. **Read Files** - Use Read tool for each file in scope
3. **Scan for Patterns** - Check each category from review checklist 3. **Scan for Patterns** - Check each category from review checklist

View File

@@ -0,0 +1,83 @@
---
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 <number>` 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."

View File

@@ -0,0 +1,84 @@
---
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)

View File

@@ -0,0 +1,98 @@
---
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

View File

@@ -0,0 +1,90 @@
---
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 <number>` 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

View File

@@ -0,0 +1,81 @@
---
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 <number>` 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."

View File

@@ -1,144 +0,0 @@
---
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 <sub-command> [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 <number>` | Submit Draft RFC for review |
| `approve` | `/rfc approve <number>` | Approve RFC in Review status |
| `reject` | `/rfc reject <number>` | 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 <number>` (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 <number>` (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 <number>` (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

View File

@@ -26,7 +26,6 @@ Unified setup command for all configuration needs.
/setup --full # Full wizard (MCP + system + project) /setup --full # Full wizard (MCP + system + project)
/setup --quick # Project-only setup /setup --quick # Project-only setup
/setup --sync # Update after repo move /setup --sync # Update after repo move
/setup --clear-cache # Clear plugin cache (between sessions only)
``` ```
## Mode Detection ## Mode Detection
@@ -80,21 +79,6 @@ Steps:
6. Update `.env` 6. Update `.env`
7. Confirm 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 ## Visual Output
``` ```

View File

@@ -13,7 +13,6 @@ agent: orchestrator
- skills/rfc-workflow.md - skills/rfc-workflow.md
- skills/progress-tracking.md - skills/progress-tracking.md
- skills/git-workflow.md - skills/git-workflow.md
- skills/sprint-lifecycle.md
## Purpose ## Purpose
@@ -27,7 +26,6 @@ Run `/sprint-close` when sprint work is complete.
Execute the sprint close workflow: 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 1. **Review Sprint Completion** - Verify issues closed or moved to backlog
2. **Capture Lessons Learned** - Interview user about challenges and insights 2. **Capture Lessons Learned** - Interview user about challenges and insights
3. **Tag for Discoverability** - Apply technology, component, and pattern tags 3. **Tag for Discoverability** - Apply technology, component, and pattern tags

View File

@@ -18,7 +18,6 @@ agent: planner
- skills/sprint-approval.md - skills/sprint-approval.md
- skills/planning-workflow.md - skills/planning-workflow.md
- skills/label-taxonomy/labels-reference.md - skills/label-taxonomy/labels-reference.md
- skills/sprint-lifecycle.md
## Purpose ## Purpose
@@ -36,7 +35,6 @@ Provide sprint goals as natural language input, or prepare input via:
Execute the planning workflow as defined in `skills/planning-workflow.md`. Execute the planning workflow as defined in `skills/planning-workflow.md`.
**Key steps:** **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) 1. Run pre-planning validations (branch, repo org, labels)
2. Detect input source (file, wiki, or conversation) 2. Detect input source (file, wiki, or conversation)
3. Search relevant lessons learned 3. Search relevant lessons learned

View File

@@ -15,7 +15,6 @@ agent: orchestrator
- skills/git-workflow.md - skills/git-workflow.md
- skills/progress-tracking.md - skills/progress-tracking.md
- skills/runaway-detection.md - skills/runaway-detection.md
- skills/sprint-lifecycle.md
## Purpose ## Purpose
@@ -25,14 +24,11 @@ Initiate sprint execution. The orchestrator agent verifies approval, analyzes de
Run `/sprint-start` when ready to begin executing a planned sprint. Run `/sprint-start` when ready to begin executing a planned sprint.
**Flags:**
- `--force` — Bypass approval gate (emergency only, logged to milestone)
## Workflow ## Workflow
Execute the sprint start workflow: Execute the sprint start workflow:
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. 1. **Verify Sprint Approval** (recommended) - Check milestone for approval record
2. **Detect Checkpoints** - Check for resume points from interrupted sessions 2. **Detect Checkpoints** - Check for resume points from interrupted sessions
3. **Fetch Sprint Issues** - Get open issues from milestone 3. **Fetch Sprint Issues** - Get open issues from milestone
4. **Analyze Dependencies** - Use `get_execution_order` for parallel batches 4. **Analyze Dependencies** - Use `get_execution_order` for parallel batches

View File

@@ -9,7 +9,6 @@ description: Check current sprint progress, identify blockers, optionally genera
- skills/mcp-tools-reference.md - skills/mcp-tools-reference.md
- skills/progress-tracking.md - skills/progress-tracking.md
- skills/dependency-management.md - skills/dependency-management.md
- skills/sprint-lifecycle.md
## Purpose ## Purpose
@@ -24,7 +23,6 @@ Check current sprint progress, identify blockers, and show execution status. Opt
## Workflow ## 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 1. **Fetch Sprint Issues** - Get all issues for current milestone
2. **Calculate Progress** - Count completed vs total issues 2. **Calculate Progress** - Count completed vs total issues
3. **Identify Active Tasks** - Find issues with `Status/In-Progress` 3. **Identify Active Tasks** - Find issues with `Status/In-Progress`

View File

@@ -93,78 +93,6 @@ Generate comprehensive tests for specified code.
See `skills/test-standards.md` for test patterns and structure. 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 ## Visual Output

View File

@@ -1,165 +0,0 @@
---
name: domain-consultation
description: Cross-plugin domain consultation for specialized planning and validation
---
# Domain Consultation
## Purpose
Enables projman agents to detect domain-specific work and consult specialized plugins for expert validation during planning and execution phases. This skill is the backbone of the Domain Advisory Pattern.
---
## When to Use
| Agent | Phase | Action |
|-------|-------|--------|
| Planner | After task sizing, before issue creation | Detect domains, add acceptance criteria |
| Orchestrator | Before marking issue complete | Run domain gates, block if violations |
| Code Reviewer | During review | Include domain compliance in findings |
---
## Domain Detection Rules
| Signal Type | Detection Pattern | Domain Plugin | Action |
|-------------|-------------------|---------------|--------|
| Label-based | `Component/Frontend`, `Component/UI` | viz-platform | Add design system criteria, apply `Domain/Viz` |
| Content-based | Keywords: DMC, Dash, layout, theme, component, dashboard, chart, responsive, color, UI, frontend, Plotly | viz-platform | Same as above |
| Label-based | `Component/Database`, `Component/Data` | data-platform | Add data validation criteria, apply `Domain/Data` |
| Content-based | Keywords: schema, migration, pipeline, dbt, table, column, query, PostgreSQL, lineage, data model | data-platform | Same as above |
| Both signals | Frontend + Data signals present | Both plugins | Apply both sets of criteria |
---
## Planning Protocol
When creating issues, the planner MUST:
1. **Analyze each issue** for domain signals (check labels AND scan description for keywords)
2. **For Domain/Viz issues**, append this acceptance criteria block:
```markdown
## Design System Compliance
- [ ] All DMC components validated against registry
- [ ] Theme tokens used (no hardcoded colors/sizes)
- [ ] Accessibility check passed (WCAG contrast)
- [ ] Responsive breakpoints verified
```
3. **For Domain/Data issues**, append this acceptance criteria block:
```markdown
## Data Integrity
- [ ] Schema changes validated
- [ ] dbt tests pass
- [ ] Lineage intact (no orphaned models)
- [ ] Data types verified
```
4. **Apply the corresponding `Domain/*` label** to route the issue through gates
5. **Document in planning summary** which issues have domain gates active
---
## Execution Gate Protocol
Before marking any issue as complete, the orchestrator MUST:
1. **Check issue labels** for `Domain/*` labels
2. **If `Domain/Viz` label present:**
- Identify files changed by this issue
- Invoke `/design-gate <path-to-changed-files>`
- Gate PASS → proceed to mark issue complete
- Gate FAIL → add comment to issue with failure details, keep issue open
3. **If `Domain/Data` label present:**
- Identify files changed by this issue
- Invoke `/data-gate <path-to-changed-files>`
- Gate PASS → proceed to mark issue complete
- Gate FAIL → add comment to issue with failure details, keep issue open
4. **If gate command unavailable** (MCP server not running):
- Warn user: "Domain gate unavailable - proceeding without validation"
- Proceed with completion (non-blocking degradation)
- Do NOT silently skip - always inform user
---
## Review Protocol
During code review, the code reviewer SHOULD:
1. After completing standard code quality and security checks, check for `Domain/*` labels
2. **If Domain/Viz:** Include "Design System Compliance" section in review report
- Reference `/design-review` findings if available
- Check for hardcoded colors, invalid props, accessibility issues
3. **If Domain/Data:** Include "Data Integrity" section in review report
- Reference `/data-gate` findings if available
- Check for schema validity, lineage integrity
---
## Extensibility
To add a new domain (e.g., `Domain/Infra` for cmdb-assistant):
1. **In domain plugin:** Create advisory agent + gate command
- Agent: `agents/infra-advisor.md`
- Gate command: `commands/infra-gate.md`
- Audit skill: `skills/infra-audit.md`
2. **In this skill:** Add detection rules to the Detection Rules table above
- Define label-based signals (e.g., `Component/Infrastructure`)
- Define content-based keywords (e.g., "server", "network", "NetBox")
3. **In label taxonomy:** Add `Domain/Infra` label with appropriate color
- Update `plugins/projman/skills/label-taxonomy/labels-reference.md`
4. **No changes needed** to planner.md or orchestrator.md agent files
- They read this skill dynamically
- Detection rules table is the single source of truth
This pattern ensures domain expertise stays in domain plugins while projman orchestrates when to ask.
---
## Domain Acceptance Criteria Templates
### Design System Compliance (Domain/Viz)
```markdown
## Design System Compliance
- [ ] All DMC components validated against registry
- [ ] Theme tokens used (no hardcoded colors/sizes)
- [ ] Accessibility check passed (WCAG contrast)
- [ ] Responsive breakpoints verified
```
### Data Integrity (Domain/Data)
```markdown
## Data Integrity
- [ ] Schema changes validated
- [ ] dbt tests pass
- [ ] Lineage intact (no orphaned models)
- [ ] Data types verified
```
---
## Gate Command Reference
| Domain | Gate Command | Contract | Review Command | Advisory Agent |
|--------|--------------|----------|----------------|----------------|
| Viz | `/design-gate <path>` | v1 | `/design-review <path>` | `design-reviewer` |
| Data | `/data-gate <path>` | v1 | `/data-review <path>` | `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`.

View File

@@ -13,7 +13,7 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
This skill provides the current label taxonomy used for issue classification in Gitea. Labels are **fetched dynamically** from Gitea and should never be hardcoded. This skill provides the current label taxonomy used for issue classification in Gitea. Labels are **fetched dynamically** from Gitea and should never be hardcoded.
**Current Taxonomy:** 49 labels (31 organization + 18 repository) **Current Taxonomy:** 47 labels (31 organization + 16 repository)
## Organization Labels (31) ## Organization Labels (31)
@@ -66,7 +66,7 @@ Organization-level labels are shared across all repositories in your configured
- `Status/Failed` (#de350b) - Implementation attempted but failed, needs investigation - `Status/Failed` (#de350b) - Implementation attempted but failed, needs investigation
- `Status/Deferred` (#6554c0) - Moved to a future sprint or backlog - `Status/Deferred` (#6554c0) - Moved to a future sprint or backlog
## Repository Labels (18) ## Repository Labels (16)
Repository-level labels are specific to each project. Repository-level labels are specific to each project.
@@ -90,39 +90,6 @@ Repository-level labels are specific to each project.
- `Tech/Vue` (#42b883) - Vue.js frontend framework - `Tech/Vue` (#42b883) - Vue.js frontend framework
- `Tech/FastAPI` (#009688) - FastAPI backend 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.
| Label | Color | Description |
|-------|-------|-------------|
| `Domain/Viz` | `#7c4dff` | Issue involves visualization/frontend — triggers viz-platform design gates |
| `Domain/Data` | `#00bfa5` | Issue involves data engineering — triggers data-platform data gates |
**Detection Rules:**
**Domain/Viz:**
- Keywords: "dashboard", "chart", "theme", "DMC", "component", "layout", "responsive", "color", "UI", "frontend", "Dash", "Plotly"
- Also applied when: `Component/Frontend` or `Component/UI` label is present
- Example: "Create new neighbourhood comparison dashboard tab"
**Domain/Data:**
- Keywords: "schema", "migration", "pipeline", "dbt", "table", "column", "query", "PostgreSQL", "lineage", "data model"
- Also applied when: `Component/Database` or `Component/Data` label is present
- Example: "Add census demographic data pipeline"
## Label Suggestion Logic ## Label Suggestion Logic
When suggesting labels for issues, consider the following patterns: When suggesting labels for issues, consider the following patterns:

View File

@@ -138,49 +138,6 @@ 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 ## Sprint Progress Display
``` ```

View File

@@ -11,7 +11,7 @@ Provides templates for RFC wiki pages and defines the required/optional sections
## When to Use ## 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 - **Integration**: Referenced by `rfc-workflow.md` for page structure
--- ---

View File

@@ -12,7 +12,7 @@ Defines the Request for Comments (RFC) system for capturing, reviewing, and trac
## When to Use ## When to Use
- **Planner agent**: When detecting approved RFCs for sprint planning - **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 - **Integration**: With `/sprint-plan` to select approved RFCs for implementation
--- ---
@@ -298,11 +298,11 @@ When RFC status changes:
| Component | How It Uses RFC System | | Component | How It Uses RFC System |
|-----------|------------------------| |-----------|------------------------|
| `/rfc create` | Creates RFC page + updates RFC-Index | | `/rfc-create` | Creates RFC page + updates RFC-Index |
| `/rfc list` | Reads and displays RFC-Index | | `/rfc-list` | Reads and displays RFC-Index |
| `/rfc review` | Transitions Draft -> Review | | `/rfc-review` | Transitions Draft Review |
| `/rfc approve` | Transitions Review -> Approved | | `/rfc-approve` | Transitions Review Approved |
| `/rfc reject` | Transitions Review/Draft -> Rejected | | `/rfc-reject` | Transitions Review/Draft Rejected |
| `/sprint-plan` | Detects Approved RFCs, transitions to Implementing | | `/sprint-plan` | Detects Approved RFCs, transitions to Implementing |
| `/sprint-close` | Transitions Implementing -> Implemented | | `/sprint-close` | Transitions Implementing Implemented |
| `clarity-assist` | Suggests `/rfc create` for feature ideas | | `clarity-assist` | Suggests `/rfc-create` for feature ideas |

View File

@@ -84,17 +84,15 @@ get_milestone(repo="org/repo", milestone_id=17)
### If Approval Missing ### If Approval Missing
``` ```
🔴 SPRINT APPROVAL NOT FOUND — BLOCKED ⚠️ SPRINT APPROVAL NOT FOUND (Warning)
Sprint 17 milestone does not contain an approval record. Sprint 17 milestone does not contain an approval record.
Execution cannot proceed without approval.
Required: Run /sprint-plan first to: Recommended: Run /sprint-plan first to:
1. Review the sprint scope 1. Review the sprint scope
2. Get explicit approval for execution 2. Document the approved execution plan
To override (emergency only): /sprint-start --force Proceeding anyway - consider adding approval for audit trail.
This bypasses the approval gate and logs a warning to the milestone.
``` ```
### If Approval Found ### If Approval Found
@@ -136,16 +134,3 @@ Request re-approval when:
- Scope expansion needed (new files, new branches) - Scope expansion needed (new files, new branches)
- Dependencies change significantly - Dependencies change significantly
- Timeline changes require scope adjustment - 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.

View File

@@ -1,104 +0,0 @@
---
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:** <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]"

View File

@@ -1,101 +0,0 @@
---
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 |

View File

@@ -1,288 +0,0 @@
---
agent: design-reviewer
description: Reviews code for design system compliance using viz-platform MCP tools
triggers:
- /design-review command
- /design-gate command
- projman orchestrator domain gate
---
# Design Reviewer Agent
You are a strict design system compliance auditor. Your role is to review code for proper use of Dash Mantine Components, theme tokens, and accessibility standards.
## Visual Output Requirements
**MANDATORY: Display header at start of every response.**
```
+----------------------------------------------------------------------+
| VIZ-PLATFORM - Design Reviewer |
| [Target Path] |
+----------------------------------------------------------------------+
```
## Trigger Conditions
Activate this agent when:
- User runs `/design-review <path>`
- User runs `/design-gate <path>`
- Projman orchestrator requests design domain gate check
- Code review includes DMC/Dash components
## Skills to Load
- skills/design-system-audit.md
## Available MCP Tools
| Tool | Purpose |
|------|---------|
| `validate_component` | Check DMC component configurations for invalid props |
| `get_component_props` | Retrieve expected props for a component |
| `list_components` | Cross-reference components against DMC registry |
| `theme_validate` | Validate theme configuration |
| `accessibility_validate_colors` | Verify color contrast meets WCAG standards |
| `accessibility_validate_theme` | Full theme accessibility audit |
## Operating Modes
### Review Mode (default)
Triggered by `/design-review <path>`
**Characteristics:**
- Produces detailed report with all findings
- Groups findings by severity (FAIL/WARN/INFO)
- Includes actionable recommendations with code fixes
- Does NOT block - informational only
- Shows theme compliance percentage
### Gate Mode
Triggered by `/design-gate <path>` or projman orchestrator domain gate
**Characteristics:**
- Binary PASS/FAIL output
- Only reports FAIL-level issues
- Returns exit status for automation integration
- Blocks completion on FAIL
- Compact output for CI/CD pipelines
## Audit Workflow
### 1. Receive Target Path
Accept file or directory path from command invocation.
### 2. Scan for DMC Usage
Find relevant files:
```python
# Look for files with DMC imports
import dash_mantine_components as dmc
# Look for component instantiations
dmc.Button(...)
dmc.Card(...)
```
### 3. Component Validation
For each DMC component found:
1. Extract component name and props from code
2. Call `list_components` to verify component exists in registry
3. Call `get_component_props` to get valid prop schema
4. Compare used props against schema
5. **FAIL**: Invalid props, unknown components
6. **WARN**: Deprecated patterns, React-style props
### 4. Theme Compliance Check
Detect hardcoded values that should use theme tokens:
| Pattern | Issue | Recommendation |
|---------|-------|----------------|
| `color="#228be6"` | Hardcoded color | Use `color="blue"` or theme token |
| `color="rgb(34, 139, 230)"` | Hardcoded RGB | Use theme color reference |
| `style={"padding": "16px"}` | Hardcoded size | Use `p="md"` prop |
| `style={"fontSize": "14px"}` | Hardcoded font | Use `size="sm"` prop |
### 5. Accessibility Validation
Check accessibility compliance:
1. Call `accessibility_validate_colors` on detected color pairs
2. Check color contrast ratios (min 4.5:1 for AA)
3. Verify interactive components have accessible labels
4. Flag missing aria-labels on buttons/links
### 6. Generate Report
Output format depends on operating mode.
## Report Formats
### Gate Mode Output
**PASS:**
```
DESIGN GATE: PASS
No blocking design system violations found.
```
**FAIL:**
```
DESIGN GATE: FAIL
Blocking Issues (2):
1. app/pages/home.py:45 - Invalid prop 'onclick' on dmc.Button
Fix: Use 'n_clicks' for click handling
2. app/components/nav.py:12 - Component 'dmc.Navbar' not found
Fix: Use 'dmc.AppShell.Navbar' (DMC v0.14+)
Run /design-review for full audit report.
```
### Review Mode Output
```
+----------------------------------------------------------------------+
| VIZ-PLATFORM - Design Review Report |
| /path/to/project |
+----------------------------------------------------------------------+
Files Scanned: 8
Components Analyzed: 34
Theme Compliance: 78%
## FAIL - Must Fix (2)
### app/pages/home.py:45
**Invalid prop on dmc.Button**
- Found: `onclick=handle_click`
- Valid props: n_clicks, disabled, loading, ...
- Fix: `n_clicks` triggers callback, not `onclick`
### app/components/nav.py:12
**Component not in registry**
- Found: `dmc.Navbar`
- Status: Removed in DMC v0.14
- Fix: Use `dmc.AppShell.Navbar` instead
## WARN - Should Fix (3)
### app/pages/home.py:23
**Hardcoded color**
- Found: `color="#228be6"`
- Recommendation: Use `theme.colors.blue[6]` or `color="blue"`
### app/components/card.py:56
**Hardcoded spacing**
- Found: `style={"padding": "16px"}`
- Recommendation: Use `p="md"` prop instead
### app/layouts/header.py:18
**Low color contrast**
- Foreground: #888888, Background: #ffffff
- Contrast ratio: 3.5:1 (below AA standard of 4.5:1)
- Recommendation: Darken text to #757575 for 4.6:1 ratio
## INFO - Suggestions (2)
### app/components/card.py:8
**Consider more specific component**
- Found: `dmc.Box` used as card container
- Suggestion: `dmc.Paper` provides card semantics and shadow
### app/pages/dashboard.py:92
**Missing aria-label**
- Found: `dmc.ActionIcon` without accessible label
- Suggestion: Add `aria-label="Close"` for screen readers
## Summary
| Severity | Count | Action |
|----------|-------|--------|
| FAIL | 2 | Must fix before merge |
| WARN | 3 | Address in this PR or follow-up |
| INFO | 2 | Optional improvements |
Gate Status: FAIL (2 blocking issues)
```
## Severity Definitions
| Level | Criteria | Action Required |
|-------|----------|-----------------|
| **FAIL** | Invalid props, unknown components, breaking changes | Must fix before merge |
| **WARN** | Hardcoded values, deprecated patterns, contrast issues | Should fix |
| **INFO** | Suboptimal patterns, missing optional attributes | Consider for improvement |
## Common Violations
### FAIL-Level Issues
| Issue | Pattern | Fix |
|-------|---------|-----|
| Invalid prop | `onclick=handler` | Use `n_clicks` + callback |
| Unknown component | `dmc.Navbar` | Use `dmc.AppShell.Navbar` |
| Wrong prop type | `size=12` (int) | Use `size="lg"` (string) |
| Invalid enum value | `variant="primary"` | Use `variant="filled"` |
### WARN-Level Issues
| Issue | Pattern | Fix |
|-------|---------|-----|
| Hardcoded color | `color="#hex"` | Use theme color name |
| Hardcoded size | `padding="16px"` | Use spacing prop |
| Low contrast | ratio < 4.5:1 | Adjust colors |
| React prop pattern | `className` | Use Dash equivalents |
### INFO-Level Issues
| Issue | Pattern | Suggestion |
|-------|---------|------------|
| Generic container | `dmc.Box` for cards | Use `dmc.Paper` |
| Missing aria-label | Interactive without label | Add accessible name |
| Inline styles | `style={}` overuse | Use component props |
## Error Handling
| Error | Response |
|-------|----------|
| MCP server unavailable | Report error, suggest checking viz-platform MCP setup |
| No DMC files found | "No Dash Mantine Components detected in target path" |
| Invalid path | "Path not found: {path}" |
| Empty directory | "No Python files found in {path}" |
## Integration with Projman
When called as a domain gate by projman orchestrator:
1. Receive path from orchestrator
2. Run audit in gate mode
3. Return structured result:
```json
{
"gate": "design",
"status": "PASS|FAIL",
"blocking_count": 0,
"summary": "No violations found"
}
```
4. Orchestrator decides whether to proceed based on gate status
## Example Interactions
**User**: `/design-review src/pages/`
**Agent**:
1. Scans all .py files in src/pages/
2. Identifies DMC component usage
3. Validates each component with MCP tools
4. Checks theme token usage
5. Runs accessibility validation
6. Returns full review report
**User**: `/design-gate src/`
**Agent**:
1. Scans all .py files
2. Identifies FAIL-level issues only
3. Returns PASS if clean, FAIL with blocking issues if not
4. Compact output for pipeline integration

View File

@@ -1,94 +0,0 @@
---
description: Design system compliance gate (pass/fail) for sprint execution
gate_contract: v1
arguments:
- name: path
description: File or directory to validate
required: true
---
# /design-gate
Binary pass/fail validation for design system compliance. Used by projman orchestrator during sprint execution to gate issue completion.
## Usage
```
/design-gate <path>
```
**Examples:**
```
/design-gate ./app/pages/dashboard.py
/design-gate ./app/components/
```
## What It Does
1. **Activates** the `design-reviewer` agent in gate mode
2. **Loads** the `skills/design-system-audit.md` skill
3. **Scans** target path for DMC usage
4. **Checks only for FAIL-level violations:**
- Invalid component props
- Non-existent components
- Missing required props
- Deprecated components
5. **Returns binary result:**
- `PASS` - No blocking violations found
- `FAIL` - One or more blocking violations
## Output
### On PASS
```
DESIGN GATE: PASS
No blocking design system violations found.
```
### On FAIL
```
DESIGN GATE: FAIL
Blocking Issues (2):
1. app/pages/home.py:45 - Invalid prop 'onclick' on dmc.Button
Fix: Use 'n_clicks' for click handling
2. app/components/nav.py:12 - Component 'dmc.Navbar' not found
Fix: Use 'dmc.AppShell.Navbar' (DMC v0.14+)
Run /design-review for full audit report.
```
## Integration with projman
This command is automatically invoked by the projman orchestrator when:
1. An issue has the `Domain/Viz` label
2. The orchestrator is about to mark the issue as complete
3. The orchestrator passes the path of changed files
**Gate behavior:**
- PASS → Issue can be marked complete
- FAIL → Issue stays open, blocker comment added
## Differences from /design-review
| Aspect | /design-gate | /design-review |
|--------|--------------|----------------|
| Output | Binary PASS/FAIL | Detailed report |
| Severity | FAIL only | FAIL + WARN + INFO |
| Purpose | Automation gate | Human review |
| Verbosity | Minimal | Comprehensive |
## When to Use
- **Automated pipelines**: CI/CD design system checks
- **Sprint execution**: Automatic quality gates
- **Quick validation**: Fast pass/fail without full report
For detailed findings, use `/design-review` instead.
## Requirements
- viz-platform MCP server must be running
- Target path must exist

View File

@@ -1,70 +0,0 @@
---
description: Audit codebase for design system compliance
arguments:
- name: path
description: File or directory to audit
required: true
---
# /design-review
Scans target path for Dash Mantine Components usage and validates against design system standards.
## Usage
```
/design-review <path>
```
**Examples:**
```
/design-review ./app/pages/
/design-review ./app/components/dashboard.py
/design-review .
```
## What It Does
1. **Activates** the `design-reviewer` agent in review mode
2. **Loads** the `skills/design-system-audit.md` skill
3. **Scans** target path for:
- Python files with DMC imports
- Component instantiations and their props
- Style dictionaries and color values
- Accessibility attributes
4. **Validates** against:
- DMC component registry (valid components and props)
- Theme token usage (no hardcoded colors/sizes)
- Accessibility standards (contrast, ARIA labels)
5. **Produces** detailed report grouped by severity
## Output
Generates a comprehensive audit report with:
- **FAIL**: Invalid props, deprecated components, missing required props
- **WARN**: Hardcoded colors/sizes, missing accessibility attributes
- **INFO**: Optimization suggestions, consistency recommendations
Each finding includes:
- File path and line number
- Description of the issue
- Recommended fix
## When to Use
- **Before PR review**: Catch design system violations early
- **On existing codebases**: Audit for compliance gaps
- **During refactoring**: Ensure changes maintain compliance
- **Learning**: Understand design system best practices
## Related Commands
- `/design-gate` - Binary pass/fail for sprint execution (no detailed report)
- `/component` - Inspect individual DMC component props
- `/theme` - Check active theme configuration
## Requirements
- viz-platform MCP server must be running
- Target path must contain Python files with DMC usage

View File

@@ -1,280 +0,0 @@
---
name: design-system-audit
description: Design system compliance rules and violation patterns for viz-platform audits
---
# Design System Audit
## Purpose
Defines what to check, how to classify violations, and common patterns for design system compliance auditing of Dash Mantine Components (DMC) code.
---
## What to Check
### 1. Component Prop Validity
| Check | Tool | Severity |
|-------|------|----------|
| Invalid prop names (typos) | `validate_component` | FAIL |
| Invalid prop values | `validate_component` | FAIL |
| Missing required props | `validate_component` | FAIL |
| Deprecated props | `get_component_props` | WARN |
| Unknown props | `validate_component` | WARN |
### 2. Theme Token Usage
| Check | Detection | Severity |
|-------|-----------|----------|
| Hardcoded hex colors | Regex `#[0-9a-fA-F]{3,6}` | WARN |
| Hardcoded RGB/RGBA | Regex `rgb\(` | WARN |
| Hardcoded font sizes | Regex `fontSize=\d+` | WARN |
| Hardcoded spacing | Regex `margin=\d+|padding=\d+` | INFO |
| Missing theme provider | AST analysis | FAIL |
**Allowed exceptions:**
- Colors in theme definition files
- Test/fixture files
- Comments and documentation
### 3. Accessibility Compliance
| Check | Tool | Severity |
|-------|------|----------|
| Color contrast ratio < 4.5:1 (AA) | `accessibility_validate_colors` | WARN |
| Color contrast ratio < 3:1 (large text) | `accessibility_validate_colors` | WARN |
| Missing aria-label on interactive | Manual scan | WARN |
| Color-only information | `accessibility_validate_theme` | WARN |
| Focus indicator missing | Manual scan | INFO |
### 4. Responsive Design
| Check | Detection | Severity |
|-------|-----------|----------|
| Fixed pixel widths > 600px | Regex `width=\d{3,}` | INFO |
| Missing breakpoint handling | No `visibleFrom`/`hiddenFrom` | INFO |
| Non-responsive layout | Fixed Grid columns | INFO |
---
## Common Violations
### FAIL-Level Violations
```python
# Invalid prop name (typo)
dmc.Button(colour="blue") # Should be 'color'
# Invalid enum value
dmc.Button(size="large") # Should be 'lg'
# Missing required prop
dmc.Select(data=[...]) # Missing 'id' for callbacks
# Invalid component name
dmc.Buttons(...) # Should be 'Button'
# Wrong case
dmc.Button(fullwidth=True) # Should be 'fullWidth'
# React patterns in Dash
dmc.Button(onClick=fn) # Should use 'id' + callback
```
### WARN-Level Violations
```python
# Hardcoded colors
dmc.Text(color="#ff0000") # Use theme token
dmc.Button(style={"color": "red"}) # Use theme token
# Hardcoded font size
dmc.Text(style={"fontSize": "14px"}) # Use 'size' prop
# Poor contrast
dmc.Text(color="gray") # Check contrast ratio
# Inline styles for colors
dmc.Container(style={"backgroundColor": "#f0f0f0"})
# Deprecated patterns
dmc.Button(variant="subtle") # Check if still supported
```
### INFO-Level Violations
```python
# Fixed widths
dmc.Container(w=800) # Consider responsive
# Missing responsive handling
dmc.Grid.Col(span=6) # Consider span={{ base: 12, md: 6 }}
# Optimization opportunity
dmc.Stack([dmc.Text(...) for _ in range(100)]) # Consider virtualization
```
---
## Severity Classification
| Level | Icon | Meaning | Action |
|-------|------|---------|--------|
| **FAIL** | Red circle | Blocking issue, will cause runtime error | Must fix before completion |
| **WARN** | Orange circle | Quality issue, violates best practices | Should fix, may be waived |
| **INFO** | Yellow circle | Suggestion for improvement | Consider for future |
### Severity Decision Tree
```
Is it invalid syntax/props?
YES -> FAIL
NO -> Does it violate accessibility standards?
YES -> WARN
NO -> Does it use hardcoded styles?
YES -> WARN
NO -> Is it a best practice suggestion?
YES -> INFO
NO -> Not a violation
```
---
## Scanning Strategy
### File Types to Scan
| Extension | Priority | Check For |
|-----------|----------|-----------|
| `*.py` | High | DMC component usage |
| `*.dash.py` | High | Layout definitions |
| `theme*.py` | High | Theme configuration |
| `layout*.py` | High | Layout structure |
| `components/*.py` | High | Custom components |
| `callbacks/*.py` | Medium | Component references |
### Scan Process
1. **Find relevant files**
```
glob: **/*.py
filter: Contains 'dmc.' or 'dash_mantine_components'
```
2. **Extract component usages**
- Parse Python AST
- Find all `dmc.*` calls
- Extract component name and kwargs
3. **Validate each component**
- Call `validate_component(name, props)`
- Record violations with file:line reference
4. **Scan for patterns**
- Hardcoded colors (regex)
- Inline styles (AST)
- Fixed dimensions (regex)
5. **Run accessibility checks**
- Extract color combinations
- Call `accessibility_validate_colors`
---
## Report Template
```
Design System Audit Report
==========================
Path: <scanned-path>
Files Scanned: N
Timestamp: YYYY-MM-DD HH:MM:SS
Summary
-------
FAIL: N blocking violations
WARN: N quality warnings
INFO: N suggestions
Findings
--------
FAIL Violations (must fix)
--------------------------
[file.py:42] Invalid prop 'colour' on Button
Found: colour="blue"
Expected: color="blue"
Docs: https://mantine.dev/core/button
[file.py:58] Invalid size value on Text
Found: size="huge"
Expected: One of ['xs', 'sm', 'md', 'lg', 'xl']
WARN Violations (should fix)
----------------------------
[theme.py:15] Hardcoded color detected
Found: color="#ff0000"
Suggestion: Use theme color token (e.g., color="red")
[layout.py:23] Low contrast ratio (3.2:1)
Found: Text on background
Required: 4.5:1 for WCAG AA
Suggestion: Darken text or lighten background
INFO Suggestions
----------------
[dashboard.py:100] Consider responsive breakpoints
Found: span=6 (fixed)
Suggestion: span={{ base: 12, md: 6 }}
Files Scanned
-------------
- src/components/button.py (3 components)
- src/layouts/main.py (8 components)
- src/theme.py (1 theme config)
Gate Result: PASS | FAIL
```
---
## Integration with MCP Tools
### Required Tools
| Tool | Purpose | When Used |
|------|---------|-----------|
| `validate_component` | Check component props | Every component found |
| `get_component_props` | Get expected props | When suggesting fixes |
| `list_components` | Verify component exists | Unknown component names |
| `theme_validate` | Validate theme config | Theme files |
| `accessibility_validate_colors` | Check contrast | Color combinations |
| `accessibility_validate_theme` | Full a11y audit | Theme files |
### Tool Call Pattern
```
For each Python file:
For each dmc.Component(...) found:
result = validate_component(
component_name="Component",
props={extracted_props}
)
if result.errors:
record FAIL violation
if result.warnings:
record WARN violation
```
---
## Skip Patterns
Do not flag violations in:
- `**/tests/**` - Test files may have intentional violations
- `**/__pycache__/**` - Compiled files
- `**/fixtures/**` - Test fixtures
- Files with `# noqa: design-audit` comment
- Theme definition files (colors are expected there)

View File

@@ -278,7 +278,7 @@ print_report() {
# --- Main --- # --- Main ---
main() { main() {
echo "==============================================" echo "=============================================="
echo " Leo Claude Marketplace Setup (v5.7.1)" echo " Leo Claude Marketplace Setup (v5.1.0)"
echo "==============================================" echo "=============================================="
echo "" echo ""