mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add templates for epics, product brief, and requirements PRD
- Created a new directory structure for epics and stories with templates for individual epics and an index file. - Added a product brief template for generating product brief documents in Phase 2. - Introduced a requirements PRD template for generating a Product Requirements Document as a directory of individual requirement files in Phase 3. feat: implement V2PipelineTab component for Memory V2 management - Developed the V2PipelineTab component to manage extraction and consolidation processes. - Included ExtractionCard and ConsolidationCard components to handle respective functionalities. - Added JobsList component to display job statuses and allow filtering by job kind. feat: create hooks for Memory V2 pipeline - Implemented custom hooks for managing extraction and consolidation statuses, as well as job listings. - Added mutation hooks to trigger extraction and consolidation processes with automatic query invalidation on success.
This commit is contained in:
catlog22
@@ -150,6 +150,8 @@ Task completion with optional fast-advance to skip coordinator round-trip:
|
||||
| No ready tasks + nothing running | SendMessage to coordinator (pipeline may be complete) |
|
||||
| Checkpoint task (e.g., spec->impl transition) | SendMessage to coordinator (needs user confirmation) |
|
||||
|
||||
**Fast-advance failure recovery**: If a fast-advanced task fails (worker exits without completing), the coordinator detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing, no manual intervention required. See [monitor.md](roles/coordinator/commands/monitor.md) Fast-Advance Failure Recovery.
|
||||
|
||||
### Inline Discuss Protocol (produce roles: analyst, writer, reviewer)
|
||||
|
||||
After completing their primary output, produce roles call the discuss subagent inline:
|
||||
@@ -176,13 +178,36 @@ Task({
|
||||
|
||||
The discuss subagent writes its record to `discussions/` and returns the verdict. The calling role includes the discuss result in its Phase 5 report.
|
||||
|
||||
**Consensus-blocked handling** (produce role responsibility):
|
||||
|
||||
| Verdict | Severity | Role Action |
|
||||
|---------|----------|-------------|
|
||||
| consensus_reached | - | Include action items in report, proceed to Phase 5 |
|
||||
| consensus_blocked | HIGH | SendMessage with `consensus_blocked=true, severity=HIGH`, include divergence details + action items. Coordinator creates revision task or pauses. |
|
||||
| consensus_blocked | MEDIUM | SendMessage with `consensus_blocked=true, severity=MEDIUM`. Proceed to Phase 5 normally. Coordinator logs warning to wisdom. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. |
|
||||
|
||||
**SendMessage format for consensus_blocked**:
|
||||
|
||||
```
|
||||
[<role>] <task-id> complete. Discuss <round-id>: consensus_blocked (severity=<HIGH|MEDIUM>)
|
||||
Divergences: <divergence-summary>
|
||||
Action items: <top-3-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
```
|
||||
|
||||
**Coordinator response** (see monitor.md Consensus-Blocked Handling for full flow):
|
||||
- HIGH -> revision task (max 1 per task) or pause for user decision
|
||||
- MEDIUM -> proceed with warning, log to wisdom/issues.md
|
||||
- DISCUSS-006 HIGH -> always pause for user (final sign-off gate)
|
||||
|
||||
### Shared Explore Utility
|
||||
|
||||
Any role needing codebase context calls the explore subagent:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore <angle>",
|
||||
prompt: <see subagents/explore-subagent.md for prompt template>
|
||||
|
||||
@@ -84,7 +84,7 @@ EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], e
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore general context",
|
||||
prompt: "Explore codebase for: <topic>
|
||||
@@ -139,10 +139,25 @@ Task({
|
||||
```
|
||||
|
||||
**Discuss result handling**:
|
||||
- `consensus_reached` -> include in report, proceed normally
|
||||
- `consensus_blocked` -> flag in SendMessage, coordinator decides next step
|
||||
|
||||
**Report**: complexity, codebase presence, problem statement, exploration dimensions, discuss verdict, output paths.
|
||||
| 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. |
|
||||
| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
|
||||
**consensus_blocked SendMessage format**:
|
||||
```
|
||||
[analyst] RESEARCH-001 complete. Discuss DISCUSS-001: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <session-folder>/spec/discovery-context.json
|
||||
Discussion: <session-folder>/discussions/DISCUSS-001-discussion.md
|
||||
```
|
||||
|
||||
**Report**: complexity, codebase presence, problem statement, exploration dimensions, discuss verdict + severity, output paths.
|
||||
|
||||
**Success**: Both JSON files created; discuss record written; design-intelligence.json created if UI mode.
|
||||
|
||||
|
||||
@@ -170,6 +170,80 @@ When a worker has unexpected status (not completed, not in_progress):
|
||||
2. Log via team_msg (type: error)
|
||||
3. Report to user: task reset, will retry on next resume
|
||||
|
||||
### Fast-Advance Failure Recovery
|
||||
|
||||
When coordinator detects a fast-advanced task has failed (task in_progress but no callback and worker gone):
|
||||
|
||||
```
|
||||
handleCallback / handleResume detects:
|
||||
+- Task is in_progress (was fast-advanced by predecessor)
|
||||
+- No active_worker entry for this task
|
||||
+- Original fast-advancing worker has already completed and exited
|
||||
+- Resolution:
|
||||
1. TaskUpdate -> reset task to pending
|
||||
2. Remove stale active_worker entry (if any)
|
||||
3. Log via team_msg (type: error, summary: "Fast-advanced task <ID> failed, resetting for retry")
|
||||
4. -> handleSpawnNext (will re-spawn the task normally)
|
||||
```
|
||||
|
||||
**Detection in handleResume**:
|
||||
|
||||
```
|
||||
For each in_progress task in TaskList():
|
||||
+- Has matching active_worker? -> normal, skip
|
||||
+- No matching active_worker? -> orphaned (likely fast-advance failure)
|
||||
+- Check creation time: if > 5 minutes with no progress callback
|
||||
+- Reset to pending -> handleSpawnNext
|
||||
```
|
||||
|
||||
**Prevention**: Fast-advance failures are self-healing. The coordinator reconciles orphaned tasks on every `resume`/`check` cycle. No manual intervention required unless the same task fails repeatedly (3+ resets -> escalate to user).
|
||||
|
||||
### Consensus-Blocked Handling
|
||||
|
||||
When a produce role reports `consensus_blocked` in its callback:
|
||||
|
||||
```
|
||||
handleCallback receives message with consensus_blocked flag
|
||||
+- Extract: divergence_severity, blocked_round, action_recommendation
|
||||
+- Route by severity:
|
||||
|
|
||||
+- severity = HIGH (rating <= 2 or critical risk)
|
||||
| +- Is this DISCUSS-006 (final sign-off)?
|
||||
| | +- YES -> PAUSE: output warning, wait for user `resume` with decision
|
||||
| | +- NO -> Create REVISION task:
|
||||
| | +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1)
|
||||
| | +- Description includes: divergence details + action items from discuss
|
||||
| | +- blockedBy: none (immediate execution)
|
||||
| | +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2)
|
||||
| | +- If already revised once -> PAUSE, escalate to user
|
||||
| +- Update session: mark task as "revised", log revision chain
|
||||
|
|
||||
+- severity = MEDIUM (rating spread or single low rating)
|
||||
| +- Proceed with warning: include divergence in next task's context
|
||||
| +- Log action items to wisdom/issues.md for downstream awareness
|
||||
| +- Normal handleSpawnNext
|
||||
|
|
||||
+- severity = LOW (minor suggestions only)
|
||||
+- Proceed normally: treat as consensus_reached with notes
|
||||
+- Normal handleSpawnNext
|
||||
```
|
||||
|
||||
**Revision task template** (for HIGH severity):
|
||||
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "<ORIGINAL-ID>-R1",
|
||||
description: "Revision of <ORIGINAL-ID>: address consensus-blocked divergences.\n
|
||||
Session: <session-folder>\n
|
||||
Original artifact: <artifact-path>\n
|
||||
Divergences:\n<divergence-details>\n
|
||||
Action items:\n<action-items-from-discuss>\n
|
||||
InlineDiscuss: <same-round-id>",
|
||||
owner: "<same-role>",
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | Criteria |
|
||||
@@ -179,6 +253,8 @@ When a worker has unexpected status (not completed, not in_progress):
|
||||
| Pipeline completeness | All expected tasks exist per mode |
|
||||
| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
|
||||
| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
|
||||
| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending |
|
||||
| Consensus-blocked routing | HIGH -> revision/pause, MEDIUM -> warn+proceed, LOW -> proceed |
|
||||
|
||||
## Error Handling
|
||||
|
||||
@@ -189,3 +265,7 @@ When a worker has unexpected status (not completed, not in_progress):
|
||||
| All workers still running on resume | Report status, suggest check later |
|
||||
| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
|
||||
| Fast-advance conflict | Coordinator reconciles, no duplicate spawns |
|
||||
| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext |
|
||||
| consensus_blocked HIGH | Create revision task (max 1) or pause for user |
|
||||
| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md |
|
||||
| Revision task also blocked | Escalate to user, pause pipeline |
|
||||
|
||||
@@ -83,7 +83,7 @@ For each uncached angle, call the shared explore subagent:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore: <angle>",
|
||||
prompt: "Explore codebase for: <task-description>
|
||||
|
||||
@@ -105,15 +105,16 @@ Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, de
|
||||
|
||||
**Session files**:
|
||||
```
|
||||
<session-folder>/explorations/ (shared cache, written by explore subagent)
|
||||
+-- cache-index.json
|
||||
+-- explore-<angle>.json
|
||||
|
||||
<session-folder>/plan/
|
||||
+-- exploration-<angle>.json (per angle, from shared cache)
|
||||
+-- explorations-manifest.json (summary)
|
||||
+-- explorations-manifest.json (summary, references ../explorations/)
|
||||
+-- plan.json
|
||||
+-- .task/TASK-*.json
|
||||
```
|
||||
|
||||
Note: exploration files may be symlinked or referenced from `<session-folder>/explorations/` (shared cache location).
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
@@ -118,8 +118,25 @@ Task({
|
||||
```
|
||||
|
||||
**Discuss result handling**:
|
||||
- `consensus_reached` -> include in quality report as final endorsement
|
||||
- `consensus_blocked` -> flag in SendMessage, report specific divergences
|
||||
|
||||
| Verdict | Severity | Action |
|
||||
|---------|----------|--------|
|
||||
| consensus_reached | - | Include as final endorsement in quality report, proceed to Phase 5 |
|
||||
| consensus_blocked | HIGH | **DISCUSS-006 is final sign-off gate**. Phase 5 SendMessage includes structured format. Coordinator always pauses for user decision. |
|
||||
| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed to Phase 5. Coordinator logs to wisdom. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
|
||||
**consensus_blocked SendMessage format**:
|
||||
```
|
||||
[reviewer] QUALITY-001 complete. Discuss DISCUSS-006: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <session-folder>/spec/readiness-report.md
|
||||
Discussion: <session-folder>/discussions/DISCUSS-006-discussion.md
|
||||
```
|
||||
|
||||
> **Note**: DISCUSS-006 HIGH always triggers user pause regardless of revision count, since this is the spec->impl gate.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -19,10 +19,10 @@ Multi-CLI document generation for 4 document types. Each uses parallel or staged
|
||||
|
||||
| Doc Type | Task | Template | Discussion Input | Output |
|
||||
|----------|------|----------|-----------------|--------|
|
||||
| product-brief | DRAFT-001 | templates/product-brief.md | discuss-001-scope.md | spec/product-brief.md |
|
||||
| requirements | DRAFT-002 | templates/requirements-prd.md | discuss-002-brief.md | spec/requirements/_index.md |
|
||||
| architecture | DRAFT-003 | templates/architecture-doc.md | discuss-003-requirements.md | spec/architecture/_index.md |
|
||||
| epics | DRAFT-004 | templates/epics-template.md | discuss-004-architecture.md | spec/epics/_index.md |
|
||||
| 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
|
||||
|
||||
|
||||
@@ -118,10 +118,25 @@ Task({
|
||||
```
|
||||
|
||||
**Discuss result handling**:
|
||||
- `consensus_reached` -> include action items in report
|
||||
- `consensus_blocked` -> flag in SendMessage, include divergence details
|
||||
|
||||
**Report**: doc type, validation status, discuss verdict, average rating, summary, output path.
|
||||
| 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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -77,7 +77,7 @@
|
||||
},
|
||||
"explore": {
|
||||
"spec": "subagents/explore-subagent.md",
|
||||
"type": "Explore",
|
||||
"type": "cli-explore-agent",
|
||||
"callable_by": ["analyst", "planner", "any"],
|
||||
"purpose": "Codebase exploration with centralized cache"
|
||||
}
|
||||
|
||||
@@ -87,12 +87,27 @@ Task({
|
||||
| <name> | <n>/5 |
|
||||
|
||||
### Return Value
|
||||
|
||||
**When consensus_reached**:
|
||||
Return a summary string with:
|
||||
- Verdict: consensus_reached or consensus_blocked
|
||||
- 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
|
||||
@@ -118,9 +133,29 @@ 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**:
|
||||
- Include discuss verdict in Phase 5 report
|
||||
- If `consensus_blocked` with high-severity divergences -> flag in SendMessage to coordinator
|
||||
- Discussion record is written by the subagent, no further action needed
|
||||
|
||||
| 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
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Results were scattered across different directories and never shared. In v4, all
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore <angle>",
|
||||
prompt: `Explore codebase for: <query>
|
||||
@@ -136,7 +136,7 @@ For complex queries, call cli-explore-agent per angle. The calling role determin
|
||||
```
|
||||
# After seed analysis, explore codebase context
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Explore general context",
|
||||
prompt: "Explore codebase for: <topic>\nFocus angle: general\n..."
|
||||
})
|
||||
@@ -149,7 +149,7 @@ Task({
|
||||
# Multi-angle exploration before plan generation
|
||||
for angle in selected_angles:
|
||||
Task({
|
||||
subagent_type: "Explore",
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Explore <angle>",
|
||||
prompt: "Explore codebase for: <task>\nFocus angle: <angle>\n..."
|
||||
})
|
||||
|
||||
Reference in New Issue
Block a user