docs(marketplace): documentation cleanup, version alignment, architecture doc
- Delete orphan files (.doc-guardian-queue, stale backup, switch-profile.sh) - Delete stale doc folders (architecture/, designs/, prompts/) - Create consolidated docs/ARCHITECTURE.md for v9.1.0 - Bump all 12 original plugin versions to 9.0.1 - Fix project-hygiene descriptions (no longer a hook) - Normalize /rfc, /project, /adr command rows in all docs - Update CANONICAL-PATHS.md, UPDATING.md, README.md, CLAUDE.md - COMMANDS-CHEATSHEET.md expanded to one row per sub-command Version: 9.1.0 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
184
docs/ARCHITECTURE.md
Normal file
184
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Architecture — Leo Claude Marketplace v9.1.0
|
||||
|
||||
## Overview
|
||||
|
||||
Plugin marketplace for Claude Code. 20 plugins across 5 domains, 5 shared MCP servers,
|
||||
4 PreToolUse safety hooks + 1 UserPromptSubmit quality hook.
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Plugin Domains
|
||||
|
||||
| Domain | Purpose | Plugins |
|
||||
|--------|---------|---------|
|
||||
| core | Development workflow | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist, contract-validator, claude-config-maintainer, project-hygiene |
|
||||
| data | Data engineering | data-platform, viz-platform, data-seed |
|
||||
| saas | SaaS development | saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot |
|
||||
| ops | Operations | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
|
||||
| debug | Diagnostics | debug-mcp |
|
||||
|
||||
### MCP Servers (Shared at Root)
|
||||
|
||||
| Server | Plugins Using It | External System |
|
||||
|--------|-------------------|-----------------|
|
||||
| gitea | projman, pr-review | Gitea (issues, PRs, wiki) |
|
||||
| netbox | cmdb-assistant | NetBox (DCIM, IPAM) |
|
||||
| data-platform | data-platform | PostgreSQL, dbt |
|
||||
| viz-platform | viz-platform | DMC registry |
|
||||
| contract-validator | contract-validator | (internal validation) |
|
||||
|
||||
### Hook Architecture
|
||||
|
||||
| Plugin | Event | Trigger | Script |
|
||||
|--------|-------|---------|--------|
|
||||
| code-sentinel | PreToolUse | Write\|Edit\|MultiEdit | security-check.sh |
|
||||
| git-flow | PreToolUse | Bash (branch naming) | branch-check.sh |
|
||||
| git-flow | PreToolUse | Bash (git commit) | commit-msg-check.sh |
|
||||
| cmdb-assistant | PreToolUse | MCP create/update | validate-input.sh |
|
||||
| clarity-assist | UserPromptSubmit | All prompts | vagueness-check.sh |
|
||||
|
||||
No other hook types permitted. All workflow automation is via explicit commands.
|
||||
|
||||
### Agent Model (projman)
|
||||
|
||||
| Agent | Model | Permission Mode | Role |
|
||||
|-------|-------|-----------------|------|
|
||||
| Planner | opus | default | Sprint planning, architecture analysis, issue creation |
|
||||
| Orchestrator | sonnet | acceptEdits | Sprint execution, parallel batching, lesson capture |
|
||||
| Executor | sonnet | bypassPermissions | Code implementation, branch management |
|
||||
| Code Reviewer | opus | default | Pre-close quality review, security, tests |
|
||||
|
||||
### Config Hierarchy
|
||||
|
||||
| Level | Location | Contains |
|
||||
|-------|----------|----------|
|
||||
| System | ~/.config/claude/{service}.env | Credentials |
|
||||
| Project | .env in project root | Repo-specific config |
|
||||
|
||||
### Branch Security
|
||||
|
||||
| Pattern | Access |
|
||||
|---------|--------|
|
||||
| development, feat/*, fix/* | Full |
|
||||
| staging, stage/* | Read-only code, can create issues |
|
||||
| main, master, prod/* | READ-ONLY. Emergency only. |
|
||||
|
||||
### Launch Profiles
|
||||
|
||||
| Profile | Plugins |
|
||||
|---------|---------|
|
||||
| sprint | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist |
|
||||
| data | data-platform, viz-platform, data-seed |
|
||||
| saas | saas-api-platform, saas-react-platform, saas-db-migrate, saas-test-pilot |
|
||||
| ops | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
|
||||
| review | pr-review, code-sentinel |
|
||||
| debug | debug-mcp |
|
||||
| full | all plugins |
|
||||
|
||||
---
|
||||
|
||||
## Plugin Reference
|
||||
|
||||
### Core Domain
|
||||
|
||||
#### projman (v9.0.1)
|
||||
Sprint planning and project management with Gitea integration.
|
||||
- **Commands:** /sprint (plan|start|status|close|review|test), /project (initiation|plan|status|close), /adr (create|list|update|supersede), /rfc (create|list|review|approve|reject), /labels sync, /projman setup
|
||||
- **Agents:** planner, orchestrator, executor, code-reviewer
|
||||
- **MCP:** gitea
|
||||
|
||||
#### git-flow (v9.0.1)
|
||||
Git workflow automation with smart commits and branch management.
|
||||
- **Commands:** /gitflow (commit|branch-start|branch-cleanup|status|config)
|
||||
- **Commit flags:** --push, --merge, --sync
|
||||
- **Agents:** git-assistant
|
||||
- **Hooks:** PreToolUse (branch-check.sh, commit-msg-check.sh)
|
||||
|
||||
#### pr-review (v9.0.1)
|
||||
Multi-agent PR review with confidence scoring.
|
||||
- **Commands:** /pr (review|summary|findings|diff|setup|init|sync)
|
||||
- **Agents:** coordinator, security-reviewer, performance-analyst, maintainability-auditor, test-validator
|
||||
- **MCP:** gitea
|
||||
|
||||
#### code-sentinel (v9.0.1)
|
||||
Security scanning and code refactoring.
|
||||
- **Commands:** /sentinel (scan|refactor|refactor-dry)
|
||||
- **Agents:** security-reviewer, refactor-advisor
|
||||
- **Hooks:** PreToolUse (security-check.sh)
|
||||
|
||||
#### doc-guardian (v9.0.1)
|
||||
Documentation drift detection and synchronization.
|
||||
- **Commands:** /doc (audit|sync|changelog-gen|coverage|stale-docs)
|
||||
- **Agents:** doc-analyzer
|
||||
|
||||
#### clarity-assist (v9.0.1)
|
||||
Prompt optimization with ND-friendly accommodations.
|
||||
- **Commands:** /clarity (clarify|quick-clarify)
|
||||
- **Agents:** clarity-coach
|
||||
- **Hooks:** UserPromptSubmit (vagueness-check.sh)
|
||||
|
||||
#### contract-validator (v9.0.1)
|
||||
Cross-plugin compatibility validation.
|
||||
- **Commands:** /cv (validate|check-agent|list-interfaces|dependency-graph|setup|status)
|
||||
- **Agents:** full-validation, agent-check
|
||||
- **MCP:** contract-validator
|
||||
|
||||
#### claude-config-maintainer (v9.0.1)
|
||||
CLAUDE.md and settings optimization.
|
||||
- **Commands:** /claude-config (analyze|optimize|init|diff|lint|audit-settings|optimize-settings|permissions-map)
|
||||
- **Agents:** maintainer
|
||||
|
||||
#### project-hygiene (v9.0.1)
|
||||
Manual project file cleanup checks.
|
||||
- **Commands:** /hygiene check (--fix flag for auto-fix)
|
||||
|
||||
### Data Domain
|
||||
|
||||
#### data-platform (v9.0.1)
|
||||
pandas, PostgreSQL, and dbt integration.
|
||||
- **Commands:** /data (ingest|profile|schema|explain|lineage|lineage-viz|run|dbt-test|quality|review|gate|setup)
|
||||
- **Agents:** data-advisor, data-analysis, data-ingestion
|
||||
- **MCP:** data-platform
|
||||
|
||||
#### viz-platform (v9.0.1)
|
||||
DMC validation, Plotly charts, and theming.
|
||||
- **Commands:** /viz (setup|chart|chart-export|dashboard|theme|theme-new|theme-css|component|accessibility-check|breakpoints|design-review|design-gate)
|
||||
- **Agents:** design-reviewer, layout-builder, component-check, theme-setup
|
||||
- **MCP:** viz-platform
|
||||
|
||||
#### data-seed (v0.1.0)
|
||||
Test data generation and database seeding. *Scaffold — not yet implemented.*
|
||||
|
||||
### SaaS Domain
|
||||
|
||||
#### saas-api-platform (v0.1.0)
|
||||
REST/GraphQL API scaffolding for FastAPI and Express. *Scaffold.*
|
||||
|
||||
#### saas-db-migrate (v0.1.0)
|
||||
Database migration management for Alembic, Prisma, raw SQL. *Scaffold.*
|
||||
|
||||
#### saas-react-platform (v0.1.0)
|
||||
React frontend toolkit for Next.js and Vite. *Scaffold.*
|
||||
|
||||
#### saas-test-pilot (v0.1.0)
|
||||
Test automation for pytest, Jest, Vitest, Playwright. *Scaffold.*
|
||||
|
||||
### Ops Domain
|
||||
|
||||
#### cmdb-assistant (v9.0.1)
|
||||
NetBox CMDB integration for infrastructure management.
|
||||
- **Commands:** /cmdb (search|device|ip|site|audit|register|sync|topology|change-audit|ip-conflicts|setup)
|
||||
- **Agents:** cmdb-assistant
|
||||
- **MCP:** netbox
|
||||
- **Hooks:** PreToolUse (validate-input.sh)
|
||||
|
||||
#### ops-release-manager (v0.1.0)
|
||||
Release management with SemVer and changelog automation. *Scaffold.*
|
||||
|
||||
#### ops-deploy-pipeline (v0.1.0)
|
||||
Deployment pipeline for Docker Compose and systemd. *Scaffold.*
|
||||
|
||||
### Debug Domain
|
||||
|
||||
#### debug-mcp (v0.1.0)
|
||||
MCP server debugging and diagnostics. *Scaffold.*
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
|
||||
|
||||
Last Updated: 2026-02-06 (v8.0.0)
|
||||
Last Updated: 2026-02-07 (v9.1.0)
|
||||
|
||||
---
|
||||
|
||||
@@ -19,17 +19,13 @@ leo-claude-mktplace/
|
||||
├── .mcp-full.json # Full profile MCP config (all servers)
|
||||
├── .scratch/ # Transient work (auto-cleaned)
|
||||
├── docs/ # All documentation
|
||||
│ ├── architecture/ # Draw.io diagrams and specs
|
||||
│ ├── prompts/ # Shared prompt templates
|
||||
│ │ └── INDEX.md # Prompt template index
|
||||
│ ├── project-lessons-learned/ # Project-level lessons (not sprint-specific)
|
||||
│ │ └── INDEX.md # Lessons index
|
||||
│ ├── ARCHITECTURE.md # System architecture and plugin reference
|
||||
│ ├── CANONICAL-PATHS.md # This file - single source of truth
|
||||
│ ├── COMMANDS-CHEATSHEET.md # All commands quick reference
|
||||
│ ├── CONFIGURATION.md # Centralized configuration guide
|
||||
│ ├── DEBUGGING-CHECKLIST.md # Systematic troubleshooting guide
|
||||
│ ├── MIGRATION-v9.md # v8.x → v9.0.0 migration guide
|
||||
│ └── UPDATING.md # Update guide
|
||||
├── hooks/ # Shared hooks (if any)
|
||||
├── mcp-servers/ # SHARED MCP servers (v3.0.0+)
|
||||
│ ├── gitea/ # Gitea MCP server
|
||||
│ │ ├── mcp_server/
|
||||
@@ -90,7 +86,6 @@ leo-claude-mktplace/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── doc-guardian/ # Documentation drift detection
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
@@ -114,7 +109,7 @@ leo-claude-mktplace/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── project-hygiene/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── commands/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── clarity-assist/
|
||||
│ │ ├── .claude-plugin/
|
||||
@@ -138,18 +133,64 @@ leo-claude-mktplace/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── contract-validator/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ └── viz-platform/
|
||||
│ ├── viz-platform/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── saas-api-platform/ # REST/GraphQL API scaffolding (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── saas-db-migrate/ # Database migration management (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── saas-react-platform/ # React frontend toolkit (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── saas-test-pilot/ # Test automation (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── data-seed/ # Test data generation (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── ops-release-manager/ # Release management (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── ops-deploy-pipeline/ # Deployment pipeline (scaffold)
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ └── debug-mcp/ # MCP debugging toolkit (scaffold)
|
||||
│ ├── .claude-plugin/
|
||||
│ ├── commands/
|
||||
│ ├── agents/
|
||||
│ ├── hooks/
|
||||
│ ├── skills/
|
||||
│ └── claude-md-integration.md
|
||||
├── scripts/ # Setup and maintenance scripts
|
||||
│ ├── setup.sh # Initial setup (create venvs, config templates)
|
||||
@@ -159,8 +200,7 @@ leo-claude-mktplace/
|
||||
│ ├── verify-hooks.sh # Verify all hooks use correct event types
|
||||
│ ├── setup-venvs.sh # Setup MCP server venvs (create only, never delete)
|
||||
│ ├── release.sh # Release automation with version bumping
|
||||
│ ├── claude-launch.sh # Task-specific launcher with profile selection
|
||||
│ └── switch-profile.sh # DEPRECATED: use claude-launch.sh instead
|
||||
│ └── claude-launch.sh # Task-specific launcher with profile selection
|
||||
├── CLAUDE.md
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
@@ -260,12 +300,13 @@ fi
|
||||
|
||||
| Type | Location |
|
||||
|------|----------|
|
||||
| Architecture diagrams | `docs/architecture/` |
|
||||
| Architecture & plugin reference | `docs/ARCHITECTURE.md` |
|
||||
| This file | `docs/CANONICAL-PATHS.md` |
|
||||
| Update guide | `docs/UPDATING.md` |
|
||||
| Configuration guide | `docs/CONFIGURATION.md` |
|
||||
| Commands cheat sheet | `docs/COMMANDS-CHEATSHEET.md` |
|
||||
| Debugging checklist | `docs/DEBUGGING-CHECKLIST.md` |
|
||||
| Migration guide (v8→v9) | `docs/MIGRATION-v9.md` |
|
||||
|
||||
---
|
||||
|
||||
@@ -355,10 +396,10 @@ Both manifest files require a `domain` field (v8.0.0+):
|
||||
| Domain | Purpose | Existing Plugins |
|
||||
|--------|---------|-----------------|
|
||||
| `core` | Development workflow plugins | projman, git-flow, pr-review, code-sentinel, doc-guardian, clarity-assist, contract-validator, claude-config-maintainer, project-hygiene |
|
||||
| `data` | Data engineering and visualization | data-platform, viz-platform |
|
||||
| `ops` | Operations and infrastructure | cmdb-assistant |
|
||||
| `saas` | SaaS application development | (Phase 2) |
|
||||
| `debug` | Debugging and diagnostics | (Phase 2) |
|
||||
| `data` | Data engineering and visualization | data-platform, viz-platform, data-seed |
|
||||
| `ops` | Operations and infrastructure | cmdb-assistant, ops-release-manager, ops-deploy-pipeline |
|
||||
| `saas` | SaaS application development | saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot |
|
||||
| `debug` | Debugging and diagnostics | debug-mcp |
|
||||
|
||||
### Plugin Naming Convention
|
||||
|
||||
@@ -376,25 +417,13 @@ jq '.plugins[] | select(.domain=="saas") | .name' .claude-plugin/marketplace.jso
|
||||
jq '[.plugins[] | .domain] | group_by(.) | map({domain: .[0], count: length})' .claude-plugin/marketplace.json
|
||||
```
|
||||
|
||||
### Future Plugin Path Patterns
|
||||
|
||||
```
|
||||
plugins/saas-api-platform/
|
||||
plugins/saas-db-migrate/
|
||||
plugins/saas-react-platform/
|
||||
plugins/saas-test-pilot/
|
||||
plugins/data-seed/
|
||||
plugins/ops-release-manager/
|
||||
plugins/ops-deploy-pipeline/
|
||||
plugins/debug-mcp/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Change Log
|
||||
|
||||
| Date | Change | By |
|
||||
|------|--------|-----|
|
||||
| 2026-02-07 | v9.1.0: Removed deleted dirs (architecture/, prompts/, project-lessons-learned/), added Phase 3 plugins, added ARCHITECTURE.md, MIGRATION-v9.md, updated Domain table, removed stale hooks/ dirs | Claude Code |
|
||||
| 2026-02-06 | v8.0.0: Added domain metadata section, Phase 1a paths, future plugin paths | Claude Code |
|
||||
| 2026-02-04 | v7.1.0: Added profile configs, prompts/, project-lessons-learned/, metadata.json, deprecated switch-profile.sh | Claude Code |
|
||||
| 2026-01-30 | v5.5.0: Removed plugin-level mcp-servers symlinks - all MCP config now in root .mcp.json | Claude Code |
|
||||
|
||||
@@ -18,9 +18,19 @@ All commands follow the `/<noun> <action>` sub-command pattern.
|
||||
| **projman** | `/sprint close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
|
||||
| **projman** | `/labels sync` | | X | Synchronize label taxonomy from Gitea |
|
||||
| **projman** | `/projman setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` |
|
||||
| **projman** | `/rfc create\|list\|review\|approve\|reject` | | X | RFC lifecycle management |
|
||||
| **projman** | `/project initiation\|plan\|status\|close` | | X | Project lifecycle management |
|
||||
| **projman** | `/adr create\|list\|update\|supersede` | | X | Architecture Decision Records |
|
||||
| **projman** | `/rfc create` | | X | Create new RFC from conversation or spec |
|
||||
| **projman** | `/rfc list` | | X | List all RFCs grouped by status |
|
||||
| **projman** | `/rfc review` | | X | Submit RFC for maintainer review |
|
||||
| **projman** | `/rfc approve` | | X | Approve RFC for sprint planning |
|
||||
| **projman** | `/rfc reject` | | X | Reject RFC with documented reason |
|
||||
| **projman** | `/project initiation` | | X | Discovery, source analysis, project charter |
|
||||
| **projman** | `/project plan` | | X | WBS, risk register, sprint roadmap |
|
||||
| **projman** | `/project status` | | X | Project health check across all sprints |
|
||||
| **projman** | `/project close` | | X | Final retrospective and archival |
|
||||
| **projman** | `/adr create` | | X | Create new Architecture Decision Record |
|
||||
| **projman** | `/adr list` | | X | List all ADRs with status |
|
||||
| **projman** | `/adr update` | | X | Update existing ADR |
|
||||
| **projman** | `/adr supersede` | | X | Supersede ADR with new decision |
|
||||
| **git-flow** | `/gitflow commit` | | X | Create commit with auto-generated conventional message. Flags: `--push`, `--merge`, `--sync` |
|
||||
| **git-flow** | `/gitflow branch-start` | | X | Create new feature/fix/chore branch with naming conventions |
|
||||
| **git-flow** | `/gitflow branch-cleanup` | | X | Remove merged branches locally and optionally on remote |
|
||||
|
||||
@@ -38,7 +38,7 @@ cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
|
||||
|
||||
## What the Post-Update Script Does
|
||||
|
||||
1. **Updates Python dependencies** for MCP servers (gitea, netbox)
|
||||
1. **Updates Python dependencies** for all 5 MCP servers (gitea, netbox, data-platform, viz-platform, contract-validator)
|
||||
2. **Shows recent changelog entries** so you know what changed
|
||||
3. **Validates your configuration** is still compatible
|
||||
|
||||
@@ -157,10 +157,11 @@ cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
|
||||
If that doesn't work:
|
||||
|
||||
1. Check Python version: `python3 --version` (requires 3.10+)
|
||||
2. Verify venv exists in INSTALLED location:
|
||||
2. Verify venvs exist in INSTALLED location:
|
||||
```bash
|
||||
ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/gitea/.venv
|
||||
ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/netbox/.venv
|
||||
for server in gitea netbox data-platform viz-platform contract-validator; do
|
||||
ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/$server/.venv && echo "$server: OK" || echo "$server: MISSING"
|
||||
done
|
||||
```
|
||||
3. If missing, run setup.sh as shown above.
|
||||
4. Restart Claude Code session
|
||||
|
||||
@@ -1,271 +0,0 @@
|
||||
# Agent Workflow - Draw.io Specification
|
||||
|
||||
**Target File:** `docs/architecture/agent-workflow.drawio`
|
||||
|
||||
**Purpose:** Shows when Planner, Orchestrator, Executor, and Code Reviewer agents trigger during sprint lifecycle.
|
||||
|
||||
**Diagram Type:** Swimlane / Sequence Diagram
|
||||
|
||||
---
|
||||
|
||||
## SWIMLANES
|
||||
|
||||
| ID | Label | Color | Position |
|
||||
|----|-------|-------|----------|
|
||||
| user-lane | User | #E3F2FD | 1 (leftmost) |
|
||||
| planner-lane | Planner Agent | #4A90D9 | 2 |
|
||||
| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
|
||||
| executor-lane | Executor Agent | #FF9800 | 4 |
|
||||
| reviewer-lane | Code Reviewer Agent | #9C27B0 | 5 |
|
||||
| gitea-lane | Gitea (Issues + Wiki) | #9E9E9E | 6 (rightmost) |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 1: SPRINT PLANNING
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p1-start | /sprint plan | rounded-rect | user-lane | 1 |
|
||||
| p1-activate | Planner Activates | rectangle | planner-lane | 2 |
|
||||
| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
|
||||
| p1-gitea-wiki-query | Query Past Lessons (Wiki) | rectangle | gitea-lane | 4 |
|
||||
| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
|
||||
| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
|
||||
| p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
|
||||
| p1-create-issues | Create Issues with Labels | rectangle | planner-lane | 8 |
|
||||
| p1-gitea-create | Store Issues | rectangle | gitea-lane | 9 |
|
||||
| p1-plan-complete | Planning Complete | rounded-rect | planner-lane | 10 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p1-start | p1-activate | invokes | solid |
|
||||
| p1-activate | p1-search-lessons | | solid |
|
||||
| p1-search-lessons | p1-gitea-wiki-query | REST API (search_lessons) | solid |
|
||||
| p1-gitea-wiki-query | p1-return-lessons | lessons data | dashed |
|
||||
| p1-return-lessons | p1-clarify | | solid |
|
||||
| p1-clarify | p1-user-answers | questions | solid |
|
||||
| p1-user-answers | p1-clarify | answers | dashed |
|
||||
| p1-clarify | p1-create-issues | | solid |
|
||||
| p1-create-issues | p1-gitea-create | REST API | solid |
|
||||
| p1-gitea-create | p1-plan-complete | confirm | dashed |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 2: SPRINT EXECUTION
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p2-start | /sprint start | rounded-rect | user-lane | 11 |
|
||||
| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
|
||||
| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
|
||||
| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
|
||||
| p2-sequence | Sequence Work (Dependencies) | rectangle | orchestrator-lane | 15 |
|
||||
| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
|
||||
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
|
||||
| p2-implement | Implement Task | rectangle | executor-lane | 18 |
|
||||
| p2-update-status | Update Issue Status | rectangle | executor-lane | 19 |
|
||||
| p2-gitea-update | Update Issue | rectangle | gitea-lane | 20 |
|
||||
| p2-report | Report Completion | rectangle | executor-lane | 21 |
|
||||
| p2-loop | More Tasks? | diamond | orchestrator-lane | 22 |
|
||||
| p2-exec-complete | Execution Complete | rounded-rect | orchestrator-lane | 23 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p2-start | p2-orch-activate | invokes | solid |
|
||||
| p2-orch-activate | p2-fetch-issues | | solid |
|
||||
| p2-fetch-issues | p2-gitea-list | REST API | solid |
|
||||
| p2-gitea-list | p2-sequence | issues data | dashed |
|
||||
| p2-sequence | p2-dispatch | parallel batching | solid |
|
||||
| p2-dispatch | p2-exec-activate | execution prompt | solid |
|
||||
| p2-exec-activate | p2-implement | | solid |
|
||||
| p2-implement | p2-update-status | | solid |
|
||||
| p2-update-status | p2-gitea-update | REST API | solid |
|
||||
| p2-gitea-update | p2-report | confirm | dashed |
|
||||
| p2-report | p2-loop | | solid |
|
||||
| p2-loop | p2-dispatch | yes | solid |
|
||||
| p2-loop | p2-exec-complete | no | solid |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 2.5: CODE REVIEW (Pre-Close)
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p25-start | /review | rounded-rect | user-lane | 24 |
|
||||
| p25-reviewer-activate | Code Reviewer Activates | rectangle | reviewer-lane | 25 |
|
||||
| p25-scan-changes | Scan Recent Changes | rectangle | reviewer-lane | 26 |
|
||||
| p25-check-quality | Check Code Quality | rectangle | reviewer-lane | 27 |
|
||||
| p25-security-scan | Security Scan | rectangle | reviewer-lane | 28 |
|
||||
| p25-report | Generate Review Report | rectangle | reviewer-lane | 29 |
|
||||
| p25-complete | Review Complete | rounded-rect | reviewer-lane | 30 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p25-start | p25-reviewer-activate | invokes | solid |
|
||||
| p25-reviewer-activate | p25-scan-changes | | solid |
|
||||
| p25-scan-changes | p25-check-quality | | solid |
|
||||
| p25-check-quality | p25-security-scan | | solid |
|
||||
| p25-security-scan | p25-report | | solid |
|
||||
| p25-report | p25-complete | | solid |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 3: SPRINT CLOSE
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p3-start | /sprint close | rounded-rect | user-lane | 31 |
|
||||
| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 32 |
|
||||
| p3-review | Review Sprint | rectangle | orchestrator-lane | 33 |
|
||||
| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 34 |
|
||||
| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 35 |
|
||||
| p3-user-input | Confirm Lessons | diamond | user-lane | 36 |
|
||||
| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 37 |
|
||||
| p3-gitea-wiki-create | Store Lessons (Wiki) | rectangle | gitea-lane | 38 |
|
||||
| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 39 |
|
||||
| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 40 |
|
||||
| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 41 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p3-start | p3-orch-activate | invokes | solid |
|
||||
| p3-orch-activate | p3-review | | solid |
|
||||
| p3-review | p3-gitea-status | REST API | solid |
|
||||
| p3-gitea-status | p3-capture | status data | dashed |
|
||||
| p3-capture | p3-user-input | proposed lessons | solid |
|
||||
| p3-user-input | p3-create-wiki | confirmed | solid |
|
||||
| p3-create-wiki | p3-gitea-wiki-create | REST API (create_lesson) | solid |
|
||||
| p3-gitea-wiki-create | p3-close-issues | confirm | dashed |
|
||||
| p3-close-issues | p3-gitea-close | REST API | solid |
|
||||
| p3-gitea-close | p3-complete | confirm | dashed |
|
||||
|
||||
---
|
||||
|
||||
## LAYOUT NOTES
|
||||
|
||||
```
|
||||
+--------+------------+---------------+------------+----------+------------------+
|
||||
| User | Planner | Orchestrator | Executor | Reviewer | Gitea |
|
||||
| | | | | | (Issues + Wiki) |
|
||||
+--------+------------+---------------+------------+----------+------------------+
|
||||
| | | | | | |
|
||||
| PHASE 1: SPRINT PLANNING |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +---->| O | | | | |
|
||||
| | | | | | | |
|
||||
| | +----------|---------------|------------|--------->| O (Wiki Query) |
|
||||
| | |<---------|---------------|------------|----------+ | |
|
||||
| | | | | | | |
|
||||
| | O<> | | | | |
|
||||
| O<--->+ | | | | | |
|
||||
| | | | | | | |
|
||||
| | +----------|---------------|------------|--------->| O (Issues) |
|
||||
| | O | | | | |
|
||||
| | | | | | |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| PHASE 2: SPRINT EXECUTION |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +-----|----------->| O | | | |
|
||||
| | | | | | | |
|
||||
| | | +-------------|------------|--------->| O (Issues) |
|
||||
| | | |<------------|------------|----------+ | |
|
||||
| | | | | | | |
|
||||
| | | +------------>| O | | |
|
||||
| | | | | | | |
|
||||
| | | | +----------|--------->| O (Issues) |
|
||||
| | | | |<---------|----------+ | |
|
||||
| | | O<------------+ | | | |
|
||||
| | | | | | | |
|
||||
| | | O (loop) | | | |
|
||||
| | | | | | |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| PHASE 2.5: CODE REVIEW |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +-----|------------|---------------|----------->| O | |
|
||||
| | | | | | | |
|
||||
| | | | | O->O->O | |
|
||||
| | | | | | | |
|
||||
| | | | | O | |
|
||||
| | | | | | |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| PHASE 3: SPRINT CLOSE |
|
||||
|-------------------------------------------------------------------------------|
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +-----|----------->| O | | | |
|
||||
| | | +-------------|------------|--------->| O (Issues) |
|
||||
| | | |<------------|------------|----------+ | |
|
||||
| | | | | | | |
|
||||
| O<----|-----------<+ | | | | |
|
||||
| +-----|----------->| | | | | |
|
||||
| | | +-------------|------------|--------->| O (Wiki Create) |
|
||||
| | | |<------------|------------|----------+ | |
|
||||
| | | +-------------|------------|--------->| O (Issues Close) |
|
||||
| | | O | | | |
|
||||
+--------+------------+---------------+------------+----------+------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## COLOR LEGEND
|
||||
|
||||
| Color | Hex | Meaning |
|
||||
|-------|-----|---------|
|
||||
| Light Blue | #E3F2FD | User actions |
|
||||
| Blue | #4A90D9 | Planner Agent |
|
||||
| Green | #7CB342 | Orchestrator Agent |
|
||||
| Orange | #FF9800 | Executor Agent |
|
||||
| Purple | #9C27B0 | Code Reviewer Agent |
|
||||
| Gray | #9E9E9E | External Services (Gitea) |
|
||||
|
||||
---
|
||||
|
||||
## SHAPE LEGEND
|
||||
|
||||
| Shape | Meaning |
|
||||
|-------|---------|
|
||||
| Rounded Rectangle | Start/End points (commands) |
|
||||
| Rectangle | Process/Action |
|
||||
| Diamond | Decision point |
|
||||
| Cylinder | Data store (in component map) |
|
||||
|
||||
---
|
||||
|
||||
## ARROW LEGEND
|
||||
|
||||
| Style | Meaning |
|
||||
|-------|---------|
|
||||
| Solid | Action/Request |
|
||||
| Dashed | Response/Data return |
|
||||
|
||||
---
|
||||
|
||||
## ARCHITECTURE NOTES
|
||||
|
||||
- **Gitea provides BOTH issue tracking AND wiki** (no separate wiki service)
|
||||
- All wiki operations use Gitea REST API via MCP tools
|
||||
- Lessons learned stored in Gitea Wiki under `lessons-learned/sprints/`
|
||||
- MCP tools: `search_lessons`, `create_lesson`, `list_wiki_pages`, `get_wiki_page`
|
||||
- Four-agent model: Planner, Orchestrator, Executor, Code Reviewer
|
||||
@@ -1,139 +0,0 @@
|
||||
# Component Map - Draw.io Specification
|
||||
|
||||
**Target File:** `docs/architecture/component-map.drawio`
|
||||
|
||||
**Purpose:** Shows all plugins, MCP servers, hooks and their relationships.
|
||||
|
||||
---
|
||||
|
||||
## NODES
|
||||
|
||||
### Plugins (Blue - #4A90D9)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| projman | projman | rectangle | #4A90D9 | top-center |
|
||||
| projman-pmo | projman-pmo (planned) | rectangle | #4A90D9 | top-right |
|
||||
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
|
||||
| claude-config | claude-config-maintainer | rectangle | #4A90D9 | bottom-left |
|
||||
| cmdb-assistant | cmdb-assistant | rectangle | #4A90D9 | bottom-right |
|
||||
|
||||
### MCP Servers (Green - #7CB342)
|
||||
|
||||
MCP servers are **bundled inside each plugin** that needs them.
|
||||
|
||||
| ID | Label | Type | Color | Position | Bundled In |
|
||||
|----|-------|------|-------|----------|------------|
|
||||
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | projman |
|
||||
| netbox-mcp | NetBox MCP Server | rectangle | #7CB342 | middle-right | cmdb-assistant |
|
||||
|
||||
### External Systems (Gray - #9E9E9E)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| gitea-instance | Gitea\n(Issues + Wiki) | cylinder | #9E9E9E | bottom-left |
|
||||
| netbox-instance | NetBox | cylinder | #9E9E9E | bottom-right |
|
||||
|
||||
### Configuration (Orange - #FF9800)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| system-config | System Config\n~/.config/claude/ | rectangle | #FF9800 | far-left |
|
||||
| project-config | Project Config\n.env | rectangle | #FF9800 | far-right |
|
||||
|
||||
---
|
||||
|
||||
## EDGES
|
||||
|
||||
### Plugin to MCP Server Connections
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| projman | gitea-mcp | bundled | solid | bidirectional |
|
||||
| cmdb-assistant | netbox-mcp | bundled | solid | bidirectional |
|
||||
|
||||
### Plugin Dependencies
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| projman-pmo | projman | depends on | dashed | forward |
|
||||
|
||||
### MCP Server to External System Connections
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| gitea-mcp | gitea-instance | REST API | solid | forward |
|
||||
| netbox-mcp | netbox-instance | REST API | solid | forward |
|
||||
|
||||
### Configuration Connections
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| system-config | gitea-mcp | credentials | dashed | forward |
|
||||
| system-config | netbox-mcp | credentials | dashed | forward |
|
||||
| project-config | gitea-mcp | repo context | dashed | forward |
|
||||
| project-config | netbox-mcp | site context | dashed | forward |
|
||||
|
||||
---
|
||||
|
||||
## GROUPS
|
||||
|
||||
| ID | Label | Contains | Style |
|
||||
|----|-------|----------|-------|
|
||||
| plugins-group | Plugins | projman, projman-pmo, project-hygiene, claude-config, cmdb-assistant | light blue border |
|
||||
| external-group | External Services | gitea-instance, netbox-instance | light gray border |
|
||||
| config-group | Configuration | system-config, project-config | light orange border |
|
||||
|
||||
---
|
||||
|
||||
## LAYOUT NOTES
|
||||
|
||||
```
|
||||
+------------------------------------------------------------------+
|
||||
| PLUGINS GROUP |
|
||||
| +----------------+ +----------------+ +-------------------+ |
|
||||
| | project- | | projman | | projman-pmo | |
|
||||
| | hygiene | | [gitea-mcp] | | (planned) | |
|
||||
| +----------------+ +-------+--------+ +-------------------+ |
|
||||
| | |
|
||||
| +----------------+ +-------------------+ |
|
||||
| | claude-config | | cmdb-assistant | |
|
||||
| | -maintainer | | [netbox-mcp] | |
|
||||
| +----------------+ +--------+----------+ |
|
||||
+------------------------------------------------------------------+
|
||||
|
|
||||
v
|
||||
+------------------------------------------------------------------+
|
||||
| EXTERNAL SERVICES GROUP |
|
||||
| +-------------------+ +-------------------+ |
|
||||
| | Gitea | | NetBox | |
|
||||
| | (Issues + Wiki) | | | |
|
||||
| +-------------------+ +-------------------+ |
|
||||
+------------------------------------------------------------------+
|
||||
|
||||
CONFIG GROUP (left side): CONFIG GROUP (right side):
|
||||
+-------------------+ +-------------------+
|
||||
| System Config | | Project Config |
|
||||
| ~/.config/claude/ | | .env |
|
||||
+-------------------+ +-------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## COLOR LEGEND
|
||||
|
||||
| Color | Hex | Meaning |
|
||||
|-------|-----|---------|
|
||||
| Blue | #4A90D9 | Plugins |
|
||||
| Green | #7CB342 | MCP Servers (bundled in plugins) |
|
||||
| Gray | #9E9E9E | External Systems |
|
||||
| Orange | #FF9800 | Configuration |
|
||||
|
||||
---
|
||||
|
||||
## ARCHITECTURE NOTES
|
||||
|
||||
- MCP servers are **bundled inside plugins** (not shared at root)
|
||||
- Gitea provides both issue tracking AND wiki (lessons learned)
|
||||
- No separate Wiki.js - all wiki functionality uses Gitea Wiki
|
||||
- Each plugin is self-contained for Claude Code caching
|
||||
@@ -1,70 +0,0 @@
|
||||
# Design: data-seed
|
||||
|
||||
**Domain:** `data`
|
||||
**Target Version:** v9.3.0
|
||||
|
||||
## Purpose
|
||||
|
||||
Test data generation and database seeding. Generates realistic fake data based on schema definitions, supports reproducible seeds, and manages seed files for development and testing environments.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Developers needing test data for local development
|
||||
- QA teams requiring reproducible datasets
|
||||
- Projects with complex relational data models
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/seed setup` | Setup wizard — detect schema source, configure output paths |
|
||||
| `/seed generate` | Generate seed data from schema or model definitions |
|
||||
| `/seed apply` | Apply seed data to database or create fixture files |
|
||||
| `/seed profile` | Define reusable data profiles (small, medium, large, edge-cases) |
|
||||
| `/seed validate` | Validate seed data against schema constraints and foreign keys |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `seed-generator` | sonnet | acceptEdits | Data generation, profile management |
|
||||
| `seed-validator` | haiku | plan | Read-only validation of seed data integrity |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `schema-inference` | Infer data types and constraints from models/migrations |
|
||||
| `faker-patterns` | Realistic data generation patterns (names, emails, addresses, etc.) |
|
||||
| `relationship-resolution` | Foreign key and relationship-aware data generation |
|
||||
| `profile-management` | Seed profile definitions and sizing |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** Seed data is generated as files (JSON, SQL, CSV). Database insertion is handled by the application's own tooling.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| saas-db-migrate | Schema models used as seed generation input |
|
||||
| data-platform | Generated data can be loaded via `/data ingest` |
|
||||
| saas-test-pilot | Seed data used in integration test fixtures |
|
||||
| projman | Issue labels: `Component/Data`, `Tech/Faker` |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~500 |
|
||||
| Dispatch file (`seed.md`) | ~200 |
|
||||
| 5 commands (avg) | ~3,000 |
|
||||
| 2 agents | ~1,000 |
|
||||
| 5 skills | ~2,000 |
|
||||
| **Total** | **~6,700** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should we support database-specific seed formats (pg_dump, mysqldump)?
|
||||
- Integration with Faker library or custom generation?
|
||||
@@ -1,70 +0,0 @@
|
||||
# Design: debug-mcp
|
||||
|
||||
**Domain:** `debug`
|
||||
**Target Version:** v9.8.0
|
||||
|
||||
## Purpose
|
||||
|
||||
MCP server debugging and development toolkit. Provides tools for inspecting MCP server health, testing tool calls, viewing server logs, and developing new MCP servers. Essential for marketplace developers building or troubleshooting MCP integrations.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Plugin developers building MCP servers
|
||||
- Users troubleshooting MCP connectivity issues
|
||||
- Marketplace maintainers validating MCP configurations
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/debug-mcp status` | Show all MCP servers: running/failed, tool count, last error |
|
||||
| `/debug-mcp test` | Test a specific MCP tool call with sample input |
|
||||
| `/debug-mcp logs` | View recent MCP server stderr/stdout logs |
|
||||
| `/debug-mcp inspect` | Inspect MCP server config (.mcp.json entry, venv, dependencies) |
|
||||
| `/debug-mcp scaffold` | Generate MCP server skeleton (Python, stdio transport) |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `mcp-debugger` | sonnet | default | Server inspection, log analysis, scaffold generation |
|
||||
|
||||
Single agent is sufficient — this plugin is primarily diagnostic with one generative command.
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `mcp-protocol` | MCP stdio protocol, tool/resource/prompt schemas |
|
||||
| `server-patterns` | Python MCP server patterns (FastMCP, raw protocol) |
|
||||
| `venv-diagnostics` | Virtual environment health checks, dependency validation |
|
||||
| `log-analysis` | MCP server error pattern recognition |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** This plugin inspects other MCP servers via file system (reading .mcp.json, checking venvs, reading logs). It does not need its own MCP server.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| contract-validator | `/cv status` delegates to debug-mcp for detailed MCP diagnostics |
|
||||
| projman | `/projman setup` can invoke `/debug-mcp status` for post-setup verification |
|
||||
| All plugins with MCP | Debug-mcp can diagnose any MCP server in the marketplace |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~500 |
|
||||
| Dispatch file (`debug-mcp.md`) | ~200 |
|
||||
| 5 commands (avg) | ~3,000 |
|
||||
| 1 agent | ~600 |
|
||||
| 5 skills | ~2,000 |
|
||||
| **Total** | **~6,300** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should this plugin have a hook that auto-runs on MCP failure (SessionStart)?
|
||||
- Should `/debug-mcp scaffold` generate both Python and TypeScript templates?
|
||||
@@ -1,72 +0,0 @@
|
||||
# Design: ops-deploy-pipeline
|
||||
|
||||
**Domain:** `ops`
|
||||
**Target Version:** v9.7.0
|
||||
|
||||
## Purpose
|
||||
|
||||
CI/CD deployment pipeline management for Docker Compose and systemd-based services. Generates deployment configurations, validates pipeline definitions, and manages environment-specific settings. Tailored for self-hosted infrastructure (not cloud-native).
|
||||
|
||||
## Target Users
|
||||
|
||||
- Self-hosted service operators (Raspberry Pi, VPS, bare-metal)
|
||||
- Teams deploying via Docker Compose
|
||||
- Projects needing environment-specific configuration management
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/deploy setup` | Setup wizard — detect deployment method, configure targets |
|
||||
| `/deploy generate` | Generate docker-compose.yml, Caddyfile entries, systemd units |
|
||||
| `/deploy validate` | Validate deployment configs (ports, volumes, networks, env vars) |
|
||||
| `/deploy env` | Manage environment-specific config files (.env.production, etc.) |
|
||||
| `/deploy check` | Pre-deployment health check (disk, memory, port conflicts) |
|
||||
| `/deploy rollback` | Generate rollback plan for a deployment |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `deploy-planner` | sonnet | default | Configuration generation, rollback planning |
|
||||
| `deploy-validator` | haiku | plan | Read-only validation of configs and pre-flight checks |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `compose-patterns` | Docker Compose best practices, multi-service patterns |
|
||||
| `caddy-conventions` | Caddyfile reverse proxy patterns, subdomain routing |
|
||||
| `env-management` | Environment variable management across environments |
|
||||
| `health-checks` | Pre-deployment system health validation |
|
||||
| `rollback-patterns` | Deployment rollback strategies |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required initially.** Could add SSH-based remote execution MCP server in the future for remote deployment.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| cmdb-assistant | Deployment targets pulled from NetBox device inventory |
|
||||
| ops-release-manager | Release tags trigger deployment preparation |
|
||||
| projman | Issue labels: `Component/Infra`, `Tech/Docker`, `Tech/Caddy` |
|
||||
| code-sentinel | Security scan of deployment configs (exposed ports, secrets in env) |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~700 |
|
||||
| Dispatch file (`deploy.md`) | ~200 |
|
||||
| 6 commands (avg) | ~3,600 |
|
||||
| 2 agents | ~1,200 |
|
||||
| 6 skills | ~2,500 |
|
||||
| **Total** | **~8,200** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should this support Kubernetes/Helm for users who need it?
|
||||
- SSH-based remote execution via MCP server for actual deployments?
|
||||
@@ -1,71 +0,0 @@
|
||||
# Design: ops-release-manager
|
||||
|
||||
**Domain:** `ops`
|
||||
**Target Version:** v9.6.0
|
||||
|
||||
## Purpose
|
||||
|
||||
Release management automation including semantic versioning, changelog generation, release branch creation, and tag management. Coordinates the release process across git, changelogs, and package manifests.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Project maintainers managing releases
|
||||
- Teams following SemVer and conventional commits
|
||||
- Projects with multiple version locations to keep in sync
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/release setup` | Setup wizard — detect version locations, configure release flow |
|
||||
| `/release prepare` | Prepare release: bump versions, update changelog, create branch |
|
||||
| `/release validate` | Pre-release checks (clean tree, tests pass, changelog has content) |
|
||||
| `/release tag` | Create and push git tag with release notes |
|
||||
| `/release rollback` | Revert a release (delete tag, revert version bump commit) |
|
||||
| `/release status` | Show current version, unreleased changes, next version suggestion |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `release-coordinator` | sonnet | acceptEdits | Version bumping, changelog updates, branch/tag creation |
|
||||
| `release-validator` | haiku | plan | Pre-release validation, dependency checks |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `version-detection` | Find version locations (package.json, pyproject.toml, marketplace.json, etc.) |
|
||||
| `semver-rules` | SemVer bump logic based on conventional commits |
|
||||
| `changelog-conventions` | Keep a Changelog format, unreleased section management |
|
||||
| `release-workflow` | Branch-based vs tag-based release patterns |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** All operations are git and file-based.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| git-flow | `/release prepare` uses gitflow conventions for branch creation |
|
||||
| doc-guardian | `/release validate` checks documentation is up to date |
|
||||
| projman | Sprint close can trigger `/release prepare` for sprint-based releases |
|
||||
| ops-deploy-pipeline | Release tags trigger deployment pipeline |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~600 |
|
||||
| Dispatch file (`release.md`) | ~200 |
|
||||
| 6 commands (avg) | ~3,600 |
|
||||
| 2 agents | ~1,200 |
|
||||
| 5 skills | ~2,000 |
|
||||
| **Total** | **~7,600** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should this subsume the existing `release.sh` script in this repo?
|
||||
- Support for GitHub Releases / Gitea Releases API via MCP?
|
||||
@@ -1,71 +0,0 @@
|
||||
# Design: saas-api-platform
|
||||
|
||||
**Domain:** `saas`
|
||||
**Target Version:** v9.1.0
|
||||
|
||||
## Purpose
|
||||
|
||||
Provides scaffolding, validation, and development workflow tools for REST and GraphQL API backends. Supports FastAPI (Python) and Express (Node.js) with OpenAPI spec generation, route validation, and middleware management.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Backend developers building API services
|
||||
- Teams using FastAPI or Express frameworks
|
||||
- Projects requiring OpenAPI/Swagger documentation
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/api setup` | Setup wizard — detect framework, configure MCP server |
|
||||
| `/api scaffold` | Generate API routes, models, schemas from spec or description |
|
||||
| `/api validate` | Validate routes against OpenAPI spec, check missing endpoints |
|
||||
| `/api docs` | Generate/update OpenAPI spec from code annotations |
|
||||
| `/api test-routes` | Generate request/response test cases for API endpoints |
|
||||
| `/api middleware` | Add/configure middleware (auth, CORS, rate-limiting, logging) |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `api-architect` | sonnet | default | Route design, schema generation, middleware planning |
|
||||
| `api-validator` | haiku | plan | Read-only validation of routes against spec |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `framework-detection` | Detect FastAPI vs Express, identify project structure |
|
||||
| `openapi-conventions` | OpenAPI 3.x spec generation rules and patterns |
|
||||
| `route-patterns` | RESTful route naming, versioning, pagination conventions |
|
||||
| `middleware-catalog` | Common middleware patterns per framework |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** All operations are file-based (reading/writing code and specs). No external API needed.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| projman | Issue labels: `Component/API`, `Tech/FastAPI`, `Tech/Express` |
|
||||
| code-sentinel | PreToolUse hook scans generated routes for security issues |
|
||||
| saas-test-pilot | `/api test-routes` generates stubs consumable by test-pilot |
|
||||
| saas-db-migrate | Schema models shared between API models and migrations |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~800 |
|
||||
| Dispatch file (`api.md`) | ~200 |
|
||||
| 6 commands (avg) | ~3,600 |
|
||||
| 2 agents | ~1,200 |
|
||||
| 5 skills | ~2,500 |
|
||||
| **Total** | **~8,300** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should MCP server be added later for live API testing (curl-like requests)?
|
||||
- Support for gRPC/tRPC in addition to REST/GraphQL?
|
||||
@@ -1,71 +0,0 @@
|
||||
# Design: saas-db-migrate
|
||||
|
||||
**Domain:** `saas`
|
||||
**Target Version:** v9.2.0
|
||||
|
||||
## Purpose
|
||||
|
||||
Database migration management for SQL databases. Supports Alembic (Python/SQLAlchemy), Prisma (Node.js), and raw SQL migrations. Provides migration generation, validation, rollback planning, and drift detection.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Backend developers managing database schemas
|
||||
- Teams using SQLAlchemy/Alembic or Prisma
|
||||
- Projects needing migration safety checks before deployment
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/db-migrate setup` | Setup wizard — detect ORM/migration tool, configure paths |
|
||||
| `/db-migrate generate` | Generate migration from model diff or description |
|
||||
| `/db-migrate validate` | Check migration safety (destructive ops, data loss risk, locking) |
|
||||
| `/db-migrate plan` | Show migration execution plan with rollback strategy |
|
||||
| `/db-migrate history` | Display migration history and current state |
|
||||
| `/db-migrate rollback` | Generate rollback migration for a given migration |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `migration-planner` | sonnet | default | Migration generation, rollback planning |
|
||||
| `migration-auditor` | haiku | plan | Read-only safety validation (destructive op detection) |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `orm-detection` | Detect Alembic vs Prisma vs raw SQL, identify config |
|
||||
| `migration-safety` | Rules for detecting destructive operations (DROP, ALTER, data loss) |
|
||||
| `rollback-patterns` | Standard rollback generation patterns per tool |
|
||||
| `naming-conventions` | Migration file naming and ordering conventions |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** Migrations are file-based. Database connectivity is handled by the ORM tool itself, not by Claude.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| projman | Issue labels: `Component/Database`, `Tech/SQLAlchemy`, `Tech/Prisma` |
|
||||
| saas-api-platform | Schema models shared between API and migration layers |
|
||||
| code-sentinel | Migration validation as part of security scan |
|
||||
| data-platform | PostgreSQL tools can inspect live schema for drift detection |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~600 |
|
||||
| Dispatch file (`db-migrate.md`) | ~200 |
|
||||
| 6 commands (avg) | ~3,600 |
|
||||
| 2 agents | ~1,200 |
|
||||
| 5 skills | ~2,000 |
|
||||
| **Total** | **~7,600** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should this integrate with data-platform's PostgreSQL MCP server for live schema comparison?
|
||||
- Support for NoSQL migration tools (Mongoose, etc.)?
|
||||
@@ -1,73 +0,0 @@
|
||||
# Design: saas-react-platform
|
||||
|
||||
**Domain:** `saas`
|
||||
**Target Version:** v9.4.0
|
||||
|
||||
## Purpose
|
||||
|
||||
React frontend development toolkit with component scaffolding, routing setup, state management patterns, and build configuration. Supports Next.js and Vite-based React projects with TypeScript.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Frontend developers building React applications
|
||||
- Teams using Next.js or Vite + React
|
||||
- Projects needing consistent component architecture
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/react setup` | Setup wizard — detect framework (Next.js/Vite), configure paths |
|
||||
| `/react component` | Scaffold React component with props, types, tests, stories |
|
||||
| `/react route` | Add route with page component, loader, and error boundary |
|
||||
| `/react state` | Set up state management pattern (Context, Zustand, Redux Toolkit) |
|
||||
| `/react hook` | Generate custom hook with TypeScript types and tests |
|
||||
| `/react lint` | Validate component tree, check prop drilling, detect anti-patterns |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `react-architect` | sonnet | default | Component design, routing, state management |
|
||||
| `react-auditor` | haiku | plan | Read-only lint and anti-pattern detection |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `framework-detection` | Detect Next.js vs Vite, App Router vs Pages Router |
|
||||
| `component-patterns` | Standard component structure, naming, file organization |
|
||||
| `state-patterns` | State management patterns and when to use each |
|
||||
| `routing-conventions` | Route naming, dynamic routes, middleware patterns |
|
||||
| `typescript-patterns` | TypeScript utility types, generics, prop typing |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** All operations are file-based (component generation, route configuration).
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| projman | Issue labels: `Component/Frontend`, `Tech/React`, `Tech/Next.js` |
|
||||
| viz-platform | DMC components integrate with React component architecture |
|
||||
| saas-api-platform | API client generation from OpenAPI spec |
|
||||
| saas-test-pilot | Component test generation via `/react component` |
|
||||
| code-sentinel | Security scan for XSS, unsafe HTML, client-side secrets |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~800 |
|
||||
| Dispatch file (`react.md`) | ~200 |
|
||||
| 6 commands (avg) | ~3,600 |
|
||||
| 2 agents | ~1,200 |
|
||||
| 6 skills | ~3,000 |
|
||||
| **Total** | **~8,800** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should we support Vue.js/Svelte as alternative frameworks?
|
||||
- Integration with Storybook for component documentation?
|
||||
@@ -1,73 +0,0 @@
|
||||
# Design: saas-test-pilot
|
||||
|
||||
**Domain:** `saas`
|
||||
**Target Version:** v9.5.0
|
||||
|
||||
## Purpose
|
||||
|
||||
Test automation toolkit supporting unit, integration, and end-to-end testing. Generates test cases from code analysis, manages test fixtures, and provides coverage analysis with gap detection.
|
||||
|
||||
## Target Users
|
||||
|
||||
- Developers writing tests for Python or JavaScript/TypeScript projects
|
||||
- Teams enforcing test coverage requirements
|
||||
- Projects needing test generation from existing code
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/test setup` | Setup wizard — detect test framework, configure paths |
|
||||
| `/test generate` | Generate test cases for functions/classes/modules |
|
||||
| `/test coverage` | Analyze test coverage and identify untested code paths |
|
||||
| `/test fixtures` | Generate or manage test fixtures and mocks |
|
||||
| `/test e2e` | Generate end-to-end test scenarios from user stories |
|
||||
| `/test run` | Run tests with formatted output and failure analysis |
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
| Agent | Model | Mode | Role |
|
||||
|-------|-------|------|------|
|
||||
| `test-architect` | sonnet | acceptEdits | Test generation, fixture creation, e2e scenarios |
|
||||
| `coverage-analyst` | haiku | plan | Read-only coverage analysis and gap detection |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `framework-detection` | Detect pytest/Jest/Vitest/Playwright, identify config |
|
||||
| `test-patterns` | Unit/integration/e2e test patterns and best practices |
|
||||
| `mock-patterns` | Mocking strategies for different dependency types |
|
||||
| `coverage-analysis` | Coverage gap detection and prioritization |
|
||||
| `fixture-management` | Fixture organization, factories, builders |
|
||||
| `visual-header` | Standard command output headers |
|
||||
|
||||
## MCP Server
|
||||
|
||||
**Not required.** Test generation is file-based. Test execution uses the project's own test runner via Bash.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Plugin | Integration |
|
||||
|--------|-------------|
|
||||
| projman | `/sprint test` delegates to test-pilot when installed |
|
||||
| saas-api-platform | API route tests generated from `/api test-routes` |
|
||||
| saas-react-platform | Component tests generated alongside components |
|
||||
| data-seed | Test fixtures use seed data profiles |
|
||||
| code-sentinel | Security test patterns included in generation |
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Component | Estimated Tokens |
|
||||
|-----------|-----------------|
|
||||
| `claude-md-integration.md` | ~700 |
|
||||
| Dispatch file (`test.md`) | ~200 |
|
||||
| 6 commands (avg) | ~3,600 |
|
||||
| 2 agents | ~1,200 |
|
||||
| 6 skills | ~2,500 |
|
||||
| **Total** | **~8,200** |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should `/test run` replace projman's `/sprint test run` or supplement it?
|
||||
- Support for property-based testing (Hypothesis, fast-check)?
|
||||
@@ -1,9 +0,0 @@
|
||||
# Prompt Index
|
||||
|
||||
Tracks execution status of structured prompts used for marketplace evolution and maintenance.
|
||||
|
||||
| ID | Title | Status | Date | Version |
|
||||
|----|-------|--------|------|---------|
|
||||
| 001 | Phase 1 Evolution — Domain Metadata + Hook Migration | executed | 2026-02-06 | 8.0.0 → 8.1.0 |
|
||||
| 002 | Phase 1b — Command Consolidation + 8 New Plugins | executed | 2026-02-06 | 8.1.0 → 9.0.0 |
|
||||
| 003 | Post-Evolution Cleanup — Stale References and Migration Guide Fixes | executed | 2026-02-06 | 9.0.0 → 9.0.1 |
|
||||
Reference in New Issue
Block a user