# ============================================================= # Project Context — AI-First Spec-Driven Development # ============================================================= # This is the SINGLE SOURCE OF TRUTH for project-specific # paths, tools, and routing used by all workflows. # # Workflows reference this file for WHERE to find things. # Workflow steps define WHAT to do (universal best practices). # ============================================================= # # HOW AI AGENTS USE THIS FILE: # 1. Open this file at the start of any workflow # 2. Parse the YAML structure # 3. When a workflow says "→ key.subkey", look up that key # and use the resolved value as the actual path # 4. All paths are RELATIVE to workspace root # 5. For "{domain}", substitute the feature's domain (PRD: row `Domain` in Metadata / folder path; .feature: @trace.domain) # ============================================================= project: name: "{{PROJECT_NAME}}" description: "{{PROJECT_DESCRIPTION}}" # ----- File Paths ----- # All paths are relative to workspace root. paths: # Feature-Package Layout: # specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md — PRD document # specs/{domain}/{prd-slug}/bdd/ — BDD .feature files # specs/{domain}/{prd-slug}/tech-docs/ — Technical design docs # specs/{domain}/{prd-slug}/design-spec/ — Design specs (FE/App only) # .trace/{domain}/{prd-slug}/{UC-ID}.tsv — Trace state # # specs_dir is the unified root for all spec artifact types (PRD, BDD, tech-docs, design-spec). # prd-slug is derived from the PRD folder path — not a separate config variable. specs_dir: "specs" templates_dir: "specs/templates" feature_template: ".agent/templates/feature.template" # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}}) bdd_writing_guide: "specs/templates/bdd-writing-guide.md" trace_report: "specs/.trace/trace-report.md" # PRD template (PRDs are at specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md) prd_template: "specs/templates/prd.template.md" refinement_dir: ".agent/review" # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs: # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md). # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature / # design-spec) are NOT here — they come from the PO spec submodule (spec_source). qc_dir: "docs" # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g. # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path). qc_skills_dir: ".agent/skills/qc" # Product Definitions product_definitions_dir: "specs/product-definition" product_definition_template: "specs/templates/product-definition.template.md" # Domain Knowledge domain_knowledge_dir: "specs/domain-knowledge" business_dictionary: "specs/domain-knowledge/business-dictionary.md" core_entities: "specs/domain-knowledge/core-entities.md" # Project Lessons (guardrails accumulated via /learn — loaded by context-loader Step 6.7) # Single-service default below. In umbrella/service mode, set this in each service's # .agent/project-context.yaml to ".agent/project-lessons.md" (resolved per service_root). lessons_file: "specs/domain-knowledge/lessons-learned.md" # Tech Docs (BE-authored API contract). # Merged into specs_dir in the feature-package layout: # tech-docs live at specs/{domain}/{prd-slug}/tech-docs/. # In umbrella mode with spec_source set, context-loader auto-routes this to # {spec_source}/specs so FE/App read the contract via the spec submodule. tech_docs_dir: "specs" # Design Specs (FE/App platforms only — web, app). # In the feature-package layout, design-specs live at specs/{domain}/{prd-slug}/design-spec/. # This variable is no longer needed as a separate path — derived from specs_dir. # design_spec_dir: "specs/design-spec" ← removed; use specs_dir instead # Trace (internal structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv) trace_dir: ".trace" # Tester / QC feedback (written by /report-bug and /propose-scenario). # These live in the SHARED spec repo so PO/Dev see them on their next /sync. # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/. bug_reports_dir: "feedback/bug-reports" bdd_proposals_dir: "feedback/bdd-proposals" # PRD change requests (new requirement found in test, not covered by any AC) — # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd. prd_change_requests_dir: "feedback/prd-change-requests" tech_stack: language: "{{LANGUAGE}}" # e.g., Java 17 / TypeScript / C# / Go framework: "{{FRAMEWORK}}" # e.g., Spring Boot 3.2 / Angular 17 / .NET 8 build_tool: "{{BUILD_TOOL}}" # e.g., Maven / npm / dotnet / go test_framework: "{{TEST_FRAMEWORK}}" # e.g., JUnit 5 + Mockito / Jest / xUnit database: "{{DATABASE}}" # e.g., PostgreSQL / MySQL / MongoDB module: "{{MODULE}}" # e.g., java-spring / angular / dotnet / golang / context-engineering conventions: build_command: "{{BUILD_COMMAND}}" # e.g., mvn clean install -DskipTests test_command: "{{TEST_COMMAND}}" # e.g., mvn test service_run: "{{RUN_COMMAND}}" # e.g., mvn spring-boot:run ticket_prefix: "{{TICKET_PREFIX}}" # e.g., PROJ / FEAT / UC domains: - "{{DOMAIN_1}}" # - "{{DOMAIN_2}}" # ----- Multi-Service / Umbrella Setup ----- # Fill this section ONLY if this is an UMBRELLA repo that contains multiple # service submodules. Leave commented out for single-service projects. # # setup: # mode: umbrella # "umbrella" | "single" (default: single) # spec_source: "{{SPEC_SUBMODULE_PATH}}" # path to PO spec submodule, e.g. "free-trial-specs" # # When spec_source is set, context-loader auto-derives (ALL specs live in the spec repo # using the feature-package layout; service submodules hold only code): # specs_dir → {spec_source}/specs # unified root — PRD/BDD/tech-docs/design-spec # tech_docs_dir → {spec_source}/specs # merged into specs_dir # domain_knowledge_dir → {spec_source}/specs/domain-knowledge # trace_dir → {spec_source}/.trace # structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv # (You can still override these manually in paths: section below.) # With spec_source set, only ONE override is needed instead of four separate dir vars. # # services: # domain → service submodule routing # {{DOMAIN_1}}: # must match the PRD's `Domain` (Metadata row) / folder path segment # path: "{{SERVICE_SUBMODULE_DIR}}" # relative path to service submodule (code + .trace/) # module: "{{STACK_MODULE}}" # e.g., java-spring, nextjs, flutter # # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo — # # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored). # # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source. # # IMPORTANT — per-service CLAUDE.md: # Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its # architecture + coding standards for ITS stack. context-loader loads CLAUDE.md in two # layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay, # wins on conflict for architecture/coding-standards). The agent sits at the umbrella # root, so without a service CLAUDE.md, code generation falls back to umbrella defaults # (likely the wrong stack). Generate one per service via /setup-ai-first inside each. # {{DOMAIN_2}}: # path: "{{SERVICE_2_DIR}}" # module: "{{STACK_MODULE}}" # specs_dir: "{{SERVICE_2_DIR}}/specs" # tech_docs_dir: "{{SERVICE_2_DIR}}/specs" # ----- Architecture ----- architecture: style: "{{ARCH_STYLE}}" # e.g., Layered / Clean / Hexagonal layers: "{{LAYER_STACK}}" # e.g., Controller → Facade → Service → Repository key_rules: - "{{ARCH_RULE_1}}" - "{{ARCH_RULE_2}}"