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

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,