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