From f662524f9a75936052cbdf5d04fda0588f16aa61 Mon Sep 17 00:00:00 2001 From: Seth Hobson Date: Thu, 15 Jan 2026 17:38:21 -0500 Subject: [PATCH] feat: add Conductor plugin for Context-Driven Development Add comprehensive Conductor plugin implementing Context-Driven Development methodology with tracks, specs, and phased implementation plans. Components: - 5 commands: setup, new-track, implement, status, revert - 1 agent: conductor-validator - 3 skills: context-driven-development, track-management, workflow-patterns - 18 templates for project artifacts Documentation updates: - README.md: Updated counts (68 plugins, 100 agents, 110 skills, 76 tools) - docs/plugins.md: Added Conductor to Workflows section - docs/agents.md: Added conductor-validator agent - docs/agent-skills.md: Added Conductor skills section Also includes Prettier formatting across all project files. --- .claude-plugin/marketplace.json | 472 ++++--------- .github/CODE_OF_CONDUCT.md | 4 +- .github/CONTRIBUTING.md | 17 +- .github/FUNDING.yml | 2 +- README.md | 39 +- conductor/.claude-plugin/plugin.json | 18 + conductor/README.md | 109 +++ conductor/agents/conductor-validator.md | 268 +++++++ conductor/commands/implement.md | 369 ++++++++++ conductor/commands/new-track.md | 414 +++++++++++ conductor/commands/revert.md | 361 ++++++++++ conductor/commands/setup.md | 406 +++++++++++ conductor/commands/status.md | 323 +++++++++ .../context-driven-development/SKILL.md | 385 ++++++++++ conductor/skills/track-management/SKILL.md | 593 ++++++++++++++++ conductor/skills/workflow-patterns/SKILL.md | 623 ++++++++++++++++ .../templates/code_styleguides/csharp.md | 600 ++++++++++++++++ conductor/templates/code_styleguides/dart.md | 668 ++++++++++++++++++ .../templates/code_styleguides/general.md | 235 ++++++ conductor/templates/code_styleguides/go.md | 562 +++++++++++++++ .../templates/code_styleguides/html-css.md | 618 ++++++++++++++++ .../templates/code_styleguides/javascript.md | 569 +++++++++++++++ .../templates/code_styleguides/python.md | 566 +++++++++++++++ .../templates/code_styleguides/typescript.md | 451 ++++++++++++ conductor/templates/index.md | 90 +++ conductor/templates/product-guidelines.md | 196 +++++ conductor/templates/product.md | 102 +++ conductor/templates/tech-stack.md | 204 ++++++ conductor/templates/track-metadata.json | 10 + conductor/templates/track-plan.md | 198 ++++++ conductor/templates/track-spec.md | 169 +++++ conductor/templates/tracks.md | 53 ++ conductor/templates/workflow.md | 192 +++++ docs/agent-skills.md | 301 ++++---- docs/agents.md | 288 ++++---- docs/architecture.md | 21 +- docs/plugins.md | 209 +++--- docs/usage.md | 188 ++--- .../agents/ui-visual-validator.md | 19 +- .../commands/accessibility-audit.md | 431 +++++------ .../skills/screen-reader-testing/SKILL.md | 130 ++-- .../skills/wcag-audit-patterns/SKILL.md | 133 ++-- .../agents/context-manager.md | 15 + .../commands/improve-agent.md | 29 +- .../commands/multi-agent-optimize.md | 22 +- .../agents/backend-architect.md | 27 + plugins/api-scaffolding/agents/django-pro.md | 17 +- plugins/api-scaffolding/agents/fastapi-pro.md | 17 +- .../agents/graphql-architect.md | 15 + .../skills/fastapi-templates/SKILL.md | 3 + .../agents/api-documenter.md | 15 + .../commands/api-mock.md | 347 ++++----- .../agents/frontend-developer.md | 15 + .../agents/observability-engineer.md | 18 + .../agents/performance-engineer.md | 17 + .../commands/performance-optimization.md | 15 +- .../agents/arm-cortex-expert.md | 47 +- .../agents/backend-architect.md | 27 + .../agents/backend-security-coder.md | 16 + .../agents/backend-architect.md | 27 + .../agents/graphql-architect.md | 15 + .../agents/tdd-orchestrator.md | 19 +- .../agents/temporal-python-pro.md | 38 + .../commands/feature-development.md | 8 +- .../skills/api-design-principles/SKILL.md | 21 +- .../assets/api-design-checklist.md | 19 + .../references/graphql-schema-design.md | 49 +- .../references/rest-best-practices.md | 23 + .../skills/architecture-patterns/SKILL.md | 7 + .../skills/cqrs-implementation/SKILL.md | 16 +- .../skills/event-store-design/SKILL.md | 30 +- .../skills/microservices-patterns/SKILL.md | 10 + .../skills/projection-patterns/SKILL.md | 14 +- .../skills/saga-orchestration/SKILL.md | 16 +- .../skills/temporal-python-testing/SKILL.md | 12 + .../resources/integration-testing.md | 3 + .../resources/local-setup.md | 3 + .../resources/replay-testing.md | 7 + .../resources/unit-testing.md | 8 + .../workflow-orchestration-patterns/SKILL.md | 30 + .../agents/blockchain-developer.md | 16 + .../skills/nft-standards/SKILL.md | 2 + .../skills/solidity-security/SKILL.md | 78 +- .../skills/web3-testing/SKILL.md | 74 +- .../agents/business-analyst.md | 15 + .../skills/data-storytelling/SKILL.md | 80 ++- .../skills/kpi-dashboard-design/SKILL.md | 12 +- plugins/c4-architecture/agents/c4-code.md | 45 +- .../c4-architecture/agents/c4-component.md | 51 +- .../c4-architecture/agents/c4-container.md | 39 +- plugins/c4-architecture/agents/c4-context.md | 35 +- .../commands/c4-architecture.md | 94 +-- .../cicd-automation/agents/cloud-architect.md | 14 + .../agents/deployment-engineer.md | 140 ---- 94 files changed, 11610 insertions(+), 1728 deletions(-) create mode 100644 conductor/.claude-plugin/plugin.json create mode 100644 conductor/README.md create mode 100644 conductor/agents/conductor-validator.md create mode 100644 conductor/commands/implement.md create mode 100644 conductor/commands/new-track.md create mode 100644 conductor/commands/revert.md create mode 100644 conductor/commands/setup.md create mode 100644 conductor/commands/status.md create mode 100644 conductor/skills/context-driven-development/SKILL.md create mode 100644 conductor/skills/track-management/SKILL.md create mode 100644 conductor/skills/workflow-patterns/SKILL.md create mode 100644 conductor/templates/code_styleguides/csharp.md create mode 100644 conductor/templates/code_styleguides/dart.md create mode 100644 conductor/templates/code_styleguides/general.md create mode 100644 conductor/templates/code_styleguides/go.md create mode 100644 conductor/templates/code_styleguides/html-css.md create mode 100644 conductor/templates/code_styleguides/javascript.md create mode 100644 conductor/templates/code_styleguides/python.md create mode 100644 conductor/templates/code_styleguides/typescript.md create mode 100644 conductor/templates/index.md create mode 100644 conductor/templates/product-guidelines.md create mode 100644 conductor/templates/product.md create mode 100644 conductor/templates/tech-stack.md create mode 100644 conductor/templates/track-metadata.json create mode 100644 conductor/templates/track-plan.md create mode 100644 conductor/templates/track-spec.md create mode 100644 conductor/templates/tracks.md create mode 100644 conductor/templates/workflow.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0485599..c70bcb6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -30,10 +30,7 @@ ], "category": "documentation", "strict": false, - "commands": [ - "./commands/doc-generate.md", - "./commands/code-explain.md" - ], + "commands": ["./commands/doc-generate.md", "./commands/code-explain.md"], "agents": [ "./agents/docs-architect.md", "./agents/tutorial-engineer.md", @@ -60,13 +57,8 @@ ], "category": "development", "strict": false, - "commands": [ - "./commands/smart-debug.md" - ], - "agents": [ - "./agents/debugger.md", - "./agents/dx-optimizer.md" - ] + "commands": ["./commands/smart-debug.md"], + "agents": ["./agents/debugger.md", "./agents/dx-optimizer.md"] }, { "name": "git-pr-workflows", @@ -94,9 +86,7 @@ "./commands/onboard.md", "./commands/git-workflow.md" ], - "agents": [ - "./agents/code-reviewer.md" - ] + "agents": ["./agents/code-reviewer.md"] }, { "name": "backend-development", @@ -122,9 +112,7 @@ ], "category": "development", "strict": false, - "commands": [ - "./commands/feature-development.md" - ], + "commands": ["./commands/feature-development.md"], "agents": [ "./agents/backend-architect.md", "./agents/graphql-architect.md", @@ -156,18 +144,10 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "frontend", - "mobile", - "react", - "ui", - "cross-platform" - ], + "keywords": ["frontend", "mobile", "react", "ui", "cross-platform"], "category": "development", "strict": false, - "commands": [ - "./commands/component-scaffold.md" - ], + "commands": ["./commands/component-scaffold.md"], "agents": [ "./agents/frontend-developer.md", "./agents/mobile-developer.md" @@ -200,9 +180,7 @@ ], "category": "workflows", "strict": false, - "commands": [ - "./commands/full-stack-feature.md" - ], + "commands": ["./commands/full-stack-feature.md"], "agents": [ "./agents/test-automator.md", "./agents/security-auditor.md", @@ -231,13 +209,8 @@ ], "category": "testing", "strict": false, - "commands": [ - "./commands/test-generate.md" - ], - "agents": [ - "./agents/test-automator.md", - "./agents/debugger.md" - ] + "commands": ["./commands/test-generate.md"], + "agents": ["./agents/test-automator.md", "./agents/debugger.md"] }, { "name": "tdd-workflows", @@ -251,12 +224,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "tdd", - "test-driven", - "workflow", - "red-green-refactor" - ], + "keywords": ["tdd", "test-driven", "workflow", "red-green-refactor"], "category": "workflows", "strict": false, "commands": [ @@ -265,10 +233,7 @@ "./commands/tdd-green.md", "./commands/tdd-refactor.md" ], - "agents": [ - "./agents/tdd-orchestrator.md", - "./agents/code-reviewer.md" - ] + "agents": ["./agents/tdd-orchestrator.md", "./agents/code-reviewer.md"] }, { "name": "code-review-ai", @@ -282,20 +247,11 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "code-review", - "architecture", - "ai-analysis", - "quality" - ], + "keywords": ["code-review", "architecture", "ai-analysis", "quality"], "category": "quality", "strict": false, - "commands": [ - "./commands/ai-review.md" - ], - "agents": [ - "./agents/architect-review.md" - ] + "commands": ["./commands/ai-review.md"], + "agents": ["./agents/architect-review.md"] }, { "name": "code-refactoring", @@ -309,12 +265,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "refactoring", - "code-quality", - "technical-debt", - "cleanup" - ], + "keywords": ["refactoring", "code-quality", "technical-debt", "cleanup"], "category": "utilities", "strict": false, "commands": [ @@ -322,10 +273,7 @@ "./commands/tech-debt.md", "./commands/context-restore.md" ], - "agents": [ - "./agents/legacy-modernizer.md", - "./agents/code-reviewer.md" - ] + "agents": ["./agents/legacy-modernizer.md", "./agents/code-reviewer.md"] }, { "name": "dependency-management", @@ -339,21 +287,11 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "dependencies", - "npm", - "security", - "auditing", - "upgrades" - ], + "keywords": ["dependencies", "npm", "security", "auditing", "upgrades"], "category": "utilities", "strict": false, - "commands": [ - "./commands/deps-audit.md" - ], - "agents": [ - "./agents/legacy-modernizer.md" - ] + "commands": ["./commands/deps-audit.md"], + "agents": ["./agents/legacy-modernizer.md"] }, { "name": "error-debugging", @@ -380,10 +318,7 @@ "./commands/error-trace.md", "./commands/multi-agent-review.md" ], - "agents": [ - "./agents/debugger.md", - "./agents/error-detective.md" - ] + "agents": ["./agents/debugger.md", "./agents/error-detective.md"] }, { "name": "team-collaboration", @@ -397,21 +332,11 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "collaboration", - "team", - "standup", - "issue-management" - ], + "keywords": ["collaboration", "team", "standup", "issue-management"], "category": "utilities", "strict": false, - "commands": [ - "./commands/issue.md", - "./commands/standup-notes.md" - ], - "agents": [ - "./agents/dx-optimizer.md" - ] + "commands": ["./commands/issue.md", "./commands/standup-notes.md"], + "agents": ["./agents/dx-optimizer.md"] }, { "name": "llm-application-dev", @@ -468,21 +393,14 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "multi-agent", - "orchestration", - "ai-agents", - "optimization" - ], + "keywords": ["multi-agent", "orchestration", "ai-agents", "optimization"], "category": "ai-ml", "strict": false, "commands": [ "./commands/multi-agent-optimize.md", "./commands/improve-agent.md" ], - "agents": [ - "./agents/context-manager.md" - ] + "agents": ["./agents/context-manager.md"] }, { "name": "context-management", @@ -496,21 +414,14 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "context", - "persistence", - "conversation", - "memory" - ], + "keywords": ["context", "persistence", "conversation", "memory"], "category": "ai-ml", "strict": false, "commands": [ "./commands/context-save.md", "./commands/context-restore.md" ], - "agents": [ - "./agents/context-manager.md" - ] + "agents": ["./agents/context-manager.md"] }, { "name": "machine-learning-ops", @@ -534,17 +445,13 @@ ], "category": "ai-ml", "strict": false, - "commands": [ - "./commands/ml-pipeline.md" - ], + "commands": ["./commands/ml-pipeline.md"], "agents": [ "./agents/data-scientist.md", "./agents/ml-engineer.md", "./agents/mlops-engineer.md" ], - "skills": [ - "./skills/ml-pipeline-workflow" - ] + "skills": ["./skills/ml-pipeline-workflow"] }, { "name": "data-engineering", @@ -571,10 +478,7 @@ "./commands/data-driven-feature.md", "./commands/data-pipeline.md" ], - "agents": [ - "./agents/data-engineer.md", - "./agents/backend-architect.md" - ], + "agents": ["./agents/data-engineer.md", "./agents/backend-architect.md"], "skills": [ "./skills/dbt-transformation-patterns", "./skills/airflow-dag-patterns", @@ -594,12 +498,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "incident-response", - "production", - "sre", - "troubleshooting" - ], + "keywords": ["incident-response", "production", "sre", "troubleshooting"], "category": "operations", "strict": false, "commands": [ @@ -628,12 +527,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "diagnostics", - "error-tracing", - "root-cause", - "debugging" - ], + "keywords": ["diagnostics", "error-tracing", "root-cause", "debugging"], "category": "operations", "strict": false, "commands": [ @@ -641,10 +535,7 @@ "./commands/error-analysis.md", "./commands/smart-debug.md" ], - "agents": [ - "./agents/debugger.md", - "./agents/error-detective.md" - ] + "agents": ["./agents/debugger.md", "./agents/error-detective.md"] }, { "name": "distributed-debugging", @@ -666,9 +557,7 @@ ], "category": "operations", "strict": false, - "commands": [ - "./commands/debug-trace.md" - ], + "commands": ["./commands/debug-trace.md"], "agents": [ "./agents/error-detective.md", "./agents/devops-troubleshooter.md" @@ -727,13 +616,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "deployment", - "rollout", - "rollback", - "canary", - "blue-green" - ], + "keywords": ["deployment", "rollout", "rollback", "canary", "blue-green"], "category": "infrastructure", "strict": false, "commands": [], @@ -762,12 +645,8 @@ ], "category": "infrastructure", "strict": false, - "commands": [ - "./commands/config-validate.md" - ], - "agents": [ - "./agents/cloud-architect.md" - ] + "commands": ["./commands/config-validate.md"], + "agents": ["./agents/cloud-architect.md"] }, { "name": "kubernetes-operations", @@ -792,9 +671,7 @@ "category": "infrastructure", "strict": false, "commands": [], - "agents": [ - "./agents/kubernetes-architect.md" - ], + "agents": ["./agents/kubernetes-architect.md"], "skills": [ "./skills/gitops-workflow", "./skills/helm-chart-scaffolding", @@ -867,9 +744,7 @@ ], "category": "infrastructure", "strict": false, - "commands": [ - "./commands/workflow-automate.md" - ], + "commands": ["./commands/workflow-automate.md"], "agents": [ "./agents/deployment-engineer.md", "./agents/devops-troubleshooter.md", @@ -904,9 +779,7 @@ ], "category": "performance", "strict": false, - "commands": [ - "./commands/performance-optimization.md" - ], + "commands": ["./commands/performance-optimization.md"], "agents": [ "./agents/performance-engineer.md", "./agents/frontend-developer.md", @@ -933,9 +806,7 @@ ], "category": "performance", "strict": false, - "commands": [ - "./commands/cost-optimize.md" - ], + "commands": ["./commands/cost-optimize.md"], "agents": [ "./agents/database-optimizer.md", "./agents/database-architect.md", @@ -964,10 +835,7 @@ ], "category": "quality", "strict": false, - "commands": [ - "./commands/full-review.md", - "./commands/pr-enhance.md" - ], + "commands": ["./commands/full-review.md", "./commands/pr-enhance.md"], "agents": [ "./agents/code-reviewer.md", "./agents/architect-review.md", @@ -986,11 +854,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "performance-review", - "test-coverage", - "quality-analysis" - ], + "keywords": ["performance-review", "test-coverage", "quality-analysis"], "category": "quality", "strict": false, "commands": [ @@ -1051,12 +915,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "technical-debt", - "cleanup", - "refactoring", - "dependencies" - ], + "keywords": ["technical-debt", "cleanup", "refactoring", "dependencies"], "category": "modernization", "strict": false, "commands": [ @@ -1064,10 +923,7 @@ "./commands/tech-debt.md", "./commands/refactor-clean.md" ], - "agents": [ - "./agents/test-automator.md", - "./agents/code-reviewer.md" - ] + "agents": ["./agents/test-automator.md", "./agents/code-reviewer.md"] }, { "name": "database-design", @@ -1081,22 +937,12 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "database-design", - "schema", - "sql", - "data-modeling" - ], + "keywords": ["database-design", "schema", "sql", "data-modeling"], "category": "database", "strict": false, "commands": [], - "agents": [ - "./agents/database-architect.md", - "./agents/sql-pro.md" - ], - "skills": [ - "./skills/postgresql" - ] + "agents": ["./agents/database-architect.md", "./agents/sql-pro.md"], + "skills": ["./skills/postgresql"] }, { "name": "database-migrations", @@ -1123,10 +969,7 @@ "./commands/sql-migrations.md", "./commands/migration-observability.md" ], - "agents": [ - "./agents/database-optimizer.md", - "./agents/database-admin.md" - ] + "agents": ["./agents/database-optimizer.md", "./agents/database-admin.md"] }, { "name": "security-scanning", @@ -1188,12 +1031,8 @@ ], "category": "security", "strict": false, - "commands": [ - "./commands/compliance-check.md" - ], - "agents": [ - "./agents/security-auditor.md" - ] + "commands": ["./commands/compliance-check.md"], + "agents": ["./agents/security-auditor.md"] }, { "name": "backend-api-security", @@ -1243,9 +1082,7 @@ ], "category": "security", "strict": false, - "commands": [ - "./commands/xss-scan.md" - ], + "commands": ["./commands/xss-scan.md"], "agents": [ "./agents/frontend-security-coder.md", "./agents/mobile-security-coder.md", @@ -1274,9 +1111,7 @@ "category": "data", "strict": false, "commands": [], - "agents": [ - "./agents/backend-security-coder.md" - ] + "agents": ["./agents/backend-security-coder.md"] }, { "name": "api-scaffolding", @@ -1290,14 +1125,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "api", - "rest", - "graphql", - "fastapi", - "django", - "express" - ], + "keywords": ["api", "rest", "graphql", "fastapi", "django", "express"], "category": "api", "strict": false, "commands": [], @@ -1307,9 +1135,7 @@ "./agents/fastapi-pro.md", "./agents/django-pro.md" ], - "skills": [ - "./skills/fastapi-templates" - ] + "skills": ["./skills/fastapi-templates"] }, { "name": "api-testing-observability", @@ -1332,12 +1158,8 @@ ], "category": "api", "strict": false, - "commands": [ - "./commands/api-mock.md" - ], - "agents": [ - "./agents/api-documenter.md" - ] + "commands": ["./commands/api-mock.md"], + "agents": ["./agents/api-documenter.md"] }, { "name": "seo-content-creation", @@ -1445,9 +1267,7 @@ ], "category": "documentation", "strict": false, - "commands": [ - "./commands/doc-generate.md" - ], + "commands": ["./commands/doc-generate.md"], "agents": [ "./agents/docs-architect.md", "./agents/api-documenter.md", @@ -1485,9 +1305,7 @@ ], "category": "documentation", "strict": false, - "commands": [ - "./commands/c4-architecture.md" - ], + "commands": ["./commands/c4-architecture.md"], "agents": [ "./agents/c4-code.md", "./agents/c4-component.md", @@ -1517,9 +1335,7 @@ ], "category": "development", "strict": false, - "commands": [ - "./commands/multi-platform.md" - ], + "commands": ["./commands/multi-platform.md"], "agents": [ "./agents/mobile-developer.md", "./agents/flutter-expert.md", @@ -1552,13 +1368,8 @@ "category": "business", "strict": false, "commands": [], - "agents": [ - "./agents/business-analyst.md" - ], - "skills": [ - "./skills/kpi-dashboard-design", - "./skills/data-storytelling" - ] + "agents": ["./agents/business-analyst.md"], + "skills": ["./skills/kpi-dashboard-design", "./skills/data-storytelling"] }, { "name": "startup-business-analyst", @@ -1588,9 +1399,7 @@ "./commands/financial-projections.md", "./commands/business-case.md" ], - "agents": [ - "./agents/startup-analyst.md" - ], + "agents": ["./agents/startup-analyst.md"], "skills": [ "./skills/market-sizing-analysis", "./skills/startup-financial-modeling", @@ -1623,10 +1432,7 @@ "category": "business", "strict": false, "commands": [], - "agents": [ - "./agents/hr-pro.md", - "./agents/legal-advisor.md" - ], + "agents": ["./agents/hr-pro.md", "./agents/legal-advisor.md"], "skills": [ "./skills/gdpr-data-handling", "./skills/employment-contract-templates" @@ -1654,10 +1460,7 @@ "category": "business", "strict": false, "commands": [], - "agents": [ - "./agents/customer-support.md", - "./agents/sales-automator.md" - ] + "agents": ["./agents/customer-support.md", "./agents/sales-automator.md"] }, { "name": "content-marketing", @@ -1709,9 +1512,7 @@ "category": "blockchain", "strict": false, "commands": [], - "agents": [ - "./agents/blockchain-developer.md" - ], + "agents": ["./agents/blockchain-developer.md"], "skills": [ "./skills/defi-protocol-templates", "./skills/nft-standards", @@ -1741,10 +1542,7 @@ "category": "finance", "strict": false, "commands": [], - "agents": [ - "./agents/quant-analyst.md", - "./agents/risk-manager.md" - ], + "agents": ["./agents/quant-analyst.md", "./agents/risk-manager.md"], "skills": [ "./skills/backtesting-frameworks", "./skills/risk-metrics-calculation" @@ -1774,9 +1572,7 @@ "category": "payments", "strict": false, "commands": [], - "agents": [ - "./agents/payment-integration.md" - ], + "agents": ["./agents/payment-integration.md"], "skills": [ "./skills/billing-automation", "./skills/paypal-integration", @@ -1837,12 +1633,8 @@ ], "category": "accessibility", "strict": false, - "commands": [ - "./commands/accessibility-audit.md" - ], - "agents": [ - "./agents/ui-visual-validator.md" - ], + "commands": ["./commands/accessibility-audit.md"], + "agents": ["./agents/ui-visual-validator.md"], "skills": [ "./skills/wcag-audit-patterns", "./skills/screen-reader-testing" @@ -1860,18 +1652,10 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "python", - "django", - "fastapi", - "async", - "backend" - ], + "keywords": ["python", "django", "fastapi", "async", "backend"], "category": "languages", "strict": false, - "commands": [ - "./commands/python-scaffold.md" - ], + "commands": ["./commands/python-scaffold.md"], "agents": [ "./agents/python-pro.md", "./agents/django-pro.md", @@ -1897,22 +1681,11 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "javascript", - "typescript", - "es6", - "nodejs", - "react" - ], + "keywords": ["javascript", "typescript", "es6", "nodejs", "react"], "category": "languages", "strict": false, - "commands": [ - "./commands/typescript-scaffold.md" - ], - "agents": [ - "./agents/javascript-pro.md", - "./agents/typescript-pro.md" - ], + "commands": ["./commands/typescript-scaffold.md"], + "agents": ["./agents/javascript-pro.md", "./agents/typescript-pro.md"], "skills": [ "./skills/typescript-advanced-types", "./skills/nodejs-backend-patterns", @@ -1942,9 +1715,7 @@ ], "category": "languages", "strict": false, - "commands": [ - "./commands/rust-project.md" - ], + "commands": ["./commands/rust-project.md"], "agents": [ "./agents/rust-pro.md", "./agents/golang-pro.md", @@ -1969,14 +1740,7 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "java", - "scala", - "csharp", - "jvm", - "enterprise", - "dotnet" - ], + "keywords": ["java", "scala", "csharp", "jvm", "enterprise", "dotnet"], "category": "languages", "strict": false, "commands": [], @@ -1998,20 +1762,11 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "php", - "ruby", - "rails", - "wordpress", - "web-scripting" - ], + "keywords": ["php", "ruby", "rails", "wordpress", "web-scripting"], "category": "languages", "strict": false, "commands": [], - "agents": [ - "./agents/php-pro.md", - "./agents/ruby-pro.md" - ] + "agents": ["./agents/php-pro.md", "./agents/ruby-pro.md"] }, { "name": "functional-programming", @@ -2025,19 +1780,11 @@ "homepage": "https://github.com/wshobson/agents", "repository": "https://github.com/wshobson/agents", "license": "MIT", - "keywords": [ - "elixir", - "functional", - "phoenix", - "otp", - "distributed" - ], + "keywords": ["elixir", "functional", "phoenix", "otp", "distributed"], "category": "languages", "strict": false, "commands": [], - "agents": [ - "./agents/elixir-pro.md" - ] + "agents": ["./agents/elixir-pro.md"] }, { "name": "julia-development", @@ -2062,9 +1809,7 @@ "category": "languages", "strict": false, "commands": [], - "agents": [ - "./agents/julia-pro.md" - ], + "agents": ["./agents/julia-pro.md"], "skills": [] }, { @@ -2091,9 +1836,7 @@ "category": "languages", "strict": false, "commands": [], - "agents": [ - "./agents/arm-cortex-expert.md" - ] + "agents": ["./agents/arm-cortex-expert.md"] }, { "name": "shell-scripting", @@ -2119,10 +1862,7 @@ "category": "languages", "strict": false, "commands": [], - "agents": [ - "./agents/bash-pro.md", - "./agents/posix-shell-pro.md" - ], + "agents": ["./agents/bash-pro.md", "./agents/posix-shell-pro.md"], "skills": [ "./skills/bash-defensive-patterns/SKILL.md", "./skills/shellcheck-configuration/SKILL.md", @@ -2154,9 +1894,7 @@ "category": "development", "strict": false, "commands": [], - "agents": [ - "./agents/monorepo-architect.md" - ], + "agents": ["./agents/monorepo-architect.md"], "skills": [ "./skills/git-advanced-workflows", "./skills/sql-optimization-patterns", @@ -2208,6 +1946,44 @@ "./skills/protocol-reverse-engineering", "./skills/anti-reversing-techniques" ] + }, + { + "name": "conductor", + "source": "./conductor", + "description": "Context-Driven Development plugin that transforms Claude Code into a project management tool. Implements structured workflow: Context → Spec & Plan → Implement with full TDD support, track-based work units, semantic git reversion, and resumable sessions", + "version": "0.1.0", + "author": { + "name": "Seth Hobson", + "url": "https://github.com/wshobson" + }, + "homepage": "https://github.com/wshobson/agents", + "repository": "https://github.com/wshobson/agents", + "license": "MIT", + "keywords": [ + "project-management", + "context-driven-development", + "tdd", + "planning", + "specifications", + "workflow", + "tracks", + "git-integration" + ], + "category": "workflows", + "strict": false, + "commands": [ + "./commands/setup.md", + "./commands/new-track.md", + "./commands/implement.md", + "./commands/status.md", + "./commands/revert.md" + ], + "agents": ["./agents/conductor-validator.md"], + "skills": [ + "./skills/context-driven-development", + "./skills/track-management", + "./skills/workflow-patterns" + ] } ] } diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index f17855e..fd7b393 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -37,6 +37,7 @@ The following behaviors are considered harassment and are unacceptable: ### Reporting If you experience or witness unacceptable behavior, please report it by: + - Creating an issue with the `moderation` label - Contacting the repository maintainers directly - Using GitHub's built-in reporting mechanisms @@ -59,6 +60,7 @@ Community leaders will follow these guidelines in determining consequences: ## Scope This Code of Conduct applies within all community spaces, including: + - Issues and pull requests - Discussions and comments - Wiki and documentation @@ -70,4 +72,4 @@ This Code of Conduct is adapted from the [Contributor Covenant](https://www.cont ## Contact -Questions about the Code of Conduct can be directed to the repository maintainers through GitHub issues or discussions. \ No newline at end of file +Questions about the Code of Conduct can be directed to the repository maintainers through GitHub issues or discussions. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e268876..2a15109 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -11,18 +11,21 @@ Thank you for your interest in contributing to this collection of Claude Code su ## Types of Contributions ### Subagent Improvements + - Bug fixes in existing agent prompts - Performance optimizations - Enhanced capabilities or instructions - Documentation improvements ### New Subagents + - Well-defined specialized agents for specific domains - Clear use cases and examples - Comprehensive documentation - Integration with existing workflows ### Infrastructure + - GitHub Actions improvements - Template enhancements - Community tooling @@ -30,12 +33,14 @@ Thank you for your interest in contributing to this collection of Claude Code su ## Contribution Process ### 1. Issues First + - **Always create an issue before starting work** on significant changes - Use the appropriate issue template - Provide clear, detailed descriptions - Include relevant examples or use cases ### 2. Pull Requests + - Fork the repository and create a feature branch - Follow existing code style and formatting - Include tests or examples where appropriate @@ -43,6 +48,7 @@ Thank you for your interest in contributing to this collection of Claude Code su - Use clear, descriptive commit messages ### 3. Review Process + - All PRs require review from maintainers - Address feedback promptly and professionally - Be patient - reviews may take time @@ -50,6 +56,7 @@ Thank you for your interest in contributing to this collection of Claude Code su ## Content Guidelines ### What We Accept + - ✅ Constructive feedback and suggestions - ✅ Well-researched feature requests - ✅ Clear bug reports with reproduction steps @@ -58,6 +65,7 @@ Thank you for your interest in contributing to this collection of Claude Code su - ✅ Specialized domain expertise ### What We Don't Accept + - ❌ Hate speech, discrimination, or harassment - ❌ Spam, promotional content, or off-topic posts - ❌ Personal attacks or inflammatory language @@ -68,6 +76,7 @@ Thank you for your interest in contributing to this collection of Claude Code su ## Quality Standards ### For Subagents + - Clear, specific domain expertise - Well-structured prompt engineering - Practical use cases and examples @@ -75,6 +84,7 @@ Thank you for your interest in contributing to this collection of Claude Code su - Integration with existing patterns ### For Documentation + - Clear, concise writing - Accurate technical information - Consistent formatting and style @@ -83,12 +93,14 @@ Thank you for your interest in contributing to this collection of Claude Code su ## Community Guidelines ### Communication + - **Be respectful** - Treat all community members with dignity - **Be constructive** - Focus on improving the project - **Be patient** - Allow time for responses and reviews - **Be helpful** - Share knowledge and assist others ### Collaboration + - **Give credit** - Acknowledge others' contributions - **Share knowledge** - Help others learn and grow - **Stay focused** - Keep discussions on topic @@ -104,6 +116,7 @@ Thank you for your interest in contributing to this collection of Claude Code su ## Recognition Contributors who consistently provide high-quality submissions and maintain professional conduct will be: + - Acknowledged in release notes - Given priority review for future contributions - Potentially invited to become maintainers @@ -111,15 +124,17 @@ Contributors who consistently provide high-quality submissions and maintain prof ## Enforcement Violations of these guidelines may result in: + 1. **Warning** - First offense or minor issues 2. **Temporary restrictions** - Suspension of contribution privileges 3. **Permanent ban** - Severe or repeated violations Reports of violations should be made through: + - GitHub's built-in reporting tools - Issues tagged with `moderation` - Direct contact with maintainers --- -Thank you for helping make this project a welcoming, productive environment for everyone! \ No newline at end of file +Thank you for helping make this project a welcoming, productive environment for everyone! diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index ecec527..88698fa 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1 +1 @@ -github: wshobson \ No newline at end of file +github: wshobson diff --git a/README.md b/README.md index 5bafea8..2a78507 100644 --- a/README.md +++ b/README.md @@ -4,26 +4,26 @@ [![Run in Smithery](https://smithery.ai/badge/skills/wshobson)](https://smithery.ai/skills?ns=wshobson&utm_source=github&utm_medium=badge) -> **🎯 Agent Skills Enabled** — 107 specialized skills extend Claude's capabilities across plugins with progressive disclosure +> **🎯 Agent Skills Enabled** — 110 specialized skills extend Claude's capabilities across plugins with progressive disclosure -A comprehensive production-ready system combining **99 specialized AI agents**, **15 multi-agent workflow orchestrators**, **107 agent skills**, and **71 development tools** organized into **67 focused, single-purpose plugins** for [Claude Code](https://docs.claude.com/en/docs/claude-code/overview). +A comprehensive production-ready system combining **100 specialized AI agents**, **15 multi-agent workflow orchestrators**, **110 agent skills**, and **76 development tools** organized into **68 focused, single-purpose plugins** for [Claude Code](https://docs.claude.com/en/docs/claude-code/overview). ## Overview This unified repository provides everything needed for intelligent automation and multi-agent orchestration across modern software development: -- **67 Focused Plugins** - Granular, single-purpose plugins optimized for minimal token usage and composability -- **99 Specialized Agents** - Domain experts with deep knowledge across architecture, languages, infrastructure, quality, data/AI, documentation, business operations, and SEO -- **107 Agent Skills** - Modular knowledge packages with progressive disclosure for specialized expertise +- **68 Focused Plugins** - Granular, single-purpose plugins optimized for minimal token usage and composability +- **100 Specialized Agents** - Domain experts with deep knowledge across architecture, languages, infrastructure, quality, data/AI, documentation, business operations, and SEO +- **110 Agent Skills** - Modular knowledge packages with progressive disclosure for specialized expertise - **15 Workflow Orchestrators** - Multi-agent coordination systems for complex operations like full-stack development, security hardening, ML pipelines, and incident response -- **71 Development Tools** - Optimized utilities including project scaffolding, security scanning, test automation, and infrastructure setup +- **76 Development Tools** - Optimized utilities including project scaffolding, security scanning, test automation, and infrastructure setup ### Key Features -- **Granular Plugin Architecture**: 67 focused plugins optimized for minimal token usage -- **Comprehensive Tooling**: 71 development tools including test generation, scaffolding, and security scanning +- **Granular Plugin Architecture**: 68 focused plugins optimized for minimal token usage +- **Comprehensive Tooling**: 76 development tools including test generation, scaffolding, and security scanning - **100% Agent Coverage**: All plugins include specialized agents -- **Agent Skills**: 107 specialized skills following for progressive disclosure and token efficiency +- **Agent Skills**: 110 specialized skills following for progressive disclosure and token efficiency - **Clear Organization**: 23 categories with 1-6 plugins each for easy discovery - **Efficient Design**: Average 3.4 components per plugin (follows Anthropic's 2-8 pattern) @@ -49,7 +49,7 @@ Add this marketplace to Claude Code: /plugin marketplace add wshobson/agents ``` -This makes all 67 plugins available for installation, but **does not load any agents or tools** into your context. +This makes all 68 plugins available for installation, but **does not load any agents or tools** into your context. ### Step 2: Install Plugins @@ -113,9 +113,9 @@ rm -rf ~/.claude/plugins/cache/claude-code-workflows && rm ~/.claude/plugins/ins ### Core Guides -- **[Plugin Reference](docs/plugins.md)** - Complete catalog of all 67 plugins -- **[Agent Reference](docs/agents.md)** - All 99 agents organized by category -- **[Agent Skills](docs/agent-skills.md)** - 107 specialized skills with progressive disclosure +- **[Plugin Reference](docs/plugins.md)** - Complete catalog of all 68 plugins +- **[Agent Reference](docs/agents.md)** - All 100 agents organized by category +- **[Agent Skills](docs/agent-skills.md)** - 110 specialized skills with progressive disclosure - **[Usage Guide](docs/usage.md)** - Commands, workflows, and best practices - **[Architecture](docs/architecture.md)** - Design principles and patterns @@ -129,7 +129,7 @@ rm -rf ~/.claude/plugins/cache/claude-code-workflows && rm ~/.claude/plugins/ins ## What's New -### Agent Skills (107 skills across 18 plugins) +### Agent Skills (110 skills across 19 plugins) Specialized knowledge packages following Anthropic's progressive disclosure architecture: @@ -148,6 +148,9 @@ Specialized knowledge packages following Anthropic's progressive disclosure arch **Blockchain & Web3** (4 skills): DeFi protocols, NFT standards, Solidity security, Web3 testing +**Project Management:** +- **Conductor** (3 skills): context-driven development, track management, workflow patterns + **And more:** Framework migration, observability, payment processing, ML operations, security scanning [→ View complete skills documentation](docs/agent-skills.md) @@ -233,11 +236,11 @@ Uses kubernetes-architect agent with 4 specialized skills for production-grade c ## Plugin Categories -**23 categories, 67 plugins:** +**23 categories, 68 plugins:** - 🎨 **Development** (4) - debugging, backend, frontend, multi-platform - 📚 **Documentation** (3) - code docs, API specs, diagrams, C4 architecture -- 🔄 **Workflows** (3) - git, full-stack, TDD +- 🔄 **Workflows** (4) - git, full-stack, TDD, **Conductor** (context-driven development) - ✅ **Testing** (2) - unit testing, TDD workflows - 🔍 **Quality** (3) - code review, comprehensive review, performance - 🤖 **AI & ML** (4) - LLM apps, agent orchestration, context, MLOps @@ -265,7 +268,7 @@ Uses kubernetes-architect agent with 4 specialized skills for production-grade c - **Single responsibility** - Each plugin does one thing well - **Minimal token usage** - Average 3.4 components per plugin - **Composable** - Mix and match for complex workflows -- **100% coverage** - All 99 agents accessible across plugins +- **100% coverage** - All 100 agents accessible across plugins ### Progressive Disclosure (Skills) @@ -279,7 +282,7 @@ Three-tier architecture for token efficiency: ``` claude-agents/ ├── .claude-plugin/ -│ └── marketplace.json # 67 plugins +│ └── marketplace.json # 68 plugins ├── plugins/ │ ├── python-development/ │ │ ├── agents/ # 3 Python experts diff --git a/conductor/.claude-plugin/plugin.json b/conductor/.claude-plugin/plugin.json new file mode 100644 index 0000000..8a26dc6 --- /dev/null +++ b/conductor/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "conductor", + "version": "0.1.0", + "description": "Context-Driven Development plugin that transforms Claude Code into a project management tool. Implements structured workflow: Context → Spec & Plan → Implement with full TDD support, track-based work units, and semantic git reversion.", + "author": { + "name": "Claude Agents", + "url": "https://github.com/wshobson/claude-agents" + }, + "license": "MIT", + "keywords": [ + "project-management", + "context-driven-development", + "tdd", + "planning", + "specifications", + "workflow" + ] +} diff --git a/conductor/README.md b/conductor/README.md new file mode 100644 index 0000000..296457f --- /dev/null +++ b/conductor/README.md @@ -0,0 +1,109 @@ +# Conductor - Context-Driven Development Plugin for Claude Code + +Conductor transforms Claude Code into a project management tool by implementing **Context-Driven Development**. It enforces a structured workflow: **Context → Spec & Plan → Implement**. + +## Philosophy + +By treating context as a managed artifact alongside code, teams establish a persistent, project-aware foundation for all AI interactions. The system maintains: + +- **Product vision** as living documentation +- **Technical decisions** as structured artifacts +- **Work units (tracks)** with specifications and phased plans +- **TDD workflow** with verification checkpoints + +## Features + +- **Specification & Planning**: Generate detailed specs and actionable task plans before implementation +- **Context Management**: Maintain style guides, tech stack preferences, and product goals +- **Safe Iteration**: Review plans before code generation, keeping humans in control +- **Team Collaboration**: Project-level context documents become shared foundations +- **Project Intelligence**: Handles both greenfield (new) and brownfield (existing) projects +- **Semantic Reversion**: Git-aware revert by logical work units (tracks, phases, tasks) +- **State Persistence**: Resume setup across multiple sessions + +## Commands + +| Command | Description | +| ---------------------- | ---------------------------------------------------------------------------------- | +| `/conductor:setup` | Initialize project with product definition, tech stack, workflow, and style guides | +| `/conductor:new-track` | Create a feature or bug track with spec.md and plan.md | +| `/conductor:implement` | Execute tasks from the plan following workflow rules | +| `/conductor:status` | Display project progress overview | +| `/conductor:revert` | Git-aware undo by track, phase, or task | + +## Generated Artifacts + +``` +conductor/ +├── index.md # Navigation hub +├── product.md # Product vision & goals +├── product-guidelines.md # Standards & messaging +├── tech-stack.md # Technology preferences +├── workflow.md # Development practices (TDD, commits) +├── tracks.md # Master track registry +├── setup_state.json # Resumable setup state +├── code_styleguides/ # Language-specific conventions +└── tracks/ + └── / + ├── spec.md # Requirements specification + ├── plan.md # Phased task breakdown + ├── metadata.json # Track metadata + └── index.md # Track navigation +``` + +## Workflow + +### 1. Setup (`/conductor:setup`) + +Interactive initialization that creates foundational project documentation: + +- Detects greenfield vs brownfield projects +- Asks sequential questions about product, tech stack, workflow preferences +- Generates style guides for selected languages +- Creates tracks registry + +### 2. Create Track (`/conductor:new-track`) + +Start a new feature or bug fix: + +- Interactive Q&A to gather requirements +- Generates detailed specification (spec.md) +- Creates phased implementation plan (plan.md) +- Registers track in tracks.md + +### 3. Implement (`/conductor:implement`) + +Execute the plan systematically: + +- Follows TDD red-green-refactor cycle +- Updates task status markers +- Includes manual verification checkpoints +- Synchronizes documentation on completion + +### 4. Monitor (`/conductor:status`) + +View project progress: + +- Current phase and task +- Completion percentage +- Identified blockers + +### 5. Revert (`/conductor:revert`) + +Undo work by logical unit: + +- Select track, phase, or task to revert +- Git-aware: finds all associated commits +- Requires confirmation before execution + +## Installation + +```bash +claude --plugin-dir /path/to/conductor +``` + +Or copy to your project's `.claude-plugin/` directory. + +## License + +MIT diff --git a/conductor/agents/conductor-validator.md b/conductor/agents/conductor-validator.md new file mode 100644 index 0000000..a80ab1e --- /dev/null +++ b/conductor/agents/conductor-validator.md @@ -0,0 +1,268 @@ +--- +name: conductor-validator +description: | + Validates Conductor project artifacts for completeness, consistency, and correctness. Use after setup, when diagnosing issues, or before implementation to verify project context. + + + Context: User just ran /conductor:setup + User: "Can you verify conductor is set up correctly?" + Assistant: Uses conductor-validator agent to check the setup + + + + Context: User getting errors with conductor commands + User: "Why isn't /conductor:new-track working?" + Assistant: Uses conductor-validator agent to diagnose the issue + + + + Context: Before starting implementation + User: "Is my project ready for /conductor:implement?" + Assistant: Uses conductor-validator agent to verify prerequisites + +model: opus +color: cyan +tools: + - Read + - Glob + - Grep + - Bash +--- + +You are an expert validator for Conductor project artifacts. Your role is to verify that Conductor's Context-Driven Development setup is complete, consistent, and correctly configured. + +## When to Use This Agent + +- After `/conductor:setup` completes to verify all artifacts were created correctly +- When a user reports issues with Conductor commands not working +- Before starting implementation to verify project context is complete +- When synchronizing documentation after track completion + +## Validation Categories + +### A. Setup Validation + +Verify the foundational Conductor structure exists and is properly configured. + +**Directory Check:** + +- `conductor/` directory exists at project root + +**Required Files:** + +- `conductor/index.md` - Navigation hub +- `conductor/product.md` - Product vision and goals +- `conductor/product-guidelines.md` - Standards and messaging +- `conductor/tech-stack.md` - Technology preferences +- `conductor/workflow.md` - Development practices +- `conductor/tracks.md` - Master track registry + +**File Integrity:** + +- All required files exist +- Files are not empty (have meaningful content) +- Markdown structure is valid (proper headings, lists) + +### B. Content Validation + +Verify required sections exist within each artifact. + +**product.md Required Sections:** + +- Overview or Introduction +- Problem Statement +- Target Users +- Value Proposition + +**tech-stack.md Required Elements:** + +- Technology decisions documented +- At least one language/framework specified +- Rationale for choices (preferred) + +**workflow.md Required Elements:** + +- Task lifecycle defined +- TDD workflow (if applicable) +- Commit message conventions +- Review/verification checkpoints + +**tracks.md Required Format:** + +- Status legend present ([ ], [~], [x] markers) +- Separator line usage (----) +- Track listing section + +### C. Track Validation + +When tracks exist, verify each track is properly configured. + +**Track Registry Consistency:** + +- Each track listed in `tracks.md` has a corresponding directory in `conductor/tracks/` +- Track directories contain required files: + - `spec.md` - Requirements specification + - `plan.md` - Phased task breakdown + - `metadata.json` - Track metadata + +**Status Marker Validation:** + +- Status markers in `tracks.md` match actual track states +- `[ ]` = not started (no tasks marked in progress or complete) +- `[~]` = in progress (has tasks marked `[~]` in plan.md) +- `[x]` = complete (all tasks marked `[x]` in plan.md) + +**Plan Task Markers:** + +- Tasks use proper markers: `[ ]` (pending), `[~]` (in progress), `[x]` (complete) +- Phases are properly numbered and structured +- At most one task should be `[~]` at a time + +### D. Consistency Validation + +Verify cross-artifact consistency. + +**Track ID Uniqueness:** + +- All track IDs are unique +- Track IDs follow naming convention (e.g., `feature_name_YYYYMMDD`) + +**Reference Resolution:** + +- All track references in `tracks.md` resolve to existing directories +- Cross-references between documents are valid + +**Metadata Consistency:** + +- `metadata.json` in each track is valid JSON +- Metadata reflects actual track state (status, dates, etc.) + +### E. State Validation + +Verify state files are valid. + +**setup_state.json (if exists):** + +- Valid JSON structure +- State reflects actual file system state +- No orphaned or inconsistent state entries + +## Validation Process + +1. **Use Glob** to find all relevant files and directories +2. **Use Read** to check file contents and structure +3. **Use Grep** to search for specific patterns and markers +4. **Use Bash** only for directory existence checks (e.g., `ls -la`) + +## Output Format + +Always produce a structured validation report: + +``` +## Conductor Validation Report + +### Summary +- Status: PASS | FAIL | WARNINGS +- Files checked: X +- Issues found: Y + +### Setup Validation +- [x] conductor/ directory exists +- [x] index.md exists and valid +- [x] product.md exists and valid +- [x] product-guidelines.md exists and valid +- [x] tech-stack.md exists and valid +- [x] workflow.md exists and valid +- [x] tracks.md exists and valid +- [ ] tech-stack.md missing required sections + +### Content Validation +- [x] product.md has required sections +- [ ] tech-stack.md missing "Backend" section +- [x] workflow.md has task lifecycle + +### Track Validation (if tracks exist) +- Track: auth_20250115 + - [x] Directory exists + - [x] spec.md present + - [x] plan.md present + - [x] metadata.json valid + - [ ] Status mismatch: tracks.md shows [~] but no tasks in progress + +### Issues +1. [CRITICAL] tech-stack.md: Missing "Backend" section +2. [WARNING] Track "auth_20250115": Status is [~] but no tasks in progress in plan.md +3. [INFO] product.md: Consider adding more detail to Value Proposition + +### Recommendations +1. Add Backend section to tech-stack.md with your server-side technology choices +2. Update track status in tracks.md to reflect actual progress +3. Expand Value Proposition in product.md (optional) +``` + +## Issue Severity Levels + +**CRITICAL** - Validation failure that will break Conductor commands: + +- Missing required files +- Invalid JSON in metadata files +- Missing required sections that commands depend on + +**WARNING** - Inconsistencies that may cause confusion: + +- Status markers don't match actual state +- Track references don't resolve +- Empty sections that should have content + +**INFO** - Suggestions for improvement: + +- Missing optional sections +- Best practice recommendations +- Documentation quality suggestions + +## Key Rules + +1. **Be thorough** - Check all files and cross-references +2. **Be concise** - Report findings clearly without excessive verbosity +3. **Be actionable** - Provide specific recommendations for each issue +4. **Read-only** - Never modify files; only validate and report +5. **Report all issues** - Don't stop at the first error; find everything +6. **Prioritize** - List CRITICAL issues first, then WARNING, then INFO + +## Example Validation Commands + +```bash +# Check if conductor directory exists +ls -la conductor/ + +# Find all track directories +ls -la conductor/tracks/ + +# Check for required files +ls conductor/index.md conductor/product.md conductor/tech-stack.md conductor/workflow.md conductor/tracks.md +``` + +## Pattern Matching + +**Status markers in tracks.md:** + +``` +- [ ] Track Name # Not started +- [~] Track Name # In progress +- [x] Track Name # Complete +``` + +**Task markers in plan.md:** + +``` +- [ ] Task description # Pending +- [~] Task description # In progress +- [x] Task description # Complete +``` + +**Track ID pattern:** + +``` +__ +Example: feature_user_auth_20250115 +``` diff --git a/conductor/commands/implement.md b/conductor/commands/implement.md new file mode 100644 index 0000000..46fc188 --- /dev/null +++ b/conductor/commands/implement.md @@ -0,0 +1,369 @@ +--- +name: implement +description: Execute tasks from a track's implementation plan following workflow rules +model: opus +argument-hint: "[track-id]" +--- + +Execute tasks from a track's implementation plan, following the workflow rules defined in `conductor/workflow.md`. + +## Pre-flight Checks + +1. Verify Conductor is initialized: + - Check `conductor/product.md` exists + - Check `conductor/workflow.md` exists + - Check `conductor/tracks.md` exists + - If missing: Display error and suggest running `/conductor:setup` first + +2. Load workflow configuration: + - Read `conductor/workflow.md` + - Parse TDD strictness level + - Parse commit strategy + - Parse verification checkpoint rules + +## Track Selection + +### If argument provided: + +- Validate track exists: `conductor/tracks/{argument}/plan.md` +- If not found: Search for partial matches, suggest corrections + +### If no argument: + +1. Read `conductor/tracks.md` +2. Parse for incomplete tracks (status `[ ]` or `[~]`) +3. Display selection menu: + + ``` + Select a track to implement: + + In Progress: + 1. [~] auth_20250115 - User Authentication (Phase 2, Task 3) + + Pending: + 2. [ ] nav-fix_20250114 - Navigation Bug Fix + 3. [ ] dashboard_20250113 - Dashboard Feature + + Enter number or track ID: + ``` + +## Context Loading + +Load all relevant context for implementation: + +1. Track documents: + - `conductor/tracks/{trackId}/spec.md` - Requirements + - `conductor/tracks/{trackId}/plan.md` - Task list + - `conductor/tracks/{trackId}/metadata.json` - Progress state + +2. Project context: + - `conductor/product.md` - Product understanding + - `conductor/tech-stack.md` - Technical constraints + - `conductor/workflow.md` - Process rules + +3. Code style (if exists): + - `conductor/code_styleguides/{language}.md` + +## Track Status Update + +Update track to in-progress: + +1. In `conductor/tracks.md`: + - Change `[ ]` to `[~]` for this track + +2. In `conductor/tracks/{trackId}/metadata.json`: + - Set `status: "in_progress"` + - Update `updated` timestamp + +## Task Execution Loop + +For each incomplete task in plan.md (marked with `[ ]`): + +### 1. Task Identification + +Parse plan.md to find next incomplete task: + +- Look for lines matching `- [ ] Task X.Y: {description}` +- Track current phase from structure + +### 2. Task Start + +Mark task as in-progress: + +- Update plan.md: Change `[ ]` to `[~]` for current task +- Announce: "Starting Task X.Y: {description}" + +### 3. TDD Workflow (if TDD enabled in workflow.md) + +**Red Phase - Write Failing Test:** + +``` +Following TDD workflow for Task X.Y... + +Step 1: Writing failing test +``` + +- Create test file if needed +- Write test(s) for the task functionality +- Run tests to confirm they fail +- If tests pass unexpectedly: HALT, investigate + +**Green Phase - Implement:** + +``` +Step 2: Implementing minimal code to pass test +``` + +- Write minimum code to make test pass +- Run tests to confirm they pass +- If tests fail: Debug and fix + +**Refactor Phase:** + +``` +Step 3: Refactoring while keeping tests green +``` + +- Clean up code +- Run tests to ensure still passing + +### 4. Non-TDD Workflow (if TDD not strict) + +- Implement the task directly +- Run any existing tests +- Manual verification as needed + +### 5. Task Completion + +**Commit changes** (following commit strategy from workflow.md): + +```bash +git add -A +git commit -m "{commit_prefix}: {task description} ({trackId})" +``` + +**Update plan.md:** + +- Change `[~]` to `[x]` for completed task +- Commit plan update: + +```bash +git add conductor/tracks/{trackId}/plan.md +git commit -m "chore: mark task X.Y complete ({trackId})" +``` + +**Update metadata.json:** + +- Increment `tasks.completed` +- Update `updated` timestamp + +### 6. Phase Completion Check + +After each task, check if phase is complete: + +- Parse plan.md for phase structure +- If all tasks in current phase are `[x]`: + +**Run phase verification:** + +``` +Phase {N} complete. Running verification... +``` + +- Execute verification tasks listed for the phase +- Run full test suite: `npm test` / `pytest` / etc. + +**Report and wait for approval:** + +``` +Phase {N} Verification Results: +- All phase tasks: Complete +- Tests: {passing/failing} +- Verification: {pass/fail} + +Approve to continue to Phase {N+1}? +1. Yes, continue +2. No, there are issues to fix +3. Pause implementation +``` + +**CRITICAL: Wait for explicit user approval before proceeding to next phase.** + +## Error Handling During Implementation + +### On Tool Failure + +``` +ERROR: {tool} failed with: {error message} + +Options: +1. Retry the operation +2. Skip this task and continue +3. Pause implementation +4. Revert current task changes +``` + +- HALT and present options +- Do NOT automatically continue + +### On Test Failure + +``` +TESTS FAILING after Task X.Y + +Failed tests: +- {test name}: {failure reason} + +Options: +1. Attempt to fix +2. Rollback task changes +3. Pause for manual intervention +``` + +### On Git Failure + +``` +GIT ERROR: {error message} + +This may indicate: +- Uncommitted changes from outside Conductor +- Merge conflicts +- Permission issues + +Options: +1. Show git status +2. Attempt to resolve +3. Pause for manual intervention +``` + +## Track Completion + +When all phases and tasks are complete: + +### 1. Final Verification + +``` +All tasks complete. Running final verification... +``` + +- Run full test suite +- Check all acceptance criteria from spec.md +- Generate verification report + +### 2. Update Track Status + +In `conductor/tracks.md`: + +- Change `[~]` to `[x]` for this track +- Update the "Updated" column + +In `conductor/tracks/{trackId}/metadata.json`: + +- Set `status: "complete"` +- Set `phases.completed` to total +- Set `tasks.completed` to total +- Update `updated` timestamp + +In `conductor/tracks/{trackId}/plan.md`: + +- Update header status to `[x] Complete` + +### 3. Documentation Sync Offer + +``` +Track complete! Would you like to sync documentation? + +This will update: +- conductor/product.md (if new features added) +- conductor/tech-stack.md (if new dependencies added) +- README.md (if applicable) + +1. Yes, sync documentation +2. No, skip +``` + +### 4. Cleanup Offer + +``` +Track {trackId} is complete. + +Cleanup options: +1. Archive - Move to conductor/tracks/_archive/ +2. Delete - Remove track directory +3. Keep - Leave as-is +``` + +### 5. Completion Summary + +``` +Track Complete: {track title} + +Summary: +- Track ID: {trackId} +- Phases completed: {N}/{N} +- Tasks completed: {M}/{M} +- Commits created: {count} +- Tests: All passing + +Next steps: +- Run /conductor:status to see project progress +- Run /conductor:new-track for next feature +``` + +## Progress Tracking + +Maintain progress in `metadata.json` throughout: + +```json +{ + "id": "auth_20250115", + "title": "User Authentication", + "type": "feature", + "status": "in_progress", + "created": "2025-01-15T10:00:00Z", + "updated": "2025-01-15T14:30:00Z", + "current_phase": 2, + "current_task": "2.3", + "phases": { + "total": 3, + "completed": 1 + }, + "tasks": { + "total": 12, + "completed": 7 + }, + "commits": [ + "abc1234: feat: add login form (auth_20250115)", + "def5678: feat: add password validation (auth_20250115)" + ] +} +``` + +## Resumption + +If implementation is paused and resumed: + +1. Load `metadata.json` for current state +2. Find current task from `current_task` field +3. Check if task is `[~]` in plan.md +4. Ask user: + + ``` + Resuming track: {title} + + Last task in progress: Task {X.Y}: {description} + + Options: + 1. Continue from where we left off + 2. Restart current task + 3. Show progress summary first + ``` + +## Critical Rules + +1. **NEVER skip verification checkpoints** - Always wait for user approval between phases +2. **STOP on any failure** - Do not attempt to continue past errors +3. **Follow workflow.md strictly** - TDD, commit strategy, and verification rules are mandatory +4. **Keep plan.md updated** - Task status must reflect actual progress +5. **Commit frequently** - Each task completion should be committed +6. **Track all commits** - Record commit hashes in metadata.json for potential revert diff --git a/conductor/commands/new-track.md b/conductor/commands/new-track.md new file mode 100644 index 0000000..9c30924 --- /dev/null +++ b/conductor/commands/new-track.md @@ -0,0 +1,414 @@ +--- +name: new-track +description: Create a new feature or bug track with specification and phased implementation plan +model: opus +argument-hint: "[track description]" +--- + +Create a new track (feature, bug fix, chore, or refactor) with a detailed specification and phased implementation plan. + +## Pre-flight Checks + +1. Verify Conductor is initialized: + - Check `conductor/product.md` exists + - Check `conductor/tech-stack.md` exists + - Check `conductor/workflow.md` exists + - If missing: Display error and suggest running `/conductor:setup` first + +2. Load context files: + - Read `conductor/product.md` for product context + - Read `conductor/tech-stack.md` for technical context + - Read `conductor/workflow.md` for TDD/commit preferences + +## Track Classification + +Determine track type based on description or ask user: + +``` +What type of track is this? + +1. Feature - New functionality +2. Bug - Fix for existing issue +3. Chore - Maintenance, dependencies, config +4. Refactor - Code improvement without behavior change +``` + +## Interactive Specification Gathering + +**CRITICAL RULES:** + +- Ask ONE question per turn +- Wait for user response before proceeding +- Tailor questions based on track type +- Maximum 6 questions total + +### For Feature Tracks + +**Q1: Feature Summary** + +``` +Describe the feature in 1-2 sentences. +[If argument provided, confirm: "You want to: {argument}. Is this correct?"] +``` + +**Q2: User Story** + +``` +Who benefits and how? + +Format: As a [user type], I want to [action] so that [benefit]. +``` + +**Q3: Acceptance Criteria** + +``` +What must be true for this feature to be complete? + +List 3-5 acceptance criteria (one per line): +``` + +**Q4: Dependencies** + +``` +Does this depend on any existing code, APIs, or other tracks? + +1. No dependencies +2. Depends on existing code (specify) +3. Depends on incomplete track (specify) +``` + +**Q5: Scope Boundaries** + +``` +What is explicitly OUT of scope for this track? +(Helps prevent scope creep) +``` + +**Q6: Technical Considerations (optional)** + +``` +Any specific technical approach or constraints? +(Press enter to skip) +``` + +### For Bug Tracks + +**Q1: Bug Summary** + +``` +What is broken? +[If argument provided, confirm] +``` + +**Q2: Steps to Reproduce** + +``` +How can this bug be reproduced? +List steps: +``` + +**Q3: Expected vs Actual Behavior** + +``` +What should happen vs what actually happens? +``` + +**Q4: Affected Areas** + +``` +What parts of the system are affected? +``` + +**Q5: Root Cause Hypothesis (optional)** + +``` +Any hypothesis about the cause? +(Press enter to skip) +``` + +### For Chore/Refactor Tracks + +**Q1: Task Summary** + +``` +What needs to be done? +[If argument provided, confirm] +``` + +**Q2: Motivation** + +``` +Why is this work needed? +``` + +**Q3: Success Criteria** + +``` +How will we know this is complete? +``` + +**Q4: Risk Assessment** + +``` +What could go wrong? Any risky changes? +``` + +## Track ID Generation + +Generate track ID in format: `{shortname}_{YYYYMMDD}` + +- Extract shortname from feature/bug summary (2-3 words, lowercase, hyphenated) +- Use current date +- Example: `user-auth_20250115`, `nav-bug_20250115` + +Validate uniqueness: + +- Check `conductor/tracks.md` for existing IDs +- If collision, append counter: `user-auth_20250115_2` + +## Specification Generation + +Create `conductor/tracks/{trackId}/spec.md`: + +```markdown +# Specification: {Track Title} + +**Track ID:** {trackId} +**Type:** {Feature|Bug|Chore|Refactor} +**Created:** {YYYY-MM-DD} +**Status:** Draft + +## Summary + +{1-2 sentence summary} + +## Context + +{Product context from product.md relevant to this track} + +## User Story (for features) + +As a {user}, I want to {action} so that {benefit}. + +## Problem Description (for bugs) + +{Bug description, steps to reproduce} + +## Acceptance Criteria + +- [ ] {Criterion 1} +- [ ] {Criterion 2} +- [ ] {Criterion 3} + +## Dependencies + +{List dependencies or "None"} + +## Out of Scope + +{Explicit exclusions} + +## Technical Notes + +{Technical considerations or "None specified"} + +--- + +_Generated by Conductor. Review and edit as needed._ +``` + +## User Review of Spec + +Display the generated spec and ask: + +``` +Here is the specification I've generated: + +{spec content} + +Is this specification correct? +1. Yes, proceed to plan generation +2. No, let me edit (opens for inline edits) +3. Start over with different inputs +``` + +## Plan Generation + +After spec approval, generate `conductor/tracks/{trackId}/plan.md`: + +### Plan Structure + +```markdown +# Implementation Plan: {Track Title} + +**Track ID:** {trackId} +**Spec:** [spec.md](./spec.md) +**Created:** {YYYY-MM-DD} +**Status:** [ ] Not Started + +## Overview + +{Brief summary of implementation approach} + +## Phase 1: {Phase Name} + +{Phase description} + +### Tasks + +- [ ] Task 1.1: {Description} +- [ ] Task 1.2: {Description} +- [ ] Task 1.3: {Description} + +### Verification + +- [ ] {Verification step for phase 1} + +## Phase 2: {Phase Name} + +{Phase description} + +### Tasks + +- [ ] Task 2.1: {Description} +- [ ] Task 2.2: {Description} + +### Verification + +- [ ] {Verification step for phase 2} + +## Phase 3: {Phase Name} (if needed) + +... + +## Final Verification + +- [ ] All acceptance criteria met +- [ ] Tests passing +- [ ] Documentation updated (if applicable) +- [ ] Ready for review + +--- + +_Generated by Conductor. Tasks will be marked [~] in progress and [x] complete._ +``` + +### Phase Guidelines + +- Group related tasks into logical phases +- Each phase should be independently verifiable +- Include verification task after each phase +- TDD tracks: Include test writing tasks before implementation tasks +- Typical structure: + 1. **Setup/Foundation** - Initial scaffolding, interfaces + 2. **Core Implementation** - Main functionality + 3. **Integration** - Connect with existing system + 4. **Polish** - Error handling, edge cases, docs + +## User Review of Plan + +Display the generated plan and ask: + +``` +Here is the implementation plan: + +{plan content} + +Is this plan correct? +1. Yes, create the track +2. No, let me edit (opens for inline edits) +3. Add more phases/tasks +4. Start over +``` + +## Track Creation + +After plan approval: + +1. Create directory structure: + + ``` + conductor/tracks/{trackId}/ + ├── spec.md + ├── plan.md + ├── metadata.json + └── index.md + ``` + +2. Create `metadata.json`: + + ```json + { + "id": "{trackId}", + "title": "{Track Title}", + "type": "feature|bug|chore|refactor", + "status": "pending", + "created": "ISO_TIMESTAMP", + "updated": "ISO_TIMESTAMP", + "phases": { + "total": N, + "completed": 0 + }, + "tasks": { + "total": M, + "completed": 0 + } + } + ``` + +3. Create `index.md`: + + ```markdown + # Track: {Track Title} + + **ID:** {trackId} + **Status:** Pending + + ## Documents + + - [Specification](./spec.md) + - [Implementation Plan](./plan.md) + + ## Progress + + - Phases: 0/{N} complete + - Tasks: 0/{M} complete + + ## Quick Links + + - [Back to Tracks](../../tracks.md) + - [Product Context](../../product.md) + ``` + +4. Register in `conductor/tracks.md`: + - Add row to tracks table + - Format: `| [ ] | {trackId} | {title} | {created} | {created} |` + +5. Update `conductor/index.md`: + - Add track to "Active Tracks" section + +## Completion Message + +``` +Track created successfully! + +Track ID: {trackId} +Location: conductor/tracks/{trackId}/ + +Files created: +- spec.md - Requirements specification +- plan.md - Phased implementation plan +- metadata.json - Track metadata +- index.md - Track navigation + +Next steps: +1. Review spec.md and plan.md, make any edits +2. Run /conductor:implement {trackId} to start implementation +3. Run /conductor:status to see project progress +``` + +## Error Handling + +- If directory creation fails: Halt and report, do not register in tracks.md +- If any file write fails: Clean up partial track, report error +- If tracks.md update fails: Warn user to manually register track diff --git a/conductor/commands/revert.md b/conductor/commands/revert.md new file mode 100644 index 0000000..41da1b7 --- /dev/null +++ b/conductor/commands/revert.md @@ -0,0 +1,361 @@ +--- +name: revert +description: Git-aware undo by logical work unit (track, phase, or task) +model: opus +allowed-tools: + - Read + - Write + - Edit + - Bash + - Glob + - Grep + - AskUserQuestion +argument-hint: "[track-id | track-id:phase | track-id:task]" +--- + +Revert changes by logical work unit with full git awareness. Supports reverting entire tracks, specific phases, or individual tasks. + +## Pre-flight Checks + +1. Verify Conductor is initialized: + - Check `conductor/tracks.md` exists + - If missing: Display error and suggest running `/conductor:setup` first + +2. Verify git repository: + - Run `git status` to confirm git repo + - Check for uncommitted changes + - If uncommitted changes exist: + + ``` + WARNING: Uncommitted changes detected + + Files with changes: + {list of files} + + Options: + 1. Stash changes and continue + 2. Commit changes first + 3. Cancel revert + ``` + +3. Verify git is clean enough to revert: + - No merge in progress + - No rebase in progress + - If issues found: Halt and explain resolution steps + +## Target Selection + +### If argument provided: + +Parse the argument format: + +**Full track:** `{trackId}` + +- Example: `auth_20250115` +- Reverts all commits for the entire track + +**Specific phase:** `{trackId}:phase{N}` + +- Example: `auth_20250115:phase2` +- Reverts commits for phase N and all subsequent phases + +**Specific task:** `{trackId}:task{X.Y}` + +- Example: `auth_20250115:task2.3` +- Reverts commits for task X.Y only + +### If no argument: + +Display guided selection menu: + +``` +What would you like to revert? + +Currently In Progress: +1. [~] Task 2.3 in dashboard_20250112 (most recent) + +Recently Completed: +2. [x] Task 2.2 in dashboard_20250112 (1 hour ago) +3. [x] Phase 1 in dashboard_20250112 (3 hours ago) +4. [x] Full track: auth_20250115 (yesterday) + +Options: +5. Enter specific reference (track:phase or track:task) +6. Cancel + +Select option: +``` + +## Commit Discovery + +### For Task Revert + +1. Search git log for task-specific commits: + + ```bash + git log --oneline --grep="{trackId}" --grep="Task {X.Y}" --all-match + ``` + +2. Also find the plan.md update commit: + + ```bash + git log --oneline --grep="mark task {X.Y} complete" --grep="{trackId}" --all-match + ``` + +3. Collect all matching commit SHAs + +### For Phase Revert + +1. Determine task range for the phase by reading plan.md +2. Search for all task commits in that phase: + + ```bash + git log --oneline --grep="{trackId}" | grep -E "Task {N}\.[0-9]" + ``` + +3. Find phase verification commit if exists +4. Find all plan.md update commits for phase tasks +5. Collect all matching commit SHAs in chronological order + +### For Full Track Revert + +1. Find ALL commits mentioning the track: + + ```bash + git log --oneline --grep="{trackId}" + ``` + +2. Find track creation commits: + + ```bash + git log --oneline -- "conductor/tracks/{trackId}/" + ``` + +3. Collect all matching commit SHAs in chronological order + +## Execution Plan Display + +Before any revert operations, display full plan: + +``` +================================================================================ + REVERT EXECUTION PLAN +================================================================================ + +Target: {description of what's being reverted} + +Commits to revert (in reverse chronological order): + 1. abc1234 - feat: add chart rendering (dashboard_20250112) + 2. def5678 - chore: mark task 2.3 complete (dashboard_20250112) + 3. ghi9012 - feat: add data hooks (dashboard_20250112) + 4. jkl3456 - chore: mark task 2.2 complete (dashboard_20250112) + +Files that will be affected: + - src/components/Dashboard.tsx (modified) + - src/hooks/useData.ts (will be deleted - was created in these commits) + - conductor/tracks/dashboard_20250112/plan.md (modified) + +Plan updates: + - Task 2.2: [x] -> [ ] + - Task 2.3: [~] -> [ ] + +================================================================================ + !! WARNING !! +================================================================================ + +This operation will: +- Create {N} revert commits +- Modify {M} files +- Reset {P} tasks to pending status + +This CANNOT be easily undone without manual intervention. + +================================================================================ + +Type 'YES' to proceed, or anything else to cancel: +``` + +**CRITICAL: Require explicit 'YES' confirmation. Do not proceed on 'y', 'yes', or enter.** + +## Revert Execution + +Execute reverts in reverse chronological order (newest first): + +``` +Executing revert plan... + +[1/4] Reverting abc1234... + git revert --no-edit abc1234 + ✓ Success + +[2/4] Reverting def5678... + git revert --no-edit def5678 + ✓ Success + +[3/4] Reverting ghi9012... + git revert --no-edit ghi9012 + ✓ Success + +[4/4] Reverting jkl3456... + git revert --no-edit jkl3456 + ✓ Success +``` + +### On Merge Conflict + +If any revert produces a merge conflict: + +``` +================================================================================ + MERGE CONFLICT DETECTED +================================================================================ + +Conflict occurred while reverting: {sha} - {message} + +Conflicted files: + - src/components/Dashboard.tsx + +Options: +1. Show conflict details +2. Abort revert sequence (keeps completed reverts) +3. Open manual resolution guide + +IMPORTANT: Reverts 1-{N} have been completed. You may need to manually +resolve this conflict before continuing or fully undo the revert sequence. + +Select option: +``` + +**HALT immediately on any conflict. Do not attempt automatic resolution.** + +## Plan.md Updates + +After successful git reverts, update plan.md: + +1. Read current plan.md +2. For each reverted task, change marker: + - `[x]` -> `[ ]` + - `[~]` -> `[ ]` +3. Write updated plan.md +4. Update metadata.json: + - Decrement `tasks.completed` + - Update `status` if needed + - Update `updated` timestamp + +**Do NOT commit plan.md changes** - they are part of the revert operation + +## Track Status Updates + +### If reverting entire track: + +- In tracks.md: Change `[x]` or `[~]` to `[ ]` +- Consider offering to delete the track directory entirely + +### If reverting to incomplete state: + +- In tracks.md: Ensure marked as `[~]` if partially complete, `[ ]` if fully reverted + +## Verification + +After revert completion: + +``` +================================================================================ + REVERT COMPLETE +================================================================================ + +Summary: + - Reverted {N} commits + - Reset {P} tasks to pending + - {M} files affected + +Git log now shows: + {recent commit history} + +Plan.md status: + - Task 2.2: [ ] Pending + - Task 2.3: [ ] Pending + +================================================================================ + +Verify the revert was successful: + 1. Run tests: {test command} + 2. Check application: {relevant check} + +If issues are found, you may need to: + - Fix conflicts manually + - Re-implement the reverted tasks + - Use 'git revert HEAD~{N}..HEAD' to undo the reverts + +================================================================================ +``` + +## Safety Rules + +1. **NEVER use `git reset --hard`** - Only use `git revert` +2. **NEVER use `git push --force`** - Only safe push operations +3. **NEVER auto-resolve conflicts** - Always halt for human intervention +4. **ALWAYS show full plan** - User must see exactly what will happen +5. **REQUIRE explicit 'YES'** - Not 'y', not enter, only 'YES' +6. **HALT on ANY error** - Do not attempt to continue past failures +7. **PRESERVE history** - Revert commits are preferred over history rewriting + +## Edge Cases + +### Track Never Committed + +``` +No commits found for track: {trackId} + +The track exists but has no associated commits. This may mean: +- Implementation never started +- Commits used different format + +Options: +1. Delete track directory only +2. Cancel +``` + +### Commits Already Reverted + +``` +Some commits appear to already be reverted: + - abc1234 was reverted by xyz9876 + +Options: +1. Skip already-reverted commits +2. Cancel and investigate +``` + +### Remote Already Pushed + +``` +WARNING: Some commits have been pushed to remote + +Commits on remote: + - abc1234 (origin/main) + - def5678 (origin/main) + +Reverting will create new revert commits that you'll need to push. +This is the safe approach (no force push required). + +Continue with revert? (YES/no): +``` + +## Undo the Revert + +If user needs to undo the revert itself: + +``` +To undo this revert operation: + + git revert HEAD~{N}..HEAD + +This will create new commits that restore the reverted changes. + +Alternatively, if not yet pushed: + git reset --soft HEAD~{N} + git checkout -- . + +(Use with caution - this discards the revert commits) +``` diff --git a/conductor/commands/setup.md b/conductor/commands/setup.md new file mode 100644 index 0000000..8debb77 --- /dev/null +++ b/conductor/commands/setup.md @@ -0,0 +1,406 @@ +--- +name: setup +description: Initialize project with Conductor artifacts (product definition, tech stack, workflow, style guides) +model: opus +argument-hint: "[--resume]" +--- + +Initialize or resume Conductor project setup. This command creates foundational project documentation through interactive Q&A. + +## Pre-flight Checks + +1. Check if `conductor/` directory already exists in the project root: + - If `conductor/product.md` exists: Ask user whether to resume setup or reinitialize + - If `conductor/setup_state.json` exists with incomplete status: Offer to resume from last step + +2. Detect project type by checking for existing indicators: + - **Greenfield (new project)**: No .git, no package.json, no requirements.txt, no go.mod, no src/ directory + - **Brownfield (existing project)**: Any of the above exist + +3. Load or create `conductor/setup_state.json`: + ```json + { + "status": "in_progress", + "project_type": "greenfield|brownfield", + "current_section": "product|guidelines|tech_stack|workflow|styleguides", + "current_question": 1, + "completed_sections": [], + "answers": {}, + "files_created": [], + "started_at": "ISO_TIMESTAMP", + "last_updated": "ISO_TIMESTAMP" + } + ``` + +## Interactive Q&A Protocol + +**CRITICAL RULES:** + +- Ask ONE question per turn +- Wait for user response before proceeding +- Offer 2-3 suggested answers plus "Type your own" option +- Maximum 5 questions per section +- Update `setup_state.json` after each successful step +- Validate file writes succeeded before continuing + +### Section 1: Product Definition (max 5 questions) + +**Q1: Project Name** + +``` +What is your project name? + +Suggested: +1. [Infer from directory name] +2. [Infer from package.json/go.mod if brownfield] +3. Type your own +``` + +**Q2: Project Description** + +``` +Describe your project in one sentence. + +Suggested: +1. A web application that [does X] +2. A CLI tool for [doing Y] +3. Type your own +``` + +**Q3: Problem Statement** + +``` +What problem does this project solve? + +Suggested: +1. Users struggle to [pain point] +2. There's no good way to [need] +3. Type your own +``` + +**Q4: Target Users** + +``` +Who are the primary users? + +Suggested: +1. Developers building [X] +2. End users who need [Y] +3. Internal teams managing [Z] +4. Type your own +``` + +**Q5: Key Goals (optional)** + +``` +What are 2-3 key goals for this project? (Press enter to skip) +``` + +### Section 2: Product Guidelines (max 3 questions) + +**Q1: Voice and Tone** + +``` +What voice/tone should documentation and UI text use? + +Suggested: +1. Professional and technical +2. Friendly and approachable +3. Concise and direct +4. Type your own +``` + +**Q2: Design Principles** + +``` +What design principles guide this project? + +Suggested: +1. Simplicity over features +2. Performance first +3. Developer experience focused +4. User safety and reliability +5. Type your own (comma-separated) +``` + +### Section 3: Tech Stack (max 5 questions) + +For **brownfield projects**, first analyze existing code: + +- Run `Glob` to find package.json, requirements.txt, go.mod, Cargo.toml, etc. +- Parse detected files to pre-populate tech stack +- Present findings and ask for confirmation/additions + +**Q1: Primary Language(s)** + +``` +What primary language(s) does this project use? + +[For brownfield: "I detected: Python 3.11, JavaScript. Is this correct?"] + +Suggested: +1. TypeScript +2. Python +3. Go +4. Rust +5. Type your own (comma-separated) +``` + +**Q2: Frontend Framework (if applicable)** + +``` +What frontend framework (if any)? + +Suggested: +1. React +2. Vue +3. Next.js +4. None / CLI only +5. Type your own +``` + +**Q3: Backend Framework (if applicable)** + +``` +What backend framework (if any)? + +Suggested: +1. Express / Fastify +2. Django / FastAPI +3. Go standard library +4. None / Frontend only +5. Type your own +``` + +**Q4: Database (if applicable)** + +``` +What database (if any)? + +Suggested: +1. PostgreSQL +2. MongoDB +3. SQLite +4. None / Stateless +5. Type your own +``` + +**Q5: Infrastructure** + +``` +Where will this be deployed? + +Suggested: +1. AWS (Lambda, ECS, etc.) +2. Vercel / Netlify +3. Self-hosted / Docker +4. Not decided yet +5. Type your own +``` + +### Section 4: Workflow Preferences (max 4 questions) + +**Q1: TDD Strictness** + +``` +How strictly should TDD be enforced? + +Suggested: +1. Strict - tests required before implementation +2. Moderate - tests encouraged, not blocked +3. Flexible - tests recommended for complex logic +``` + +**Q2: Commit Strategy** + +``` +What commit strategy should be followed? + +Suggested: +1. Conventional Commits (feat:, fix:, etc.) +2. Descriptive messages, no format required +3. Squash commits per task +``` + +**Q3: Code Review Requirements** + +``` +What code review policy? + +Suggested: +1. Required for all changes +2. Required for non-trivial changes +3. Optional / self-review OK +``` + +**Q4: Verification Checkpoints** + +``` +When should manual verification be required? + +Suggested: +1. After each phase completion +2. After each task completion +3. Only at track completion +``` + +### Section 5: Code Style Guides (max 2 questions) + +**Q1: Languages to Include** + +``` +Which language style guides should be generated? + +[Based on detected languages, pre-select] + +Options: +1. TypeScript/JavaScript +2. Python +3. Go +4. Rust +5. All detected languages +6. Skip style guides +``` + +**Q2: Existing Conventions** + +``` +Do you have existing linting/formatting configs to incorporate? + +[For brownfield: "I found .eslintrc, .prettierrc. Should I incorporate these?"] + +Suggested: +1. Yes, use existing configs +2. No, generate fresh guides +3. Skip this step +``` + +## Artifact Generation + +After completing Q&A, generate the following files: + +### 1. conductor/index.md + +```markdown +# Conductor - [Project Name] + +Navigation hub for project context. + +## Quick Links + +- [Product Definition](./product.md) +- [Product Guidelines](./product-guidelines.md) +- [Tech Stack](./tech-stack.md) +- [Workflow](./workflow.md) +- [Tracks](./tracks.md) + +## Active Tracks + + + +## Getting Started + +Run `/conductor:new-track` to create your first feature track. +``` + +### 2. conductor/product.md + +Template populated with Q&A answers for: + +- Project name and description +- Problem statement +- Target users +- Key goals + +### 3. conductor/product-guidelines.md + +Template populated with: + +- Voice and tone +- Design principles +- Any additional standards + +### 4. conductor/tech-stack.md + +Template populated with: + +- Languages (with versions if detected) +- Frameworks (frontend, backend) +- Database +- Infrastructure +- Key dependencies (for brownfield, from package files) + +### 5. conductor/workflow.md + +Template populated with: + +- TDD policy and strictness level +- Commit strategy and conventions +- Code review requirements +- Verification checkpoint rules +- Task lifecycle definition + +### 6. conductor/tracks.md + +```markdown +# Tracks Registry + +| Status | Track ID | Title | Created | Updated | +| ------ | -------- | ----- | ------- | ------- | + + +``` + +### 7. conductor/code_styleguides/ + +Generate selected style guides from `$CLAUDE_PLUGIN_ROOT/templates/code_styleguides/` + +## State Management + +After each successful file creation: + +1. Update `setup_state.json`: + - Add filename to `files_created` array + - Update `last_updated` timestamp + - If section complete, add to `completed_sections` +2. Verify file exists with `Read` tool + +## Completion + +When all files are created: + +1. Set `setup_state.json` status to "complete" +2. Display summary: + + ``` + Conductor setup complete! + + Created artifacts: + - conductor/index.md + - conductor/product.md + - conductor/product-guidelines.md + - conductor/tech-stack.md + - conductor/workflow.md + - conductor/tracks.md + - conductor/code_styleguides/[languages] + + Next steps: + 1. Review generated files and customize as needed + 2. Run /conductor:new-track to create your first track + ``` + +## Resume Handling + +If `--resume` argument or resuming from state: + +1. Load `setup_state.json` +2. Skip completed sections +3. Resume from `current_section` and `current_question` +4. Verify previously created files still exist +5. If files missing, offer to regenerate + +## Error Handling + +- If file write fails: Halt and report error, do not update state +- If user cancels: Save current state for future resume +- If state file corrupted: Offer to start fresh or attempt recovery diff --git a/conductor/commands/status.md b/conductor/commands/status.md new file mode 100644 index 0000000..7566a9b --- /dev/null +++ b/conductor/commands/status.md @@ -0,0 +1,323 @@ +--- +name: status +description: Display project progress overview including tracks, phases, and tasks +model: opus +allowed-tools: + - Read + - Glob + - Grep +argument-hint: "[track-id]" +--- + +Display the current status of the Conductor project, including overall progress, active tracks, and next actions. + +## Pre-flight Checks + +1. Verify Conductor is initialized: + - Check `conductor/product.md` exists + - Check `conductor/tracks.md` exists + - If missing: Display error and suggest running `/conductor:setup` first + +2. Check for any tracks: + - Read `conductor/tracks.md` + - If no tracks registered: Display setup complete message with suggestion to create first track + +## Data Collection + +### 1. Project Information + +Read `conductor/product.md` and extract: + +- Project name +- Project description + +### 2. Tracks Overview + +Read `conductor/tracks.md` and parse: + +- Total tracks count +- Completed tracks (marked `[x]`) +- In-progress tracks (marked `[~]`) +- Pending tracks (marked `[ ]`) + +### 3. Detailed Track Analysis + +For each track in `conductor/tracks/`: + +Read `conductor/tracks/{trackId}/plan.md`: + +- Count total tasks (lines matching `- [x]`, `- [~]`, `- [ ]` with Task prefix) +- Count completed tasks (`[x]`) +- Count in-progress tasks (`[~]`) +- Count pending tasks (`[ ]`) +- Identify current phase (first phase with incomplete tasks) +- Identify next pending task + +Read `conductor/tracks/{trackId}/metadata.json`: + +- Track type (feature, bug, chore, refactor) +- Created date +- Last updated date +- Status + +Read `conductor/tracks/{trackId}/spec.md`: + +- Check for any noted blockers or dependencies + +### 4. Blocker Detection + +Scan for potential blockers: + +- Tasks marked with `BLOCKED:` prefix +- Dependencies on incomplete tracks +- Failed verification tasks + +## Output Format + +### Full Project Status (no argument) + +``` +================================================================================ + PROJECT STATUS: {Project Name} +================================================================================ +Last Updated: {current timestamp} + +-------------------------------------------------------------------------------- + OVERALL PROGRESS +-------------------------------------------------------------------------------- + +Tracks: {completed}/{total} completed ({percentage}%) +Tasks: {completed}/{total} completed ({percentage}%) + +Progress: [##########..........] {percentage}% + +-------------------------------------------------------------------------------- + TRACK SUMMARY +-------------------------------------------------------------------------------- + +| Status | Track ID | Type | Tasks | Last Updated | +|--------|-------------------|---------|------------|--------------| +| [x] | auth_20250110 | feature | 12/12 (100%)| 2025-01-12 | +| [~] | dashboard_20250112| feature | 7/15 (47%) | 2025-01-15 | +| [ ] | nav-fix_20250114 | bug | 0/4 (0%) | 2025-01-14 | + +-------------------------------------------------------------------------------- + CURRENT FOCUS +-------------------------------------------------------------------------------- + +Active Track: dashboard_20250112 - Dashboard Feature +Current Phase: Phase 2: Core Components +Current Task: [~] Task 2.3: Implement chart rendering + +Progress in Phase: + - [x] Task 2.1: Create dashboard layout + - [x] Task 2.2: Add data fetching hooks + - [~] Task 2.3: Implement chart rendering + - [ ] Task 2.4: Add filter controls + +-------------------------------------------------------------------------------- + NEXT ACTIONS +-------------------------------------------------------------------------------- + +1. Complete: Task 2.3 - Implement chart rendering (dashboard_20250112) +2. Then: Task 2.4 - Add filter controls (dashboard_20250112) +3. After Phase 2: Phase verification checkpoint + +-------------------------------------------------------------------------------- + BLOCKERS +-------------------------------------------------------------------------------- + +{If blockers found:} +! BLOCKED: Task 3.1 in dashboard_20250112 depends on api_20250111 (incomplete) + +{If no blockers:} +No blockers identified. + +================================================================================ +Commands: /conductor:implement {trackId} | /conductor:new-track | /conductor:revert +================================================================================ +``` + +### Single Track Status (with track-id argument) + +``` +================================================================================ + TRACK STATUS: {Track Title} +================================================================================ +Track ID: {trackId} +Type: {feature|bug|chore|refactor} +Status: {Pending|In Progress|Complete} +Created: {date} +Updated: {date} + +-------------------------------------------------------------------------------- + SPECIFICATION +-------------------------------------------------------------------------------- + +Summary: {brief summary from spec.md} + +Acceptance Criteria: + - [x] {Criterion 1} + - [ ] {Criterion 2} + - [ ] {Criterion 3} + +-------------------------------------------------------------------------------- + IMPLEMENTATION +-------------------------------------------------------------------------------- + +Overall: {completed}/{total} tasks ({percentage}%) +Progress: [##########..........] {percentage}% + +## Phase 1: {Phase Name} [COMPLETE] + - [x] Task 1.1: {description} + - [x] Task 1.2: {description} + - [x] Verification: {description} + +## Phase 2: {Phase Name} [IN PROGRESS] + - [x] Task 2.1: {description} + - [~] Task 2.2: {description} <-- CURRENT + - [ ] Task 2.3: {description} + - [ ] Verification: {description} + +## Phase 3: {Phase Name} [PENDING] + - [ ] Task 3.1: {description} + - [ ] Task 3.2: {description} + - [ ] Verification: {description} + +-------------------------------------------------------------------------------- + GIT HISTORY +-------------------------------------------------------------------------------- + +Related Commits: + abc1234 - feat: add login form ({trackId}) + def5678 - feat: add password validation ({trackId}) + ghi9012 - chore: mark task 1.2 complete ({trackId}) + +-------------------------------------------------------------------------------- + NEXT STEPS +-------------------------------------------------------------------------------- + +1. Current: Task 2.2 - {description} +2. Next: Task 2.3 - {description} +3. Phase 2 verification pending + +================================================================================ +Commands: /conductor:implement {trackId} | /conductor:revert {trackId} +================================================================================ +``` + +## Status Markers Legend + +Display at bottom if helpful: + +``` +Legend: + [x] = Complete + [~] = In Progress + [ ] = Pending + [!] = Blocked +``` + +## Error States + +### No Tracks Found + +``` +================================================================================ + PROJECT STATUS: {Project Name} +================================================================================ + +Conductor is set up but no tracks have been created yet. + +To get started: + /conductor:new-track "your feature description" + +================================================================================ +``` + +### Conductor Not Initialized + +``` +ERROR: Conductor not initialized + +Could not find conductor/product.md + +Run /conductor:setup to initialize Conductor for this project. +``` + +### Track Not Found (with argument) + +``` +ERROR: Track not found: {argument} + +Available tracks: + - auth_20250115 + - dashboard_20250112 + - nav-fix_20250114 + +Usage: /conductor:status [track-id] +``` + +## Calculation Logic + +### Task Counting + +``` +For each plan.md: + - Complete: count lines matching /^- \[x\] Task/ + - In Progress: count lines matching /^- \[~\] Task/ + - Pending: count lines matching /^- \[ \] Task/ + - Total: Complete + In Progress + Pending +``` + +### Phase Detection + +``` +Current phase = first phase header followed by any incomplete task ([ ] or [~]) +``` + +### Progress Bar + +``` +filled = floor((completed / total) * 20) +empty = 20 - filled +bar = "[" + "#".repeat(filled) + ".".repeat(empty) + "]" +``` + +## Quick Mode + +If invoked with `--quick` or `-q`: + +``` +{Project Name}: {completed}/{total} tasks ({percentage}%) +Active: {trackId} - Task {X.Y} +``` + +## JSON Output + +If invoked with `--json`: + +```json +{ + "project": "{name}", + "timestamp": "ISO_TIMESTAMP", + "tracks": { + "total": N, + "completed": X, + "in_progress": Y, + "pending": Z + }, + "tasks": { + "total": M, + "completed": A, + "in_progress": B, + "pending": C + }, + "current": { + "track": "{trackId}", + "phase": N, + "task": "{X.Y}" + }, + "blockers": [] +} +``` diff --git a/conductor/skills/context-driven-development/SKILL.md b/conductor/skills/context-driven-development/SKILL.md new file mode 100644 index 0000000..0b29c71 --- /dev/null +++ b/conductor/skills/context-driven-development/SKILL.md @@ -0,0 +1,385 @@ +--- +name: context-driven-development +description: Use this skill when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship between product.md, tech-stack.md, and workflow.md files. +version: 1.0.0 +--- + +# Context-Driven Development + +Guide for implementing and maintaining context as a managed artifact alongside code, enabling consistent AI interactions and team alignment through structured project documentation. + +## When to Use This Skill + +- Setting up new projects with Conductor +- Understanding the relationship between context artifacts +- Maintaining consistency across AI-assisted development sessions +- Onboarding team members to an existing Conductor project +- Deciding when to update context documents +- Managing greenfield vs brownfield project contexts + +## Core Philosophy + +Context-Driven Development treats project context as a first-class artifact managed alongside code. Instead of relying on ad-hoc prompts or scattered documentation, establish a persistent, structured foundation that informs all AI interactions. + +Key principles: + +1. **Context precedes code**: Define what you're building and how before implementation +2. **Living documentation**: Context artifacts evolve with the project +3. **Single source of truth**: One canonical location for each type of information +4. **AI alignment**: Consistent context produces consistent AI behavior + +## The Workflow + +Follow the **Context → Spec & Plan → Implement** workflow: + +1. **Context Phase**: Establish or verify project context artifacts exist and are current +2. **Specification Phase**: Define requirements and acceptance criteria for work units +3. **Planning Phase**: Break specifications into phased, actionable tasks +4. **Implementation Phase**: Execute tasks following established workflow patterns + +## Artifact Relationships + +### product.md - Defines WHAT and WHY + +Purpose: Captures product vision, goals, target users, and business context. + +Contents: + +- Product name and one-line description +- Problem statement and solution approach +- Target user personas +- Core features and capabilities +- Success metrics and KPIs +- Product roadmap (high-level) + +Update when: + +- Product vision or goals change +- New major features are planned +- Target audience shifts +- Business priorities evolve + +### product-guidelines.md - Defines HOW to Communicate + +Purpose: Establishes brand voice, messaging standards, and communication patterns. + +Contents: + +- Brand voice and tone guidelines +- Terminology and glossary +- Error message conventions +- User-facing copy standards +- Documentation style + +Update when: + +- Brand guidelines change +- New terminology is introduced +- Communication patterns need refinement + +### tech-stack.md - Defines WITH WHAT + +Purpose: Documents technology choices, dependencies, and architectural decisions. + +Contents: + +- Primary languages and frameworks +- Key dependencies with versions +- Infrastructure and deployment targets +- Development tools and environment +- Testing frameworks +- Code quality tools + +Update when: + +- Adding new dependencies +- Upgrading major versions +- Changing infrastructure +- Adopting new tools or patterns + +### workflow.md - Defines HOW to Work + +Purpose: Establishes development practices, quality gates, and team workflows. + +Contents: + +- Development methodology (TDD, etc.) +- Git workflow and commit conventions +- Code review requirements +- Testing requirements and coverage targets +- Quality assurance gates +- Deployment procedures + +Update when: + +- Team practices evolve +- Quality standards change +- New workflow patterns are adopted + +### tracks.md - Tracks WHAT'S HAPPENING + +Purpose: Registry of all work units with status and metadata. + +Contents: + +- Active tracks with current status +- Completed tracks with completion dates +- Track metadata (type, priority, assignee) +- Links to individual track directories + +Update when: + +- New tracks are created +- Track status changes +- Tracks are completed or archived + +## Context Maintenance Principles + +### Keep Artifacts Synchronized + +Ensure changes in one artifact reflect in related documents: + +- New feature in product.md → Update tech-stack.md if new dependencies needed +- Completed track → Update product.md to reflect new capabilities +- Workflow change → Update all affected track plans + +### Update tech-stack.md When Adding Dependencies + +Before adding any new dependency: + +1. Check if existing dependencies solve the need +2. Document the rationale for new dependencies +3. Add version constraints +4. Note any configuration requirements + +### Update product.md When Features Complete + +After completing a feature track: + +1. Move feature from "planned" to "implemented" in product.md +2. Update any affected success metrics +3. Document any scope changes from original plan + +### Verify Context Before Implementation + +Before starting any track: + +1. Read all context artifacts +2. Flag any outdated information +3. Propose updates before proceeding +4. Confirm context accuracy with stakeholders + +## Greenfield vs Brownfield Handling + +### Greenfield Projects (New) + +For new projects: + +1. Run `/conductor:setup` to create all artifacts interactively +2. Answer questions about product vision, tech preferences, and workflow +3. Generate initial style guides for chosen languages +4. Create empty tracks registry + +Characteristics: + +- Full control over context structure +- Define standards before code exists +- Establish patterns early + +### Brownfield Projects (Existing) + +For existing codebases: + +1. Run `/conductor:setup` with existing codebase detection +2. System analyzes existing code, configs, and documentation +3. Pre-populate artifacts based on discovered patterns +4. Review and refine generated context + +Characteristics: + +- Extract implicit context from existing code +- Reconcile existing patterns with desired patterns +- Document technical debt and modernization plans +- Preserve working patterns while establishing standards + +## Benefits + +### Team Alignment + +- New team members onboard faster with explicit context +- Consistent terminology and conventions across the team +- Shared understanding of product goals and technical decisions + +### AI Consistency + +- AI assistants produce aligned outputs across sessions +- Reduced need to re-explain context in each interaction +- Predictable behavior based on documented standards + +### Institutional Memory + +- Decisions and rationale are preserved +- Context survives team changes +- Historical context informs future decisions + +### Quality Assurance + +- Standards are explicit and verifiable +- Deviations from context are detectable +- Quality gates are documented and enforceable + +## Directory Structure + +``` +conductor/ +├── index.md # Navigation hub linking all artifacts +├── product.md # Product vision and goals +├── product-guidelines.md # Communication standards +├── tech-stack.md # Technology preferences +├── workflow.md # Development practices +├── tracks.md # Work unit registry +├── setup_state.json # Resumable setup state +├── code_styleguides/ # Language-specific conventions +│ ├── python.md +│ ├── typescript.md +│ └── ... +└── tracks/ + └── / + ├── spec.md + ├── plan.md + ├── metadata.json + └── index.md +``` + +## Context Lifecycle + +1. **Creation**: Initial setup via `/conductor:setup` +2. **Validation**: Verify before each track +3. **Evolution**: Update as project grows +4. **Synchronization**: Keep artifacts aligned +5. **Archival**: Document historical decisions + +## Context Validation Checklist + +Before starting implementation on any track, validate context: + +### Product Context + +- [ ] product.md reflects current product vision +- [ ] Target users are accurately described +- [ ] Feature list is up to date +- [ ] Success metrics are defined + +### Technical Context + +- [ ] tech-stack.md lists all current dependencies +- [ ] Version numbers are accurate +- [ ] Infrastructure targets are correct +- [ ] Development tools are documented + +### Workflow Context + +- [ ] workflow.md describes current practices +- [ ] Quality gates are defined +- [ ] Coverage targets are specified +- [ ] Commit conventions are documented + +### Track Context + +- [ ] tracks.md shows all active work +- [ ] No stale or abandoned tracks +- [ ] Dependencies between tracks are noted + +## Common Anti-Patterns + +Avoid these context management mistakes: + +### Stale Context + +Problem: Context documents become outdated and misleading. +Solution: Update context as part of each track's completion process. + +### Context Sprawl + +Problem: Information scattered across multiple locations. +Solution: Use the defined artifact structure; resist creating new document types. + +### Implicit Context + +Problem: Relying on knowledge not captured in artifacts. +Solution: If you reference something repeatedly, add it to the appropriate artifact. + +### Context Hoarding + +Problem: One person maintains context without team input. +Solution: Review context artifacts in pull requests; make updates collaborative. + +### Over-Specification + +Problem: Context becomes so detailed it's impossible to maintain. +Solution: Keep artifacts focused on decisions that affect AI behavior and team alignment. + +## Integration with Development Tools + +### IDE Integration + +Configure your IDE to display context files prominently: + +- Pin conductor/product.md for quick reference +- Add tech-stack.md to project notes +- Create snippets for common patterns from style guides + +### Git Hooks + +Consider pre-commit hooks that: + +- Warn when dependencies change without tech-stack.md update +- Remind to update product.md when feature branches merge +- Validate context artifact syntax + +### CI/CD Integration + +Include context validation in pipelines: + +- Check tech-stack.md matches actual dependencies +- Verify links in context documents resolve +- Ensure tracks.md status matches git branch state + +## Session Continuity + +Conductor supports multi-session development through context persistence: + +### Starting a New Session + +1. Read index.md to orient yourself +2. Check tracks.md for active work +3. Review relevant track's plan.md for current task +4. Verify context artifacts are current + +### Ending a Session + +1. Update plan.md with current progress +2. Note any blockers or decisions made +3. Commit in-progress work with clear status +4. Update tracks.md if status changed + +### Handling Interruptions + +If interrupted mid-task: + +1. Mark task as `[~]` with note about stopping point +2. Commit work-in-progress to feature branch +3. Document any uncommitted decisions in plan.md + +## Best Practices + +1. **Read context first**: Always read relevant artifacts before starting work +2. **Small updates**: Make incremental context changes, not massive rewrites +3. **Link decisions**: Reference context when making implementation choices +4. **Version context**: Commit context changes alongside code changes +5. **Review context**: Include context artifact reviews in code reviews +6. **Validate regularly**: Run context validation checklist before major work +7. **Communicate changes**: Notify team when context artifacts change significantly +8. **Preserve history**: Use git to track context evolution over time +9. **Question staleness**: If context feels wrong, investigate and update +10. **Keep it actionable**: Every context item should inform a decision or behavior diff --git a/conductor/skills/track-management/SKILL.md b/conductor/skills/track-management/SKILL.md new file mode 100644 index 0000000..27e5ec0 --- /dev/null +++ b/conductor/skills/track-management/SKILL.md @@ -0,0 +1,593 @@ +--- +name: track-management +description: Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan.md, and track lifecycle operations. +version: 1.0.0 +--- + +# Track Management + +Guide for creating, managing, and completing Conductor tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases. + +## When to Use This Skill + +- Creating new feature, bug, or refactor tracks +- Writing or reviewing spec.md files +- Creating or updating plan.md files +- Managing track lifecycle from creation to completion +- Understanding track status markers and conventions +- Working with the tracks.md registry +- Interpreting or updating track metadata + +## Track Concept + +A track is a logical work unit that encapsulates a complete piece of work. Each track has: + +- A unique identifier +- A specification defining requirements +- A phased plan breaking work into tasks +- Metadata tracking status and progress + +Tracks provide semantic organization for work, enabling: + +- Clear scope boundaries +- Progress tracking +- Git-aware operations (revert by track) +- Team coordination + +## Track Types + +### feature + +New functionality or capabilities. Use for: + +- New user-facing features +- New API endpoints +- New integrations +- Significant enhancements + +### bug + +Defect fixes. Use for: + +- Incorrect behavior +- Error conditions +- Performance regressions +- Security vulnerabilities + +### chore + +Maintenance and housekeeping. Use for: + +- Dependency updates +- Configuration changes +- Documentation updates +- Cleanup tasks + +### refactor + +Code improvement without behavior change. Use for: + +- Code restructuring +- Pattern adoption +- Technical debt reduction +- Performance optimization (same behavior, better performance) + +## Track ID Format + +Track IDs follow the pattern: `{shortname}_{YYYYMMDD}` + +- **shortname**: 2-4 word kebab-case description (e.g., `user-auth`, `api-rate-limit`) +- **YYYYMMDD**: Creation date in ISO format + +Examples: + +- `user-auth_20250115` +- `fix-login-error_20250115` +- `upgrade-deps_20250115` +- `refactor-api-client_20250115` + +## Track Lifecycle + +### 1. Creation (newTrack) + +**Define Requirements** + +1. Gather requirements through interactive Q&A +2. Identify acceptance criteria +3. Determine scope boundaries +4. Identify dependencies + +**Generate Specification** + +1. Create `spec.md` with structured requirements +2. Document functional and non-functional requirements +3. Define acceptance criteria +4. List dependencies and constraints + +**Generate Plan** + +1. Create `plan.md` with phased task breakdown +2. Organize tasks into logical phases +3. Add verification tasks after phases +4. Estimate effort and complexity + +**Register Track** + +1. Add entry to `tracks.md` registry +2. Create track directory structure +3. Generate `metadata.json` +4. Create track `index.md` + +### 2. Implementation + +**Execute Tasks** + +1. Select next pending task from plan +2. Mark task as in-progress +3. Implement following workflow (TDD) +4. Mark task complete with commit SHA + +**Update Status** + +1. Update task markers in plan.md +2. Record commit SHAs for traceability +3. Update phase progress +4. Update track status in tracks.md + +**Verify Progress** + +1. Complete verification tasks +2. Wait for checkpoint approval +3. Record checkpoint commits + +### 3. Completion + +**Sync Documentation** + +1. Update product.md if features added +2. Update tech-stack.md if dependencies changed +3. Verify all acceptance criteria met + +**Archive or Delete** + +1. Mark track as completed in tracks.md +2. Record completion date +3. Archive or retain track directory + +## Specification (spec.md) Structure + +```markdown +# {Track Title} + +## Overview + +Brief description of what this track accomplishes and why. + +## Functional Requirements + +### FR-1: {Requirement Name} + +Description of the functional requirement. + +- Acceptance: How to verify this requirement is met + +### FR-2: {Requirement Name} + +... + +## Non-Functional Requirements + +### NFR-1: {Requirement Name} + +Description of the non-functional requirement (performance, security, etc.) + +- Target: Specific measurable target +- Verification: How to test + +## Acceptance Criteria + +- [ ] Criterion 1: Specific, testable condition +- [ ] Criterion 2: Specific, testable condition +- [ ] Criterion 3: Specific, testable condition + +## Scope + +### In Scope + +- Explicitly included items +- Features to implement +- Components to modify + +### Out of Scope + +- Explicitly excluded items +- Future considerations +- Related but separate work + +## Dependencies + +### Internal + +- Other tracks or components this depends on +- Required context artifacts + +### External + +- Third-party services or APIs +- External dependencies + +## Risks and Mitigations + +| Risk | Impact | Mitigation | +| ---------------- | --------------- | ------------------- | +| Risk description | High/Medium/Low | Mitigation strategy | + +## Open Questions + +- [ ] Question that needs resolution +- [x] Resolved question - Answer +``` + +## Plan (plan.md) Structure + +```markdown +# Implementation Plan: {Track Title} + +Track ID: `{track-id}` +Created: YYYY-MM-DD +Status: pending | in-progress | completed + +## Overview + +Brief description of implementation approach. + +## Phase 1: {Phase Name} + +### Tasks + +- [ ] **Task 1.1**: Task description + - Sub-task or detail + - Sub-task or detail +- [ ] **Task 1.2**: Task description +- [ ] **Task 1.3**: Task description + +### Verification + +- [ ] **Verify 1.1**: Verification step for phase + +## Phase 2: {Phase Name} + +### Tasks + +- [ ] **Task 2.1**: Task description +- [ ] **Task 2.2**: Task description + +### Verification + +- [ ] **Verify 2.1**: Verification step for phase + +## Phase 3: Finalization + +### Tasks + +- [ ] **Task 3.1**: Update documentation +- [ ] **Task 3.2**: Final integration test + +### Verification + +- [ ] **Verify 3.1**: All acceptance criteria met + +## Checkpoints + +| Phase | Checkpoint SHA | Date | Status | +| ------- | -------------- | ---- | ------- | +| Phase 1 | | | pending | +| Phase 2 | | | pending | +| Phase 3 | | | pending | +``` + +## Status Marker Conventions + +Use consistent markers in plan.md: + +| Marker | Meaning | Usage | +| ------ | ----------- | --------------------------- | +| `[ ]` | Pending | Task not started | +| `[~]` | In Progress | Currently being worked | +| `[x]` | Complete | Task finished (include SHA) | +| `[-]` | Skipped | Intentionally not done | +| `[!]` | Blocked | Waiting on dependency | + +Example: + +```markdown +- [x] **Task 1.1**: Set up database schema `abc1234` +- [~] **Task 1.2**: Implement user model +- [ ] **Task 1.3**: Add validation logic +- [!] **Task 1.4**: Integrate auth service (blocked: waiting for API key) +- [-] **Task 1.5**: Legacy migration (skipped: not needed) +``` + +## Track Registry (tracks.md) Format + +```markdown +# Track Registry + +## Active Tracks + +| Track ID | Type | Status | Phase | Started | Assignee | +| ------------------------------------------------ | ------- | ----------- | ----- | ---------- | ---------- | +| [user-auth_20250115](tracks/user-auth_20250115/) | feature | in-progress | 2/3 | 2025-01-15 | @developer | +| [fix-login_20250114](tracks/fix-login_20250114/) | bug | pending | 0/2 | 2025-01-14 | - | + +## Completed Tracks + +| Track ID | Type | Completed | Duration | +| ---------------------------------------------- | ----- | ---------- | -------- | +| [setup-ci_20250110](tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2 days | + +## Archived Tracks + +| Track ID | Reason | Archived | +| ---------------------------------------------------- | ---------- | ---------- | +| [old-feature_20241201](tracks/old-feature_20241201/) | Superseded | 2025-01-05 | +``` + +## Metadata (metadata.json) Fields + +```json +{ + "id": "user-auth_20250115", + "title": "User Authentication System", + "type": "feature", + "status": "in-progress", + "priority": "high", + "created": "2025-01-15T10:30:00Z", + "updated": "2025-01-15T14:45:00Z", + "started": "2025-01-15T11:00:00Z", + "completed": null, + "assignee": "@developer", + "phases": { + "total": 3, + "current": 2, + "completed": 1 + }, + "tasks": { + "total": 12, + "completed": 5, + "in_progress": 1, + "pending": 6 + }, + "checkpoints": [ + { + "phase": 1, + "sha": "abc1234", + "date": "2025-01-15T13:00:00Z" + } + ], + "dependencies": [], + "tags": ["auth", "security"] +} +``` + +## Track Operations + +### Creating a Track + +1. Run `/conductor:new-track` +2. Answer interactive questions +3. Review generated spec.md +4. Review generated plan.md +5. Confirm track creation + +### Starting Implementation + +1. Read spec.md and plan.md +2. Verify context artifacts are current +3. Mark first task as `[~]` +4. Begin TDD workflow + +### Completing a Phase + +1. Ensure all phase tasks are `[x]` +2. Complete verification tasks +3. Wait for checkpoint approval +4. Record checkpoint SHA +5. Proceed to next phase + +### Completing a Track + +1. Verify all phases complete +2. Verify all acceptance criteria met +3. Update product.md if needed +4. Mark track completed in tracks.md +5. Update metadata.json + +### Reverting a Track + +1. Run `/conductor:revert` +2. Select track to revert +3. Choose granularity (track/phase/task) +4. Confirm revert operation +5. Update status markers + +## Handling Track Dependencies + +### Identifying Dependencies + +During track creation, identify: + +- **Hard dependencies**: Must complete before this track can start +- **Soft dependencies**: Can proceed in parallel but may affect integration +- **External dependencies**: Third-party services, APIs, or team decisions + +### Documenting Dependencies + +In spec.md, list dependencies with: + +- Dependency type (hard/soft/external) +- Current status (available/pending/blocked) +- Resolution path (what needs to happen) + +### Managing Blocked Tracks + +When a track is blocked: + +1. Mark blocked tasks with `[!]` and reason +2. Update tracks.md status +3. Document blocker in metadata.json +4. Consider creating dependency track if needed + +## Track Sizing Guidelines + +### Right-Sized Tracks + +Aim for tracks that: + +- Complete in 1-5 days of work +- Have 2-4 phases +- Contain 8-20 tasks total +- Deliver a coherent, testable unit + +### Too Large + +Signs a track is too large: + +- More than 5 phases +- More than 25 tasks +- Multiple unrelated features +- Estimated duration > 1 week + +Solution: Split into multiple tracks with clear boundaries. + +### Too Small + +Signs a track is too small: + +- Single phase with 1-2 tasks +- No meaningful verification needed +- Could be a sub-task of another track +- Less than a few hours of work + +Solution: Combine with related work or handle as part of existing track. + +## Specification Quality Checklist + +Before finalizing spec.md, verify: + +### Requirements Quality + +- [ ] Each requirement has clear acceptance criteria +- [ ] Requirements are testable +- [ ] Requirements are independent (can verify separately) +- [ ] No ambiguous language ("should be fast" → "response < 200ms") + +### Scope Clarity + +- [ ] In-scope items are specific +- [ ] Out-of-scope items prevent scope creep +- [ ] Boundaries are clear to implementer + +### Dependencies Identified + +- [ ] All internal dependencies listed +- [ ] External dependencies have owners/contacts +- [ ] Dependency status is current + +### Risks Addressed + +- [ ] Major risks identified +- [ ] Impact assessment realistic +- [ ] Mitigations are actionable + +## Plan Quality Checklist + +Before starting implementation, verify plan.md: + +### Task Quality + +- [ ] Tasks are atomic (one logical action) +- [ ] Tasks are independently verifiable +- [ ] Task descriptions are clear +- [ ] Sub-tasks provide helpful detail + +### Phase Organization + +- [ ] Phases group related tasks +- [ ] Each phase delivers something testable +- [ ] Verification tasks after each phase +- [ ] Phases build on each other logically + +### Completeness + +- [ ] All spec requirements have corresponding tasks +- [ ] Documentation tasks included +- [ ] Testing tasks included +- [ ] Integration tasks included + +## Common Track Patterns + +### Feature Track Pattern + +``` +Phase 1: Foundation +- Data models +- Database migrations +- Basic API structure + +Phase 2: Core Logic +- Business logic implementation +- Input validation +- Error handling + +Phase 3: Integration +- UI integration +- API documentation +- End-to-end tests +``` + +### Bug Fix Track Pattern + +``` +Phase 1: Reproduction +- Write failing test capturing bug +- Document reproduction steps + +Phase 2: Fix +- Implement fix +- Verify test passes +- Check for regressions + +Phase 3: Verification +- Manual verification +- Update documentation if needed +``` + +### Refactor Track Pattern + +``` +Phase 1: Preparation +- Add characterization tests +- Document current behavior + +Phase 2: Refactoring +- Apply changes incrementally +- Maintain green tests throughout + +Phase 3: Cleanup +- Remove dead code +- Update documentation +``` + +## Best Practices + +1. **One track, one concern**: Keep tracks focused on a single logical change +2. **Small phases**: Break work into phases of 3-5 tasks maximum +3. **Verification after phases**: Always include verification tasks +4. **Update markers immediately**: Mark task status as you work +5. **Record SHAs**: Always note commit SHAs for completed tasks +6. **Review specs before planning**: Ensure spec is complete before creating plan +7. **Link dependencies**: Explicitly note track dependencies +8. **Archive, don't delete**: Preserve completed tracks for reference +9. **Size appropriately**: Keep tracks between 1-5 days of work +10. **Clear acceptance criteria**: Every requirement must be testable diff --git a/conductor/skills/workflow-patterns/SKILL.md b/conductor/skills/workflow-patterns/SKILL.md new file mode 100644 index 0000000..3050998 --- /dev/null +++ b/conductor/skills/workflow-patterns/SKILL.md @@ -0,0 +1,623 @@ +--- +name: workflow-patterns +description: Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding the verification protocol. +version: 1.0.0 +--- + +# Workflow Patterns + +Guide for implementing tasks using Conductor's TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation. + +## When to Use This Skill + +- Implementing tasks from a track's plan.md +- Following TDD red-green-refactor cycle +- Completing phase checkpoints +- Managing git commits and notes +- Understanding quality assurance gates +- Handling verification protocols +- Recording progress in plan files + +## TDD Task Lifecycle + +Follow these 11 steps for each task: + +### Step 1: Select Next Task + +Read plan.md and identify the next pending `[ ]` task. Select tasks in order within the current phase. Do not skip ahead to later phases. + +### Step 2: Mark as In Progress + +Update plan.md to mark the task as `[~]`: + +```markdown +- [~] **Task 2.1**: Implement user validation +``` + +Commit this status change separately from implementation. + +### Step 3: RED - Write Failing Tests + +Write tests that define the expected behavior before writing implementation: + +- Create test file if needed +- Write test cases covering happy path +- Write test cases covering edge cases +- Write test cases covering error conditions +- Run tests - they should FAIL + +Example: + +```python +def test_validate_user_email_valid(): + user = User(email="test@example.com") + assert user.validate_email() is True + +def test_validate_user_email_invalid(): + user = User(email="invalid") + assert user.validate_email() is False +``` + +### Step 4: GREEN - Implement Minimum Code + +Write the minimum code necessary to make tests pass: + +- Focus on making tests green, not perfection +- Avoid premature optimization +- Keep implementation simple +- Run tests - they should PASS + +### Step 5: REFACTOR - Improve Clarity + +With green tests, improve the code: + +- Extract common patterns +- Improve naming +- Remove duplication +- Simplify logic +- Run tests after each change - they should remain GREEN + +### Step 6: Verify Coverage + +Check test coverage meets the 80% target: + +```bash +pytest --cov=module --cov-report=term-missing +``` + +If coverage is below 80%: + +- Identify uncovered lines +- Add tests for missing paths +- Re-run coverage check + +### Step 7: Document Deviations + +If implementation deviated from plan or introduced new dependencies: + +- Update tech-stack.md with new dependencies +- Note deviations in plan.md task comments +- Update spec.md if requirements changed + +### Step 8: Commit Implementation + +Create a focused commit for the task: + +```bash +git add -A +git commit -m "feat(user): implement email validation + +- Add validate_email method to User class +- Handle empty and malformed emails +- Add comprehensive test coverage + +Task: 2.1 +Track: user-auth_20250115" +``` + +Commit message format: + +- Type: feat, fix, refactor, test, docs, chore +- Scope: affected module or component +- Summary: imperative, present tense +- Body: bullet points of changes +- Footer: task and track references + +### Step 9: Attach Git Notes + +Add rich task summary as git note: + +```bash +git notes add -m "Task 2.1: Implement user validation + +Summary: +- Added email validation using regex pattern +- Handles edge cases: empty, no @, no domain +- Coverage: 94% on validation module + +Files changed: +- src/models/user.py (modified) +- tests/test_user.py (modified) + +Decisions: +- Used simple regex over email-validator library +- Reason: No external dependency for basic validation" +``` + +### Step 10: Update Plan with SHA + +Update plan.md to mark task complete with commit SHA: + +```markdown +- [x] **Task 2.1**: Implement user validation `abc1234` +``` + +### Step 11: Commit Plan Update + +Commit the plan status update: + +```bash +git add conductor/tracks/*/plan.md +git commit -m "docs: update plan - task 2.1 complete + +Track: user-auth_20250115" +``` + +## Phase Completion Protocol + +When all tasks in a phase are complete, execute the verification protocol: + +### Identify Changed Files + +List all files modified since the last checkpoint: + +```bash +git diff --name-only ..HEAD +``` + +### Ensure Test Coverage + +For each modified file: + +1. Identify corresponding test file +2. Verify tests exist for new/changed code +3. Run coverage for modified modules +4. Add tests if coverage < 80% + +### Run Full Test Suite + +Execute complete test suite: + +```bash +pytest -v --tb=short +``` + +All tests must pass before proceeding. + +### Generate Manual Verification Steps + +Create checklist of manual verifications: + +```markdown +## Phase 1 Verification Checklist + +- [ ] User can register with valid email +- [ ] Invalid email shows appropriate error +- [ ] Database stores user correctly +- [ ] API returns expected response codes +``` + +### WAIT for User Approval + +Present verification checklist to user: + +``` +Phase 1 complete. Please verify: +1. [ ] Test suite passes (automated) +2. [ ] Coverage meets target (automated) +3. [ ] Manual verification items (requires human) + +Respond with 'approved' to continue, or note issues. +``` + +Do NOT proceed without explicit approval. + +### Create Checkpoint Commit + +After approval, create checkpoint commit: + +```bash +git add -A +git commit -m "checkpoint: phase 1 complete - user-auth_20250115 + +Verified: +- All tests passing +- Coverage: 87% +- Manual verification approved + +Phase 1 tasks: +- [x] Task 1.1: Setup database schema +- [x] Task 1.2: Implement user model +- [x] Task 1.3: Add validation logic" +``` + +### Record Checkpoint SHA + +Update plan.md checkpoints table: + +```markdown +## Checkpoints + +| Phase | Checkpoint SHA | Date | Status | +| ------- | -------------- | ---------- | -------- | +| Phase 1 | def5678 | 2025-01-15 | verified | +| Phase 2 | | | pending | +``` + +## Quality Assurance Gates + +Before marking any task complete, verify these gates: + +### Passing Tests + +- All existing tests pass +- New tests pass +- No test regressions + +### Coverage >= 80% + +- New code has 80%+ coverage +- Overall project coverage maintained +- Critical paths fully covered + +### Style Compliance + +- Code follows style guides +- Linting passes +- Formatting correct + +### Documentation + +- Public APIs documented +- Complex logic explained +- README updated if needed + +### Type Safety + +- Type hints present (if applicable) +- Type checker passes +- No type: ignore without reason + +### No Linting Errors + +- Zero linter errors +- Warnings addressed or justified +- Static analysis clean + +### Mobile Compatibility + +If applicable: + +- Responsive design verified +- Touch interactions work +- Performance acceptable + +### Security Audit + +- No secrets in code +- Input validation present +- Authentication/authorization correct +- Dependencies vulnerability-free + +## Git Integration + +### Commit Message Format + +``` +(): + + + +