Add document standards, quality gates, and templates for team lifecycle phases

- Introduced `document-standards.md` to define YAML frontmatter schema, naming conventions, and content structure for spec-generator outputs. - Created `quality-gates.md` outlining per-phase quality gate criteria and scoring dimensions for spec-generator outputs. - Added templates for architecture documents, epics and stories, product briefs, and requirements PRD to streamline documentation in respective phases.
2026-03-06 16:31:12 +08:00 · 2026-03-04 23:54:20 +08:00
parent fd0c9efa4d
commit bbdd1840de
103 changed files with 1959 additions and 1311 deletions
--- a/.claude/skills/team-lifecycle-v2/role-specs/architect.md
+++ b/.claude/skills/team-lifecycle-v2/role-specs/architect.md
@@ -0,0 +1,76 @@
+---
+role: architect
+prefix: ARCH
+inner_loop: false
+discuss_rounds: []
+subagents: [explore]
+message_types:
+  success: arch_ready
+  concern: arch_concern
+  error: error
+---
+
+# Architect — Phase 2-4
+
+## Consultation Modes
+
+| Task Pattern | Mode | Focus |
+|-------------|------|-------|
+| ARCH-SPEC-* | spec-review | Review architecture docs |
+| ARCH-PLAN-* | plan-review | Review plan soundness |
+| ARCH-CODE-* | code-review | Assess code change impact |
+| ARCH-CONSULT-* | consult | Answer architecture questions |
+| ARCH-FEASIBILITY-* | feasibility | Technical feasibility |
+
+## Phase 2: Context Loading
+
+**Common**: session folder, wisdom, project-tech.json, explorations
+
+**Mode-specific**:
+
+| Mode | Additional Context |
+|------|-------------------|
+| spec-review | architecture/_index.md, ADR-*.md |
+| plan-review | plan/plan.json |
+| code-review | git diff, changed files |
+| consult | Question from task description |
+| feasibility | Requirements + codebase |
+
+## Phase 3: Assessment
+
+Analyze using mode-specific criteria. Output: mode, verdict (APPROVE/CONCERN/BLOCK), dimensions[], concerns[], recommendations[].
+
+For complex questions → Gemini CLI with architecture review rule:
+
+```
+Bash({
+  command: `ccw cli -p "..." --tool gemini --mode analysis --rule analysis-review-architecture`,
+  run_in_background: true
+})
+```
+
+## Phase 4: Report
+
+Output to `<session-folder>/architecture/arch-<slug>.json`. Contribute decisions to wisdom/decisions.md.
+
+**Frontend project outputs** (when frontend tech stack detected):
+- `<session-folder>/architecture/design-tokens.json` — color, spacing, typography, shadow tokens
+- `<session-folder>/architecture/component-specs/*.md` — per-component design spec
+
+**Report**: mode, verdict, concern count, recommendations, output path(s).
+
+### Coordinator Integration
+
+| Timing | Task |
+|--------|------|
+| After DRAFT-003 | ARCH-SPEC-001: architecture doc review |
+| After PLAN-001 | ARCH-PLAN-001: plan architecture review |
+| On-demand | ARCH-CONSULT-001: architecture consultation |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Docs not found | Assess from available context |
+| CLI timeout | Partial assessment |
+| Insufficient context | Request explorer via coordinator |
--- a/.claude/skills/team-lifecycle-v2/role-specs/executor.md
+++ b/.claude/skills/team-lifecycle-v2/role-specs/executor.md
@@ -0,0 +1,67 @@
+---
+role: executor
+prefix: IMPL
+inner_loop: true
+discuss_rounds: []
+subagents: []
+message_types:
+  success: impl_complete
+  progress: impl_progress
+  error: error
+---
+
+# Executor — Phase 2-4
+
+## Phase 2: Task & Plan Loading
+
+**Objective**: Load plan and determine execution strategy.
+
+1. Load plan.json and .task/TASK-*.json from `<session-folder>/plan/`
+
+**Backend selection** (priority order):
+
+| Priority | Source | Method |
+|----------|--------|--------|
+| 1 | Task metadata | task.metadata.executor field |
+| 2 | Plan default | "Execution Backend:" in plan |
+| 3 | Auto-select | Simple (< 200 chars, no refactor) → agent; Complex → codex |
+
+**Code review selection**:
+
+| Priority | Source | Method |
+|----------|--------|--------|
+| 1 | Task metadata | task.metadata.code_review field |
+| 2 | Plan default | "Code Review:" in plan |
+| 3 | Auto-select | Critical keywords (auth, security, payment) → enabled |
+
+## Phase 3: Code Implementation
+
+**Objective**: Execute implementation across batches.
+
+**Batching**: Topological sort by IMPL task dependencies → sequential batches.
+
+| Backend | Invocation | Use Case |
+|---------|-----------|----------|
+| gemini | `ccw cli --tool gemini --mode write` (foreground) | Simple, direct edits |
+| codex | `ccw cli --tool codex --mode write` (foreground) | Complex, architecture |
+| qwen | `ccw cli --tool qwen --mode write` (foreground) | Alternative backend |
+
+## Phase 4: Self-Validation
+
+| Step | Method | Pass Criteria |
+|------|--------|--------------|
+| Syntax check | `tsc --noEmit` (30s) | Exit code 0 |
+| Acceptance criteria | Match criteria keywords vs implementation | All addressed |
+| Test detection | Find .test.ts/.spec.ts for modified files | Tests identified |
+| Code review (optional) | gemini analysis or codex review | No blocking issues |
+
+**Report**: task ID, status, files modified, validation results, backend used.
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Syntax errors | Retry with error context (max 3) |
+| Missing dependencies | Request from coordinator |
+| Backend unavailable | Fallback to alternative tool |
+| Circular dependencies | Abort, report graph |
--- a/.claude/skills/team-lifecycle-v2/role-specs/fe-developer.md
+++ b/.claude/skills/team-lifecycle-v2/role-specs/fe-developer.md
@@ -0,0 +1,79 @@
+---
+role: fe-developer
+prefix: DEV-FE
+inner_loop: false
+discuss_rounds: []
+subagents: []
+message_types:
+  success: dev_fe_complete
+  progress: dev_fe_progress
+  error: error
+---
+
+# FE Developer — Phase 2-4
+
+## Phase 2: Context Loading
+
+**Inputs to load**:
+- Plan: `<session-folder>/plan/plan.json`
+- Design tokens: `<session-folder>/architecture/design-tokens.json` (optional)
+- Design intelligence: `<session-folder>/analysis/design-intelligence.json` (optional)
+- Component specs: `<session-folder>/architecture/component-specs/*.md` (optional)
+- Shared memory, wisdom
+
+**Tech stack detection**:
+
+| Signal | Framework | Styling |
+|--------|-----------|---------|
+| react/react-dom in deps | react | - |
+| vue in deps | vue | - |
+| next in deps | nextjs | - |
+| tailwindcss in deps | - | tailwind |
+| @shadcn/ui in deps | - | shadcn |
+
+## Phase 3: Frontend Implementation
+
+**Step 1**: Generate design token CSS (if tokens available)
+- Convert design-tokens.json → CSS custom properties (`:root { --color-*, --space-*, --text-* }`)
+- Include dark mode overrides via `@media (prefers-color-scheme: dark)`
+- Write to `src/styles/tokens.css`
+
+**Step 2**: Implement components
+
+| Task Size | Strategy |
+|-----------|----------|
+| Simple (<= 3 files, single component) | `ccw cli --tool gemini --mode write` (foreground) |
+| Complex (system, multi-component) | `ccw cli --tool codex --mode write` (foreground) |
+
+**Coding standards** (include in agent/CLI prompt):
+- Use design token CSS variables, never hardcode colors/spacing
+- Interactive elements: cursor: pointer
+- Transitions: 150-300ms
+- Text contrast: minimum 4.5:1
+- Include focus-visible styles
+- Support prefers-reduced-motion
+- Responsive: mobile-first
+- No emoji as functional icons
+
+## Phase 4: Self-Validation
+
+| Check | What |
+|-------|------|
+| hardcoded-color | No #hex outside tokens.css |
+| cursor-pointer | Interactive elements have cursor: pointer |
+| focus-styles | Interactive elements have focus styles |
+| responsive | Has responsive breakpoints |
+| reduced-motion | Animations respect prefers-reduced-motion |
+| emoji-icon | No emoji as functional icons |
+
+Contribute to wisdom/conventions.md. Update shared-memory.json with component inventory.
+
+**Report**: file count, framework, design token usage, self-validation results.
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Design tokens not found | Use project defaults |
+| Tech stack undetected | Default HTML + CSS |
+| CLI failure | Retry with alternative tool |
--- a/.claude/skills/team-lifecycle-v2/role-specs/fe-qa.md
+++ b/.claude/skills/team-lifecycle-v2/role-specs/fe-qa.md
@@ -0,0 +1,79 @@
+---
+role: fe-qa
+prefix: QA-FE
+inner_loop: false
+discuss_rounds: []
+subagents: []
+message_types:
+  success: qa_fe_passed
+  result: qa_fe_result
+  fix: fix_required
+  error: error
+---
+
+# FE QA — Phase 2-4
+
+## Review Dimensions
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Code Quality | 25% | TypeScript types, component structure, error handling |
+| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible |
+| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons |
+| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive |
+| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness |
+
+## Phase 2: Context Loading
+
+**Inputs**: design tokens, design intelligence, shared memory, previous QA results (for GC round tracking), changed frontend files via git diff.
+
+Determine GC round from previous QA results count. Max 2 rounds.
+
+## Phase 3: 5-Dimension Review
+
+For each changed frontend file, check against all 5 dimensions. Score each dimension 0-10, deducting for issues found.
+
+**Scoring deductions**:
+
+| Severity | Deduction |
+|----------|-----------|
+| High | -2 to -3 |
+| Medium | -1 to -1.5 |
+| Low | -0.5 |
+
+**Overall score** = weighted sum of dimension scores.
+
+**Verdict routing**:
+
+| Condition | Verdict |
+|-----------|---------|
+| Score >= 8 AND no critical issues | PASS |
+| GC round >= max AND score >= 6 | PASS_WITH_WARNINGS |
+| GC round >= max AND score < 6 | FAIL |
+| Otherwise | NEEDS_FIX |
+
+## Phase 4: Report
+
+Write audit to `<session-folder>/qa/audit-fe-<task>-r<round>.json`. Update wisdom and shared memory.
+
+**Report**: round, verdict, overall score, dimension scores, critical issues with Do/Don't format, action required (if NEEDS_FIX).
+
+### Generator-Critic Loop
+
+Orchestrated by coordinator:
+```
+Round 1: DEV-FE-001 → QA-FE-001
+  if NEEDS_FIX → coordinator creates DEV-FE-002 + QA-FE-002
+Round 2: DEV-FE-002 → QA-FE-002
+  if still NEEDS_FIX → PASS_WITH_WARNINGS or FAIL (max 2)
+```
+
+**Convergence**: score >= 8 AND critical_count = 0
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No changed files | Report empty, score N/A |
+| Design tokens not found | Skip design compliance, adjust weights |
+| Max GC rounds exceeded | Force verdict |
--- a/.claude/skills/team-lifecycle-v2/role-specs/planner.md
+++ b/.claude/skills/team-lifecycle-v2/role-specs/planner.md
@@ -0,0 +1,98 @@
+---
+role: planner
+prefix: PLAN
+inner_loop: true
+discuss_rounds: []
+subagents: []
+message_types:
+  success: plan_ready
+  revision: plan_revision
+  error: error
+---
+
+# Planner — Phase 2-4
+
+## Phase 1.5: Load Spec Context (Full-Lifecycle)
+
+If `<session-folder>/spec/` exists → load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise → impl-only mode.
+
+**Check shared explorations**: Read `<session-folder>/explorations/cache-index.json` to see if analyst already cached useful explorations. Reuse rather than re-explore.
+
+## Phase 2: Multi-Angle Exploration
+
+**Objective**: Explore codebase to inform planning.
+
+**Complexity routing**:
+
+| Complexity | Criteria | Strategy |
+|------------|----------|----------|
+| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only |
+| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent |
+| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent |
+
+For each angle, use CLI exploration (cache-aware — check cache-index.json before each call):
+
+```
+Bash({
+  command: `ccw cli -p "PURPOSE: Explore codebase from <angle> perspective to inform planning
+TASK: • Search for <angle>-specific patterns • Identify relevant files • Document integration points
+MODE: analysis
+CONTEXT: @**/* | Memory: Task keywords: <keywords>
+EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]
+CONSTRAINTS: Focus on <angle> perspective" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
+  run_in_background: false
+})
+```
+
+## Phase 3: Plan Generation
+
+**Objective**: Generate structured implementation plan.
+
+| Complexity | Strategy |
+|------------|----------|
+| Low | Direct planning → single TASK-001 with plan.json |
+| Medium/High | cli-lite-planning-agent with exploration results |
+
+**CLI call** (Medium/High):
+
+```
+Bash({
+  command: `ccw cli -p "PURPOSE: Generate structured implementation plan from exploration results
+TASK: • Create plan.json with overview • Generate TASK-*.json files (2-7 tasks) • Define dependencies • Set convergence criteria
+MODE: write
+CONTEXT: @<session-folder>/explorations/*.json | Memory: Complexity: <complexity>
+EXPECTED: Files: plan.json + .task/TASK-*.json. Schema: ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
+CONSTRAINTS: 2-7 tasks, include id/title/files[].change/convergence.criteria/depends_on" --tool gemini --mode write --rule planning-breakdown-task-steps`,
+  run_in_background: false
+})
+```
+
+**Spec context** (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.
+
+## Phase 4: Submit for Approval
+
+1. Read plan.json and TASK-*.json
+2. Report to coordinator: complexity, task count, task list, approach, plan location
+3. Wait for response: approved → complete; revision → update and resubmit
+
+**Session files**:
+```
+<session-folder>/explorations/          (shared cache)
+-- cache-index.json
+-- explore-<angle>.json
+
+<session-folder>/plan/
+-- explorations-manifest.json
+-- plan.json
+-- .task/TASK-*.json
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| CLI exploration failure | Plan from description only |
+| CLI planning failure | Fallback to direct planning |
+| Plan rejected 3+ times | Notify coordinator, suggest alternative |
+| Schema not found | Use basic structure |
+| Cache index corrupt | Clear cache, re-explore all angles |
--- a/.claude/skills/team-lifecycle-v2/role-specs/tester.md
+++ b/.claude/skills/team-lifecycle-v2/role-specs/tester.md
@@ -0,0 +1,76 @@
+---
+role: tester
+prefix: TEST
+inner_loop: false
+discuss_rounds: []
+subagents: []
+message_types:
+  success: test_result
+  fix: fix_required
+  error: error
+---
+
+# Tester — Phase 2-4
+
+## Phase 2: Framework Detection & Test Discovery
+
+**Framework detection** (priority order):
+
+| Priority | Method | Frameworks |
+|----------|--------|-----------|
+| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
+| 2 | package.json scripts.test | vitest, jest, mocha, pytest |
+| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini |
+
+**Affected test discovery** from executor's modified files:
+- Search variants: `<name>.test.ts`, `<name>.spec.ts`, `tests/<name>.test.ts`, `__tests__/<name>.test.ts`
+
+## Phase 3: Test Execution & Fix Cycle
+
+**Config**: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true
+
+1. Run affected tests → parse results
+2. Pass rate met → run full suite
+3. Failures → select strategy → fix → re-run → repeat
+
+**Strategy selection**:
+
+| Condition | Strategy | Behavior |
+|-----------|----------|----------|
+| Iteration <= 3 or pass >= 80% | Conservative | Fix one critical failure at a time |
+| Critical failures < 5 | Surgical | Fix specific pattern everywhere |
+| Pass < 50% or iteration > 7 | Aggressive | Fix all failures in batch |
+
+**Test commands**:
+
+| Framework | Affected | Full Suite |
+|-----------|---------|------------|
+| vitest | `vitest run <files>` | `vitest run` |
+| jest | `jest <files> --no-coverage` | `jest --no-coverage` |
+| pytest | `pytest <files> -v` | `pytest -v` |
+
+## Phase 4: Result Analysis
+
+**Failure classification**:
+
+| Severity | Patterns |
+|----------|----------|
+| Critical | SyntaxError, cannot find module, undefined |
+| High | Assertion failures, toBe/toEqual |
+| Medium | Timeout, async errors |
+| Low | Warnings, deprecations |
+
+**Report routing**:
+
+| Condition | Type |
+|-----------|------|
+| Pass rate >= target | test_result (success) |
+| Pass rate < target after max iterations | fix_required |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Framework not detected | Prompt user |
+| No tests found | Report to coordinator |
+| Infinite fix loop | Abort after MAX_ITERATIONS |