cc-devflow 1.0.1

package/.claude/skills/devflow-file-standards/SKILL.md

@@ -0,0 +1,353 @@
+---
+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
+```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.

package/.claude/skills/devflow-tdd-enforcer/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: devflow-tdd-enforcer
+description: Enforces TDD order in TASKS.md - Tests MUST be marked complete before Implementation tasks. Blocks violations in real-time.
+---
+
+# DevFlow TDD Enforcer
+
+## Purpose
+Enforce Test-First Development (TDD) order by preventing users from marking implementation tasks complete before their corresponding test tasks.
+
+**Trigger**: PreToolUse hook when editing `devflow/requirements/**/TASKS.md`
+
+## Enforcement Rule
+
+**Source**: Extracted from planner agent's TDD mandate + Constitution Article VI
+
+### ❌ BLOCKED Pattern (Violation)
+```markdown
+- [x] **T010** [US1] Implement user registration endpoint
+- [ ] **T011** [US1] Test user registration with valid data
+```
+**Problem**: Implementation marked done BEFORE test
+
+**Regex Pattern**: `\[x\].*Implementation.*\n.*\[ \].*Test`
+
+### ✅ CORRECT Pattern (TDD Sequence)
+```markdown
+- [ ] **T010** [US1] Test user registration with valid data (write FAILING test)
+- [ ] **T011** [US1] Implement user registration endpoint (make test PASS)
+```
+
+**Or after completion**:
+```markdown
+- [x] **T010** [US1] Test user registration with valid data
+- [x] **T011** [US1] Implement user registration endpoint
+```
+
+## Blocking Message
+
+When violation detected, PreToolUse hook returns **exit code 2** (blocks file save):
+
+```
+⚠️ BLOCKED - TDD Violation Detected
+
+📋 REQUIRED ACTION:
+1. Re-order TASKS.md to follow TDD sequence
+2. Mark test tasks [x] BEFORE implementation tasks
+3. Review Constitution Article VI - Test-First Development
+
+Reason: CC-DevFlow enforces TDD (Tests First → Implementation)
+Source: planner agent mandate + Constitution Article VI
+File: {file_path}
+
+Current Issue:
+  Line {N}: Implementation task marked complete
+  Line {N+1}: Test task NOT marked complete
+
+💡 SKIP: Add `@skip-tdd-check` comment or set SKIP_TDD_ENFORCER=1
+```
+
+## Constitutional Basis
+
+### Article VI: Test-First Development
+```yaml
+TDD MANDATE:
+  - Write test FIRST (must fail)
+  - Implement code SECOND (make test pass)
+  - No implementation without corresponding test
+  - Test coverage ≥80%
+```
+
+### planner agent enforces
+- Generates TASKS.md with correct TDD order
+- Phase 2: All tests listed first
+- Phase 3+: Each user story has Test task before Implementation task
+- Inserts "⚠️ TEST VERIFICATION CHECKPOINT" between Phase 2 and Phase 3
+
+### devflow-tdd-enforcer guardrail prevents
+- Users from manually reversing that order
+- Implementation tasks marked complete before test tasks
+- Real-time detection during file editing
+
+## Additional Violation Patterns
+
+### Pattern 2: Phase 3+ User Story TDD Order
+```markdown
+# ❌ BLOCKED
+- [x] **T020** [US2] Implement login endpoint
+- [ ] **T021** [US2] Test login with valid credentials
+
+# ✅ CORRECT
+- [x] **T020** [US2] Test login with valid credentials
+- [x] **T021** **T021** [US2] Implement login endpoint
+```
+
+**Regex Pattern**: `\[x\].*\[US\d+\].*Implement.*\n.*\[ \].*\[US\d+\].*Test`
+
+### Pattern 3: Implementation without Test
+```markdown
+# ❌ BLOCKED (if no corresponding test found)
+- [ ] **T030** [US3] Implement password reset endpoint
+# (No T029 or T031 test task found)
+
+# ✅ CORRECT
+- [ ] **T029** [US3] Test password reset with valid email
+- [ ] **T030** [US3] Implement password reset endpoint
+```
+
+## Skip Conditions
+
+Users can bypass TDD enforcer in specific scenarios:
+
+### 1. Session Skip (One-time per session)
+- **Mechanism**: `sessionSkillUsed: true` in skill-rules.json
+- **Behavior**: Guardrail only triggers once per Claude session
+- **Use case**: User acknowledged TDD violation, wants to continue
+
+### 2. File Marker (Permanent skip for specific file)
+- **Marker**: Add `@skip-tdd-check` comment anywhere in TASKS.md
+- **Example**:
+  ```markdown
+  <!-- @skip-tdd-check: Hotfix deployment, will add tests in follow-up -->
+  ```
+- **Use case**: Emergency hotfix, tests to be added later
+
+### 3. Environment Variable (Temporary global skip)
+- **Variable**: `SKIP_TDD_ENFORCER=1`
+- **Scope**: Current terminal session
+- **Use case**: Batch operations, automated scripts
+
+## Relationship with Other Components
+
+### mark-task-complete.sh (Script)
+- **Purpose**: Marks tasks complete in正常 workflow (via /flow-dev)
+- **Validation**: Batch validation at phase completion
+- **Timing**: After task execution
+
+### devflow-tdd-enforcer (Guardrail)
+- **Purpose**: Real-time prevention of manual TDD violations
+- **Validation**: Per-edit, blocks save if violation detected
+- **Timing**: During file editing (PreToolUse hook)
+
+**Relationship**: **Complementary (双重保险)**
+- Script ensures正常流程 follows TDD
+- Guardrail prevents手动编辑 from breaking TDD
+
+### Constitution Article VI
+- **Defines**: TDD philosophy and mandates
+- **Enforcement**: planner agent (generation time) + devflow-tdd-enforcer (edit time)
+
+## Configuration
+
+In `.claude/skills/skill-rules.json`:
+
+```json
+{
+  "devflow-tdd-enforcer": {
+    "type": "guardrail",
+    "enforcement": "block",
+    "priority": "critical",
+    "description": "Enforces TDD order, extracted from planner agent rules",
+    "fileTriggers": {
+      "pathPatterns": ["devflow/requirements/**/TASKS.md"],
+      "contentPatterns": [
+        "\\[x\\].*Implementation.*\\n.*\\[ \\].*Test",
+        "\\[x\\].*\\[US\\d+\\].*Implement.*\\n.*\\[ \\].*\\[US\\d+\\].*Test"
+      ]
+    },
+    "blockMessage": "⚠️ BLOCKED - TDD Violation\n\nTasks must follow TDD order:\n1. [ ] Test (write failing test)\n2. [ ] Implementation (make test pass)\n\n📋 ACTION: Re-order TASKS.md\nSource: planner agent mandate + Constitution Article VI\n\n💡 SKIP: @skip-tdd-check or SKIP_TDD_ENFORCER=1",
+    "skipConditions": {
+      "sessionSkillUsed": true,
+      "fileMarkers": ["@skip-tdd-check"],
+      "envOverride": "SKIP_TDD_ENFORCER"
+    }
+  }
+}
+```
+
+## Design Principle
+
+**This guardrail does NOT contain**:
+- ❌ Complete TDD methodology (that's in planner agent)
+- ❌ Task generation logic (that's in planner agent)
+- ❌ Full Constitution Article VI (that's in project-constitution.md)
+
+**This guardrail ONLY contains**:
+- ✅ Prohibition rule extraction (from planner agent)
+- ✅ Real-time violation detection (content pattern matching)
+- ✅ Blocking mechanism (PreToolUse hook, exit code 2)
+- ✅ Links to source documentation
+
+**Rationale**: Avoid duplication ("不重不漏" principle). planner agent owns TDD generation logic, guardrail owns real-time enforcement.