feat(marketplace): command consolidation + 8 new plugins (v8.1.0 → v9.0.0) [BREAKING]

Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 14:52:11 -05:00
parent 5098422858
commit 2d51df7a42
321 changed files with 13582 additions and 1019 deletions
--- a/docs/designs/data-seed.md
+++ b/docs/designs/data-seed.md
@@ -0,0 +1,70 @@
+# 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?
--- a/docs/designs/debug-mcp.md
+++ b/docs/designs/debug-mcp.md
@@ -0,0 +1,70 @@
+# 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?
--- a/docs/designs/ops-deploy-pipeline.md
+++ b/docs/designs/ops-deploy-pipeline.md
@@ -0,0 +1,72 @@
+# 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?
--- a/docs/designs/ops-release-manager.md
+++ b/docs/designs/ops-release-manager.md
@@ -0,0 +1,71 @@
+# 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?
--- a/docs/designs/saas-api-platform.md
+++ b/docs/designs/saas-api-platform.md
@@ -0,0 +1,71 @@
+# 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?
--- a/docs/designs/saas-db-migrate.md
+++ b/docs/designs/saas-db-migrate.md
@@ -0,0 +1,71 @@
+# 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.)?
--- a/docs/designs/saas-react-platform.md
+++ b/docs/designs/saas-react-platform.md
@@ -0,0 +1,73 @@
+# 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?
--- a/docs/designs/saas-test-pilot.md
+++ b/docs/designs/saas-test-pilot.md
@@ -0,0 +1,73 @@
+# 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)?