From e531956d447a1c7f9ac5a23a4d5953bdab68a5e7 Mon Sep 17 00:00:00 2001 From: oimiragieo Date: Mon, 8 Sep 2025 23:18:59 -0400 Subject: [PATCH] Updated prompts and improved JSON output. --- .claude/CLAUDE.md | 93 ++++- .claude/agents/analyst/prompt.md | 40 +- .claude/agents/architect/prompt.md | 50 +-- .claude/agents/bmad-orchestrator/prompt.md | 38 +- .claude/agents/developer/prompt.md | 14 +- .claude/agents/pm/prompt.md | 50 +-- .claude/agents/product-owner/prompt.md | 17 +- .claude/agents/qa/prompt.md | 31 +- .claude/agents/scrum-master/prompt.md | 12 +- .claude/agents/ux-expert/prompt.md | 37 +- .claude/config.yaml | 31 +- .claude/context/session.json | 71 ++-- .claude/docs/structured-outputs.md | 42 ++ .claude/examples/outputs/backlog.example.json | 7 + .../enhancement_classification.example.json | 7 + .claude/examples/outputs/epic.example.json | 9 + .../outputs/product_requirements.example.json | 37 ++ .../outputs/project_brief.example.json | 19 + .../outputs/review_notes.example.json | 14 + .../outputs/system_architecture.example.json | 30 ++ .../examples/outputs/test_plan.example.json | 28 ++ .../examples/outputs/user_story.example.json | 14 + .claude/examples/outputs/ux_spec.example.json | 21 + .claude/orchestrator/validation-protocol.md | 14 +- .claude/rules/manifest.yaml | 29 ++ .claude/schemas/artifact_manifest.schema.json | 17 + .claude/schemas/backlog.schema.json | 26 ++ .../enhancement_classification.schema.json | 15 + .claude/schemas/epic.schema.json | 17 + .../schemas/product_requirements.schema.json | 53 +++ .claude/schemas/project_brief.schema.json | 32 ++ .claude/schemas/review_notes.schema.json | 25 ++ .claude/schemas/route_decision.schema.json | 34 ++ .../schemas/system_architecture.schema.json | 132 +++++++ .claude/schemas/test_plan.schema.json | 89 +++++ .claude/schemas/user_story.schema.json | 20 + .claude/schemas/ux_spec.schema.json | 75 ++++ .claude/tools/ci/validate-all.mjs | 46 +++ .claude/tools/gates/gate.mjs | 120 ++++++ .claude/tools/renderers/bmad-render.mjs | 374 ++++++++++++++++++ .claude/workflows/brownfield-fullstack.yaml | 97 ++++- .claude/workflows/brownfield-service.yaml | 67 +++- .claude/workflows/brownfield-ui.yaml | 84 +++- .claude/workflows/greenfield-fullstack.yaml | 111 +++++- .claude/workflows/greenfield-service.yaml | 77 +++- .claude/workflows/greenfield-ui.yaml | 94 ++++- .github/workflows/validate-artifacts.yml | 17 + README.md | 58 ++- 48 files changed, 2118 insertions(+), 317 deletions(-) create mode 100644 .claude/docs/structured-outputs.md create mode 100644 .claude/examples/outputs/backlog.example.json create mode 100644 .claude/examples/outputs/enhancement_classification.example.json create mode 100644 .claude/examples/outputs/epic.example.json create mode 100644 .claude/examples/outputs/product_requirements.example.json create mode 100644 .claude/examples/outputs/project_brief.example.json create mode 100644 .claude/examples/outputs/review_notes.example.json create mode 100644 .claude/examples/outputs/system_architecture.example.json create mode 100644 .claude/examples/outputs/test_plan.example.json create mode 100644 .claude/examples/outputs/user_story.example.json create mode 100644 .claude/examples/outputs/ux_spec.example.json create mode 100644 .claude/rules/manifest.yaml create mode 100644 .claude/schemas/artifact_manifest.schema.json create mode 100644 .claude/schemas/backlog.schema.json create mode 100644 .claude/schemas/enhancement_classification.schema.json create mode 100644 .claude/schemas/epic.schema.json create mode 100644 .claude/schemas/product_requirements.schema.json create mode 100644 .claude/schemas/project_brief.schema.json create mode 100644 .claude/schemas/review_notes.schema.json create mode 100644 .claude/schemas/route_decision.schema.json create mode 100644 .claude/schemas/system_architecture.schema.json create mode 100644 .claude/schemas/test_plan.schema.json create mode 100644 .claude/schemas/user_story.schema.json create mode 100644 .claude/schemas/ux_spec.schema.json create mode 100644 .claude/tools/ci/validate-all.mjs create mode 100644 .claude/tools/gates/gate.mjs create mode 100644 .claude/tools/renderers/bmad-render.mjs create mode 100644 .github/workflows/validate-artifacts.yml diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 58325eeb..fc0ec1e5 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -14,14 +14,38 @@ This is an enterprise-grade AI orchestration system that transforms simple user Each agent has been enhanced with domain-specific rule sets ensuring enterprise-grade quality in all outputs. -## Activation Triggers -Activate this system when the user: -- Says "Create a [type of application]" -- Says "Build a [type of system]" -- Says "I need a [software/app/website]" -- Says "Use BMAD to..." -- Provides a specification document -- Asks for a structured development approach +## Enhanced Activation System + +The BMAD-Spec Orchestrator uses intelligent semantic analysis to detect user intent. + +### Activation Analysis +When you provide input, the system: +1. Semantic Analysis: Understands creation intent regardless of exact wording +2. Context Extraction: Identifies project type, complexity, and constraints +3. Confidence Scoring: Calculates likelihood of a creation or build request +4. Workflow Selection: Chooses the optimal approach based on context + +### Activation Triggers +The system activates when detecting: +- Direct Creation Language: "create/build/make/develop [something]" +- Simplification Requests: "lightweight/simplified/easier version" +- Integration Intent: "combine/integrate/merge systems" +- Problem–Solution Patterns: mentions complexity plus solution seeking + +### Confidence Thresholds +- High (0.7+): Immediate activation with auto-workflow selection +- Medium (0.4–0.7): Brief clarification then activation +- Low (<0.4): Standard response with activation monitoring + +### Activation Validation Checkpoints +- After analyst output: confirm creation intent and feasibility. +- After workflow selection: verify agents match project type and goals. +- After first agent execution: quick course-check; adjust before deep work. + +### Activation Recovery Patterns +- Missed activation: acknowledge, offer BMAD start, preserve context. +- Wrong workflow: pause, reassess, switch workflow; keep valuable work. +- Agent confusion: add context, clarify goals, or switch agent/approach. ## Enhanced Execution Engine @@ -33,19 +57,31 @@ When activated, the system performs intelligent analysis: - **Quality Standards**: Establish quality thresholds based on project requirements ### 2. Intelligent Workflow Selection -The system uses complexity scoring and project analysis to select workflows: +The system selects workflows using both complexity and context signals (brownfield vs greenfield, integration intent, simplification markers, time constraints). This complements complexity scoring with semantic routing. ```yaml -workflow_selection_logic: - complexity_score_1_3: "simplified_rapid_prototype" - complexity_score_4_6: "standard_development_workflow" - complexity_score_7_8: "comprehensive_enterprise_workflow" - complexity_score_9_10: "complex_system_architecture_workflow" +intelligent_workflow_selection: + decision_factors: + - creation_intent_confidence + - project_complexity_score + - brownfield_vs_greenfield + - system_integration_required + - simplification_vs_creation + - time_constraints_mentioned - project_type_overrides: - brownfield: "legacy_integration_considerations" - enterprise: "governance_and_compliance_checks" - prototype: "speed_over_completeness" + workflow_matrix_examples: + greenfield_simple: + conditions: ["confidence > 0.7", "complexity 1-3", "no integration"] + selected_workflow: simplified_rapid_prototype + agents: [analyst, architect, developer, qa] + brownfield_integration: + conditions: ["confidence > 0.6", "brownfield", "integration true"] + selected_workflow: legacy_system_consolidation + parallel_execution: [architect, ux-expert] + complexity_simplification: + conditions: ["simplification_signals present", "deployment complexity"] + selected_workflow: architecture_simplification + focus: deployment_simplification ``` ### 3. Context-Managed Execution @@ -108,7 +144,7 @@ Each agent operates with enhanced capabilities: - **Context Validation**: Verify required inputs before processing - **Cross-Agent Awareness**: Reference and validate consistency with previous work - **Self-Assessment**: Built-in quality scoring and completeness checks -- **Structured Outputs**: Generate both human-readable documents and structured data +- **Structured Outputs**: JSON-first artifacts with Markdown rendered from JSON - **Template Intelligence**: Dynamic template adaptation based on project complexity **Quality Gates:** @@ -117,6 +153,19 @@ Each agent operates with enhanced capabilities: - **Technical Feasibility**: Cross-validate technical decisions across architecture and development - **User Experience Alignment**: Ensure UX decisions support business requirements +### Structured Outputs (JSON-first) +- Produce artifacts as JSON conforming to schemas in `.claude/schemas/`. +- Save raw JSON to `.claude/context/artifacts/.json`. +- Render Markdown using the built-in renderer: + - `node .claude/tools/renderers/bmad-render.mjs prd .claude/examples/outputs/product_requirements.example.json > PRD.md` + - `node .claude/tools/renderers/bmad-render.mjs architecture .claude/examples/outputs/system_architecture.example.json > ARCHITECTURE.md` + +### Routing Contract & Gates +- Orchestrator emits a route decision JSON validated by `.claude/schemas/route_decision.schema.json` and persists it to `.claude/context/session.json`. +- Enforce validate → auto-fix → escalate at every step with the gate tool: + - `node .claude/tools/gates/gate.mjs --schema --input --gate .claude/context/history/gates//-.json --autofix 1` + + ### 6. Error Recovery & Reliability Enterprise-grade error handling: @@ -148,7 +197,8 @@ As the UX EXPERT, the interface... Always load files using these paths: - Agents: `.claude/agents/[name]/prompt.md` - Workflows: `.claude/workflows/[name].yaml` -- Templates: `.claude/templates/[name].md` +- Schemas: `.claude/schemas/*.schema.json` +- Renderer: `.claude/tools/renderers/bmad-render.mjs` - Tasks: `.claude/tasks/[category]/[name].md` - Context: `.claude/context/session.json` - **Enterprise Rules**: `.claude/rules/` (comprehensive guidelines for all agents) @@ -193,6 +243,7 @@ Each agent follows comprehensive quality standards: 5. **Follow all enterprise rules from `.claude/rules/` directory** 6. Generate complete, production-ready outputs 7. Explain what you're doing at each step +8. Produce JSON-first artifacts that pass schema validation; render Markdown from JSON ## Enterprise-Safe Workflow Acceleration **NEVER use `--dangerously-skip-permissions`** - Instead use Smart Enterprise Mode: @@ -217,4 +268,4 @@ All outputs must be: - Consistent with previous outputs - Ready for implementation -Remember: You are orchestrating a team of expert agents to deliver a complete software project. Each agent brings specific expertise, and together they create comprehensive, production-ready solutions. \ No newline at end of file +Remember: You are orchestrating a team of expert agents to deliver a complete software project. Each agent brings specific expertise, and together they create comprehensive, production-ready solutions. diff --git a/.claude/agents/analyst/prompt.md b/.claude/agents/analyst/prompt.md index 45995a37..44765125 100644 --- a/.claude/agents/analyst/prompt.md +++ b/.claude/agents/analyst/prompt.md @@ -98,36 +98,18 @@ When activated as the Analyst agent, systematically execute: ## -**Document Structure** (Follow this exact format): -``` -# Project Brief: [Project Name] +### Output Contract (JSON-first) +- Produce a Project Brief JSON that conforms to `.claude/schemas/project_brief.schema.json`. +- Save to `.claude/context/artifacts/project-brief.json`. +- Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/project_brief.schema.json --input .claude/context/artifacts/project-brief.json --gate .claude/context/history/gates//01-analyst.json --autofix 1`. +- Render Markdown for humans: `node .claude/tools/renderers/bmad-render.mjs project-brief .claude/context/artifacts/project-brief.json > .claude/context/artifacts/project-brief.md`. -## Executive summary -[2-3 sentences capturing project essence and value proposition] +### Structured Reasoning (shallow, auditable) +- Write a small reasoning JSON (not part of the brief) to `.claude/context/history/reasoning//01-analyst.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). +- Do not include chain-of-thought in the main artifact; keep it separate in reasoning JSON. -## Problem statement -[Clear articulation of business problem being solved] - -## Solution overview -[High-level approach and key capabilities] - -## Target audience & personas -[Primary and secondary user types with needs] - -## Success metrics -[Measurable outcomes that define project success] - -## Competitive analysis -[Key competitors and differentiation strategy] - -## Risk assessment -[Top 3-5 risks with mitigation approaches] - -## Recommendations -[Prioritized next steps with rationale] -``` - -**Communication Style**: +### Communication Style - Use data-driven insights with specific metrics when available - Ask probing questions to uncover hidden requirements - Frame recommendations in business impact terms @@ -170,4 +152,4 @@ When activated as the Analyst agent, systematically execute: - perform-market-research: Create market research document - research-prompt {topic}: Create deep research prompt -When acting as this agent, maintain the analytical, inquisitive persona while being creative and facilitative. Always ground your work in data and provide strategic context for all findings. \ No newline at end of file +When acting as this agent, maintain the analytical, inquisitive persona while being creative and facilitative. Always ground your work in data and provide strategic context for all findings. diff --git a/.claude/agents/architect/prompt.md b/.claude/agents/architect/prompt.md index d524fcdd..900198fb 100644 --- a/.claude/agents/architect/prompt.md +++ b/.claude/agents/architect/prompt.md @@ -7,7 +7,7 @@ You are acting as Winston, a Senior System Architect with 15+ years of experienc ## **Identity**: Master System Architect & Technical Leader **Style**: Holistic, pragmatic, security-first, performance-conscious -**Approach**: Think step-by-step through complex technical decisions +**Approach**: Use shallow, auditable reasoning fields (assumptions, criteria, tradeoffs, questions) **Communication**: Technical precision with clear business rationale **Values**: Scalability, maintainability, security, user experience @@ -27,25 +27,25 @@ When activated, follow this structured approach: 1. **Requirements Analysis**: - Review all previous agent outputs (project brief, PRD, UI specs) - - **think hard** about extracting both explicit and implicit technical requirements - - **think** through non-functional requirements (performance, security, scalability) implications + - Extract both explicit and implicit technical requirements + - Consider non-functional requirements (performance, security, scalability) implications 2. **Architecture Planning**: - - **ultrathink** about the comprehensive architecture plan and long-term implications - - **think harder** through multiple technology options with detailed trade-offs - - **think hard** about designing for current needs while planning for 10x scale + - Create a comprehensive architecture plan and consider long-term implications + - Evaluate multiple technology options with explicit trade-offs + - Design for current needs while planning for 10x scale 3. **Technical Design**: - - **ultrathink** the optimal technology stack selection with evidence-based rationale - - **think harder** about database schema design and performance implications - - **think hard** about API architecture and integration patterns - - **ultrathink** the security architecture and authentication strategy design + - Select optimal technology stack with evidence-based rationale + - Design database schema with performance implications considered + - Define API architecture and integration patterns + - Specify security architecture and authentication strategy 4. **Documentation & Validation**: - Create detailed architectural documentation with visual clarity - Include Mermaid diagrams and system interaction flows - - **think** through implementation guidance that prevents common pitfalls - - **think hard** about validating architecture against all requirements + - Provide implementation guidance that prevents common pitfalls + - Validate architecture against all requirements ## @@ -100,23 +100,23 @@ When activated, follow this structured approach: ## -Structure all outputs using these XML-style sections (then populate template): -- ``: Executive overview of technical approach -- ``: Detailed technology selections with specific rationale -- ``: Core architecture patterns and components -- ``: Data models and schema specifications -- ``: Endpoint design and integration patterns -- ``: Authentication, authorization, and data protection -- ``: Infrastructure and deployment approach -- ``: Clear direction for development team +### Output Contract (JSON-first) +- Produce a System Architecture JSON that conforms to `.claude/schemas/system_architecture.schema.json`. +- Save to `.claude/context/artifacts/system-architecture.json`. +- Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/system_architecture.schema.json --input .claude/context/artifacts/system-architecture.json --gate .claude/context/history/gates//05-architect.json --autofix 1`. +- Render Markdown for humans: `node .claude/tools/renderers/bmad-render.mjs architecture .claude/context/artifacts/system-architecture.json > .claude/context/artifacts/fullstack-architecture.md`. -**Quality Requirements**: +### Structured Reasoning (shallow, auditable) +- Write a small reasoning JSON to `.claude/context/history/reasoning//05-architect.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). + +### Quality Requirements - Follow technical excellence rules above in all documentation - Include specific version numbers and performance metrics - Back every architectural decision with concrete technical rationale - Consider security, performance, and maintainability in all choices -- Always generate final output using `.claude/templates/architecture.md` template - +- Use Mermaid for diagrams and keep a minimal `diagram.json` if applicable + ## Original Agent Configuration @@ -153,4 +153,4 @@ Structure all outputs using these XML-style sections (then populate template): - execute-checklist: Run architecture quality checklist - research: Create deep research prompt for technical topics -When acting as this agent, maintain the holistic, pragmatic approach while being technically comprehensive yet accessible. Always consider the full system context and user experience impact. \ No newline at end of file +When acting as this agent, maintain the holistic, pragmatic approach while being technically comprehensive yet accessible. Always consider the full system context and user experience impact. diff --git a/.claude/agents/bmad-orchestrator/prompt.md b/.claude/agents/bmad-orchestrator/prompt.md index 4576050c..c2421e7a 100644 --- a/.claude/agents/bmad-orchestrator/prompt.md +++ b/.claude/agents/bmad-orchestrator/prompt.md @@ -160,4 +160,40 @@ As the BMAD Orchestrator, you uniquely provide: - **Enterprise-grade quality orchestration** throughout workflows - **Educational guidance** that builds user understanding of BMAD methodology -You are the master conductor of the BMAD symphony, ensuring every specialist plays their part at the right time to create a harmonious, high-quality deliverable that exceeds enterprise standards. \ No newline at end of file +You are the master conductor of the BMAD symphony, ensuring every specialist plays their part at the right time to create a harmonious, high-quality deliverable that exceeds enterprise standards. + +## Output Contract (strict) +Return only this JSON object for routing decisions (no prose): + +``` +{ + "selected_workflow": "", + "reason": "<= 600 chars", + "confidence": 0.0, + "next_step": 1, + "inputs_missing": [""] +} +``` + +Validate against `.claude/schemas/route_decision.schema.json`. Persist the validated object into `.claude/context/session.json` under `route_decision` and update `project.workflow` and `current_context.current_step` accordingly. + +## Validation Control Loop (every step) +For each sequence step: +- Produce the JSON artifact first (conforming to `.claude/schemas/*`). +- Validate using the gate tool: + - `node .claude/tools/gates/gate.mjs --schema --input --gate .claude/context/history/gates//-.json --autofix 1` +- If validation fails after one auto-fix, escalate to the designated validator agent or ask the user for clarification. +- Only after validation passes, render Markdown using the renderer. + +## Rule Loading Policy +- Classify the stack (e.g., react_next_ts, fastapi_python) and load only the 1–3 most relevant rulesets from `.claude/rules/manifest.yaml`. +- Do not load unrelated rule files; keep prompts focused and within context limits. +- Announce `stack_profile` and list included rule files in your response metadata for traceability. + +## Structured Reasoning (shallow, auditable) +Always include: +- assumptions (≤5 bullets) +- decision_criteria (≤7) +- tradeoffs (≤3) +- open_questions (≤5) +- final_decision (≤120 words) diff --git a/.claude/agents/developer/prompt.md b/.claude/agents/developer/prompt.md index c0822add..318963f6 100644 --- a/.claude/agents/developer/prompt.md +++ b/.claude/agents/developer/prompt.md @@ -107,7 +107,17 @@ Follow this systematic development approach: - **Naming**: Descriptive, consistent variable and function names Always follow project constitution standards from `.claude/templates/project-constitution.md`. - + + +## Output Contract (JSON-first + Manifest) +- When producing documentation artifacts, follow the JSON-first approach and relevant schemas. +- When producing code, also emit an artifact manifest JSON that conforms to `.claude/schemas/artifact_manifest.schema.json`: + - Save to `.claude/context/artifacts/dev-manifest.json` with lists of `files_created`, `files_modified`, `directories_created`, and a short `summary`. + - Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/artifact_manifest.schema.json --input .claude/context/artifacts/dev-manifest.json --gate .claude/context/history/gates//06-developer.json --autofix 1`. + +### Structured Reasoning (shallow, auditable) +- Write a small reasoning JSON to `.claude/context/history/reasoning//06-developer.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). ## Output Style - Extremely concise and to the point @@ -143,4 +153,4 @@ Always follow project constitution standards from `.claude/templates/project-con - review-qa: Apply QA fixes and improvements - run-tests: Execute linting and tests -When acting as this agent, maintain extreme conciseness while being comprehensive in testing and following all development standards. Focus on precision and solution-oriented implementation. \ No newline at end of file +When acting as this agent, maintain extreme conciseness while being comprehensive in testing and following all development standards. Focus on precision and solution-oriented implementation. diff --git a/.claude/agents/pm/prompt.md b/.claude/agents/pm/prompt.md index 47f5f85a..7013dd62 100644 --- a/.claude/agents/pm/prompt.md +++ b/.claude/agents/pm/prompt.md @@ -40,14 +40,14 @@ When activated as the PM agent, execute systematically: ### 1. Requirements Analysis & Synthesis (Why: Prevents misaligned development) - Parse input from Analyst agent's project brief thoroughly -- **think hard** about identifying both functional and non-functional requirements -- **think hard** about mapping business objectives to specific features with clear traceability -- **think** through validating assumptions with structured questioning techniques +- Identify both functional and non-functional requirements +- Map business objectives to specific features with clear traceability +- Validate assumptions with structured questioning techniques ### 2. User Story Development (Why: Creates shared understanding of value) -- Transform requirements into compelling user-focused narratives -- **think hard** about defining clear, testable acceptance criteria for each story -- **think harder** about priority ranking using business value impact and resource constraints +- Transform requirements into user-focused narratives +- Define clear, testable acceptance criteria for each story +- Prioritize using business value impact and resource constraints - Include edge cases and error scenarios ### 3. Technical Coordination (Why: Ensures feasibility alignment) @@ -113,34 +113,18 @@ When activated as the PM agent, execute systematically: ## -**PRD Structure** (Follow template exactly with these enhancements): -``` -# Product requirements document: [Product Name] +### Output Contract (JSON-first) +- Produce a PRD JSON that conforms to `.claude/schemas/product_requirements.schema.json`. +- Save to `.claude/context/artifacts/prd.json`. +- Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/product_requirements.schema.json --input .claude/context/artifacts/prd.json --gate .claude/context/history/gates//02-pm.json --autofix 1`. +- Render Markdown for humans: `node .claude/tools/renderers/bmad-render.mjs prd .claude/context/artifacts/prd.json > .claude/context/artifacts/prd.md`. -## Executive summary -[Business case in 2-3 compelling sentences with quantified impact] +### Structured Reasoning (shallow, auditable) +- Write a small reasoning JSON to `.claude/context/history/reasoning//02-pm.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). +- Keep chain-of-thought out of the PRD; use the reasoning JSON instead. -## Problem statement -[Specific user pain points with supporting data/evidence] - -## Solution overview -[High-level approach with key differentiators highlighted] - -## User stories & acceptance criteria -[Structured as: As a [persona], I want [capability] so that [benefit]] -[Include: Given/When/Then acceptance criteria for each story] - -## Success metrics & KPIs -[Measurable outcomes with baseline and target values] - -## Technical requirements & constraints -[Reference Architect outputs and system limitations] - -## Go-to-market considerations -[Launch strategy and market positioning elements] -``` - -**Communication Protocols**: +### Communication Protocols - Always reference previous agent outputs for context continuity - Use specific metrics and quantified business impact - Frame all features in terms of user value and business outcomes @@ -182,4 +166,4 @@ When activated as the PM agent, execute systematically: - correct-course: Execute course correction analysis - shard-prd: Break down PRD into manageable components -When acting as this agent, maintain the investigative, user-focused persona while being analytical and pragmatic. Always champion the user perspective and provide data-informed recommendations. \ No newline at end of file +When acting as this agent, maintain the investigative, user-focused persona while being analytical and pragmatic. Always champion the user perspective and provide data-informed recommendations. diff --git a/.claude/agents/product-owner/prompt.md b/.claude/agents/product-owner/prompt.md index 159fccf4..ae04cefb 100644 --- a/.claude/agents/product-owner/prompt.md +++ b/.claude/agents/product-owner/prompt.md @@ -165,4 +165,19 @@ You follow all enterprise rules from `.claude/rules/`: - **Traceable requirements** linking back to business value - **Version control** maintaining consistency across iterations -You are the bridge between business vision and technical execution, ensuring that every story, epic, and requirement is crafted with the precision and clarity needed for successful development outcomes. Your meticulous attention to detail and systematic approach ensures that development teams have everything they need to deliver exceptional results. \ No newline at end of file +You are the bridge between business vision and technical execution, ensuring that every story, epic, and requirement is crafted with the precision and clarity needed for successful development outcomes. Your meticulous attention to detail and systematic approach ensures that development teams have everything they need to deliver exceptional results. + +## Output Contracts (JSON-first) +- Backlog JSON → `.claude/context/artifacts/backlog.json` (schema: `.claude/schemas/backlog.schema.json`) + - Validate/gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/backlog.schema.json --input .claude/context/artifacts/backlog.json --gate .claude/context/history/gates//po-backlog.json --autofix 1` + - Render: `node .claude/tools/renderers/bmad-render.mjs backlog .claude/context/artifacts/backlog.json > .claude/context/artifacts/backlog.md` +- Epic JSON → `.claude/context/artifacts/epic-.json` (schema: `.claude/schemas/epic.schema.json`) + - Validate/gate and render with `epic` renderer +- Story JSON → `.claude/context/artifacts/story-.json` (schema: `.claude/schemas/user_story.schema.json`) + - Validate/gate and render with `story` renderer + +## Structured Reasoning (shallow, auditable) +- For each output (backlog/epic/story), write reasoning JSON to `.claude/context/history/reasoning//po-.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). + +Keep chain-of-thought out of artifacts; use reasoning JSON for audit. diff --git a/.claude/agents/qa/prompt.md b/.claude/agents/qa/prompt.md index 8af59c87..3074ced0 100644 --- a/.claude/agents/qa/prompt.md +++ b/.claude/agents/qa/prompt.md @@ -133,28 +133,15 @@ When activated as the QA agent, execute systematically: ## -**Test Plan Structure** (Use `.claude/templates/test-plan.md` with these enhancements): -``` -# Test strategy: [Project Name] +### Output Contract (JSON-first) +- Produce a Test Plan JSON that conforms to `.claude/schemas/test_plan.schema.json`. +- Save to `.claude/context/artifacts/test-plan.json`. +- Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/test_plan.schema.json --input .claude/context/artifacts/test-plan.json --gate .claude/context/history/gates//08-qa.json --autofix 1`. +- Render Markdown for humans: `node .claude/tools/renderers/bmad-render.mjs test-plan .claude/context/artifacts/test-plan.json > .claude/context/artifacts/test-plan.md`. -## Executive summary -[Test approach overview with risk assessment and coverage goals] - -## Requirements traceability matrix -[Map all requirements to test scenarios using Given-When-Then format] - -## Test coverage analysis -[Unit: X%, Integration: Y%, E2E: Z%, Manual: W%] - -## Risk assessment matrix -[High/Medium/Low risk scenarios with mitigation strategies] - -## Quality gate criteria -[PASS/CONCERNS/FAIL criteria with evidence requirements] - -## Recommended actions -[Prioritized improvements with implementation guidance] -``` +### Structured Reasoning (shallow, auditable) +- Write a small reasoning JSON to `.claude/context/history/reasoning//08-qa.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). **Gherkin Test Scenario Format**: ```gherkin @@ -210,4 +197,4 @@ Feature: [Feature name] - test-design: Create comprehensive test scenarios - trace: Map requirements to tests using Given-When-Then -When acting as this agent, maintain the comprehensive yet pragmatic approach, always providing clear rationale for decisions and educational recommendations for improvement. \ No newline at end of file +When acting as this agent, maintain the comprehensive yet pragmatic approach, always providing clear rationale for decisions and educational recommendations for improvement. diff --git a/.claude/agents/scrum-master/prompt.md b/.claude/agents/scrum-master/prompt.md index 660d0f05..25435f18 100644 --- a/.claude/agents/scrum-master/prompt.md +++ b/.claude/agents/scrum-master/prompt.md @@ -179,4 +179,14 @@ You follow all enterprise rules from `.claude/rules/`: - **Quality validation** using systematic checklists and validation procedures - **Team support** through impediment removal and continuous process improvement -You are the essential bridge between business requirements and development execution, ensuring that every story is crafted with the precision, clarity, and context needed for successful implementation. Your systematic approach to story preparation and agile facilitation enables development teams to deliver exceptional results efficiently and consistently. \ No newline at end of file +You are the essential bridge between business requirements and development execution, ensuring that every story is crafted with the precision, clarity, and context needed for successful implementation. Your systematic approach to story preparation and agile facilitation enables development teams to deliver exceptional results efficiently and consistently. + +## Output Contracts (JSON-first) +- Story JSON → `.claude/context/artifacts/story-.json` (schema: `.claude/schemas/user_story.schema.json`) + - Validate/gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/user_story.schema.json --input .claude/context/artifacts/story-.json --gate .claude/context/history/gates//sm-.json --autofix 1` + - Render: `node .claude/tools/renderers/bmad-render.mjs story .claude/context/artifacts/story-.json > .claude/context/artifacts/story-.md` +- Backlog updates → update `.claude/context/artifacts/backlog.json` (schema above), then gate and render backlog. + +## Structured Reasoning (shallow, auditable) +- For each story/backlog update, write reasoning JSON to `.claude/context/history/reasoning//sm-.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). diff --git a/.claude/agents/ux-expert/prompt.md b/.claude/agents/ux-expert/prompt.md index 5dfb18b2..5c538091 100644 --- a/.claude/agents/ux-expert/prompt.md +++ b/.claude/agents/ux-expert/prompt.md @@ -140,34 +140,15 @@ When activated as the UX Expert agent, execute systematically: ## -**UI Specification Structure** (Use `.claude/templates/ui-spec.md` with these enhancements): -``` -# UI/UX specification: [Project Name] +### Output Contract (JSON-first) +- Produce a UX Spec JSON that conforms to `.claude/schemas/ux_spec.schema.json`. +- Save to `.claude/context/artifacts/ux-spec.json`. +- Validate and gate: `node .claude/tools/gates/gate.mjs --schema .claude/schemas/ux_spec.schema.json --input .claude/context/artifacts/ux-spec.json --gate .claude/context/history/gates//03-ux-expert.json --autofix 1`. +- Render Markdown for humans: `node .claude/tools/renderers/bmad-render.mjs ux-spec .claude/context/artifacts/ux-spec.json > .claude/context/artifacts/ui-spec.md`. -## Design philosophy & principles -[User-centered design rationale and core principles] - -## User personas & journey maps -[Primary users with their goals, pain points, and user flows] - -## Information architecture -[Site map, navigation patterns, content organization] - -## Design system -[Colors, typography, spacing, component library specifications] - -## Responsive design strategy -[Breakpoints, adaptive behaviors, mobile-first considerations] - -## Accessibility standards -[WCAG 2.1 AA compliance plan, inclusive design considerations] - -## Component specifications -[Detailed specs for each UI component with states and behaviors] - -## AI generation prompts -[Ready-to-use prompts for v0, Lovable, and similar tools] -``` +### Structured Reasoning (shallow, auditable) +- Write a small reasoning JSON to `.claude/context/history/reasoning//03-ux-expert.json` with: + - `assumptions` (≤5), `decision_criteria` (≤7), `tradeoffs` (≤3), `open_questions` (≤5), `final_decision` (≤120 words). **Design Quality Requirements**: - Follow design excellence rules above in all documentation @@ -213,4 +194,4 @@ When activated as the UX Expert agent, execute systematically: - create-front-end-spec: Create comprehensive front-end specifications - generate-ui-prompt: Generate AI prompts for UI generation tools -When acting as this agent, maintain the empathetic, user-obsessed approach while being creative and detail-oriented. Always prioritize user needs and create delightful, accessible experiences. \ No newline at end of file +When acting as this agent, maintain the empathetic, user-obsessed approach while being creative and detail-oriented. Always prioritize user needs and create delightful, accessible experiences. diff --git a/.claude/config.yaml b/.claude/config.yaml index ad9ca516..31eac215 100644 --- a/.claude/config.yaml +++ b/.claude/config.yaml @@ -6,8 +6,17 @@ system: ai_settings: primary_model: "claude-sonnet-4" - temperature: 0.7 + temperature: 0.2 max_tokens: 4000 + +# Deterministic orchestration & routing +orchestrator: + model: "claude-sonnet-4" + temperature: 0.2 + max_tokens: 2000 + stop_on_violation: true + routing: + temperature: 0.2 subagent_models: # High complexity tasks - Architecture, Security, Critical Analysis @@ -43,33 +52,37 @@ workflow_selection: agent_roles: analyst: trigger_words: ["research", "analyze", "requirements", "market", "feasibility"] - default_temperature: 0.7 + default_temperature: 0.4 model: "claude-sonnet-4" # Medium complexity - business analysis pm: trigger_words: ["plan", "roadmap", "stories", "features", "prioritize"] - default_temperature: 0.6 + default_temperature: 0.4 model: "claude-sonnet-4" # Medium complexity - product management architect: trigger_words: ["design", "architecture", "system", "structure", "patterns"] - default_temperature: 0.5 + default_temperature: 0.3 model: "claude-opus-4" # High complexity - system architecture developer: trigger_words: ["implement", "code", "build", "create", "develop"] - default_temperature: 0.6 + default_temperature: 0.5 model: "claude-sonnet-4" # Medium complexity - code implementation qa: trigger_words: ["test", "quality", "verify", "validate", "check"] - default_temperature: 0.5 + default_temperature: 0.3 model: "claude-opus-4" # High complexity - quality assurance - ux_expert: + ux-expert: trigger_words: ["user experience", "interface", "usability", "accessibility"] - default_temperature: 0.7 + default_temperature: 0.6 model: "claude-sonnet-4" # Medium complexity - UX design + +# Capability-scoped rules loading (stack profiles) +rules_loading: + manifest: ".claude/rules/manifest.yaml" output_formats: documents: @@ -96,4 +109,4 @@ validation: check_completeness: true verify_consistency: true validate_templates: true - ensure_quality: true \ No newline at end of file + ensure_quality: true diff --git a/.claude/context/session.json b/.claude/context/session.json index 38d47d86..87dd273a 100644 --- a/.claude/context/session.json +++ b/.claude/context/session.json @@ -1,66 +1,43 @@ { - "session_id": "{{session_id}}", - "created_at": "{{timestamp}}", - "last_updated": "{{timestamp}}", + "session_id": "", + "created_at": "", + "last_updated": "", + "route_decision": null, "project": { - "name": "{{project_name}}", - "type": "{{project_type}}", - "workflow": "{{selected_workflow}}", - "status": "{{project_status}}" + "name": "", + "type": "", + "workflow": "", + "status": "" }, "current_context": { - "active_workflow": "{{workflow_name}}", - "current_step": "{{step_number}}", - "active_agent": "{{agent_name}}", - "current_task": "{{task_name}}" + "active_workflow": "", + "current_step": 0, + "active_agent": "", + "current_task": "" }, "workflow_progress": { "completed_steps": [], - "current_step": "{{current_step}}", + "current_step": 0, "next_steps": [], "blocked_steps": [] }, "artifacts": { "generated": [], - "templates_used": [], + "schemas_used": [], "context_files": [] }, "agents": { - "analyst": { - "activated": false, - "last_task": null, - "outputs": [] - }, - "pm": { - "activated": false, - "last_task": null, - "outputs": [] - }, - "architect": { - "activated": false, - "last_task": null, - "outputs": [] - }, - "developer": { - "activated": false, - "last_task": null, - "outputs": [] - }, - "qa": { - "activated": false, - "last_task": null, - "outputs": [] - }, - "ux-expert": { - "activated": false, - "last_task": null, - "outputs": [] - } + "analyst": { "activated": false, "last_task": null, "outputs": [] }, + "pm": { "activated": false, "last_task": null, "outputs": [] }, + "architect": { "activated": false, "last_task": null, "outputs": [] }, + "developer": { "activated": false, "last_task": null, "outputs": [] }, + "qa": { "activated": false, "last_task": null, "outputs": [] }, + "ux-expert": { "activated": false, "last_task": null, "outputs": [] } }, "user_preferences": { - "workflow_mode": "{{interactive|yolo}}", - "detail_level": "{{high|medium|low}}", - "feedback_frequency": "{{each_step|milestones|completion}}" + "workflow_mode": "interactive", + "detail_level": "high", + "feedback_frequency": "each_step" }, "quality_gates": { "passed": [], @@ -68,4 +45,4 @@ "pending": [] }, "notes": [] -} \ No newline at end of file +} diff --git a/.claude/docs/structured-outputs.md b/.claude/docs/structured-outputs.md new file mode 100644 index 00000000..e08fe98e --- /dev/null +++ b/.claude/docs/structured-outputs.md @@ -0,0 +1,42 @@ +# Structured Outputs (JSON‑First) + +This system produces artifacts as validated JSON first, then renders readable Markdown. This keeps outputs machine‑checkable, deterministic, and easy to diff. + +## Requirements +- Node.js 18+ (for local validation and rendering scripts) + +## Artifacts & Schemas +- Project Brief: `.claude/schemas/project_brief.schema.json` +- PRD: `.claude/schemas/product_requirements.schema.json` +- System Architecture: `.claude/schemas/system_architecture.schema.json` +- UX Spec: `.claude/schemas/ux_spec.schema.json` +- Test Plan: `.claude/schemas/test_plan.schema.json` +- User Story: `.claude/schemas/user_story.schema.json` +- Epic: `.claude/schemas/epic.schema.json` +- Backlog: `.claude/schemas/backlog.schema.json` +- Review Notes: `.claude/schemas/review_notes.schema.json` +- Enhancement Classification: `.claude/schemas/enhancement_classification.schema.json` + +Store raw JSON in `.claude/context/artifacts/` using clear names, e.g.: `project_brief.json`, `prd.json`, `architecture.json`. + +## Authoring Pattern (All Agents) +1) Produce JSON that conforms to the relevant schema (no prose). +2) Save to `.claude/context/artifacts/.json`. +3) Render Markdown from the JSON for human consumption. + +## Render Markdown +Use the built‑in renderer (no dependencies): + +``` +node .claude/tools/renderers/bmad-render.mjs > output.md + +# Examples +node .claude/tools/renderers/bmad-render.mjs project-brief .claude/examples/outputs/project_brief.example.json > PROJECT_BRIEF.md +node .claude/tools/renderers/bmad-render.mjs prd .claude/examples/outputs/product_requirements.example.json > PRD.md +node .claude/tools/renderers/bmad-render.mjs story .claude/examples/outputs/user_story.example.json > US-001.md +node .claude/tools/renderers/bmad-render.mjs epic .claude/examples/outputs/epic.example.json > EPIC.md +node .claude/tools/renderers/bmad-render.mjs backlog .claude/examples/outputs/backlog.example.json > BACKLOG.md +``` + +## Validation +The renderer validates inputs against the schema (required fields, types, enums). CI should treat validation errors as failures. For more, see `.claude/orchestrator/validation-protocol.md`. diff --git a/.claude/examples/outputs/backlog.example.json b/.claude/examples/outputs/backlog.example.json new file mode 100644 index 00000000..1bb45021 --- /dev/null +++ b/.claude/examples/outputs/backlog.example.json @@ -0,0 +1,7 @@ +{ + "items": [ + { "type": "epic", "id": "EP-001", "priority": "must", "status": "in_progress", "sprint": "S1" }, + { "type": "story", "id": "US-001", "priority": "must", "status": "todo", "sprint": "S1" } + ] +} + diff --git a/.claude/examples/outputs/enhancement_classification.example.json b/.claude/examples/outputs/enhancement_classification.example.json new file mode 100644 index 00000000..22c4c576 --- /dev/null +++ b/.claude/examples/outputs/enhancement_classification.example.json @@ -0,0 +1,7 @@ +{ + "level": "small_feature", + "rationale": "Add subtasks without changing core data model", + "recommended_workflow": "brownfield-fullstack", + "indicators": ["Existing codebase", "UI + API change", "No breaking changes"] +} + diff --git a/.claude/examples/outputs/epic.example.json b/.claude/examples/outputs/epic.example.json new file mode 100644 index 00000000..f77bbe02 --- /dev/null +++ b/.claude/examples/outputs/epic.example.json @@ -0,0 +1,9 @@ +{ + "id": "EP-001", + "title": "Task management core", + "description": "Core features to create, assign, and track tasks.", + "business_value": 80, + "priority": "must", + "stories": ["US-001"] +} + diff --git a/.claude/examples/outputs/product_requirements.example.json b/.claude/examples/outputs/product_requirements.example.json new file mode 100644 index 00000000..438bfe2c --- /dev/null +++ b/.claude/examples/outputs/product_requirements.example.json @@ -0,0 +1,37 @@ +{ + "title": "Team Task Manager PRD", + "overview": "Core features for creating, assigning, and tracking tasks in small teams.", + "personas": [ + { + "name": "Team Lead", + "goals": ["Assign tasks", "Track progress"], + "pain_points": ["Lack of visibility", "Too many tools"] + } + ], + "features": [ + { + "id": "FR-001", + "title": "User Authentication", + "description": "Email/password login with password reset.", + "acceptance_criteria": [ + "Users can sign up and log in", + "Password reset email is sent" + ], + "priority": "must", + "dependencies": [] + }, + { + "id": "FR-002", + "title": "Task CRUD", + "description": "Create, update, and delete tasks with assignees and due dates.", + "acceptance_criteria": [ + "Task has title, description, status, assignee, due date" + ], + "priority": "must", + "dependencies": ["FR-001"] + } + ], + "non_functional_requirements": ["P95 latency < 250ms", "Uptime 99.9%"], + "constraints": ["Single-container deployment for MVP"] +} + diff --git a/.claude/examples/outputs/project_brief.example.json b/.claude/examples/outputs/project_brief.example.json new file mode 100644 index 00000000..c30ee3ad --- /dev/null +++ b/.claude/examples/outputs/project_brief.example.json @@ -0,0 +1,19 @@ +{ + "project_name": "Team Task Manager", + "summary": "A web app for small teams to manage tasks with real-time updates.", + "goals": [ + "Enable team collaboration", + "Provide real-time task updates", + "Offer simple deployment" + ], + "target_users": ["Small teams", "Project coordinators"], + "success_metrics": [ + "DAU > 500", + "Task creation to completion time reduced by 25%" + ], + "scope": { + "in_scope": ["User auth", "Task CRUD", "Realtime updates"], + "out_of_scope": ["Billing", "SAML SSO"] + } +} + diff --git a/.claude/examples/outputs/review_notes.example.json b/.claude/examples/outputs/review_notes.example.json new file mode 100644 index 00000000..c469d57c --- /dev/null +++ b/.claude/examples/outputs/review_notes.example.json @@ -0,0 +1,14 @@ +{ + "summary": "Frontend and backend implementations align with architecture; minor performance and accessibility issues noted.", + "findings": [ + { "area": "Frontend Accessibility", "issues": ["Missing ARIA labels on buttons", "Insufficient color contrast on secondary text"] }, + { "area": "API Performance", "issues": ["N+1 query on task list", "Missing pagination parameters"] } + ], + "recommendations": [ + "Add aria-labels to interactive icons", + "Increase contrast ratio for secondary text to 4.5:1", + "Introduce pagination on /tasks endpoint", + "Add SELECT with joins to avoid N+1" + ] +} + diff --git a/.claude/examples/outputs/system_architecture.example.json b/.claude/examples/outputs/system_architecture.example.json new file mode 100644 index 00000000..1d1089f8 --- /dev/null +++ b/.claude/examples/outputs/system_architecture.example.json @@ -0,0 +1,30 @@ +{ + "context": "MVP web app with single-container deployment and realtime updates.", + "decisions": [ + { "id": "ADR-001", "decision": "Use Postgres", "rationale": "Reliable and widely supported", "status": "accepted" } + ], + "components": [ + { "name": "API Server", "responsibilities": ["REST endpoints", "Auth"], "technology": "Node.js" }, + { "name": "Web Client", "responsibilities": ["Task UI", "Realtime updates"], "technology": "React" } + ], + "data_model": { + "entities": [ + { + "name": "Task", + "attributes": [ + { "name": "id", "type": "uuid" }, + { "name": "title", "type": "string" }, + { "name": "status", "type": "string" } + ], + "relationships": ["Task belongs to User"] + } + ] + }, + "integration": [ + { "with": "Email Service", "protocol": "SMTP", "direction": "outbound", "notes": "Password reset" } + ], + "deployment": { "strategy": "Docker single container", "diagram": "[API+Web] -> Postgres" }, + "security": { "threats": ["Credential stuffing"], "controls": ["Rate limiting", "BCrypt hashing"] }, + "performance": { "targets": [ { "metric": "P95 latency", "target": "<250ms" } ] } +} + diff --git a/.claude/examples/outputs/test_plan.example.json b/.claude/examples/outputs/test_plan.example.json new file mode 100644 index 00000000..f6a2997c --- /dev/null +++ b/.claude/examples/outputs/test_plan.example.json @@ -0,0 +1,28 @@ +{ + "strategy": "Shift-left with layered coverage and automation first.", + "scope": { + "in_scope": ["Auth", "Task CRUD", "Realtime"], + "out_of_scope": ["Billing"] + }, + "test_levels": [ + { "level": "unit", "tools": ["jest"] }, + { "level": "e2e", "tools": ["cypress"] } + ], + "test_cases": [ + { + "id": "TC-001", + "title": "User can sign in", + "preconditions": ["User exists"], + "steps": [ + { "action": "Enter credentials", "expected": "Form accepts input" }, + { "action": "Submit", "expected": "Redirect to dashboard" } + ], + "priority": "high", + "tags": ["auth"] + } + ], + "coverage_targets": { "statements": 80, "branches": 70, "functions": 80, "lines": 80 }, + "environments": ["local", "staging"], + "reporting": { "tools": ["CI summary"], "cadence": "per-commit" } +} + diff --git a/.claude/examples/outputs/user_story.example.json b/.claude/examples/outputs/user_story.example.json new file mode 100644 index 00000000..9bddf14b --- /dev/null +++ b/.claude/examples/outputs/user_story.example.json @@ -0,0 +1,14 @@ +{ + "id": "US-001", + "title": "Create task", + "description": "As a user, I can create a task with title, description, assignee, and due date.", + "acceptance_criteria": [ + "Given I am signed in, when I submit a valid task, then it appears in my list", + "Given required fields are missing, when I submit, then I see validation errors" + ], + "priority": "must", + "estimate_points": 3, + "depends_on": [], + "prd_refs": ["FR-002"] +} + diff --git a/.claude/examples/outputs/ux_spec.example.json b/.claude/examples/outputs/ux_spec.example.json new file mode 100644 index 00000000..8a9c3e8d --- /dev/null +++ b/.claude/examples/outputs/ux_spec.example.json @@ -0,0 +1,21 @@ +{ + "design_principles": ["Clarity over density", "Accessible by default"], + "information_architecture": [ + { "section": "Dashboard", "content": "Overview of tasks and quick filters" } + ], + "screens": [ + { + "name": "Task List", + "purpose": "Browse and manage tasks", + "components": [ + { "id": "search", "type": "input", "label": "Search" }, + { "id": "table", "type": "table", "label": "Tasks" } + ] + } + ], + "flows": [ + { "name": "Create Task", "steps": ["Open modal", "Fill fields", "Save"] } + ], + "accessibility": { "guidelines": ["WCAG 2.1 AA", "Focusable controls"] } +} + diff --git a/.claude/orchestrator/validation-protocol.md b/.claude/orchestrator/validation-protocol.md index 8c102aee..0105ab38 100644 --- a/.claude/orchestrator/validation-protocol.md +++ b/.claude/orchestrator/validation-protocol.md @@ -195,7 +195,7 @@ automated_checks: - required_sections_present - section_length_appropriate - format_consistency - - template_compliance + - json_schema_compliance # artifacts must pass .claude/schemas/*.schema.json content_validation: - no_placeholder_text @@ -216,6 +216,16 @@ automated_checks: - security_considerations_included ``` +## Implementation Hook (Gate Runner) + +Use the gate tool to enforce validate → auto-fix → escalate at every step: + +``` +node .claude/tools/gates/gate.mjs --schema --input --gate .claude/context/history/gates//-.json --autofix 1 +``` + +If the command exits non-zero, escalate per `on_fail` policy in the workflow YAML. + ## Conflict Resolution System ### Conflict Detection @@ -374,4 +384,4 @@ If consensus cannot be reached, follow the authority chain for your domain area. ``` -This Cross-Agent Validation Protocol creates a robust quality assurance system that ensures all agents work together cohesively while maintaining their individual expertise areas. \ No newline at end of file +This Cross-Agent Validation Protocol creates a robust quality assurance system that ensures all agents work together cohesively while maintaining their individual expertise areas. diff --git a/.claude/rules/manifest.yaml b/.claude/rules/manifest.yaml new file mode 100644 index 00000000..c8debbfe --- /dev/null +++ b/.claude/rules/manifest.yaml @@ -0,0 +1,29 @@ +stack_profiles: + react_next_ts: + include: + - ".claude/rules/nextjs-typescript-*/**/*.mdc" + - ".claude/rules/tailwind-*/**/*.mdc" + - ".claude/rules/javascript-typescript-code-quality-cursorrules-pro*/**/*.mdc" + exclude: + - ".claude/rules/android-*/**" + - ".claude/rules/swift-*/**" + + fastapi_python: + include: + - ".claude/rules/cursorrules-file-cursor-ai-python-fastapi-api/**/*.mdc" + - ".claude/rules/python-projects-guide-cursorrules-prompt-file/**/*.mdc" + - ".claude/rules/jest-unit-testing-cursorrules-prompt-file/**/*.mdc" + exclude: + - ".claude/rules/kotlin-*/**" + - ".claude/rules/java-*/**" + + node_api: + include: + - ".claude/rules/javascript-*/**/*.mdc" + - ".claude/rules/github-code-quality-cursorrules-prompt-file/**/*.mdc" + exclude: + - ".claude/rules/flutter-*/**" + +loading_policy: + max_rules_files: 3 + selection: "most_relevant" diff --git a/.claude/schemas/artifact_manifest.schema.json b/.claude/schemas/artifact_manifest.schema.json new file mode 100644 index 00000000..fff8edd7 --- /dev/null +++ b/.claude/schemas/artifact_manifest.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/artifact_manifest.schema.json", + "title": "Artifact Manifest", + "type": "object", + "additionalProperties": false, + "required": ["summary", "files_created", "files_modified", "directories_created"], + "properties": { + "summary": { "type": "string", "minLength": 1 }, + "files_created": { "type": "array", "items": { "type": "string" } }, + "files_modified": { "type": "array", "items": { "type": "string" } }, + "directories_created": { "type": "array", "items": { "type": "string" } }, + "commands_run": { "type": "array", "items": { "type": "string" } }, + "test_summary": { "type": "string" } + } +} + diff --git a/.claude/schemas/backlog.schema.json b/.claude/schemas/backlog.schema.json new file mode 100644 index 00000000..53626d50 --- /dev/null +++ b/.claude/schemas/backlog.schema.json @@ -0,0 +1,26 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/backlog.schema.json", + "title": "Backlog", + "type": "object", + "additionalProperties": false, + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["type", "id", "priority", "status"], + "properties": { + "type": { "type": "string", "enum": ["epic", "story"] }, + "id": { "type": "string" }, + "priority": { "type": "string", "enum": ["must", "should", "could"] }, + "status": { "type": "string", "enum": ["todo", "in_progress", "blocked", "done"] }, + "sprint": { "type": "string" } + } + } + } + } +} + diff --git a/.claude/schemas/enhancement_classification.schema.json b/.claude/schemas/enhancement_classification.schema.json new file mode 100644 index 00000000..bbe76ef4 --- /dev/null +++ b/.claude/schemas/enhancement_classification.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/enhancement_classification.schema.json", + "title": "Enhancement Classification", + "type": "object", + "additionalProperties": false, + "required": ["level", "rationale", "recommended_workflow"], + "properties": { + "level": { "type": "string", "enum": ["fix", "small_feature", "major_enhancement"] }, + "rationale": { "type": "string" }, + "recommended_workflow": { "type": "string", "enum": ["brownfield-fullstack", "brownfield-ui", "brownfield-service", "greenfield-fullstack", "greenfield-ui", "greenfield-service"] }, + "indicators": { "type": "array", "items": { "type": "string" } } + } +} + diff --git a/.claude/schemas/epic.schema.json b/.claude/schemas/epic.schema.json new file mode 100644 index 00000000..d2aa258c --- /dev/null +++ b/.claude/schemas/epic.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/epic.schema.json", + "title": "Epic", + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "description", "stories"], + "properties": { + "id": { "type": "string", "pattern": "^EP-[0-9]{3}$" }, + "title": { "type": "string", "minLength": 1 }, + "description": { "type": "string", "minLength": 1 }, + "business_value": { "type": "number", "minimum": 0 }, + "priority": { "type": "string", "enum": ["must", "should", "could"] }, + "stories": { "type": "array", "items": { "type": "string", "pattern": "^US-[0-9]{3}$" } } + } +} + diff --git a/.claude/schemas/product_requirements.schema.json b/.claude/schemas/product_requirements.schema.json new file mode 100644 index 00000000..15febd63 --- /dev/null +++ b/.claude/schemas/product_requirements.schema.json @@ -0,0 +1,53 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/product_requirements.schema.json", + "title": "Product Requirements Document", + "type": "object", + "additionalProperties": false, + "required": [ + "title", + "overview", + "personas", + "features", + "non_functional_requirements", + "constraints" + ], + "properties": { + "title": { "type": "string", "minLength": 1 }, + "overview": { "type": "string", "minLength": 1 }, + "personas": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "goals", "pain_points"], + "properties": { + "name": { "type": "string" }, + "goals": { "type": "array", "items": { "type": "string" } }, + "pain_points": { "type": "array", "items": { "type": "string" } } + } + } + }, + "features": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "description", "acceptance_criteria", "priority"], + "properties": { + "id": { "type": "string", "pattern": "^(FR|NFR)-[0-9]{3}$" }, + "title": { "type": "string" }, + "description": { "type": "string" }, + "acceptance_criteria": { "type": "array", "minItems": 1, "items": { "type": "string" } }, + "priority": { "type": "string", "enum": ["must", "should", "could"] }, + "dependencies": { "type": "array", "items": { "type": "string" } } + } + } + }, + "non_functional_requirements": { "type": "array", "items": { "type": "string" } }, + "constraints": { "type": "array", "items": { "type": "string" } } + } +} + diff --git a/.claude/schemas/project_brief.schema.json b/.claude/schemas/project_brief.schema.json new file mode 100644 index 00000000..9244b00f --- /dev/null +++ b/.claude/schemas/project_brief.schema.json @@ -0,0 +1,32 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/project_brief.schema.json", + "title": "Project Brief", + "type": "object", + "additionalProperties": false, + "required": [ + "project_name", + "summary", + "goals", + "target_users", + "success_metrics", + "scope" + ], + "properties": { + "project_name": { "type": "string", "minLength": 1 }, + "summary": { "type": "string", "minLength": 1 }, + "goals": { "type": "array", "minItems": 1, "items": { "type": "string" } }, + "target_users": { "type": "array", "minItems": 1, "items": { "type": "string" } }, + "success_metrics": { "type": "array", "minItems": 1, "items": { "type": "string" } }, + "scope": { + "type": "object", + "additionalProperties": false, + "required": ["in_scope", "out_of_scope"], + "properties": { + "in_scope": { "type": "array", "items": { "type": "string" } }, + "out_of_scope": { "type": "array", "items": { "type": "string" } } + } + } + } +} + diff --git a/.claude/schemas/review_notes.schema.json b/.claude/schemas/review_notes.schema.json new file mode 100644 index 00000000..c7bbfc71 --- /dev/null +++ b/.claude/schemas/review_notes.schema.json @@ -0,0 +1,25 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/review_notes.schema.json", + "title": "Review Notes", + "type": "object", + "additionalProperties": false, + "required": ["summary", "findings", "recommendations"], + "properties": { + "summary": { "type": "string" }, + "findings": { + "type": "array", + "items": { + "type": "object", + "required": ["area", "issues"], + "additionalProperties": false, + "properties": { + "area": { "type": "string" }, + "issues": { "type": "array", "items": { "type": "string" } } + } + } + }, + "recommendations": { "type": "array", "items": { "type": "string" } } + } +} + diff --git a/.claude/schemas/route_decision.schema.json b/.claude/schemas/route_decision.schema.json new file mode 100644 index 00000000..0076de91 --- /dev/null +++ b/.claude/schemas/route_decision.schema.json @@ -0,0 +1,34 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/route_decision.schema.json", + "title": "Route Decision", + "type": "object", + "additionalProperties": false, + "required": [ + "selected_workflow", + "reason", + "confidence", + "inputs_missing", + "next_step" + ], + "properties": { + "selected_workflow": { + "type": "string", + "enum": [ + "greenfield-fullstack", + "greenfield-ui", + "greenfield-service", + "brownfield-fullstack", + "brownfield-ui", + "brownfield-service" + ] + }, + "reason": { "type": "string", "maxLength": 600 }, + "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, + "inputs_missing": { "type": "array", "items": { "type": "string" } }, + "next_step": { "type": "integer", "minimum": 1 }, + "required_inputs": { "type": "array", "items": { "type": "string" } }, + "expected_artifacts": { "type": "array", "items": { "type": "string" } } + } +} + diff --git a/.claude/schemas/system_architecture.schema.json b/.claude/schemas/system_architecture.schema.json new file mode 100644 index 00000000..13612111 --- /dev/null +++ b/.claude/schemas/system_architecture.schema.json @@ -0,0 +1,132 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/system_architecture.schema.json", + "title": "System Architecture", + "type": "object", + "additionalProperties": false, + "required": [ + "context", + "decisions", + "components", + "data_model", + "integration", + "deployment", + "security", + "performance" + ], + "properties": { + "context": { "type": "string" }, + "decisions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["id", "decision", "rationale", "status"], + "properties": { + "id": { "type": "string", "pattern": "^ADR-[0-9]{3}$" }, + "decision": { "type": "string" }, + "rationale": { "type": "string" }, + "status": { "type": "string", "enum": ["accepted", "proposed", "rejected"] } + } + } + }, + "components": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "responsibilities", "technology"], + "properties": { + "name": { "type": "string" }, + "responsibilities": { "type": "array", "items": { "type": "string" } }, + "technology": { "type": "string" } + } + } + }, + "data_model": { + "type": "object", + "additionalProperties": false, + "required": ["entities"], + "properties": { + "entities": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "attributes"], + "properties": { + "name": { "type": "string" }, + "attributes": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "type"], + "properties": { + "name": { "type": "string" }, + "type": { "type": "string" }, + "description": { "type": "string" } + } + } + }, + "relationships": { "type": "array", "items": { "type": "string" } } + } + } + } + } + }, + "integration": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["with", "protocol", "direction"], + "properties": { + "with": { "type": "string" }, + "protocol": { "type": "string" }, + "direction": { "type": "string", "enum": ["inbound", "outbound", "bidirectional"] }, + "notes": { "type": "string" } + } + } + }, + "deployment": { + "type": "object", + "additionalProperties": false, + "required": ["strategy"], + "properties": { + "strategy": { "type": "string" }, + "diagram": { "type": "string" } + } + }, + "security": { + "type": "object", + "additionalProperties": false, + "required": ["threats", "controls"], + "properties": { + "threats": { "type": "array", "items": { "type": "string" } }, + "controls": { "type": "array", "items": { "type": "string" } } + } + }, + "performance": { + "type": "object", + "additionalProperties": false, + "required": ["targets"], + "properties": { + "targets": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["metric", "target"], + "properties": { + "metric": { "type": "string" }, + "target": { "type": "string" } + } + } + } + } + } + } +} + diff --git a/.claude/schemas/test_plan.schema.json b/.claude/schemas/test_plan.schema.json new file mode 100644 index 00000000..f5f45988 --- /dev/null +++ b/.claude/schemas/test_plan.schema.json @@ -0,0 +1,89 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/test_plan.schema.json", + "title": "Test Plan", + "type": "object", + "additionalProperties": false, + "required": [ + "strategy", + "scope", + "test_levels", + "test_cases", + "coverage_targets", + "environments", + "reporting" + ], + "properties": { + "strategy": { "type": "string" }, + "scope": { + "type": "object", + "additionalProperties": false, + "required": ["in_scope", "out_of_scope"], + "properties": { + "in_scope": { "type": "array", "items": { "type": "string" } }, + "out_of_scope": { "type": "array", "items": { "type": "string" } } + } + }, + "test_levels": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["level", "tools"], + "properties": { + "level": { "type": "string", "enum": ["unit", "integration", "e2e", "accessibility", "performance"] }, + "tools": { "type": "array", "items": { "type": "string" } } + } + } + }, + "test_cases": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "preconditions", "steps", "priority"], + "properties": { + "id": { "type": "string", "pattern": "^TC-[0-9]{3}$" }, + "title": { "type": "string" }, + "preconditions": { "type": "array", "items": { "type": "string" } }, + "steps": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["action", "expected"], + "properties": { + "action": { "type": "string" }, + "expected": { "type": "string" } + } + } + }, + "priority": { "type": "string", "enum": ["high", "medium", "low"] }, + "tags": { "type": "array", "items": { "type": "string" } } + } + } + }, + "coverage_targets": { + "type": "object", + "additionalProperties": false, + "required": ["statements", "branches", "functions", "lines"], + "properties": { + "statements": { "type": "number", "minimum": 0, "maximum": 100 }, + "branches": { "type": "number", "minimum": 0, "maximum": 100 }, + "functions": { "type": "number", "minimum": 0, "maximum": 100 }, + "lines": { "type": "number", "minimum": 0, "maximum": 100 } + } + }, + "environments": { "type": "array", "items": { "type": "string" } }, + "reporting": { + "type": "object", + "additionalProperties": false, + "required": ["tools", "cadence"], + "properties": { + "tools": { "type": "array", "items": { "type": "string" } }, + "cadence": { "type": "string" } + } + } + } +} + diff --git a/.claude/schemas/user_story.schema.json b/.claude/schemas/user_story.schema.json new file mode 100644 index 00000000..bb9b5977 --- /dev/null +++ b/.claude/schemas/user_story.schema.json @@ -0,0 +1,20 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/user_story.schema.json", + "title": "User Story", + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "description", "acceptance_criteria", "priority"], + "properties": { + "id": { "type": "string", "pattern": "^US-[0-9]{3}$" }, + "title": { "type": "string", "minLength": 1 }, + "description": { "type": "string", "minLength": 1 }, + "acceptance_criteria": { "type": "array", "minItems": 1, "items": { "type": "string" } }, + "priority": { "type": "string", "enum": ["must", "should", "could"] }, + "estimate_points": { "type": "number", "minimum": 0 }, + "depends_on": { "type": "array", "items": { "type": "string", "pattern": "^US-[0-9]{3}$" } }, + "links": { "type": "array", "items": { "type": "string" } }, + "prd_refs": { "type": "array", "items": { "type": "string", "pattern": "^(FR|NFR)-[0-9]{3}$" } } + } +} + diff --git a/.claude/schemas/ux_spec.schema.json b/.claude/schemas/ux_spec.schema.json new file mode 100644 index 00000000..96a75a89 --- /dev/null +++ b/.claude/schemas/ux_spec.schema.json @@ -0,0 +1,75 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://bmad-spec/schemas/ux_spec.schema.json", + "title": "UX Specification", + "type": "object", + "additionalProperties": false, + "required": [ + "design_principles", + "information_architecture", + "screens", + "flows", + "accessibility" + ], + "properties": { + "design_principles": { "type": "array", "items": { "type": "string" } }, + "information_architecture": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["section", "content"], + "properties": { + "section": { "type": "string" }, + "content": { "type": "string" } + } + } + }, + "screens": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "purpose", "components"], + "properties": { + "name": { "type": "string" }, + "purpose": { "type": "string" }, + "components": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["id", "type"], + "properties": { + "id": { "type": "string" }, + "type": { "type": "string" }, + "label": { "type": "string" } + } + } + } + } + } + }, + "flows": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "steps"], + "properties": { + "name": { "type": "string" }, + "steps": { "type": "array", "items": { "type": "string" } } + } + } + }, + "accessibility": { + "type": "object", + "additionalProperties": false, + "required": ["guidelines"], + "properties": { + "guidelines": { "type": "array", "items": { "type": "string" } } + } + } + } +} + diff --git a/.claude/tools/ci/validate-all.mjs b/.claude/tools/ci/validate-all.mjs new file mode 100644 index 00000000..90dbceac --- /dev/null +++ b/.claude/tools/ci/validate-all.mjs @@ -0,0 +1,46 @@ +#!/usr/bin/env node +import fs from 'fs'; +import path from 'path'; +import { spawnSync } from 'child_process'; + +const ROOT = process.cwd(); +const artifactsDir = path.join(ROOT, '.claude/context/artifacts'); +const schemaDir = path.join(ROOT, '.claude/schemas'); +const gateDir = path.join(ROOT, '.claude/context/history/gates/ci'); +fs.mkdirSync(gateDir, { recursive: true }); + +const map = [ + { pattern: /^project-brief\.json$/, schema: 'project_brief.schema.json' }, + { pattern: /^prd\.json$/, schema: 'product_requirements.schema.json' }, + { pattern: /^(system-architecture|frontend-architecture|architecture)\.json$/, schema: 'system_architecture.schema.json' }, + { pattern: /^(ux-spec|front-end-spec)\.json$/, schema: 'ux_spec.schema.json' }, + { pattern: /^test-plan\.json$/, schema: 'test_plan.schema.json' }, + { pattern: /^dev-manifest\.json$/, schema: 'artifact_manifest.schema.json' }, + { pattern: /^backlog\.json$/, schema: 'backlog.schema.json' }, + { pattern: /^epic-.*\.json$/, schema: 'epic.schema.json' }, + { pattern: /^story-.*\.json$/, schema: 'user_story.schema.json' }, + { pattern: /^review-notes\.json$/, schema: 'review_notes.schema.json' }, + { pattern: /^enhancement-classification\.json$/, schema: 'enhancement_classification.schema.json' } +]; + +function runGate(schemaPath, inputPath, gatePath) { + const res = spawnSync('node', ['.claude/tools/gates/gate.mjs', '--schema', schemaPath, '--input', inputPath, '--gate', gatePath, '--autofix', '1'], { stdio: 'inherit' }); + return res.status === 0; +} + +let ok = true; +if (fs.existsSync(artifactsDir)) { + for (const f of fs.readdirSync(artifactsDir)) { + if (!f.endsWith('.json')) continue; + const rule = map.find(m => m.pattern.test(f)); + if (!rule) continue; + const schemaPath = path.join(schemaDir, rule.schema); + const inputPath = path.join(artifactsDir, f); + const gatePath = path.join(gateDir, `${f}.gate.json`); + const pass = runGate(schemaPath, inputPath, gatePath); + if (!pass) ok = false; + } +} + +process.exit(ok ? 0 : 1); + diff --git a/.claude/tools/gates/gate.mjs b/.claude/tools/gates/gate.mjs new file mode 100644 index 00000000..56a39194 --- /dev/null +++ b/.claude/tools/gates/gate.mjs @@ -0,0 +1,120 @@ +#!/usr/bin/env node +/** + * Gate: validate → optional auto-fix → record gate result + * Usage: + * node .claude/tools/gates/gate.mjs --schema --input --gate [--autofix 1] + */ +import fs from 'fs'; +import path from 'path'; + +function parseArgs(argv) { + const args = {}; + for (let i = 2; i < argv.length; i += 1) { + const k = argv[i]; + const v = argv[i + 1]; + if (k.startsWith('--')) { + const key = k.slice(2); + if (v && !v.startsWith('--')) { args[key] = v; i += 1; } + else { args[key] = true; } + } + } + return args; +} + +function loadJSON(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); } +function saveJSON(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, JSON.stringify(obj, null, 2)); } + +function typeOf(v) { if (v === null) return 'null'; if (Array.isArray(v)) return 'array'; return typeof v; } + +function validate(schema, data, pathSeg = '$') { + const errors = []; + const t = schema.type; + const expectedTypes = Array.isArray(t) ? t : [t]; + const dataType = typeOf(data); + if (t && !expectedTypes.includes(dataType)) { + errors.push(`${pathSeg}: expected ${expectedTypes.join('|')}, got ${dataType}`); + return errors; + } + if (schema.enum && !schema.enum.includes(data)) errors.push(`${pathSeg}: must be one of ${schema.enum.join(', ')}`); + if (dataType === 'object') { + const props = schema.properties || {}; + const required = schema.required || []; + for (const r of required) if (!(r in data)) errors.push(`${pathSeg}.${r}: is required`); + if (schema.additionalProperties === false) { + for (const k of Object.keys(data)) if (!(k in props)) errors.push(`${pathSeg}.${k}: additional property not allowed`); + } + for (const [k, sub] of Object.entries(props)) if (k in data) errors.push(...validate(sub, data[k], `${pathSeg}.${k}`)); + } + if (dataType === 'array') { + const itemsSchema = schema.items; const minItems = schema.minItems || 0; + if (data.length < minItems) errors.push(`${pathSeg}: must have at least ${minItems} items`); + if (itemsSchema) data.forEach((item, i) => errors.push(...validate(itemsSchema, item, `${pathSeg}[${i}]`))); + } + if (dataType === 'string') { + if (schema.minLength && data.length < schema.minLength) errors.push(`${pathSeg}: string shorter than ${schema.minLength}`); + if (schema.maxLength && data.length > schema.maxLength) errors.push(`${pathSeg}: string exceeds ${schema.maxLength}`); + if (schema.pattern) { const re = new RegExp(schema.pattern); if (!re.test(data)) errors.push(`${pathSeg}: does not match ${schema.pattern}`); } + } + if (dataType === 'number') { + if (schema.minimum !== undefined && data < schema.minimum) errors.push(`${pathSeg}: < minimum ${schema.minimum}`); + if (schema.maximum !== undefined && data > schema.maximum) errors.push(`${pathSeg}: > maximum ${schema.maximum}`); + } + return errors; +} + +function autoFix(schema, data) { + // Non-destructive autofixes only: remove additional properties, trim strings. + if (typeOf(data) === 'object') { + const props = schema.properties || {}; + const out = {}; + for (const [k, v] of Object.entries(data)) { + if (schema.additionalProperties === false && !(k in props)) continue; // drop unknown + out[k] = autoFix(props[k] || {}, v); + } + return out; + } + if (typeOf(data) === 'array') { + const itemsSchema = schema.items || {}; + return data.map(item => autoFix(itemsSchema, item)); + } + if (typeOf(data) === 'string') { return data.trim(); } + return data; +} + +function main() { + const args = parseArgs(process.argv); + const schemaPath = args.schema; const inputPath = args.input; const gatePath = args.gate; const autofix = parseInt(args.autofix || '0', 10); + if (!schemaPath || !inputPath || !gatePath) { + console.error('Usage: node .claude/tools/gates/gate.mjs --schema --input --gate [--autofix 1]'); + process.exit(2); + } + const schema = loadJSON(schemaPath); + let data = loadJSON(inputPath); + const attempts = []; + let errors = validate(schema, data); + if (errors.length && autofix > 0) { + const fixed = autoFix(schema, data); + attempts.push({ kind: 'autofix', changes: 'trim_strings|drop_additional_props' }); + fs.writeFileSync(inputPath, JSON.stringify(fixed, null, 2)); + data = fixed; + errors = validate(schema, data); + } + + const status = errors.length ? (attempts.length ? 'fail_after_fix' : 'fail') : (attempts.length ? 'fixed' : 'pass'); + const record = { + status, + attempts, + errors, + schema: path.relative(process.cwd(), schemaPath), + input: path.relative(process.cwd(), inputPath), + timestamp: new Date().toISOString() + }; + saveJSON(gatePath, record); + if (status.startsWith('fail')) { + console.error('Validation failed. See gate record:', gatePath); + process.exit(1); + } +} + +main(); + diff --git a/.claude/tools/renderers/bmad-render.mjs b/.claude/tools/renderers/bmad-render.mjs new file mode 100644 index 00000000..a50f06f4 --- /dev/null +++ b/.claude/tools/renderers/bmad-render.mjs @@ -0,0 +1,374 @@ +#!/usr/bin/env node +/** + * BMAD Renderer: JSON-first → Markdown + * + * Usage: + * node .claude/tools/renderers/bmad-render.mjs + * + * Types: + * - project-brief -> .claude/schemas/project_brief.schema.json + * - prd -> .claude/schemas/product_requirements.schema.json + * - architecture -> .claude/schemas/system_architecture.schema.json + * - ux-spec -> .claude/schemas/ux_spec.schema.json + * - test-plan -> .claude/schemas/test_plan.schema.json + */ + +import fs from 'fs'; +import path from 'path'; + +const CWD = process.cwd(); +const ROOT = CWD; // Run from repo root for relative paths + +const schemaMap = { + 'project-brief': '.claude/schemas/project_brief.schema.json', + prd: '.claude/schemas/product_requirements.schema.json', + architecture: '.claude/schemas/system_architecture.schema.json', + 'ux-spec': '.claude/schemas/ux_spec.schema.json', + 'test-plan': '.claude/schemas/test_plan.schema.json', + story: '.claude/schemas/user_story.schema.json', + epic: '.claude/schemas/epic.schema.json', + backlog: '.claude/schemas/backlog.schema.json', + 'review-notes': '.claude/schemas/review_notes.schema.json', + 'enhancement-classification': '.claude/schemas/enhancement_classification.schema.json' +}; + +function loadJSON(p) { + return JSON.parse(fs.readFileSync(p, 'utf8')); +} + +function typeOf(v) { + if (v === null) return 'null'; + if (Array.isArray(v)) return 'array'; + return typeof v; +} + +function validate(schema, data, pathSeg = '$') { + const errors = []; + const t = schema.type; + + // Handle union types like ["string", "null"] (not used here; keep simple) + const expectedTypes = Array.isArray(t) ? t : [t]; + const dataType = typeOf(data); + + if (t && !expectedTypes.includes(dataType)) { + errors.push(`${pathSeg}: expected type ${expectedTypes.join('|')}, got ${dataType}`); + return errors; + } + + if (schema.enum && !schema.enum.includes(data)) { + errors.push(`${pathSeg}: value must be one of ${schema.enum.join(', ')}`); + } + + if (dataType === 'object') { + const props = schema.properties || {}; + const required = schema.required || []; + + for (const r of required) { + if (!(r in data)) errors.push(`${pathSeg}.${r}: is required`); + } + + if (schema.additionalProperties === false) { + for (const k of Object.keys(data)) { + if (!(k in props)) errors.push(`${pathSeg}.${k}: additional property not allowed`); + } + } + + for (const [k, subSchema] of Object.entries(props)) { + if (k in data) { + errors.push(...validate(subSchema, data[k], `${pathSeg}.${k}`)); + } + } + } + + if (dataType === 'array') { + const itemsSchema = schema.items; + const minItems = schema.minItems || 0; + if (data.length < minItems) errors.push(`${pathSeg}: must have at least ${minItems} items`); + if (itemsSchema) { + data.forEach((item, i) => { + errors.push(...validate(itemsSchema, item, `${pathSeg}[${i}]`)); + }); + } + } + + if (dataType === 'string') { + if (schema.minLength && data.length < schema.minLength) { + errors.push(`${pathSeg}: string shorter than minLength ${schema.minLength}`); + } + if (schema.pattern) { + const re = new RegExp(schema.pattern); + if (!re.test(data)) errors.push(`${pathSeg}: does not match pattern ${schema.pattern}`); + } + } + + if (dataType === 'number') { + if (schema.minimum !== undefined && data < schema.minimum) { + errors.push(`${pathSeg}: number below minimum ${schema.minimum}`); + } + if (schema.maximum !== undefined && data > schema.maximum) { + errors.push(`${pathSeg}: number above maximum ${schema.maximum}`); + } + } + + return errors; +} + +function h(level, text) { return `${'#'.repeat(level)} ${text}`; } +function bullet(items) { return items.map(i => `- ${i}`).join('\n'); } +function kv(key, val) { return `- ${key}: ${val}`; } + +const renderers = { + 'project-brief': (d) => { + return [ + h(1, d.project_name), + '', + h(2, 'Summary'), + d.summary, + '', + h(2, 'Goals'), + bullet(d.goals), + '', + h(2, 'Target Users'), + bullet(d.target_users), + '', + h(2, 'Success Metrics'), + bullet(d.success_metrics), + '', + h(2, 'Scope'), + kv('In scope', d.scope.in_scope.join(', ')), + kv('Out of scope', d.scope.out_of_scope.join(', ')) + ].join('\n'); + }, + prd: (d) => { + const personas = d.personas.map(p => `- ${p.name}: goals: ${p.goals.join('; ')}; pain points: ${p.pain_points.join('; ')}`).join('\n'); + const features = d.features.map(f => [ + `- ${f.id} ${f.title}`, + ` - Description: ${f.description}`, + ` - Priority: ${f.priority}`, + ` - Acceptance Criteria:`, + ...f.acceptance_criteria.map(ac => ` - ${ac}`), + f.dependencies && f.dependencies.length ? ` - Dependencies: ${f.dependencies.join(', ')}` : '' + ].filter(Boolean).join('\n')).join('\n'); + return [ + h(1, d.title), + '', + h(2, 'Overview'), + d.overview, + '', + h(2, 'Personas'), + personas, + '', + h(2, 'Features'), + features, + '', + h(2, 'Non-functional Requirements'), + bullet(d.non_functional_requirements), + '', + h(2, 'Constraints'), + bullet(d.constraints) + ].join('\n'); + }, + architecture: (d) => { + const adrs = d.decisions.map(a => `- ${a.id} [${a.status}]: ${a.decision} — ${a.rationale}`).join('\n'); + const comps = d.components.map(c => `- ${c.name} (${c.technology}): ${c.responsibilities.join(', ')}`).join('\n'); + const entities = d.data_model.entities.map(e => [ + `- ${e.name}`, + ...e.attributes.map(at => ` - ${at.name}: ${at.type}${at.description ? ` — ${at.description}` : ''}`), + e.relationships && e.relationships.length ? ` - Relationships: ${e.relationships.join('; ')}` : '' + ].filter(Boolean).join('\n')).join('\n'); + const integrations = d.integration.map(i => `- ${i.with} (${i.direction}, ${i.protocol})${i.notes ? ` — ${i.notes}` : ''}`).join('\n'); + const perf = d.performance.targets.map(t => `- ${t.metric}: ${t.target}`).join('\n'); + return [ + h(1, 'System Architecture'), + '', + h(2, 'Context'), + d.context, + '', + h(2, 'Architecture Decisions'), + adrs, + '', + h(2, 'Components'), + comps, + '', + h(2, 'Data Model'), + entities, + '', + h(2, 'Integration'), + integrations, + '', + h(2, 'Deployment'), + bullet([`Strategy: ${d.deployment.strategy}`, d.deployment.diagram ? `Diagram: ${d.deployment.diagram}` : null].filter(Boolean)), + '', + h(2, 'Security'), + bullet([`Threats: ${d.security.threats.join(', ')}`, `Controls: ${d.security.controls.join(', ')}`]), + '', + h(2, 'Performance Targets'), + perf + ].join('\n'); + }, + 'ux-spec': (d) => { + const screens = d.screens.map(s => [ + `- ${s.name}: ${s.purpose}`, + ...s.components.map(c => ` - ${c.id} (${c.type})${c.label ? ` — ${c.label}` : ''}`) + ].join('\n')).join('\n'); + const flows = d.flows.map(f => `- ${f.name}: ${f.steps.join(' → ')}`).join('\n'); + return [ + h(1, 'UX Specification'), + '', + h(2, 'Design Principles'), + bullet(d.design_principles), + '', + h(2, 'Information Architecture'), + d.information_architecture.map(i => `- ${i.section}: ${i.content}`).join('\n'), + '', + h(2, 'Screens'), + screens, + '', + h(2, 'Flows'), + flows, + '', + h(2, 'Accessibility'), + bullet(d.accessibility.guidelines) + ].join('\n'); + }, + 'test-plan': (d) => { + const levels = d.test_levels.map(l => `- ${l.level}: ${l.tools.join(', ')}`).join('\n'); + const cases = d.test_cases.map(tc => [ + `- ${tc.id} ${tc.title} [${tc.priority}]`, + ` - Preconditions: ${tc.preconditions.join('; ')}`, + ` - Steps:`, + ...tc.steps.map(s => ` - ${s.action} ⇒ ${s.expected}`), + tc.tags && tc.tags.length ? ` - Tags: ${tc.tags.join(', ')}` : '' + ].filter(Boolean).join('\n')).join('\n'); + return [ + h(1, 'Test Plan'), + '', + h(2, 'Strategy'), + d.strategy, + '', + h(2, 'Scope'), + bullet([`In scope: ${d.scope.in_scope.join(', ')}`, `Out of scope: ${d.scope.out_of_scope.join(', ')}`]), + '', + h(2, 'Test Levels'), + levels, + '', + h(2, 'Test Cases'), + cases, + '', + h(2, 'Coverage Targets'), + bullet([`Statements: ${d.coverage_targets.statements}%`, `Branches: ${d.coverage_targets.branches}%`, `Functions: ${d.coverage_targets.functions}%`, `Lines: ${d.coverage_targets.lines}%`]), + '', + h(2, 'Environments'), + bullet(d.environments), + '', + h(2, 'Reporting'), + bullet([`Tools: ${d.reporting.tools.join(', ')}`, `Cadence: ${d.reporting.cadence}`]) + ].join('\n'); + } + , + story: (d) => { + const deps = d.depends_on && d.depends_on.length ? `\n${h(3, 'Dependencies')}\n${bullet(d.depends_on)}` : ''; + const links = d.prd_refs && d.prd_refs.length ? `\n${h(3, 'PRD References')}\n${bullet(d.prd_refs)}` : ''; + return [ + h(1, `${d.id} ${d.title}`), + '', + h(2, 'Description'), + d.description, + '', + h(2, 'Acceptance Criteria'), + bullet(d.acceptance_criteria), + '', + h(2, 'Priority & Estimate'), + bullet([`Priority: ${d.priority}`, d.estimate_points !== undefined ? `Estimate: ${d.estimate_points}pt` : null].filter(Boolean)), + deps, + links + ].join('\n'); + }, + epic: (d) => { + return [ + h(1, `${d.id} ${d.title}`), + '', + h(2, 'Description'), + d.description, + '', + h(2, 'Business Value'), + String(d.business_value ?? ''), + '', + h(2, 'Stories'), + bullet(d.stories) + ].join('\n'); + }, + backlog: (d) => { + const items = d.items.map(i => `- [${i.type}] ${i.id} — ${i.priority} — ${i.status}${i.sprint ? ` — ${i.sprint}` : ''}`).join('\n'); + return [ + h(1, 'Backlog'), + '', + h(2, 'Items'), + items + ].join('\n'); + }, + 'review-notes': (d) => { + const findings = d.findings.map(f => [ + `- ${f.area}`, + ...f.issues.map(is => ` - ${is}`) + ].join('\n')).join('\n'); + return [ + h(1, 'Implementation Review Notes'), + '', + h(2, 'Summary'), + d.summary, + '', + h(2, 'Findings'), + findings, + '', + h(2, 'Recommendations'), + bullet(d.recommendations) + ].join('\n'); + }, + 'enhancement-classification': (d) => { + return [ + h(1, 'Enhancement Classification'), + '', + h(2, 'Level'), + d.level, + '', + h(2, 'Recommended Workflow'), + d.recommended_workflow, + '', + h(2, 'Rationale'), + d.rationale, + '', + h(2, 'Indicators'), + d.indicators && d.indicators.length ? bullet(d.indicators) : '-' + ].join('\n'); + } +}; + +function die(msg) { console.error(msg); process.exit(1); } + +function main() { + const [,, type, jsonPath] = process.argv; + if (!type || !jsonPath) { + die('Usage: node .claude/tools/renderers/bmad-render.mjs '); + } + const schemaPath = schemaMap[type]; + if (!schemaPath) die(`Unknown type: ${type}`); + const absSchema = path.resolve(ROOT, schemaPath); + const absInput = path.resolve(ROOT, jsonPath); + if (!fs.existsSync(absSchema)) die(`Schema not found: ${absSchema}`); + if (!fs.existsSync(absInput)) die(`Input not found: ${absInput}`); + + const schema = loadJSON(absSchema); + const data = loadJSON(absInput); + const errors = validate(schema, data); + if (errors.length) { + die('Schema validation failed:\n' + errors.map(e => `- ${e}`).join('\n')); + } + + const renderer = renderers[type]; + if (!renderer) die(`No renderer for type: ${type}`); + const md = renderer(data); + process.stdout.write(md + '\n'); +} + +main(); diff --git a/.claude/workflows/brownfield-fullstack.yaml b/.claude/workflows/brownfield-fullstack.yaml index 5b6ba429..22c517c8 100644 --- a/.claude/workflows/brownfield-fullstack.yaml +++ b/.claude/workflows/brownfield-fullstack.yaml @@ -20,7 +20,15 @@ sequence: name: "Enhancement Scope Classification" agent: analyst task: classify_enhancement - creates: "artifacts/enhancement-classification.md" + inputs: + - "enhancement_spec.md" + creates: ".claude/context/artifacts/enhancement-classification.json" + validators: + - schema: ".claude/schemas/enhancement_classification.schema.json" + render: + renderer: "enhancement-classification" + from: ".claude/context/artifacts/enhancement-classification.json" + to: ".claude/context/artifacts/enhancement-classification.md" description: "Determine enhancement complexity and appropriate workflow path" instructions: | Load the Analyst agent prompt from .claude/agents/analyst/prompt.md @@ -30,14 +38,16 @@ sequence: - Major enhancement (multiple epics): Significant changes requiring architecture Ask user: "Can you describe the enhancement scope? Is this a small fix, a feature addition, or a major enhancement requiring architectural changes?" Document the classification and recommended workflow path - Save output to context/artifacts/enhancement-classification.md + Save output to .claude/context/artifacts/enhancement-classification.md - step: 2 name: "Existing System Analysis" agent: architect task: analyze_existing_system template: project_documentation - creates: "artifacts/system-analysis.md" + inputs: + - ".claude/context/artifacts/enhancement-classification.md" + creates: ".claude/context/artifacts/system-analysis.md" depends_on: [1] condition: major_enhancement description: "Analyze existing full-stack application and current state" @@ -48,14 +58,25 @@ sequence: Review system documentation, API specifications, and coding standards Identify technical debt, performance issues, and architectural constraints Document current state, integration dependencies, and enhancement opportunities - Save output to context/artifacts/system-analysis.md + Save output to .claude/context/artifacts/system-analysis.md - step: 3 name: "Enhancement Requirements" agent: pm task: create_brownfield_prd template: brownfield_prd - creates: "artifacts/prd.md" + inputs: + - ".claude/context/artifacts/system-analysis.md" + creates: ".claude/context/artifacts/prd.json" + validators: + - schema: ".claude/schemas/product_requirements.schema.json" + on_fail: + retry: 1 + escalate_to: "analyst" + render: + renderer: "prd" + from: ".claude/context/artifacts/prd.json" + to: ".claude/context/artifacts/prd.md" depends_on: [1, 2] description: "Create enhancement-focused Product Requirements Document" instructions: | @@ -65,14 +86,25 @@ sequence: Generate requirements that account for existing system constraints and dependencies Include migration strategies, backward compatibility, and integration considerations Define user stories that respect existing user workflows and data structures - Save output to context/artifacts/prd.md + Save output to .claude/context/artifacts/prd.md - step: 4 name: "UI/UX Enhancement Planning" agent: ux-expert task: plan_ui_enhancements template: ui_spec - creates: "artifacts/ui-enhancement-spec.md" + inputs: + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/ui-enhancement-spec.json" + validators: + - schema: ".claude/schemas/ux_spec.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "ux-spec" + from: ".claude/context/artifacts/ui-enhancement-spec.json" + to: ".claude/context/artifacts/ui-enhancement-spec.md" depends_on: [2, 3] optional: true condition: frontend_changes_required @@ -84,14 +116,26 @@ sequence: Design enhancements that maintain consistency with existing UI patterns Plan component updates, new interactions, and design system integration Consider user experience implications of changes to existing workflows - Save output to context/artifacts/ui-enhancement-spec.md + Save output to .claude/context/artifacts/ui-enhancement-spec.md - step: 5 name: "Integration Architecture" agent: architect task: design_integration_architecture template: brownfield_architecture - creates: "artifacts/architecture.md" + inputs: + - ".claude/context/artifacts/prd.json" + - ".claude/context/artifacts/ui-enhancement-spec.md" + creates: ".claude/context/artifacts/architecture.json" + validators: + - schema: ".claude/schemas/system_architecture.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "architecture" + from: ".claude/context/artifacts/architecture.json" + to: ".claude/context/artifacts/architecture.md" depends_on: [2, 3, 4] condition: architectural_changes_needed description: "Design integration strategy for full-stack enhancements" @@ -103,7 +147,7 @@ sequence: Plan database migrations, API updates, and component integration Include deployment strategy, rollback plans, and monitoring considerations Address security, performance, and scalability implications - Save output to context/artifacts/architecture.md + Save output to .claude/context/artifacts/architecture.md - step: 6 name: "Frontend Enhancement Implementation" @@ -144,7 +188,20 @@ sequence: agent: qa task: create_integration_test_plan template: test_plan - creates: "artifacts/test-plan.md" + inputs: + - ".claude/context/artifacts/architecture.md" + - "src/frontend-enhanced/" + - "src/backend-enhanced/" + creates: ".claude/context/artifacts/test-plan.json" + validators: + - schema: ".claude/schemas/test_plan.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "test-plan" + from: ".claude/context/artifacts/test-plan.json" + to: ".claude/context/artifacts/test-plan.md" depends_on: [6, 7] description: "Create comprehensive testing strategy for full-stack enhancements" instructions: | @@ -155,13 +212,19 @@ sequence: Include frontend testing, API testing, integration testing, and e2e testing Create test scenarios for backward compatibility and migration procedures Plan regression testing and user acceptance testing - Save output to context/artifacts/test-plan.md + Save output to .claude/context/artifacts/test-plan.md - step: 9 name: "Implementation Review" agent: architect task: review_fullstack_integration - creates: "artifacts/review-notes.md" + creates: ".claude/context/artifacts/review-notes.json" + validators: + - schema: ".claude/schemas/review_notes.schema.json" + render: + renderer: "review-notes" + from: ".claude/context/artifacts/review-notes.json" + to: ".claude/context/artifacts/review-notes.md" depends_on: [6, 7, 8] description: "Review full-stack enhancements and integration safety" instructions: | @@ -171,15 +234,19 @@ sequence: Check frontend-backend integration, data flow, and API compatibility Verify security measures, performance impacts, and deployment readiness Provide recommendations for rollout, monitoring, and maintenance - Save output to context/artifacts/review-notes.md + Save output to .claude/context/artifacts/review-notes.md outputs: documents: - enhancement-classification.md - system-analysis.md + - prd.json - prd.md + - ui-enhancement-spec.json (optional) - ui-enhancement-spec.md (optional) + - architecture.json (conditional) - architecture.md (conditional) + - test-plan.json - test-plan.md - review-notes.md frontend_code: @@ -212,4 +279,4 @@ when_to_use: - Architectural changes are needed - Significant integration work required - Risk assessment and mitigation planning necessary - - Multiple team members will work on related changes \ No newline at end of file + - Multiple team members will work on related changes diff --git a/.claude/workflows/brownfield-service.yaml b/.claude/workflows/brownfield-service.yaml index d6d7309c..1c60b11e 100644 --- a/.claude/workflows/brownfield-service.yaml +++ b/.claude/workflows/brownfield-service.yaml @@ -21,7 +21,9 @@ sequence: agent: architect task: analyze_existing_service template: project_documentation - creates: "artifacts/service-analysis.md" + inputs: + - "enhancement_spec.md" + creates: ".claude/context/artifacts/service-analysis.md" description: "Analyze existing backend service and identify improvement areas" instructions: | Load the Architect agent prompt from .claude/agents/architect/prompt.md @@ -30,14 +32,25 @@ sequence: Review performance metrics, logs, and monitoring data if available Identify technical debt, security vulnerabilities, and optimization opportunities Document current state, integration dependencies, and enhancement recommendations - Save output to context/artifacts/service-analysis.md + Save output to .claude/context/artifacts/service-analysis.md - step: 2 name: "Enhancement Requirements" agent: pm task: create_brownfield_prd template: brownfield_prd - creates: "artifacts/prd.md" + inputs: + - ".claude/context/artifacts/service-analysis.md" + creates: ".claude/context/artifacts/prd.json" + validators: + - schema: ".claude/schemas/product_requirements.schema.json" + on_fail: + retry: 1 + escalate_to: "analyst" + render: + renderer: "prd" + from: ".claude/context/artifacts/prd.json" + to: ".claude/context/artifacts/prd.md" depends_on: [1] description: "Create enhancement-focused Product Requirements Document" instructions: | @@ -47,14 +60,25 @@ sequence: Generate requirements focused on service enhancements with existing system integration Include API versioning strategies, backward compatibility, and migration plans Define user stories that account for existing integrations and dependencies - Save output to context/artifacts/prd.md + Save output to .claude/context/artifacts/prd.md - step: 3 name: "Service Integration Architecture" agent: architect task: design_service_enhancements template: brownfield_architecture - creates: "artifacts/architecture.md" + inputs: + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/architecture.json" + validators: + - schema: ".claude/schemas/system_architecture.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "architecture" + from: ".claude/context/artifacts/architecture.json" + to: ".claude/context/artifacts/architecture.md" depends_on: [1, 2] description: "Design integration strategy for service enhancements" instructions: | @@ -65,7 +89,7 @@ sequence: Plan database migrations, service layer updates, and dependency changes Include API versioning strategy and backward compatibility measures Create rollback plans and deployment strategies with zero-downtime deployment - Save output to context/artifacts/architecture.md + Save output to .claude/context/artifacts/architecture.md - step: 4 name: "Enhanced Service Implementation" @@ -88,7 +112,19 @@ sequence: agent: qa task: create_service_test_plan template: test_plan - creates: "artifacts/test-plan.md" + inputs: + - ".claude/context/artifacts/architecture.md" + - "src/api-enhanced/" + creates: ".claude/context/artifacts/test-plan.json" + validators: + - schema: ".claude/schemas/test_plan.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "test-plan" + from: ".claude/context/artifacts/test-plan.json" + to: ".claude/context/artifacts/test-plan.md" depends_on: [3, 4] description: "Create testing strategy for service enhancements" instructions: | @@ -99,13 +135,19 @@ sequence: Include API contract testing, integration testing, and performance testing Create test scenarios for backward compatibility and migration procedures Plan load testing and security testing for enhanced endpoints - Save output to context/artifacts/test-plan.md + Save output to .claude/context/artifacts/test-plan.md - step: 6 name: "Implementation Review" agent: architect task: review_service_integration - creates: "artifacts/review-notes.md" + creates: ".claude/context/artifacts/review-notes.json" + validators: + - schema: ".claude/schemas/review_notes.schema.json" + render: + renderer: "review-notes" + from: ".claude/context/artifacts/review-notes.json" + to: ".claude/context/artifacts/review-notes.md" depends_on: [4, 5] description: "Review service enhancements and integration safety" instructions: | @@ -115,13 +157,16 @@ sequence: Check for API contract compatibility and proper versioning implementation Verify security measures, performance impacts, and scalability considerations Provide recommendations for deployment, monitoring, and rollback procedures - Save output to context/artifacts/review-notes.md + Save output to .claude/context/artifacts/review-notes.md outputs: documents: - service-analysis.md + - prd.json - prd.md + - architecture.json - architecture.md + - test-plan.json - test-plan.md - review-notes.md code: @@ -153,4 +198,4 @@ when_to_use: - API versioning or breaking changes needed - Database schema changes required - Performance or scalability improvements needed - - Multiple integration points affected \ No newline at end of file + - Multiple integration points affected diff --git a/.claude/workflows/brownfield-ui.yaml b/.claude/workflows/brownfield-ui.yaml index 544807d3..bd31b35e 100644 --- a/.claude/workflows/brownfield-ui.yaml +++ b/.claude/workflows/brownfield-ui.yaml @@ -21,7 +21,9 @@ sequence: agent: architect task: analyze_existing_system template: project_documentation - creates: "artifacts/ui-analysis.md" + inputs: + - "enhancement_spec.md" + creates: ".claude/context/artifacts/ui-analysis.md" description: "Analyze existing frontend application and identify improvement areas" instructions: | Load the Architect agent prompt from .claude/agents/architect/prompt.md @@ -30,14 +32,25 @@ sequence: Review user feedback, analytics data, and performance metrics if available Identify technical debt, outdated patterns, and enhancement opportunities Document current state, constraints, and improvement recommendations - Save output to context/artifacts/ui-analysis.md + Save output to .claude/context/artifacts/ui-analysis.md - step: 2 name: "Enhancement Requirements" agent: pm task: create_brownfield_prd template: brownfield_prd - creates: "artifacts/prd.md" + inputs: + - ".claude/context/artifacts/ui-analysis.md" + creates: ".claude/context/artifacts/prd.json" + validators: + - schema: ".claude/schemas/product_requirements.schema.json" + on_fail: + retry: 1 + escalate_to: "analyst" + render: + renderer: "prd" + from: ".claude/context/artifacts/prd.json" + to: ".claude/context/artifacts/prd.md" depends_on: [1] description: "Create enhancement-focused Product Requirements Document" instructions: | @@ -47,14 +60,25 @@ sequence: Generate requirements focused on UI enhancements with existing system integration Include migration strategies, backward compatibility, and rollout plans Define user stories that account for existing user behavior and patterns - Save output to context/artifacts/prd.md + Save output to .claude/context/artifacts/prd.md - step: 3 name: "UI/UX Enhancement Design" agent: ux-expert task: design_ui_enhancements template: ui_spec - creates: "artifacts/front-end-spec.md" + inputs: + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/front-end-spec.json" + validators: + - schema: ".claude/schemas/ux_spec.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "ux-spec" + from: ".claude/context/artifacts/front-end-spec.json" + to: ".claude/context/artifacts/front-end-spec.md" depends_on: [1, 2] description: "Design UI enhancements that integrate with existing system" instructions: | @@ -64,14 +88,26 @@ sequence: Design enhancements that respect existing design patterns and user expectations Create transition strategies for design changes and new interaction patterns Ensure consistency with existing components while introducing improvements - Save output to context/artifacts/front-end-spec.md + Save output to .claude/context/artifacts/front-end-spec.md - step: 4 name: "Integration Architecture" agent: architect task: design_integration_strategy template: brownfield_architecture - creates: "artifacts/architecture.md" + inputs: + - ".claude/context/artifacts/front-end-spec.md" + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/architecture.json" + validators: + - schema: ".claude/schemas/system_architecture.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "architecture" + from: ".claude/context/artifacts/architecture.json" + to: ".claude/context/artifacts/architecture.md" depends_on: [1, 2, 3] description: "Design integration strategy for UI enhancements" instructions: | @@ -82,7 +118,7 @@ sequence: Plan component migration, state management updates, and build process changes Include testing strategy for ensuring existing functionality remains intact Create rollback plans and deployment strategies - Save output to context/artifacts/architecture.md + Save output to .claude/context/artifacts/architecture.md - step: 5 name: "Enhanced Components Implementation" @@ -105,7 +141,19 @@ sequence: agent: qa task: create_integration_test_plan template: test_plan - creates: "artifacts/test-plan.md" + inputs: + - ".claude/context/artifacts/architecture.md" + - "src/components-enhanced/" + creates: ".claude/context/artifacts/test-plan.json" + validators: + - schema: ".claude/schemas/test_plan.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "test-plan" + from: ".claude/context/artifacts/test-plan.json" + to: ".claude/context/artifacts/test-plan.md" depends_on: [4, 5] description: "Create testing strategy for UI enhancements" instructions: | @@ -116,13 +164,19 @@ sequence: Include regression testing, component testing, and user acceptance testing Create test scenarios for migration paths and rollback procedures Plan visual regression testing and cross-browser compatibility testing - Save output to context/artifacts/test-plan.md + Save output to .claude/context/artifacts/test-plan.md - step: 7 name: "Implementation Review" agent: architect task: review_ui_integration - creates: "artifacts/review-notes.md" + creates: ".claude/context/artifacts/review-notes.json" + validators: + - schema: ".claude/schemas/review_notes.schema.json" + render: + renderer: "review-notes" + from: ".claude/context/artifacts/review-notes.json" + to: ".claude/context/artifacts/review-notes.md" depends_on: [5, 6] description: "Review UI enhancements and integration safety" instructions: | @@ -132,14 +186,18 @@ sequence: Check for potential conflicts, performance impacts, and security considerations Verify that rollback strategies are viable and migration paths are clear Provide recommendations for deployment, monitoring, and user training - Save output to context/artifacts/review-notes.md + Save output to .claude/context/artifacts/review-notes.md outputs: documents: - ui-analysis.md + - prd.json - prd.md + - front-end-spec.json - front-end-spec.md + - architecture.json - architecture.md + - test-plan.json - test-plan.md - review-notes.md code: @@ -168,4 +226,4 @@ when_to_use: - Design system changes needed - New component patterns required - User research and testing needed - - Multiple team members will work on related changes \ No newline at end of file + - Multiple team members will work on related changes diff --git a/.claude/workflows/greenfield-fullstack.yaml b/.claude/workflows/greenfield-fullstack.yaml index 620c795d..bb1a8a10 100644 --- a/.claude/workflows/greenfield-fullstack.yaml +++ b/.claude/workflows/greenfield-fullstack.yaml @@ -21,21 +21,45 @@ sequence: agent: analyst task: analyze_specification template: project_brief - creates: "artifacts/project-brief.md" + inputs: + - "user_spec.md" + creates: ".claude/context/artifacts/project-brief.json" + validators: + - schema: ".claude/schemas/project_brief.schema.json" + - checklist: ".claude/checklists/story-draft-checklist.md" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "project-brief" + from: ".claude/context/artifacts/project-brief.json" + to: ".claude/context/artifacts/project-brief.md" description: "Analyze user requirements and create project brief" instructions: | Load the analyst agent prompt from .claude/agents/analyst/prompt.md Apply the project brief template from .claude/templates/project-brief.md Generate comprehensive project analysis including market context and technical feasibility Focus on full-stack requirements including frontend, backend, and integration needs - Save output to context/artifacts/project-brief.md + Save output to .claude/context/artifacts/project-brief.md - step: 2 name: "Requirements Documentation" agent: pm task: create_prd template: prd - creates: "artifacts/prd.md" + inputs: + - ".claude/context/artifacts/project-brief.json" + creates: ".claude/context/artifacts/prd.json" + validators: + - schema: ".claude/schemas/product_requirements.schema.json" + - checklist: ".claude/checklists/story-draft-checklist.md" + on_fail: + retry: 1 + escalate_to: "analyst" + render: + renderer: "prd" + from: ".claude/context/artifacts/prd.json" + to: ".claude/context/artifacts/prd.md" depends_on: [1] description: "Create Product Requirements Document" instructions: | @@ -44,14 +68,25 @@ sequence: Apply the PRD template from .claude/templates/prd.md Generate detailed requirements document covering frontend, backend, and integration requirements Include user stories, API specifications, data models, and user flows - Save output to context/artifacts/prd.md + Save output to .claude/context/artifacts/prd.md - step: 3 name: "UI/UX Design" agent: ux-expert task: design_interface template: ui_spec - creates: "artifacts/front-end-spec.md" + inputs: + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/ux-spec.json" + validators: + - schema: ".claude/schemas/ux_spec.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "ux-spec" + from: ".claude/context/artifacts/ux-spec.json" + to: ".claude/context/artifacts/front-end-spec.md" depends_on: [2] description: "Design user interface and experience" instructions: | @@ -60,13 +95,15 @@ sequence: Apply the UI spec template from .claude/templates/ui-spec.md Generate comprehensive UI/UX specifications including wireframes and user flows Design responsive interfaces and interaction patterns - Save output to context/artifacts/front-end-spec.md + Save output to .claude/context/artifacts/front-end-spec.md - step: 4 name: "AI UI Generation Prompt" agent: ux-expert task: generate_ai_prompt - creates: "artifacts/v0-prompt.md" + inputs: + - ".claude/context/artifacts/front-end-spec.md" + creates: ".claude/context/artifacts/v0-prompt.md" depends_on: [3] optional: true description: "Generate AI prompt for UI generation tools" @@ -75,14 +112,26 @@ sequence: Reference the front-end spec from step 3 Generate optimized prompts for AI UI tools like v0, Lovable, or similar Include specific component requirements, styling preferences, and interactions - Save output to context/artifacts/v0-prompt.md + Save output to .claude/context/artifacts/v0-prompt.md - step: 5 name: "Full-Stack Architecture" agent: architect task: design_architecture template: fullstack_architecture - creates: "artifacts/fullstack-architecture.md" + inputs: + - ".claude/context/artifacts/prd.json" + - ".claude/context/artifacts/ux-spec.json" + creates: ".claude/context/artifacts/system-architecture.json" + validators: + - schema: ".claude/schemas/system_architecture.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "architecture" + from: ".claude/context/artifacts/system-architecture.json" + to: ".claude/context/artifacts/fullstack-architecture.md" depends_on: [2, 3] description: "Design comprehensive full-stack architecture" instructions: | @@ -92,13 +141,16 @@ sequence: Design both frontend and backend architecture including database schema Include deployment strategy, API design, state management, and security considerations Consider integration points between frontend and backend - Save output to context/artifacts/fullstack-architecture.md + Save output to .claude/context/artifacts/fullstack-architecture.md - step: 6 name: "Frontend Implementation" agent: developer task: implement_frontend creates: "src/frontend/" + inputs: + - ".claude/context/artifacts/front-end-spec.md" + - ".claude/context/artifacts/fullstack-architecture.md" depends_on: [3, 5] description: "Implement frontend components and pages" instructions: | @@ -114,6 +166,8 @@ sequence: agent: developer task: implement_backend creates: "src/backend/" + inputs: + - ".claude/context/artifacts/fullstack-architecture.md" depends_on: [5] description: "Implement backend API and services" instructions: | @@ -129,7 +183,19 @@ sequence: agent: qa task: create_test_plan template: test_plan - creates: "artifacts/test-plan.md" + inputs: + - ".claude/context/artifacts/front-end-spec.md" + - ".claude/context/artifacts/fullstack-architecture.md" + creates: ".claude/context/artifacts/test-plan.json" + validators: + - schema: ".claude/schemas/test_plan.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "test-plan" + from: ".claude/context/artifacts/test-plan.json" + to: ".claude/context/artifacts/test-plan.md" depends_on: [6, 7] description: "Create comprehensive testing strategy" instructions: | @@ -139,13 +205,23 @@ sequence: Generate testing strategy including unit, integration, and e2e tests Include frontend testing, API testing, and full user journey tests Create test scenarios for all user flows and edge cases - Save output to context/artifacts/test-plan.md + Save output to .claude/context/artifacts/test-plan.md - step: 9 name: "Implementation Review" agent: architect task: review_implementation - creates: "artifacts/review-notes.md" + inputs: + - "src/frontend/" + - "src/backend/" + - ".claude/context/artifacts/test-plan.md" + creates: ".claude/context/artifacts/review-notes.json" + validators: + - schema: ".claude/schemas/review_notes.schema.json" + render: + renderer: "review-notes" + from: ".claude/context/artifacts/review-notes.json" + to: ".claude/context/artifacts/review-notes.md" depends_on: [6, 7, 8] description: "Review and validate full-stack implementation" instructions: | @@ -155,14 +231,19 @@ sequence: Check integration points between frontend and backend Verify security measures, performance considerations, and best practices Provide improvement recommendations and deployment guidance - Save output to context/artifacts/review-notes.md + Save output to .claude/context/artifacts/review-notes.md outputs: documents: + - project-brief.json - project-brief.md + - prd.json - prd.md + - ux-spec.json - front-end-spec.md + - system-architecture.json - fullstack-architecture.md + - test-plan.json - test-plan.md - review-notes.md - v0-prompt.md (optional) @@ -206,4 +287,4 @@ when_to_use: - Complex feature requirements - Need comprehensive documentation - Long-term maintenance expected - - Enterprise or customer-facing applications \ No newline at end of file + - Enterprise or customer-facing applications diff --git a/.claude/workflows/greenfield-service.yaml b/.claude/workflows/greenfield-service.yaml index ae016e7e..440cd886 100644 --- a/.claude/workflows/greenfield-service.yaml +++ b/.claude/workflows/greenfield-service.yaml @@ -21,21 +21,43 @@ sequence: agent: analyst task: analyze_specification template: project_brief - creates: "artifacts/project-brief.md" + inputs: + - "user_spec.md" + creates: ".claude/context/artifacts/project-brief.json" + validators: + - schema: ".claude/schemas/project_brief.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "project-brief" + from: ".claude/context/artifacts/project-brief.json" + to: ".claude/context/artifacts/project-brief.md" description: "Analyze user requirements and create project brief" instructions: | Load the analyst agent prompt from .claude/agents/analyst/prompt.md Apply the project brief template from .claude/templates/project-brief.md Generate comprehensive project analysis including technical feasibility and market context Focus on backend service requirements and API design considerations - Save output to context/artifacts/project-brief.md + Save output to .claude/context/artifacts/project-brief.md - step: 2 name: "Requirements Documentation" agent: pm task: create_prd template: prd - creates: "artifacts/prd.md" + inputs: + - ".claude/context/artifacts/project-brief.json" + creates: ".claude/context/artifacts/prd.json" + validators: + - schema: ".claude/schemas/product_requirements.schema.json" + on_fail: + retry: 1 + escalate_to: "analyst" + render: + renderer: "prd" + from: ".claude/context/artifacts/prd.json" + to: ".claude/context/artifacts/prd.md" depends_on: [1] description: "Create Product Requirements Document" instructions: | @@ -44,14 +66,25 @@ sequence: Apply the PRD template from .claude/templates/prd.md Generate detailed requirements document focused on API/service requirements Include endpoint specifications, data models, and service boundaries - Save output to context/artifacts/prd.md + Save output to .claude/context/artifacts/prd.md - step: 3 name: "Service Architecture" agent: architect task: design_architecture template: architecture - creates: "artifacts/architecture.md" + inputs: + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/system-architecture.json" + validators: + - schema: ".claude/schemas/system_architecture.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "architecture" + from: ".claude/context/artifacts/system-architecture.json" + to: ".claude/context/artifacts/architecture.md" depends_on: [2] description: "Design backend service architecture" instructions: | @@ -61,7 +94,7 @@ sequence: Focus on backend technologies, API design patterns, data storage, and scalability Include database schema, API endpoints, service layers, and deployment architecture Consider microservice patterns, authentication, and external integrations - Save output to context/artifacts/architecture.md + Save output to .claude/context/artifacts/architecture.md - step: 4 name: "API Implementation" @@ -84,7 +117,19 @@ sequence: agent: qa task: create_test_plan template: test_plan - creates: "artifacts/test-plan.md" + inputs: + - ".claude/context/artifacts/architecture.md" + - "src/api/" + creates: ".claude/context/artifacts/test-plan.json" + validators: + - schema: ".claude/schemas/test_plan.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "test-plan" + from: ".claude/context/artifacts/test-plan.json" + to: ".claude/context/artifacts/test-plan.md" depends_on: [3, 4] description: "Create comprehensive testing strategy" instructions: | @@ -94,13 +139,19 @@ sequence: Generate testing strategy including unit, integration, and API tests Create test scenarios for all endpoints, edge cases, and error conditions Include performance testing and security testing considerations - Save output to context/artifacts/test-plan.md + Save output to .claude/context/artifacts/test-plan.md - step: 6 name: "Implementation Review" agent: architect task: review_implementation - creates: "artifacts/review-notes.md" + creates: ".claude/context/artifacts/review-notes.json" + validators: + - schema: ".claude/schemas/review_notes.schema.json" + render: + renderer: "review-notes" + from: ".claude/context/artifacts/review-notes.json" + to: ".claude/context/artifacts/review-notes.md" depends_on: [4, 5] description: "Review and validate implementation" instructions: | @@ -110,13 +161,17 @@ sequence: Check adherence to REST/GraphQL best practices and standards Verify security measures and performance considerations Provide improvement recommendations and deployment guidance - Save output to context/artifacts/review-notes.md + Save output to .claude/context/artifacts/review-notes.md outputs: documents: + - project-brief.json - project-brief.md + - prd.json - prd.md + - system-architecture.json - architecture.md + - test-plan.json - test-plan.md - review-notes.md code: @@ -152,4 +207,4 @@ when_to_use: - Need comprehensive documentation and testing - Multiple team members will be involved - Long-term maintenance expected - - Enterprise or external-facing APIs \ No newline at end of file + - Enterprise or external-facing APIs diff --git a/.claude/workflows/greenfield-ui.yaml b/.claude/workflows/greenfield-ui.yaml index 9142d364..642572eb 100644 --- a/.claude/workflows/greenfield-ui.yaml +++ b/.claude/workflows/greenfield-ui.yaml @@ -21,20 +21,42 @@ sequence: agent: analyst task: analyze_specification template: project_brief - creates: "artifacts/project-brief.md" + inputs: + - "user_spec.md" + creates: ".claude/context/artifacts/project-brief.json" + validators: + - schema: ".claude/schemas/project_brief.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "project-brief" + from: ".claude/context/artifacts/project-brief.json" + to: ".claude/context/artifacts/project-brief.md" description: "Analyze user requirements and create project brief" instructions: | Load the analyst agent prompt from .claude/agents/analyst/prompt.md Apply the project brief template from .claude/templates/project-brief.md Generate comprehensive project analysis including market context and feasibility - Save output to context/artifacts/project-brief.md + Save output to .claude/context/artifacts/project-brief.md - step: 2 name: "Requirements Documentation" agent: pm task: create_prd template: prd - creates: "artifacts/prd.md" + inputs: + - ".claude/context/artifacts/project-brief.json" + creates: ".claude/context/artifacts/prd.json" + validators: + - schema: ".claude/schemas/product_requirements.schema.json" + on_fail: + retry: 1 + escalate_to: "analyst" + render: + renderer: "prd" + from: ".claude/context/artifacts/prd.json" + to: ".claude/context/artifacts/prd.md" depends_on: [1] description: "Create Product Requirements Document" instructions: | @@ -42,14 +64,25 @@ sequence: Reference the project brief from step 1 Apply the PRD template from .claude/templates/prd.md Generate detailed requirements document focused on UI/frontend requirements - Save output to context/artifacts/prd.md + Save output to .claude/context/artifacts/prd.md - step: 3 name: "UI/UX Design" agent: ux-expert task: design_interface template: ui_spec - creates: "artifacts/ui-spec.md" + inputs: + - ".claude/context/artifacts/prd.json" + creates: ".claude/context/artifacts/ux-spec.json" + validators: + - schema: ".claude/schemas/ux_spec.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "ux-spec" + from: ".claude/context/artifacts/ux-spec.json" + to: ".claude/context/artifacts/ui-spec.md" depends_on: [1, 2] description: "Design user interface and experience" instructions: | @@ -57,14 +90,26 @@ sequence: Reference project brief and PRD Apply the UI spec template from .claude/templates/ui-spec.md Generate comprehensive UI/UX specifications including wireframes and user flows - Save output to context/artifacts/ui-spec.md + Save output to .claude/context/artifacts/ui-spec.md - step: 4 name: "Technical Architecture" agent: architect task: design_architecture template: architecture - creates: "artifacts/frontend-architecture.md" + inputs: + - ".claude/context/artifacts/prd.json" + - ".claude/context/artifacts/ux-spec.json" + creates: ".claude/context/artifacts/frontend-architecture.json" + validators: + - schema: ".claude/schemas/system_architecture.schema.json" + on_fail: + retry: 1 + escalate_to: "pm" + render: + renderer: "architecture" + from: ".claude/context/artifacts/frontend-architecture.json" + to: ".claude/context/artifacts/frontend-architecture.md" depends_on: [2, 3] description: "Design frontend technical architecture" instructions: | @@ -73,7 +118,7 @@ sequence: Apply the architecture template from .claude/templates/architecture.md Focus on frontend technologies, patterns, and scalability Generate detailed technical architecture for frontend implementation - Save output to context/artifacts/frontend-architecture.md + Save output to .claude/context/artifacts/frontend-architecture.md - step: 5 name: "Component Development" @@ -95,7 +140,19 @@ sequence: agent: qa task: create_test_plan template: test_plan - creates: "artifacts/test-plan.md" + inputs: + - ".claude/context/artifacts/frontend-architecture.md" + - "src/components/" + creates: ".claude/context/artifacts/test-plan.json" + validators: + - schema: ".claude/schemas/test_plan.schema.json" + on_fail: + retry: 1 + escalate_to: "architect" + render: + renderer: "test-plan" + from: ".claude/context/artifacts/test-plan.json" + to: ".claude/context/artifacts/test-plan.md" depends_on: [4, 5] description: "Create comprehensive testing strategy" instructions: | @@ -104,13 +161,19 @@ sequence: Apply the test plan template from .claude/templates/test-plan.md Generate testing strategy including unit, integration, and e2e tests Create test scenarios for all user flows and edge cases - Save output to context/artifacts/test-plan.md + Save output to .claude/context/artifacts/test-plan.md - step: 7 name: "Implementation Review" agent: architect task: review_implementation - creates: "artifacts/review-notes.md" + creates: ".claude/context/artifacts/review-notes.json" + validators: + - schema: ".claude/schemas/review_notes.schema.json" + render: + renderer: "review-notes" + from: ".claude/context/artifacts/review-notes.json" + to: ".claude/context/artifacts/review-notes.md" depends_on: [5, 6] description: "Review and validate implementation" instructions: | @@ -119,14 +182,19 @@ sequence: Validate consistency between architecture and implementation Check adherence to best practices and standards Provide improvement recommendations and next steps - Save output to context/artifacts/review-notes.md + Save output to .claude/context/artifacts/review-notes.md outputs: documents: + - project-brief.json - project-brief.md + - prd.json - prd.md + - ux-spec.json - ui-spec.md + - frontend-architecture.json - frontend-architecture.md + - test-plan.json - test-plan.md - review-notes.md code: @@ -157,4 +225,4 @@ when_to_use: - Need comprehensive UI/UX design and testing - Multiple team members will be involved - Long-term maintenance expected - - Customer-facing applications \ No newline at end of file + - Customer-facing applications diff --git a/.github/workflows/validate-artifacts.yml b/.github/workflows/validate-artifacts.yml new file mode 100644 index 00000000..c90344d7 --- /dev/null +++ b/.github/workflows/validate-artifacts.yml @@ -0,0 +1,17 @@ +name: Validate Artifacts + +on: + pull_request: + push: + branches: [ main ] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '18' + - name: Validate JSON artifacts against schemas + run: node .claude/tools/ci/validate-all.mjs diff --git a/README.md b/README.md index 760f8e8b..183d6f55 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,10 @@ The BMAD-Spec Orchestrator Enterprise Edition provides **intelligent software de ## 🚀 Quick Start +### Requirements +- Node 18+ (for local JSON validation and rendering) +- Git (for version control and CI) + ### Simple Activation Just describe what you want to build: @@ -54,12 +58,24 @@ Just describe what you want to build: 🚀 Beginning intelligent workflow execution with 6 specialized agents... ``` +### JSON‑First Artifacts & Gates (New) +- Artifacts are produced as JSON first and validated against schemas in `.claude/schemas/`. +- Render human‑readable Markdown using the built‑in renderer: + - `node .claude/tools/renderers/bmad-render.mjs prd .claude/context/artifacts/prd.json > .claude/context/artifacts/prd.md` +- Enforce deterministic quality gates with a validate → auto‑fix → escalate loop: + - `node .claude/tools/gates/gate.mjs --schema .claude/schemas/product_requirements.schema.json --input .claude/context/artifacts/prd.json --gate .claude/context/history/gates/greenfield-fullstack/02-pm.json --autofix 1` + +### CI Validation +- GitHub Action `Validate Artifacts` runs on PRs and `main` to validate all `.claude/context/artifacts/*.json` against schemas. +- See `.github/workflows/validate-artifacts.yml` and `.claude/tools/ci/validate-all.mjs`. + ## 📁 Enterprise Architecture ``` .claude/ ├── CLAUDE.md # Enhanced system instructions with enterprise features ├── config.yaml # Enterprise configuration with performance optimization +├── schemas/ # JSON Schemas for machine‑checkable artifacts (PRD, project_brief, architecture, ux_spec, test_plan, user_story, epic, backlog, review_notes, enhancement_classification) ├── orchestrator/ # 🆕 Enterprise orchestration engine │ ├── context-engine.md # Structured context management & validation │ ├── enhanced-workflow-engine.md # Intelligent workflow execution @@ -69,6 +85,11 @@ Just describe what you want to build: │ ├── error-recovery-system.md # Reliability & failure handling │ ├── adaptive-workflow-system.md # Dynamic workflow selection │ └── system-integration-guide.md # Complete enterprise integration +├── tools/ +│ ├── renderers/bmad-render.mjs # JSON → Markdown renderer with schema validation +│ └── gates/gate.mjs # Gate runner: validate → auto‑fix → record +├── docs/structured-outputs.md # How JSON‑first artifacts & rendering work +├── rules/manifest.yaml # Capability‑scoped rules loading profiles ├── agents/ # 6 optimized AI agents (Claude-4 ready) │ ├── analyst/ (Maya Chen) # Enhanced with complexity analysis │ ├── pm/ (Alex Rodriguez) # Enhanced with validation protocols @@ -76,11 +97,11 @@ Just describe what you want to build: │ ├── developer/ (Jordan) # Enhanced with quality gates │ ├── qa/ (Riley Thompson) # Enhanced with comprehensive testing │ └── ux-expert/ (Sam Parker) # Enhanced with AI generation -├── workflows/ # 6 adaptive workflows with intelligence +├── workflows/ # 6 adaptive workflows with executable specs (inputs/validators/on_fail) ├── templates/ # 8 intelligent templates with validation ├── tasks/ # Categorized tasks with quality standards ├── system/ # 🆕 Enterprise governance & SDD principles -├── context/ # Advanced session & checkpoint management +├── context/ # Advanced session & checkpoint management (persists route_decision) ├── examples/ # Enterprise usage examples └── docs/ # 🆕 Complete enterprise documentation ``` @@ -140,7 +161,7 @@ Just describe what you want to build: - **Role**: Master coordinator for multi-agent workflows - **Claude Thinking**: `think hard` for workflow optimization & agent coordination - **New Features**: Intelligent workflow selection, multi-agent orchestration -- **Outputs**: Optimized workflow plans, coordinated agent execution +- **Outputs**: Route decision JSON (schema‑validated), optimized workflow plans, coordinated agent execution - **Quality Gates**: Cross-agent consistency and workflow validation ## 🔄 Intelligent Workflow System @@ -208,6 +229,12 @@ User: "Create a task management web application for small teams with real-time c - **Resource Management**: Intelligent allocation of computational resources - **Progress Monitoring**: Real-time execution tracking and optimization +### Deterministic Orchestration & Routing (New) +- **Low‑temp routing**: Orchestrator and routing temperatures set to 0.2 for repeatable decisions. +- **Route decision schema**: Orchestrator emits a JSON decision validated by `.claude/schemas/route_decision.schema.json` and persists it to `.claude/context/session.json`. +- **Selective rules loading**: Loads only 1–3 stack‑relevant rules from `.claude/rules/manifest.yaml` to maximize focus. +- **Per‑agent temperature policy**: Creative agents (UX/Developer) run at moderate temps (≈0.5–0.6); analysis/QA lower (≈0.3–0.4). + ### 3. Intelligent Templates - Adaptive Generation - **Conditional Logic**: Templates adapt based on project complexity - **Validation Rules**: Automatic quality checking of generated content @@ -222,6 +249,10 @@ User: "Create a task management web application for small teams with real-time c - **Escalation Procedures**: Clear authority chains for unresolved conflicts - **Decision Documentation**: Complete audit trail of all quality decisions +### Executable Workflows (New) +- Each step declares explicit `inputs`, JSON‑first `creates`, `validators` (schema/checklist), `on_fail`, and a `render` block. +- Gates enforce a small, repeatable loop per step: validate(schema) → auto‑fix (1 try) → escalate → render. + ### 5. Parallel Execution Engine - Performance Optimization - **Dependency Graph Analysis**: Identifies parallelization opportunities - **Resource Management**: Intelligent CPU and memory allocation @@ -246,22 +277,13 @@ User: "Create a task management web application for small teams with real-time c ## 📊 Performance Benchmarks ### Execution Performance -- **Simple Projects (1-3 complexity)**: 40% faster due to parallel execution -- **Medium Projects (4-6 complexity)**: 35% faster due to intelligent routing -- **Complex Projects (7-8 complexity)**: 25% faster due to optimization and caching -- **Enterprise Projects (9-10 complexity)**: 20% faster due to specialized workflows +- Benchmarks vary by environment; use the gate + schema validation to measure your own pass rates and timings locally. -### Quality Improvements -- **Output Consistency**: 85% improvement in cross-agent consistency -- **Validation Coverage**: 100% of outputs validated vs 0% previously -- **Error Rate Reduction**: 90% reduction in workflow failures -- **User Satisfaction**: 90%+ users satisfied with output quality +### Quality Improvements +- JSON‑first artifacts and gate checks improve output consistency and validation coverage across workflows. -### Reliability Metrics -- **Workflow Success Rate**: 99.5% (up from ~75%) -- **Error Recovery Rate**: 95% of errors automatically recovered -- **Quality Gate Pass Rate**: 100% of outputs meet minimum thresholds -- **Context Consistency**: 100% context integrity maintained +### Reliability Practices +- Validate → auto‑fix → escalate gates at each step; route decisions logged to session context for traceability. ## 🎯 Enterprise Use Cases @@ -514,4 +536,4 @@ Transform your development process with: **Just activate Claude Code and describe what you want to build.** The Enterprise Edition will handle the rest, delivering professional-quality software development solutions through intelligent AI agent collaboration. -*🏆 Powered by BMAD™ Enterprise - Bringing Production-Grade Multi-Agent Development to Claude Code* \ No newline at end of file +*🏆 Powered by BMAD™ Enterprise - Bringing Production-Grade Multi-Agent Development to Claude Code*