mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-11 17:21:03 +08:00
Refactor and optimize templates and code structure
- Deleted outdated templates for epics, product brief, and requirements PRD. - Introduced lazy loading for locale messages in i18n module to enhance performance. - Updated main application bootstrap to parallelize CSRF token fetching and locale loading. - Implemented code splitting for router configuration to optimize bundle size and loading times. - Added WebSocket connection limits and rate limiting to improve server performance and prevent abuse. - Enhanced input validation with compiled regex patterns for better performance and maintainability.
This commit is contained in:
catlog22
@@ -1,192 +0,0 @@
|
||||
# Command: generate-doc
|
||||
|
||||
## Purpose
|
||||
|
||||
Document generation strategy reference. Used by doc-generation-subagent.md as prompt source.
|
||||
Writer 主 agent 不再直接执行此文件中的 CLI 调用，而是将对应段落传入 subagent prompt。
|
||||
|
||||
## Usage
|
||||
|
||||
Writer Phase 3 加载此文件中对应 doc-type 的策略段落，嵌入 subagent prompt 的 "Execution Strategy" 字段。
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Document standards | `../../specs/document-standards.md` | Yes |
|
||||
| Template | From routing table below | Yes |
|
||||
| Spec config | `<session-folder>/spec/spec-config.json` | Yes |
|
||||
| Discovery context | `<session-folder>/spec/discovery-context.json` | Yes |
|
||||
| Discussion feedback | `<session-folder>/discussions/<discuss-file>` | If exists |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
|
||||
### Document Type Routing
|
||||
|
||||
| Doc Type | Task | Template | Discussion Input | Output |
|
||||
|----------|------|----------|-----------------|--------|
|
||||
| product-brief | DRAFT-001 | templates/product-brief.md | DISCUSS-001-discussion.md | spec/product-brief.md |
|
||||
| requirements | DRAFT-002 | templates/requirements-prd.md | DISCUSS-002-discussion.md | spec/requirements/_index.md |
|
||||
| architecture | DRAFT-003 | templates/architecture-doc.md | DISCUSS-003-discussion.md | spec/architecture/_index.md |
|
||||
| epics | DRAFT-004 | templates/epics-template.md | DISCUSS-004-discussion.md | spec/epics/_index.md |
|
||||
|
||||
### Progressive Dependencies
|
||||
|
||||
Each doc type requires all prior docs: discovery-context → product-brief → requirements/_index → architecture/_index.
|
||||
|
||||
## Phase 3: Document Generation
|
||||
|
||||
### Shared Context Block
|
||||
|
||||
Built from spec-config and discovery-context for all CLI prompts:
|
||||
|
||||
```
|
||||
SEED: <topic>
|
||||
PROBLEM: <problem_statement>
|
||||
TARGET USERS: <target_users>
|
||||
DOMAIN: <domain>
|
||||
CONSTRAINTS: <constraints>
|
||||
FOCUS AREAS: <focus_areas>
|
||||
CODEBASE CONTEXT: <existing_patterns, tech_stack> (if discovery-context exists)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-001: Product Brief
|
||||
|
||||
**Strategy**: 3-way parallel CLI analysis, then synthesize.
|
||||
|
||||
| Perspective | CLI Tool | Focus |
|
||||
|-------------|----------|-------|
|
||||
| Product | gemini | Vision, market fit, success metrics, scope |
|
||||
| Technical | codex | Feasibility, constraints, integration complexity |
|
||||
| User | claude | Personas, journey maps, pain points, UX |
|
||||
|
||||
**CLI call template** (one per perspective, all `run_in_background: true`):
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p \"PURPOSE: <perspective> analysis for specification.\n<shared-context>\nTASK: <perspective-specific tasks>\nMODE: analysis\nEXPECTED: <structured output>\nCONSTRAINTS: <perspective scope>\" --tool <tool> --mode analysis", run_in_background=true)
|
||||
```
|
||||
|
||||
**Synthesis flow** (after all 3 return):
|
||||
|
||||
```
|
||||
3 CLI outputs received
|
||||
├─ Identify convergent themes (2+ perspectives agree)
|
||||
├─ Identify conflicts (e.g., product wants X, technical says infeasible)
|
||||
├─ Extract unique insights per perspective
|
||||
├─ Integrate discussion feedback (if exists)
|
||||
└─ Fill template → Write to spec/product-brief.md
|
||||
```
|
||||
|
||||
**Template sections**: Vision, Problem Statement, Target Users, Goals, Scope, Success Criteria, Assumptions.
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-002: Requirements/PRD
|
||||
|
||||
**Strategy**: Single CLI expansion, then structure into individual requirement files.
|
||||
|
||||
| Step | Tool | Action |
|
||||
|------|------|--------|
|
||||
| 1 | gemini | Generate functional (REQ-NNN) and non-functional (NFR-type-NNN) requirements |
|
||||
| 2 | (local) | Integrate discussion feedback |
|
||||
| 3 | (local) | Write individual files + _index.md |
|
||||
|
||||
**CLI prompt focus**: For each product-brief goal, generate 3-7 functional requirements with user stories, acceptance criteria, and MoSCoW priority. Generate NFR categories: performance, security, scalability, usability.
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/requirements/
|
||||
├─ _index.md (summary table + MoSCoW breakdown)
|
||||
├─ REQ-001-<slug>.md (individual functional requirement)
|
||||
├─ REQ-002-<slug>.md
|
||||
├─ NFR-perf-001-<slug>.md (non-functional)
|
||||
└─ NFR-sec-001-<slug>.md
|
||||
```
|
||||
|
||||
Each requirement file has: YAML frontmatter (id, title, priority, status, traces), description, user story, acceptance criteria.
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-003: Architecture
|
||||
|
||||
**Strategy**: 2-stage CLI (design + critical review).
|
||||
|
||||
| Stage | Tool | Purpose |
|
||||
|-------|------|---------|
|
||||
| 1 | gemini | Architecture design: style, components, tech stack, ADRs, data model, security |
|
||||
| 2 | codex | Critical review: challenge ADRs, identify bottlenecks, rate quality 1-5 |
|
||||
|
||||
Stage 2 runs after stage 1 completes (sequential dependency).
|
||||
|
||||
**After both complete**:
|
||||
1. Integrate discussion feedback
|
||||
2. Map codebase integration points (from discovery-context.relevant_files)
|
||||
3. Write individual ADR files + _index.md
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/architecture/
|
||||
├─ _index.md (overview, component diagram, tech stack, data model, API, security)
|
||||
├─ ADR-001-<slug>.md (individual decision record)
|
||||
└─ ADR-002-<slug>.md
|
||||
```
|
||||
|
||||
Each ADR file has: YAML frontmatter (id, title, status, traces), context, decision, alternatives with pros/cons, consequences, review feedback.
|
||||
|
||||
---
|
||||
|
||||
### DRAFT-004: Epics & Stories
|
||||
|
||||
**Strategy**: Single CLI decomposition, then structure into individual epic files.
|
||||
|
||||
| Step | Tool | Action |
|
||||
|------|------|--------|
|
||||
| 1 | gemini | Decompose requirements into 3-7 Epics with Stories, dependency map, MVP subset |
|
||||
| 2 | (local) | Integrate discussion feedback |
|
||||
| 3 | (local) | Write individual EPIC files + _index.md |
|
||||
|
||||
**CLI prompt focus**: Group requirements by domain, generate EPIC-NNN with STORY-EPIC-NNN children, define MVP subset, create Mermaid dependency diagram, recommend execution order.
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/epics/
|
||||
├─ _index.md (overview table, dependency map, execution order, MVP scope)
|
||||
├─ EPIC-001-<slug>.md (individual epic with stories)
|
||||
└─ EPIC-002-<slug>.md
|
||||
```
|
||||
|
||||
Each epic file has: YAML frontmatter (id, title, priority, mvp, size, requirements, architecture, dependencies), stories with user stories and acceptance criteria.
|
||||
|
||||
All generated documents include YAML frontmatter: session_id, phase, document_type, status=draft, generated_at, version, dependencies.
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | What to Verify |
|
||||
|-------|---------------|
|
||||
| has_frontmatter | Document starts with valid YAML frontmatter |
|
||||
| sections_complete | All template sections present in output |
|
||||
| cross_references | session_id matches spec-config |
|
||||
| discussion_integrated | Feedback reflected (if feedback exists) |
|
||||
| files_written | All expected files exist (individual + _index.md) |
|
||||
|
||||
### Result Routing
|
||||
|
||||
| Outcome | Message Type | Content |
|
||||
|---------|-------------|---------|
|
||||
| All checks pass | draft_ready | Doc type, output path, summary |
|
||||
| Validation issues | draft_ready (with warnings) | Doc type, output path, issues list |
|
||||
| Critical failure | error | Missing template, CLI failure |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Prior doc not found | Notify coordinator, request prerequisite task completion |
|
||||
| Template not found | Error, report missing template path |
|
||||
| CLI tool fails | Retry with fallback tool (gemini → codex → claude) |
|
||||
| Discussion contradicts prior docs | Note conflict in document, flag for next discussion round |
|
||||
| Partial CLI output | Use available data, note gaps in document |
|
||||
@@ -1,246 +0,0 @@
|
||||
# Role: writer
|
||||
|
||||
Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation.
|
||||
Uses **Inner Loop** pattern: one agent handles all DRAFT-* tasks sequentially,
|
||||
delegating document generation to subagent, retaining summaries across tasks.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]`
|
||||
- **Mode**: Inner Loop (处理全部 DRAFT-* 任务)
|
||||
- **Responsibility**: [Loop: Load Context -> Subagent Generate -> Validate + Discuss -> Accumulate] -> Final Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process DRAFT-* tasks
|
||||
- Use subagent for document generation (不在主 agent 内执行 CLI)
|
||||
- Maintain context_accumulator across tasks
|
||||
- Call discuss subagent after each document output
|
||||
- Loop through all DRAFT-* tasks before reporting to coordinator
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks for other roles
|
||||
- Skip template loading
|
||||
- Execute CLI document generation in main agent (delegate to subagent)
|
||||
- SendMessage to coordinator mid-loop (除非 consensus_blocked HIGH)
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger |
|
||||
|------|-----------|---------|
|
||||
| draft_ready | -> coordinator | Document + discuss complete |
|
||||
| draft_revision | -> coordinator | Document revised per feedback |
|
||||
| error | -> coordinator | Template missing, insufficient context |
|
||||
|
||||
## Toolbox
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| subagents/doc-generation-subagent.md | Document generation (per task) |
|
||||
| discuss subagent | Inline discuss critique |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Task Discovery (Inner Loop)
|
||||
|
||||
**首次进入**：标准 Phase 1 流程，找到第一个 DRAFT-* pending 任务。
|
||||
|
||||
**循环重入**：Phase 5-L 完成后回到此处，TaskList 查找下一个 DRAFT-* pending 且 blockedBy 已全部 completed 的任务。
|
||||
|
||||
**终止条件**：无更多 DRAFT-* 可处理 → Phase 5-F。
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
**Objective**: Load all required inputs for document generation.
|
||||
|
||||
**Document type routing**:
|
||||
|
||||
| Task Subject Contains | Doc Type | Template | Prior Discussion Input |
|
||||
|----------------------|----------|----------|----------------------|
|
||||
| Product Brief | product-brief | templates/product-brief.md | discussions/DISCUSS-001-discussion.md |
|
||||
| Requirements / PRD | requirements | templates/requirements-prd.md | discussions/DISCUSS-002-discussion.md |
|
||||
| Architecture | architecture | templates/architecture-doc.md | discussions/DISCUSS-003-discussion.md |
|
||||
| Epics | epics | templates/epics-template.md | discussions/DISCUSS-004-discussion.md |
|
||||
|
||||
**Inline discuss mapping**:
|
||||
|
||||
| Doc Type | Inline Discuss Round | Perspectives |
|
||||
|----------|---------------------|-------------|
|
||||
| product-brief | DISCUSS-002 | product, technical, quality, coverage |
|
||||
| requirements | DISCUSS-003 | quality, product, coverage |
|
||||
| architecture | DISCUSS-004 | technical, risk |
|
||||
| epics | DISCUSS-005 | product, technical, quality, coverage |
|
||||
|
||||
**Progressive dependency loading**:
|
||||
|
||||
| Doc Type | Requires |
|
||||
|----------|----------|
|
||||
| product-brief | discovery-context.json |
|
||||
| requirements | + product-brief.md |
|
||||
| architecture | + requirements/_index.md |
|
||||
| epics | + architecture/_index.md |
|
||||
|
||||
**Prior decisions from accumulator**: 将 context_accumulator 中的前序摘要作为 "Prior Decisions" 传入。
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Document standards | `../../specs/document-standards.md` | Yes |
|
||||
| Template | From routing table | Yes |
|
||||
| Spec config | `<session-folder>/spec/spec-config.json` | Yes |
|
||||
| Discovery context | `<session-folder>/spec/discovery-context.json` | Yes |
|
||||
| Discussion feedback | `<session-folder>/discussions/<discuss-file>` | If exists |
|
||||
| Prior decisions | context_accumulator (内存) | 如果有前序任务 |
|
||||
|
||||
**Success**: Template loaded, prior discussion feedback loaded (if exists), prior docs loaded, accumulator context prepared.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Subagent Document Generation
|
||||
|
||||
**Objective**: Delegate document generation to doc-generation subagent.
|
||||
|
||||
**变化**：不再在主 agent 内执行 CLI 调用，而是委托给 doc-generation subagent。
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "universal-executor",
|
||||
run_in_background: false,
|
||||
description: "Generate <doc-type> document",
|
||||
prompt: `<从 subagents/doc-generation-subagent.md 加载 prompt>
|
||||
|
||||
## Task
|
||||
- Document type: <doc-type>
|
||||
- Session folder: <session-folder>
|
||||
- Template: <template-path>
|
||||
|
||||
## Context
|
||||
- Spec config: <spec-config 内容>
|
||||
- Discovery context: <discovery-context 摘要>
|
||||
- Prior discussion feedback: <discussion-file 内容 if exists>
|
||||
- Prior decisions (from writer accumulator):
|
||||
<context_accumulator 序列化>
|
||||
|
||||
## Instructions
|
||||
<从 commands/generate-doc.md 加载该 doc-type 的具体策略>
|
||||
|
||||
## Expected Output
|
||||
Return JSON:
|
||||
{
|
||||
"artifact_path": "<output-path>",
|
||||
"summary": "<100-200字摘要>",
|
||||
"key_decisions": ["<decision-1>", "<decision-2>", ...],
|
||||
"sections_generated": ["<section-1>", ...],
|
||||
"warnings": ["<warning if any>"]
|
||||
}`
|
||||
})
|
||||
```
|
||||
|
||||
**主 agent 拿到的只是上述 JSON 摘要**，不是整篇文档。文档已由 subagent 写入磁盘。
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Self-Validation + Inline Discuss
|
||||
|
||||
### 4a: Self-Validation
|
||||
|
||||
| Check | What to Verify |
|
||||
|-------|---------------|
|
||||
| has_frontmatter | Starts with YAML frontmatter |
|
||||
| sections_complete | All template sections present |
|
||||
| cross_references | session_id included |
|
||||
| discussion_integrated | Reflects prior round feedback (if exists) |
|
||||
|
||||
### 4b: Inline Discuss
|
||||
|
||||
After validation, call discuss subagent for this task's discuss round:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-discuss-agent",
|
||||
run_in_background: false,
|
||||
description: "Discuss <DISCUSS-NNN>",
|
||||
prompt: `## Multi-Perspective Critique: <DISCUSS-NNN>
|
||||
|
||||
### Input
|
||||
- Artifact: <output-path>
|
||||
- Round: <DISCUSS-NNN>
|
||||
- Perspectives: <perspectives-from-table>
|
||||
- Session: <session-folder>
|
||||
- Discovery Context: <session-folder>/spec/discovery-context.json
|
||||
|
||||
<rest of discuss subagent prompt from subagents/discuss-subagent.md>`
|
||||
})
|
||||
```
|
||||
|
||||
**Discuss result handling**:
|
||||
|
||||
| Verdict | Severity | Action |
|
||||
|---------|----------|--------|
|
||||
| consensus_reached | - | Include action items in report, proceed to Phase 5 |
|
||||
| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format (see below). Do NOT self-revise -- coordinator creates revision task. |
|
||||
| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed to Phase 5 normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
|
||||
**consensus_blocked SendMessage format**:
|
||||
```
|
||||
[writer] <task-id> complete. Discuss <DISCUSS-NNN>: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <output-path>
|
||||
Discussion: <session-folder>/discussions/<DISCUSS-NNN>-discussion.md
|
||||
```
|
||||
|
||||
**Report**: doc type, validation status, discuss verdict + severity, average rating, summary, output path.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5-L: 循环完成 (Loop Completion)
|
||||
|
||||
在还有后续 DRAFT-* 任务时执行：
|
||||
|
||||
1. **TaskUpdate**: 标记当前任务 completed
|
||||
2. **team_msg**: 记录任务完成
|
||||
3. **累积摘要**:
|
||||
```
|
||||
context_accumulator.append({
|
||||
task: "<DRAFT-NNN>",
|
||||
artifact: "<output-path>",
|
||||
key_decisions: <from subagent return>,
|
||||
discuss_verdict: <from Phase 4>,
|
||||
discuss_rating: <from Phase 4>,
|
||||
summary: <from subagent return>
|
||||
})
|
||||
```
|
||||
4. **中断检查**:
|
||||
- consensus_blocked HIGH → SendMessage → STOP
|
||||
- 累计错误 >= 3 → SendMessage → STOP
|
||||
5. **Loop**: 回到 Phase 1
|
||||
|
||||
**不做**：不 SendMessage、不 Fast-Advance spawn。
|
||||
|
||||
## Phase 5-F: 最终报告 (Final Report)
|
||||
|
||||
当所有 DRAFT-* 任务完成后：
|
||||
|
||||
1. **TaskUpdate**: 标记最后一个任务 completed
|
||||
2. **team_msg**: 记录完成
|
||||
3. **汇总报告**: 所有任务摘要 + discuss 结果 + 产出路径
|
||||
4. **Fast-Advance 检查**: 检查跨前缀后续 (如 QUALITY-001 是否 ready)
|
||||
5. **SendMessage** 或 **spawn successor**
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Subagent 失败 | 重试 1 次，换 subagent_type；仍失败则记录错误，继续下一任务 |
|
||||
| Discuss subagent 失败 | 跳过 discuss，记录 warning |
|
||||
| 累计 3 个任务失败 | SendMessage 报告 coordinator，STOP |
|
||||
| Agent crash mid-loop | Coordinator resume 检测 orphan → 重新 spawn → 从断点恢复 |
|
||||
| Prior doc not found | Notify coordinator, request prerequisite |
|
||||
| Discussion contradicts prior docs | Note conflict, flag for coordinator |
|
||||
Reference in New Issue
Block a user