doc-flow (Orchestrator) Purpose
This skill serves as the orchestrator for the AI-Driven Specification-Driven Development (SDD) workflow. It provides:
Skill Selection Guidance: Helps determine which artifact-specific skill to use Workflow Overview: Complete 15-layer SDD architecture General SDD Principles: Specification-driven methodology fundamentals Integration Guidance: How skills work together
For Artifact Creation: Use the specific artifact skill (doc-brd, doc-prd, doc-ears, doc-bdd, doc-adr, doc-sys, doc-req, doc-impl, doc-ctr, doc-spec, doc-tasks, doc-ref, doc-naming).
Authoritative Reference: ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
Prerequisites
⚠️ For New Projects (Greenfield): If starting a brand new project with no existing folder structure, use the project-init skill FIRST to initialize project structure, select domain, create folders, and configure setup. Then return here to begin workflow execution.
For Existing Projects: If project is already initialized (docs/ folders exist, domain configured), proceed directly with this skill.
Skill Selection Decision Tree "Which Skill Do I Need?"
Answer these questions to find the right skill:
Q1: What stage are you at in the workflow?
Starting new project with business requirements → Use doc-brd skill Have BRD, need product requirements → Use doc-prd skill Have PRD, need formal requirements → Use doc-ears skill Have EARS, need test scenarios → Use doc-bdd skill Have BDD, need architecture decisions → Use doc-adr skill Have ADR, need system requirements → Use doc-sys skill Have SYS, need atomic requirements → Use doc-req skill Have REQ, need implementation planning → Use doc-impl skill (if complex) or skip to doc-spec Have REQ/IMPL, need API contracts → Use doc-ctr skill (if interface requirement) Have REQ/CTR, need technical specifications → Use doc-spec skill Have SPEC, need task breakdown → Use doc-tasks skill Have TASKS, need implementation contracts → Add Section 8 to TASKS (see doc-tasks skill) Have TASKS, ready to code → Implement code per TASKS Need supplementary documentation (overview, glossary, guides) → Use doc-ref skill
Q2: What are you trying to do?
Define business needs and objectives → doc-brd Define product features and KPIs → doc-prd Write formal WHEN-THE-SHALL-WITHIN requirements → doc-ears Create Gherkin test scenarios → doc-bdd Document architecture decisions → doc-adr Define system requirements → doc-sys Define atomic requirements → doc-req Plan project implementation (WHO/WHEN/WHAT) → doc-impl Define API contracts → doc-ctr Write technical specifications → doc-spec Break down into AI tasks → doc-tasks Define implementation contracts for parallel dev → Add Section 8 to TASKS (see doc-tasks skill) Create supplementary documentation (project overview, glossary, guides) → doc-ref General guidance or unsure → Stay with doc-flow (this skill) Complete SDD Workflow (15 Layers)
Authoritative Reference: ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
Workflow Sequence Strategy (Layer 0) ↓ BRD (Layer 1) → doc-brd skill ↓ PRD (Layer 2) → doc-prd skill ↓ EARS (Layer 3) → doc-ears skill ↓ BDD (Layer 4) → doc-bdd skill ↓ ADR (Layer 5) → doc-adr skill ↓ SYS (Layer 6) → doc-sys skill ↓ REQ (Layer 7) → doc-req skill ↓ IMPL (Layer 8) [OPTIONAL] → doc-impl skill ↓ CTR (Layer 9) [OPTIONAL - IF INTERFACE] → doc-ctr skill ↓ SPEC (Layer 10) → doc-spec skill ↓ TASKS (Layer 11) → doc-tasks skill ↓ Code (Layer 12) ↓ Tests (Layer 13) ↓ Validation (Layer 14)
Layer Descriptions Layer Artifact Purpose Skill 0 Strategy Business owner documents External (strategy/) 1 BRD Business requirements doc-brd 2 PRD Product requirements doc-prd 3 EARS Formal requirements (WHEN-THE-SHALL) doc-ears 4 BDD Gherkin test scenarios doc-bdd 5 ADR Architecture decisions doc-adr 6 SYS System requirements doc-sys 7 REQ Atomic requirements doc-req 8 IMPL Implementation plans (WHO/WHEN) [OPTIONAL] doc-impl 9 CTR API contracts [OPTIONAL - IF INTERFACE] doc-ctr 10 SPEC Technical specifications (HOW) doc-spec 11 TASKS Task breakdown for implementation doc-tasks 11+ ICON Implementation Contracts (Section 8 of TASKS) doc-tasks 12 Code Python implementation Implementation 13 Tests Test suites Implementation 14 Validation BDD + contract + traceability Validation Optional Layers Decision Logic
When to Create IMPL (Layer 8):
Create IMPL When: Duration ≥2 weeks, teams ≥3, components ≥5, critical budget/timeline, external dependencies Skip IMPL When: Single component, duration <2 weeks, single developer, low risk Reference: ai_dev_flow/WHEN_TO_CREATE_IMPL.md
When to Create CTR (Layer 9):
Create CTR When: Public APIs, event schemas, data models, version compatibility requirements, interface between components Skip CTR When: Internal logic only, no external interface, no serialization Reference: ai_dev_flow/WHEN_TO_CREATE_IMPL.md#when-to-create-ctr-after-impl General SDD Principles 1. Specification-Driven Development Philosophy
Core Principle: Formalize before implementing
Traditional Approach: Code first, document later (or never) SDD Approach: Document first, generate code from specifications
Why SDD Works:
Clarity: Requirements are explicit before coding begins Traceability: Every line of code traces to business requirements Validation: Tests defined before implementation Consistency: Templates ensure uniform structure Speed: Code generation from YAML specifications (48x faster) 2. Information Flow Hierarchy
Changes flow DOWN (never UP):
strategy/ (WHAT - Product Owner Voice) ├── Strategy business logic └── Performance targets ↓ ↓ Referenced by ↓ 📚 docs/ (WHY + HOW - Project Documentation) ├── Requirements (WHY) ├── Architecture (HOW) └── Specifications (IMPLEMENTATION) ↓ ↓ Generates ↓ 💻 Source Code (Python/Infrastructure)
📝 ai_dev_flow/ feeds into 📚 docs/ for consistency
Golden Rules:
Strategy → Documentation → Code (one-way flow) Code cannot change strategy Always use templates from ai_dev_flow/ when creating docs in docs/ All business logic must reference strategy/ sections 3. Directory Structure and Roles
Critical Context: This project has three key directories with distinct roles:
strategy/ - WHAT (Product Owner Voice)
Primary Authority: Authoritative business strategy and domain logic
core_algorithm.md - Primary algorithm specifications strategy_overview.md - Strategic framework and operating modes risk_management.md - Risk management policies business_rules.md - Domain-specific business rules selection_criteria/ - Entry criteria and scoring algorithms Performance targets, state machines, resource budgets
Golden Rule: All business logic must trace back to these strategy documents.
📚 docs/ - PROJECT DOCUMENTATION
Implementation Documentation: Requirements, architecture, specifications
docs/BRD/ - Business Requirements Documents Nested folder structure: docs/BRD/BRD-NN/BRD-NN.S_slug.md docs/PRD/ - Product Requirements Documents Nested folder structure: docs/PRD/PRD-NN/PRD-NN.S_slug.md docs/ADR/ - Architecture Decision Records (HOW) Nested folder structure: docs/ADR/ADR-NN/ADR-NN.S_slug.md docs/BDD/ - BDD acceptance tests (Behavior-Driven Development) docs/CTR/ - API Contracts (dual-file format: .md + .yaml) docs/IMPL/ - Implementation Plans (Project Management: WHO/WHEN) docs/SPEC/ - YAML technical specifications docs/TASKS/ - Code Generation Plans (AI-structured implementation tasks)
Note: BRD, PRD, ADR use section-based nested folders by default. Other types use flat structure.
Purpose: Document how strategy is implemented through architecture and code.
📝 ai_dev_flow/ - AUTHORITATIVE DEVELOPMENT STANDARD
Development Standard and Templates: The single source of truth for SDD workflow
Status: Authoritative development standard for this project Contents: Complete SDD workflow (BRD → PRD → EARS → BDD → ADR → SYS → REQ → IMPL → CTR → SPEC → TASKS → Code) Templates: {TYPE}-TEMPLATE.{ext} for each artifact type (BRD, PRD, EARS, BDD, ADR, SYS, REQ, IMPL, CTR, SPEC, TASKS, REF) Indices: {TYPE}-00_index.{ext} listing all documents of each type READMEs: Detailed usage guides and best practices for each artifact type Standards: ID naming, traceability format, cross-referencing rules Examples: Reference implementations with full traceability chains
Purpose: Define the complete development methodology with templates, standards, and examples for creating all artifacts.
⚠️ CRITICAL: Archived Documents Restriction
STRICTLY PROHIBITED: DO NOT access, reference, link to, or use ANY files or directories containing the word "archived" in their path.
Automatic Filtering Rules:
❌ Skip any path containing archived, Archived, ARCHIVED, or archive ❌ Ignore files in directories with "archived" in the name ❌ Do not read, suggest, or reference archived content ❌ Do not use archived documents even if they appear in search results
Active Documentation Only:
strategy/ (current strategy - excludes archived subdirs) docs/ (active project documentation) ai_dev_flow/ (authoritative templates and standards)
If archived content is needed:
Stop immediately Inform user that content is in archived location Request explicit permission before proceeding 4. Traceability Importance
Complete Audit Trail: Every artifact must trace back to original business requirements
Benefits:
Impact Analysis: Know what breaks when requirements change Regulatory Compliance: Industry-specific audit requirements (ISO, SOC2, etc.) Change Management: Track all changes through artifact chain Coverage Metrics: Measure implementation completeness Quality Assurance: Automated validation prevents gaps
Implementation:
Cumulative tagging hierarchy (see SHARED_CONTENT.md) Traceability section in every document Bidirectional traceability matrices Automated validation scripts 5. Upstream Artifact Policy (CRITICAL)
⚠️ MANDATORY RULE: Do NOT create missing upstream artifacts. Skip functionality instead.
Policy Statement: If a required upstream artifact is missing, the downstream functionality MUST NOT be implemented. This enforces the SDD document hierarchy where every implementation must have proper business/product justification through the complete artifact chain.
Decision Rules:
Situation Action Upstream exists Reference with exact document ID Upstream required but missing Skip that functionality - do NOT implement Upstream optional and missing Use null in traceability tag Upstream not applicable Omit tag entirely
Rationale:
Prevents orphaned code: No implementation without business justification Enforces governance: Changes must flow through proper channels Maintains audit trail: Every feature traces to business need Reduces technical debt: No undocumented "nice-to-have" features
When Upstream is Missing:
Stop - Do not proceed with implementation Report - Inform user which upstream artifact is missing Advise - Recommend creating upstream artifacts first through proper channels Skip - Move on to functionality that has complete upstream chain
Reference: ai_dev_flow/TRACEABILITY.md - Section "Step 3: Decision Rules"
Integration with Other Skills Core Workflow Skills
project-init - Initialize new project structure
Use BEFORE doc-flow for greenfield projects Creates folder structure, domain setup, baseline files Reference: .claude/skills/project-init/SKILL.md
trace-check - Validate traceability after artifact creation
Use AFTER doc-flow to verify bidirectional links Validates cumulative tagging, ID formats, link resolution Detects orphaned artifacts and traceability gaps Reference: .claude/skills/trace-check/SKILL.md
doc-naming - Unified ID naming standards enforcement
Use for ID format validation across all artifact types Validates 4-segment element IDs (TYPE.NN.TT.SS) Enforces variable-length DOC_NUM (2+ digits) Reference: .claude/skills/doc-naming/SKILL.md
doc-validator - Cross-document validation orchestrator
Validates traceability across all layers Detects gaps, broken links, and format violations Runs auto-fix actions for common issues Reference: .claude/skills/doc-validator/SKILL.md Planning & Architecture
adr-roadmap - Generate implementation roadmaps from ADRs
Use AFTER creating ADR artifacts Creates timeline, risk assessment, dependency mapping Reference: .claude/skills/adr-roadmap/SKILL.md
project-mngt - MVP/MMP/MMR planning
Use for strategic release planning Integrates with IMPL artifacts Reference: .claude/skills/project-mngt/SKILL.md Typical Workflow Integration 1. project-init → Initialize project (greenfield only) 2. doc-brd → Create BRD 3. doc-prd → Create PRD 4. doc-ears → Create EARS 5. doc-bdd → Create BDD 6. doc-adr → Create ADR 7. doc-sys → Create SYS 8. doc-req → Create REQ 9. doc-impl → Create IMPL (if complex) 10. doc-ctr → Create CTR (if interface) 11. doc-spec → Create SPEC 12. doc-tasks → Create TASKS 13. Implementation → Execute based on TASKS 14. trace-check → Validate traceability
Shared Standards
CRITICAL: All artifact-specific skills share common standards defined in:
.claude/skills/doc-flow/SHARED_CONTENT.md
This document contains:
Document ID Naming Standards Traceability Section Format Cumulative Tagging Hierarchy Quality Gates & Validation Traceability Matrix Enforcement Documentation Standards Document Control Section Requirements
All artifact skills (doc-brd through doc-tasks, plus doc-ref, doc-naming) import these shared standards.
Diagram Standards (Global Requirement)
All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited.
Authority Document: ai_dev_flow/DIAGRAM_STANDARDS.md Syntax Generation: mermaid-gen skill File Management: charts-flow skill (SVG conversion, embedding)
Allowed Exception: Directory tree structures (using ├── └── │) are permitted as they represent file structure, not diagrams.
Validation Overview Automated Validation Tools
Quality Gates Validation:
Validate artifact meets layer transition requirements (≥90%)
./scripts/validate_quality_gates.sh docs/REQ/risk/lim/REQ-03.md
Artifact-specific validation
./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01.md ./ai_dev_flow/scripts/validate_req_template.sh docs/REQ/api/ib/REQ-02.md
Link integrity validation
./ai_dev_flow/scripts/validate_links.py --path docs/ --check-anchors
Tag-Based Traceability Validation:
Complete workflow (extract → validate → generate)
python ai_dev_flow/scripts/generate_traceability_matrices.py --auto
Individual steps
python ai_dev_flow/scripts/extract_tags.py --source src/ docs/ tests/ python ai_dev_flow/scripts/validate_tags_against_docs.py --strict python ai_dev_flow/scripts/generate_traceability_matrices.py --output docs/generated/matrices/
Cross-Document Validation (MANDATORY)
CRITICAL: After creating each artifact, execute cross-document validation before proceeding to the next layer.
Validation Phases Phase Trigger Command Phase 1 Per-document python scripts/validate_cross_document.py --document {doc_path} --auto-fix Phase 2 Per-layer complete python scripts/validate_cross_document.py --layer {LAYER} --auto-fix Phase 3 Final (all layers) python scripts/validate_cross_document.py --full --auto-fix Automatic Validation Loop LOOP: 1. Run: python scripts/validate_cross_document.py --document {doc_path} --auto-fix 2. IF errors fixed: GOTO LOOP (re-validate) 3. IF warnings fixed: GOTO LOOP (re-validate) 4. IF unfixable issues: Log for manual review, continue 5. IF clean: Mark VALIDATED, proceed to next layer
Layer-Specific Upstream Requirements Layer Artifact Required Upstream Tags Tag Count 1 BRD (none - root) 0 2 PRD @brd 1 3 EARS @brd, @prd 2 4 BDD @brd, @prd, @ears 3 5 ADR @brd, @prd, @ears, @bdd 4 6 SYS @brd, @prd, @ears, @bdd, @adr 5 7 REQ @brd, @prd, @ears, @bdd, @adr, @sys 6 8 IMPL @brd, @prd, @ears, @bdd, @adr, @sys, @req 7 9 CTR @brd through @req (+ optional @impl) 7-8 10 SPEC @brd through @req (+ optional @impl, @ctr) 7-9 11 TASKS @brd through @spec (+ optional @impl, @ctr) 8-10 Auto-Fix Actions (No Confirmation Required) Issue Fix Action Missing cumulative tag Add with upstream document reference Invalid tag format Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format Broken link Recalculate path from current location Missing traceability section Insert from template Validation Codes Reference Code Description Severity XDOC-001 Referenced requirement ID not found ERROR XDOC-002 Missing cumulative tag ERROR XDOC-003 Upstream document not found ERROR XDOC-004 Link target file missing WARNING XDOC-005 Anchor in link not found WARNING XDOC-006 Tag format invalid ERROR XDOC-007 Gap in cumulative tag chain ERROR XDOC-008 Circular reference detected ERROR XDOC-009 Missing traceability section ERROR XDOC-010 Orphaned document (no upstream refs) WARNING Quality Gate
Blocking: YES - Cannot proceed to next layer until Phase 1 validation passes with 0 errors for the current artifact.
Related Resources Core Standards (ai_dev_flow/)
Primary References - Authoritative Development Standard:
Main Guide: SPEC_DRIVEN_DEVELOPMENT_GUIDE.md - Complete 15-layer workflow Workflow Diagram: index.md - Complete Mermaid diagram ID Standards: ID_NAMING_STANDARDS.md - File naming, ID format rules Traceability: TRACEABILITY.md - Cross-reference format, link standards Quality Gates: TRACEABILITY_VALIDATION.md - Automated quality gates system Platform BRD Guide: PLATFORM_VS_FEATURE_BRD.md - Platform vs Feature BRD decision guide When to Create IMPL: WHEN_TO_CREATE_IMPL.md - IMPL vs direct REQ→SPEC decision guide README: README.md - Getting started guide Templates Location
All templates located in ai_dev_flow/{artifact_type}/:
BRD (BRD/): 3 templates available (comprehensive, simplified, domain-specific) PRD (PRD/): PRD-TEMPLATE.md EARS (EARS/): EARS-TEMPLATE.md BDD (BDD/): BDD-TEMPLATE.feature ADR (ADR/): ADR-TEMPLATE.md, Technology Stack reference (ADR-000) SYS (SYS/): SYS-TEMPLATE.md REQ (REQ/): REQ-TEMPLATE.md (v3.0 with 12 sections) IMPL (IMPL/): IMPL-TEMPLATE.md CTR (CTR/): CTR-TEMPLATE.md + CTR-TEMPLATE.yaml (dual-file) SPEC (10_SPEC/): SPEC-TEMPLATE.yaml TASKS (TASKS/): TASKS-TEMPLATE.md (includes Section 8 for Implementation Contracts) REF (root): REF-TEMPLATE.md (Reference Documents)
Each artifact type directory also contains:
Index file: {TYPE}-00_index.{ext} README.md: Usage guide and best practices Creation Rules: {TYPE}_CREATION_RULES.md Validation Rules: {TYPE}_VALIDATION_RULES.md Quick Reference Card Decision Matrix You Have You Need Use This Skill Nothing Business requirements doc-brd BRD Product requirements doc-prd PRD Formal requirements doc-ears EARS Test scenarios doc-bdd BDD Architecture decisions doc-adr ADR System requirements doc-sys SYS Atomic requirements doc-req REQ (complex) Implementation plan doc-impl REQ (simple) Technical specs doc-spec REQ/IMPL (interface) API contracts doc-ctr REQ/CTR Technical specs doc-spec SPEC Task breakdown doc-tasks TASKS Code Implement! Any stage Supplementary documentation doc-ref Development ROI Traditional: 70 hours/component SDD: 1.5 hours/component Speed increase: 48x faster Consistency: 100% (template-based) Traceability: Automatic, bidirectional Usage Example
User: "I need to implement position risk limit validation"
Assistant: "I'll guide you through the SDD workflow. Let me check what artifacts you have:
Current Status Check:
Do you have a BRD documenting business requirements? [If no → SKIP this functionality] Do you have a PRD with product requirements? [If no → SKIP this functionality] Do you have EARS formal requirements? [If no → SKIP this functionality] Do you have BDD test scenarios? [If no → SKIP this functionality] Do you have ADR architecture decisions? [If no → SKIP this functionality] Do you have SYS system requirements? [If no → SKIP this functionality] Do you have REQ atomic requirements? [If no → SKIP this functionality]
⚠️ CRITICAL: Upstream Artifact Policy: If ANY required upstream artifact is missing, do NOT create it and do NOT implement the downstream functionality. The SDD workflow enforces strict document hierarchy - functionality without proper business/product justification should not exist.
Next Steps: Based on your current progress, I'll recommend the appropriate skill to use next. Each skill will guide you through creating that specific artifact type with proper templates, traceability, and validation."
For detailed artifact creation guidance, use the specific artifact skill (doc-brd, doc-prd, doc-ears, doc-bdd, doc-adr, doc-sys, doc-req, doc-impl, doc-ctr, doc-spec, doc-tasks, doc-ref, doc-naming).
Version History Version Date Changes 1.3 2026-01-17 Updated to 15-layer architecture (Layers 0-14) 1.2 2025-12-29 Fixed workflow sequence; Added doc-naming and doc-validator to Integration section 1.1 2025-11-30 Added REF documents, ICON section 1.0 2025-11-01 Initial skill creation