Claude-Code-Workflow/.claude/skills/team-lifecycle-v4/roles/writer/role.md

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