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.

Install Skill

SKILL.md

DevFlow File Standards

Purpose

Requirement IDs

Format

Usage

Source

Task IDs

Format

Usage in TASKS.md

Labels

Source

Directory Structure

Requirements

TECH_DESIGN.md

EPIC.md

TASKS.md

Source

orchestration_status.json

Structure (Requirements)

Status Values

Phase Values

Source

status.json (for Bugs)

Structure

Severity Values

Source

File Naming Patterns

Markdown Documents

Scripts

Directories

Source

Contract Files

Format

Example

Source

Special Files

.gitignore Patterns (for devflow/)

.claude/tsc-cache/ (PostToolUse tracking)

Source

Agent-Specific Standards (NOT in this skill)

Usage Examples

Query 1: "What's the format of REQ-ID?"

Query 2: "Where does PRD.md go?"

Query 3: "What fields are in orchestration_status.json?"

Query 4: "How do I name a contract file?"

Query 5: "What's the YAML frontmatter for TASKS.md?"

Design Principle