claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-lifecycle-v4/specs/team-config.json

@@ -0,0 +1,200 @@
+{
+  "team_name": "team-lifecycle",
+  "team_display_name": "Team Lifecycle v4",
+  "description": "Optimized team skill: inline discuss subagent + shared explore cache, spec beats halved",
+  "version": "4.0.0",
+  "architecture": "folder-based + subagents",
+  "role_structure": "roles/{name}/role.md + roles/{name}/commands/*.md",
+  "subagent_structure": "subagents/{name}-subagent.md",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Pipeline orchestration, requirement clarification, task chain creation, message dispatch",
+      "message_types": ["plan_approved", "plan_revision", "task_unblocked", "fix_required", "error", "shutdown"]
+    },
+    "analyst": {
+      "task_prefix": "RESEARCH",
+      "responsibility": "Seed analysis, codebase exploration, multi-dimensional context gathering + inline discuss",
+      "inline_discuss": "DISCUSS-001",
+      "message_types": ["research_ready", "research_progress", "error"]
+    },
+    "writer": {
+      "task_prefix": "DRAFT",
+      "responsibility": "Product Brief / PRD / Architecture / Epics document generation + inline discuss",
+      "execution_mode": "inner_loop",
+      "subagent_type": "universal-executor",
+      "inline_discuss": ["DISCUSS-002", "DISCUSS-003", "DISCUSS-004", "DISCUSS-005"],
+      "message_types": ["draft_ready", "draft_revision", "error"]
+    },
+    "planner": {
+      "task_prefix": "PLAN",
+      "responsibility": "Multi-angle code exploration (via shared explore), structured implementation planning",
+      "execution_mode": "inner_loop",
+      "message_types": ["plan_ready", "plan_revision", "error"]
+    },
+    "executor": {
+      "task_prefix": "IMPL",
+      "responsibility": "Code implementation following approved plans",
+      "execution_mode": "inner_loop",
+      "message_types": ["impl_complete", "impl_progress", "error"]
+    },
+    "tester": {
+      "task_prefix": "TEST",
+      "responsibility": "Adaptive test-fix cycles, progressive testing, quality gates",
+      "message_types": ["test_result", "fix_required", "error"]
+    },
+    "reviewer": {
+      "task_prefix": "REVIEW",
+      "additional_prefixes": ["QUALITY", "IMPROVE"],
+      "responsibility": "Code review (REVIEW-*) + Spec quality validation (QUALITY-*) + Quality improvement recheck (IMPROVE-*) + inline discuss for sign-off",
+      "inline_discuss": "DISCUSS-006",
+      "message_types": ["review_result", "quality_result", "quality_recheck", "fix_required", "error"]
+    },
+    "architect": {
+      "task_prefix": "ARCH",
+      "responsibility": "Architecture assessment, tech feasibility, design pattern review. Consulting role -- on-demand by coordinator",
+      "role_type": "consulting",
+      "consultation_modes": ["spec-review", "plan-review", "code-review", "consult", "feasibility"],
+      "message_types": ["arch_ready", "arch_concern", "arch_progress", "error"]
+    },
+    "fe-developer": {
+      "task_prefix": "DEV-FE",
+      "responsibility": "Frontend component/page implementation, design token consumption, responsive UI",
+      "role_type": "frontend-pipeline",
+      "message_types": ["dev_fe_complete", "dev_fe_progress", "error"]
+    },
+    "fe-qa": {
+      "task_prefix": "QA-FE",
+      "responsibility": "5-dimension frontend review (quality, a11y, design compliance, UX, pre-delivery), GC loop",
+      "role_type": "frontend-pipeline",
+      "message_types": ["qa_fe_passed", "qa_fe_result", "fix_required", "error"]
+    }
+  },
+
+  "subagents": {
+    "discuss": {
+      "spec": "subagents/discuss-subagent.md",
+      "type": "cli-discuss-agent",
+      "callable_by": ["analyst", "writer", "reviewer"],
+      "purpose": "Multi-perspective critique with CLI tools, consensus synthesis"
+    },
+    "explore": {
+      "spec": "subagents/explore-subagent.md",
+      "type": "cli-explore-agent",
+      "callable_by": ["analyst", "planner", "any"],
+      "purpose": "Codebase exploration with centralized cache"
+    }
+  },
+
+  "checkpoint_commands": {
+    "revise": {
+      "handler": "handleRevise",
+      "pattern": "revise <TASK-ID> [feedback]",
+      "cascade": true,
+      "creates": "revision_task"
+    },
+    "feedback": {
+      "handler": "handleFeedback",
+      "pattern": "feedback <text>",
+      "cascade": true,
+      "creates": "revision_chain"
+    },
+    "recheck": {
+      "handler": "handleRecheck",
+      "pattern": "recheck",
+      "cascade": false,
+      "creates": "quality_recheck"
+    },
+    "improve": {
+      "handler": "handleImprove",
+      "pattern": "improve [dimension]",
+      "cascade": false,
+      "creates": "improvement_task + quality_recheck"
+    }
+  },
+
+  "pipelines": {
+    "spec-only": {
+      "description": "Specification pipeline: research+discuss -> draft+discuss x4 -> quality+discuss",
+      "task_chain": [
+        "RESEARCH-001",
+        "DRAFT-001", "DRAFT-002", "DRAFT-003", "DRAFT-004",
+        "QUALITY-001"
+      ],
+      "beats": 6,
+      "v3_beats": 12,
+      "optimization": "Discuss rounds inlined into produce roles"
+    },
+    "impl-only": {
+      "description": "Implementation pipeline: plan -> implement -> test + review",
+      "task_chain": ["PLAN-001", "IMPL-001", "TEST-001", "REVIEW-001"],
+      "beats": 3
+    },
+    "full-lifecycle": {
+      "description": "Full lifecycle: spec pipeline -> implementation pipeline",
+      "task_chain": "spec-only + impl-only (PLAN-001 blockedBy QUALITY-001)",
+      "beats": 9,
+      "v3_beats": 15,
+      "optimization": "6 fewer spec beats + QUALITY-001 is last spec task"
+    },
+    "fe-only": {
+      "description": "Frontend-only pipeline: plan -> frontend dev -> frontend QA",
+      "task_chain": ["PLAN-001", "DEV-FE-001", "QA-FE-001"],
+      "gc_loop": { "max_rounds": 2, "convergence": "score >= 8 && critical === 0" }
+    },
+    "fullstack": {
+      "description": "Fullstack pipeline: plan -> backend + frontend parallel -> test + QA",
+      "task_chain": ["PLAN-001", "IMPL-001||DEV-FE-001", "TEST-001||QA-FE-001", "REVIEW-001"],
+      "sync_points": ["REVIEW-001"]
+    },
+    "full-lifecycle-fe": {
+      "description": "Full lifecycle with frontend: spec -> plan -> backend + frontend -> test + QA",
+      "task_chain": "spec-only + fullstack (PLAN-001 blockedBy QUALITY-001)"
+    }
+  },
+
+  "frontend_detection": {
+    "keywords": ["component", "page", "UI", "frontend", "CSS", "HTML", "React", "Vue", "Tailwind", "Svelte", "Next.js", "Nuxt", "shadcn", "design system"],
+    "file_patterns": ["*.tsx", "*.jsx", "*.vue", "*.svelte", "*.css", "*.scss", "*.html"],
+    "routing_rules": {
+      "frontend_only": "All tasks match frontend keywords, no backend/API mentions",
+      "fullstack": "Mix of frontend and backend tasks",
+      "backend_only": "No frontend keywords detected (default impl-only)"
+    }
+  },
+
+  "ui_ux_pro_max": {
+    "skill_name": "ui-ux-pro-max",
+    "invocation": "Skill(skill=\"ui-ux-pro-max\", args=\"...\")",
+    "domains": ["product", "style", "typography", "color", "landing", "chart", "ux", "web"],
+    "stacks": ["html-tailwind", "react", "nextjs", "vue", "svelte", "shadcn", "swiftui", "react-native", "flutter"],
+    "design_intelligence_chain": ["analyst -> design-intelligence.json", "architect -> design-tokens.json", "fe-developer -> tokens.css", "fe-qa -> anti-pattern audit"]
+  },
+
+  "shared_memory": {
+    "file": "shared-memory.json",
+    "schema": {
+      "design_intelligence": "From analyst via ui-ux-pro-max",
+      "design_token_registry": "From architect, consumed by fe-developer/fe-qa",
+      "component_inventory": "From fe-developer, list of implemented components",
+      "style_decisions": "Accumulated design decisions",
+      "qa_history": "From fe-qa, audit trail",
+      "industry_context": "Industry + strictness config",
+      "exploration_cache": "From explore subagent, shared by all roles"
+    }
+  },
+
+  "session_dirs": {
+    "base": ".workflow/.team/TLS-{slug}-{YYYY-MM-DD}/",
+    "spec": "spec/",
+    "discussions": "discussions/",
+    "plan": "plan/",
+    "explorations": "explorations/",
+    "architecture": "architecture/",
+    "analysis": "analysis/",
+    "qa": "qa/",
+    "wisdom": "wisdom/",
+    "messages": ".msg/"
+  }
+}

package/.claude/skills/team-lifecycle-v4/subagents/discuss-subagent.md

@@ -0,0 +1,169 @@
+# Discuss Subagent
+
+Lightweight multi-perspective critique engine. Called inline by produce roles (analyst, writer, reviewer) instead of as a separate team member. Eliminates spawn overhead while preserving multi-CLI analysis quality.
+
+## Design Rationale
+
+In v3, `discussant` was a full team role requiring: agent spawn -> Skill load -> Phase 1 task discovery -> Phase 2-4 work -> Phase 5 report + callback. For what is essentially "run CLI analyses + synthesize", the framework overhead exceeded actual work time.
+
+In v4, discuss is a **subagent call** from within the producing role, reducing each discuss round from ~60-90s overhead to ~5s overhead.
+
+## Invocation
+
+Called by produce roles after artifact creation:
+
+```
+Task({
+  subagent_type: "cli-discuss-agent",
+  run_in_background: false,
+  description: "Discuss <round-id>",
+  prompt: `## Multi-Perspective Critique: <round-id>
+
+### Input
+- Artifact: <artifact-path>
+- Round: <round-id>
+- Perspectives: <perspective-list>
+- Session: <session-folder>
+- Discovery Context: <session-folder>/spec/discovery-context.json (for coverage perspective)
+
+### Perspective Routing
+
+| Perspective | CLI Tool | Role | Focus Areas |
+|-------------|----------|------|-------------|
+| Product | gemini | Product Manager | Market fit, user value, business viability |
+| Technical | codex | Tech Lead | Feasibility, tech debt, performance, security |
+| Quality | claude | QA Lead | Completeness, testability, consistency |
+| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes |
+| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context |
+
+### Execution Steps
+1. Read artifact from <artifact-path>
+2. For each perspective, launch CLI analysis in background:
+   Bash(command="ccw cli -p 'PURPOSE: Analyze from <role> perspective for <round-id>
+   TASK: <focus-areas>
+   MODE: analysis
+   CONTEXT: Artifact content below
+   EXPECTED: JSON with strengths[], weaknesses[], suggestions[], rating (1-5)
+   CONSTRAINTS: Output valid JSON only
+
+   Artifact:
+   <artifact-content>' --tool <cli-tool> --mode analysis", run_in_background=true)
+3. Wait for all CLI results
+4. Divergence detection:
+   - Coverage gap: missing_requirements non-empty -> High severity
+   - High risk: risk_level is high or critical -> High severity
+   - Low rating: any perspective rating <= 2 -> Medium severity
+   - Rating spread: max - min >= 3 -> Medium severity
+5. Consensus determination:
+   - No high-severity divergences AND average rating >= 3.0 -> consensus_reached
+   - Otherwise -> consensus_blocked
+6. Synthesize:
+   - Convergent themes (agreed by 2+ perspectives)
+   - Divergent views (conflicting assessments)
+   - Coverage gaps
+   - Action items from suggestions
+7. Write discussion record to: <session-folder>/discussions/<round-id>-discussion.md
+
+### Discussion Record Format
+# Discussion Record: <round-id>
+
+**Artifact**: <artifact-path>
+**Perspectives**: <list>
+**Consensus**: reached / blocked
+**Average Rating**: <avg>/5
+
+## Convergent Themes
+- <theme>
+
+## Divergent Views
+- **<topic>** (<severity>): <description>
+
+## Action Items
+1. <item>
+
+## Ratings
+| Perspective | Rating |
+|-------------|--------|
+| <name> | <n>/5 |
+
+### Return Value
+
+**When consensus_reached**:
+Return a summary string with:
+- Verdict: consensus_reached
+- Average rating
+- Key action items (top 3)
+- Discussion record path
+
+**When consensus_blocked**:
+Return a structured summary with:
+- Verdict: consensus_blocked
+- Severity: HIGH | MEDIUM | LOW
+  - HIGH: any rating <= 2, critical risk identified, or missing_requirements non-empty
+  - MEDIUM: rating spread >= 3, or single perspective rated <= 2 with others >= 3
+  - LOW: minor suggestions only, all ratings >= 3 but divergent views exist
+- Average rating
+- Divergence summary: top 3 divergent points with perspective attribution
+- Action items: prioritized list of required changes
+- Recommendation: revise | proceed-with-caution | escalate
+- Discussion record path
+
+### Error Handling
+- Single CLI fails -> fallback to direct Claude analysis for that perspective
+- All CLI fail -> generate basic discussion from direct artifact reading
+- Artifact not found -> return error immediately`
+})
+```
+
+## Round Configuration
+
+| Round | Artifact | Perspectives | Calling Role |
+|-------|----------|-------------|-------------|
+| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | analyst |
+| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | writer |
+| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | writer |
+| DISCUSS-004 | spec/architecture/_index.md | technical, risk | writer |
+| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | writer |
+| DISCUSS-006 | spec/readiness-report.md | all 5 | reviewer |
+
+## Integration with Calling Role
+
+The calling role is responsible for:
+
+1. **Before calling**: Complete primary artifact output
+2. **Calling**: Invoke discuss subagent with correct round config
+3. **After calling**:
+
+| Verdict | Severity | Role Action |
+|---------|----------|-------------|
+| consensus_reached | - | Include action items in Phase 5 report, proceed normally |
+| consensus_blocked | HIGH | Include divergence details in Phase 5 SendMessage with structured format (see below). **Do NOT self-revise** -- coordinator decides. |
+| consensus_blocked | MEDIUM | Include warning in Phase 5 SendMessage. Proceed to Phase 5 normally. |
+| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. |
+
+**SendMessage format for consensus_blocked (HIGH or MEDIUM)**:
+
+```
+[<role>] <task-id> complete. Discuss <round-id>: consensus_blocked (severity=<severity>)
+Divergences: <top-3-divergent-points>
+Action items: <prioritized-items>
+Recommendation: <revise|proceed-with-caution|escalate>
+Artifact: <artifact-path>
+Discussion: <discussion-record-path>
+```
+
+The coordinator receives this and routes per severity (see monitor.md Consensus-Blocked Handling):
+- HIGH -> creates revision task (max 1) or pauses for user
+- MEDIUM -> proceeds with warning logged to wisdom/issues.md
+- DISCUSS-006 HIGH -> always pauses for user decision (final sign-off gate)
+
+## Comparison with v3
+
+| Aspect | v3 (discussant role) | v4 (discuss subagent) |
+|--------|---------------------|----------------------|
+| Spawn | Full general-purpose agent | Inline subagent call |
+| Skill load | Reads SKILL.md + role.md | None (prompt contains all logic) |
+| Task discovery | TaskList + TaskGet + TaskUpdate | None (called with context) |
+| Report overhead | team_msg + SendMessage + TaskUpdate | Return value to caller |
+| Total overhead | ~25-45s framework | ~5s call overhead |
+| Pipeline beat | 1 beat per discuss round | 0 additional beats |

package/.claude/skills/team-lifecycle-v4/subagents/doc-generation-subagent.md

@@ -0,0 +1,62 @@
+# Doc Generation Subagent
+
+文档生成执行引擎。由 writer 主 agent 通过 Inner Loop 调用。
+负责 CLI 多视角分析 + 模板填充 + 文件写入。
+
+## Design Rationale
+
+从 v4.0 的 writer 内联 CLI 执行，改为 subagent 隔离调用。
+好处：CLI 调用的大量 token 消耗不污染 writer 主 agent 上下文，
+writer 只拿到压缩摘要，可在多任务间保持上下文连续。
+
+## Invocation
+
+```
+Task({
+  subagent_type: "universal-executor",
+  run_in_background: false,
+  description: "Generate <doc-type>",
+  prompt: `## Document Generation: <doc-type>
+
+### Session
+- Folder: <session-folder>
+- Spec config: <spec-config-path>
+
+### Document Config
+- Type: <product-brief | requirements | architecture | epics>
+- Template: <template-path>
+- Output: <output-path>
+- Prior discussion: <discussion-file or "none">
+
+### Writer Accumulator (prior decisions)
+<JSON array of prior task summaries>
+
+### Execution Strategy
+<从 generate-doc.md 对应 doc-type 段落加载>
+
+### Output Requirements
+1. Write document to <output-path> (follow template + document-standards.md)
+2. Return JSON summary:
+{
+  "artifact_path": "<path>",
+  "summary": "<100-200字>",
+  "key_decisions": [],
+  "sections_generated": [],
+  "cross_references": [],
+  "warnings": []
+}`
+})
+```
+
+## Doc Type Strategies
+
+(直接引用 generate-doc.md 的 DRAFT-001/002/003/004 策略，不重复)
+See: roles/writer/commands/generate-doc.md
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| CLI 工具失败 | fallback chain: gemini → codex → claude |
+| Template 不存在 | 返回错误 JSON |
+| Prior doc 不存在 | 返回错误 JSON，writer 决定是否继续 |

package/.claude/skills/team-lifecycle-v4/subagents/explore-subagent.md

@@ -0,0 +1,172 @@
+# Explore Subagent
+
+Shared codebase exploration utility with centralized caching. Callable by any role needing code context. Replaces v3's standalone explorer role.
+
+## Design Rationale
+
+In v3, exploration happened in 3 separate places:
+- `analyst` Phase 3: ACE semantic search for architecture patterns
+- `planner` Phase 2: multi-angle cli-explore-agent
+- `explorer` role: standalone service with full spawn cycle
+
+Results were scattered across different directories and never shared. In v4, all exploration routes through this subagent with a **unified cache** in `explorations/`.
+
+## Invocation
+
+```
+Task({
+  subagent_type: "cli-explore-agent",
+  run_in_background: false,
+  description: "Explore <angle>",
+  prompt: `Explore codebase for: <query>
+
+Focus angle: <angle>
+Keywords: <keyword-list>
+Session folder: <session-folder>
+
+## Cache Check
+1. Read <session-folder>/explorations/cache-index.json (if exists)
+2. Look for entry with matching angle
+3. If found AND file exists -> read cached result, return summary
+4. If not found -> proceed to exploration
+
+## Exploration
+<angle-specific-focus-from-table-below>
+
+## Output
+Write JSON to: <session-folder>/explorations/explore-<angle>.json
+Update cache-index.json with new entry
+
+## Output Schema
+{
+  "angle": "<angle>",
+  "query": "<query>",
+  "relevant_files": [
+    { "path": "...", "rationale": "...", "role": "...", "discovery_source": "...", "key_symbols": [] }
+  ],
+  "patterns": [],
+  "dependencies": [],
+  "external_refs": [],
+  "_metadata": { "created_by": "<calling-role>", "timestamp": "...", "cache_key": "..." }
+}
+
+Return summary: file count, pattern count, top 5 files, output path`
+})
+```
+
+## Cache Mechanism
+
+### Cache Index Schema
+
+`<session-folder>/explorations/cache-index.json`:
+
+```json
+{
+  "entries": [
+    {
+      "angle": "architecture",
+      "keywords": ["auth", "middleware"],
+      "file": "explore-architecture.json",
+      "created_by": "analyst",
+      "created_at": "2026-02-27T10:00:00Z",
+      "file_count": 15
+    }
+  ]
+}
+```
+
+### Cache Lookup Rules
+
+| Condition | Action |
+|-----------|--------|
+| Exact angle match exists | Return cached result |
+| No match | Execute exploration, cache result |
+| Cache file missing but index has entry | Remove stale entry, re-explore |
+
+### Cache Invalidation
+
+Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. If a role suspects stale data, it can pass `force_refresh: true` in the prompt to bypass cache.
+
+## Angle Focus Guide
+
+| Angle | Focus Points | Typical Caller |
+|-------|-------------|----------------|
+| architecture | Layer boundaries, design patterns, component responsibilities, ADRs | analyst, planner |
+| dependencies | Import chains, external libraries, circular dependencies, shared utilities | planner |
+| modularity | Module interfaces, separation of concerns, extraction opportunities | planner |
+| integration-points | API endpoints, data flow between modules, event systems | analyst, planner |
+| security | Auth/authz logic, input validation, sensitive data handling, middleware | planner |
+| auth-patterns | Auth flows, session management, token validation, permissions | planner |
+| dataflow | Data transformations, state propagation, validation points | planner |
+| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity | planner |
+| error-handling | Try-catch blocks, error propagation, recovery strategies, logging | planner |
+| patterns | Code conventions, design patterns, naming conventions, best practices | analyst, planner |
+| testing | Test files, coverage gaps, test patterns, mocking strategies | planner |
+| general | Broad semantic search for topic-related code | analyst |
+
+## Exploration Strategies
+
+### Low Complexity (direct search)
+
+For simple queries, use ACE semantic search:
+
+```
+mcp__ace-tool__search_context(project_root_path="<project-root>", query="<query>")
+```
+
+ACE failure fallback: `rg -l '<keywords>' --type ts`
+
+### Medium/High Complexity (multi-angle)
+
+For complex queries, call cli-explore-agent per angle. The calling role determines complexity and selects angles (see planner's `commands/explore.md`).
+
+## Search Tool Priority
+
+| Tool | Priority | Use Case |
+|------|----------|----------|
+| mcp__ace-tool__search_context | P0 | Semantic search |
+| Grep / Glob | P1 | Pattern matching |
+| cli-explore-agent | Deep | Multi-angle exploration |
+| WebSearch | P3 | External docs |
+
+## Integration with Roles
+
+### analyst (RESEARCH-001)
+
+```
+# After seed analysis, explore codebase context
+Task({
+  subagent_type: "cli-explore-agent",
+  description: "Explore general context",
+  prompt: "Explore codebase for: <topic>\nFocus angle: general\n..."
+})
+# Result feeds into discovery-context.json
+```
+
+### planner (PLAN-001)
+
+```
+# Multi-angle exploration before plan generation
+for angle in selected_angles:
+  Task({
+    subagent_type: "cli-explore-agent",
+    description: "Explore <angle>",
+    prompt: "Explore codebase for: <task>\nFocus angle: <angle>\n..."
+  })
+# Explorations manifest built from cache-index.json
+```
+
+### Any role needing context
+
+Any role can call explore subagent when needing codebase context for better decisions.
+
+## Comparison with v3
+
+| Aspect | v3 (explorer role) | v4 (explore subagent) |
+|--------|-------------------|----------------------|
+| Identity | Full team member | Utility subagent |
+| Task creation | Coordinator creates EXPLORE-* tasks | No tasks, direct call |
+| Spawn overhead | Full agent lifecycle | Subagent call (~5s) |
+| Result sharing | Isolated in explorations/ | Shared cache with index |
+| Caller | Only via coordinator dispatch | Any role directly |
+| Duplication | analyst + planner + explorer all explore | Single cached path |