Devflow File Standards

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.