devflow-file-standards

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

- [ ] **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

---
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

---
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

---
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)

{
  "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

{
  "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.