--- name: devflow-file-standards description: File naming conventions, directory structure, and YAML frontmatter standards for CC-DevFlow. Consolidates shared conventions from all agents. --- # DevFlow File Standards ## Purpose Consolidate file naming, directory structure, and format conventions that are shared across multiple agents and commands. This skill does NOT duplicate agent-specific standards. ## Requirement IDs ### Format ``` REQ-\d{3} # e.g., REQ-001, REQ-042, REQ-123 ``` ### Usage - **Flow commands**: All `/flow-*` commands accept REQ-ID as argument - **Git branches**: `feature/REQ-XXX-{slug-title}` - **Directory paths**: `devflow/requirements/REQ-XXX/` - **Status tracking**: `orchestration_status.json` contains `reqId` field ### Source - Enforced by: All 13 agents - Validated by: `.claude/scripts/check-prerequisites.sh` ## Task IDs ### Format ``` T\d{3} # e.g., T001, T042, T123 ``` ### Usage in TASKS.md ```markdown - [ ] **T001** [P] Task description - [ ] **T010** [US1] User story 1 task ``` ### Labels - `[P]`: Parallel execution possible - `[US#]`: User story number (e.g., [US1], [US2]) ### Source - Generated by: planner agent - Format defined in: `.claude/docs/templates/TASKS_TEMPLATE.md` ## Directory Structure ### Requirements ``` devflow/requirements/REQ-XXX/ ├── research/ # /flow-init 输出 │ ├── research.md # consolidate-research.sh 生成 │ ├── tasks.json # generate-research-tasks.sh 生成 │ ├── internal/ │ │ └── codebase-overview.md │ ├── mcp/ # MCP 服务器调查（可选） │ └── codebase-tech-analysis.md # /flow-tech 输出 ├── PRD.md # /flow-prd 输出 (prd-writer agent) ├── TECH_DESIGN.md # /flow-tech 输出 (tech-architect agent) ├── data-model.md # /flow-tech 输出 (extract-data-model.sh) ├── contracts/ # /flow-tech 输出 (export-contracts.sh) │ ├── api-users.yaml # OpenAPI contracts │ └── api-auth.yaml ├── quickstart.md # /flow-tech 输出 (generate-quickstart.sh) ├── UI_PROTOTYPE.html # /flow-ui 输出 (ui-designer agent, 可选) ├── EPIC.md # /flow-epic 输出 (planner agent) ├── TASKS.md # /flow-epic 输出 (planner agent) ├── reviews/ # /flow-qa 输出 │ ├── TEST_PLAN.md # qa-tester agent │ ├── TEST_REPORT.md # qa-tester agent │ └── SECURITY_REPORT.md # security-reviewer agent ├── EXECUTION_LOG.md # 事件日志 (所有 flow 命令追加) ├── orchestration_status.json # 状态跟踪 (所有 flow 命令更新) └── README.md # 工作流指南 ### Bugs ``` devflow/bugs/BUG-XXX/ ├── BUG_ANALYSIS.md # /flow-fix 输出 (bug-analyzer agent) ├── PLAN.md # /flow-fix 输出 (planner agent) ├── TASKS.md # /flow-fix 输出 (planner agent) ├── EXECUTION_LOG.md └── status.json # 类似 orchestration_status.json ``` ### Source - Created by: `.claude/scripts/create-requirement.sh` - Template: `.claude/docs/templates/` 目录 - Enforced by: All flow commands ## YAML Frontmatter ### Document Types #### PRD.md ```yaml --- reqId: REQ-123 title: User Authentication version: 1.0.0 createdAt: 2025-10-31T12:34:56Z updatedAt: 2025-10-31T15:20:30Z status: approved author: prd-writer agent --- ``` #### TECH_DESIGN.md ```yaml --- reqId: REQ-123 version: 1.0.0 architecture: Microservices techStack: - Node.js - PostgreSQL - Redis createdAt: 2025-10-31T14:10:00Z author: tech-architect agent --- ``` #### EPIC.md ```yaml --- reqId: REQ-123 title: User Authentication Epic version: 1.0.0 estimatedEffort: 5 days createdAt: 2025-10-31T16:00:00Z author: planner agent --- ``` #### TASKS.md ```yaml --- reqId: REQ-123 totalTasks: 25 completedTasks: 0 version: 1.0.0 createdAt: 2025-10-31T16:30:00Z updatedAt: 2025-10-31T16:30:00Z author: planner agent --- ``` ### Source - Enforced by: prd-writer, tech-architect, planner agents - Parsed by: `.claude/scripts/check-prerequisites.sh`, `.claude/scripts/generate-status-report.sh` ## orchestration_status.json ### Structure (Requirements) ```json { "reqId": "REQ-123", "title": "User Authentication", "status": "initialized", "phase": "planning", "phase0_complete": false, "phase1_complete": false, "completedSteps": [], "createdAt": "2025-10-31T12:34:56Z", "updatedAt": "2025-10-31T12:34:56Z" } ``` ### Status Values ``` initialized → /flow-init 完成 prd_generation_in_progress → /flow-prd 执行中 prd_generation_failed → /flow-prd 失败（可重试） prd_complete → /flow-prd 完成 tech_design_in_progress → /flow-tech 执行中 tech_design_failed → /flow-tech 失败 tech_design_complete → /flow-tech 完成 epic_generation_in_progress → /flow-epic 执行中 epic_generation_failed → /flow-epic 失败 epic_complete → /flow-epic 完成 development_in_progress → /flow-dev 执行中 development_complete → /flow-dev 完成 qa_in_progress → /flow-qa 执行中 qa_complete → /flow-qa 完成 released → /flow-release 完成 ``` ### Phase Values ``` planning → 需求规划阶段 (init, prd) design → 技术设计阶段 (tech, ui) epic_planning → 任务规划阶段 (epic) implementation → 开发阶段 (dev) qa → 质量保障阶段 (qa) release → 发布阶段 (release) ``` ### Source - Updated by: All flow commands - Read by: cc-devflow-orchestrator skill, check-prerequisites.sh - Schema: Implicitly defined across all flow command docs ## status.json (for Bugs) ### Structure ```json { "bugId": "BUG-456", "title": "Fix login timeout", "status": "initialized", "phase": "analysis", "severity": "high", "createdAt": "2025-10-31T12:34:56Z", "updatedAt": "2025-10-31T12:34:56Z" } ``` ### Severity Values ``` critical → 严重，系统不可用 high → 高，核心功能受影响 medium → 中，部分功能受影响 low → 低，轻微问题 ``` ### Source - Used by: `/flow-fix` command - Updated by: bug-analyzer agent ## File Naming Patterns ### Markdown Documents ``` UPPERCASE_WITH_UNDERSCORES.md # Primary documents (PRD.md, EPIC.md, TASKS.md) lowercase-with-dashes.md # Supporting documents (data-model.md, quickstart.md) ``` ### Scripts ``` kebab-case.sh # All bash scripts (check-prerequisites.sh) kebab-case.ts # All TypeScript scripts (skill-activation-prompt.ts) ``` ### Directories ``` lowercase # Top-level (devflow/, research/, contracts/) kebab-case # Multi-word (codebase-tech-analysis/) ``` ### Source - Implicitly enforced by: All agents and scripts - No explicit validator ## Contract Files ### Format ``` api-{resource}.yaml # OpenAPI 3.0 format graphql-{schema}.graphql # GraphQL schema ``` ### Example ``` contracts/ ├── api-users.yaml # User management API ├── api-auth.yaml # Authentication API └── graphql-schema.graphql # GraphQL schema (if used) ``` ### Source - Generated by: tech-architect agent via `export-contracts.sh` - Referenced by: planner agent in TASKS.md (Phase 2 contract tests) ## Special Files ### .gitignore Patterns (for devflow/) ``` # ✅ Should be committed devflow/requirements/**/PRD.md devflow/requirements/**/EPIC.md devflow/requirements/**/TASKS.md devflow/requirements/**/orchestration_status.json # ❌ Should NOT be committed devflow/requirements/**/.env devflow/requirements/**/secrets/ devflow/requirements/**/node_modules/ ``` ### .claude/tsc-cache/ (PostToolUse tracking) ``` .claude/tsc-cache/ └── {session_id}/ ├── edited-files.log # Timestamp:path:repo └── affected-repos.txt # List of affected repos (e.g., devflow/REQ-123) ``` ### Source - Generated by: PostToolUse hook (post-tool-use-tracker.sh) - Read by: check-prerequisites.sh (for REQ_ID inference) ## Agent-Specific Standards (NOT in this skill) This skill does NOT contain agent-specific content standards: - **prd-writer**: INVEST principles, Anti-Expansion mandate, Given-When-Then → See prd-writer agent - **tech-architect**: Architecture patterns, tech stack justification, Phase -1 Gates → See tech-architect agent - **ui-designer**: 80+ design masters, responsive design rules, NO PLACEHOLDER → See ui-designer agent - **planner**: Task breakdown methodology, TDD sequence, Phase -1 Gates enforcement → See planner agent - **qa-tester**: Test strategy, coverage requirements, performance benchmarks → See qa-tester agent **Rationale**: Those are agent execution standards (how to generate content), not file format standards (how to name/structure files). ## Usage Examples ### Query 1: "What's the format of REQ-ID?" **Answer**: `REQ-\d{3}` (e.g., REQ-001, REQ-042, REQ-123) ### Query 2: "Where does PRD.md go?" **Answer**: `devflow/requirements/REQ-XXX/PRD.md` ### Query 3: "What fields are in orchestration_status.json?" **Answer**: reqId, title, status, phase, phase0_complete, phase1_complete, completedSteps, createdAt, updatedAt ### Query 4: "How do I name a contract file?" **Answer**: `api-{resource}.yaml` (e.g., api-users.yaml, api-auth.yaml) ### Query 5: "What's the YAML frontmatter for TASKS.md?" **Answer**: reqId, totalTasks, completedTasks, version, createdAt, updatedAt, author ## Design Principle **This skill does NOT contain**: - ❌ Agent execution standards (PRD content rules, tech design methodology, etc.) - ❌ Detailed Phase Gate logic (that's in flow command files) - ❌ Complete template contents (that's in `.claude/docs/templates/`) **This skill ONLY contains**: - ✅ File naming conventions (shared across all agents) - ✅ Directory structure (created by scripts, used by all agents) - ✅ YAML frontmatter format (enforced by multiple agents) - ✅ orchestration_status.json schema (updated by all flow commands) - ✅ Cross-cutting file format standards **Rationale**: Avoid duplication ("不重不漏" principle). Agents own content standards, this skill owns format standards.