mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-18 18:48:48 +08:00
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# Phase 3: Enrich — Inject Checkpoints + Build DAG
|
|
|
|
## Objective
|
|
|
|
Build the directed acyclic graph (DAG) with proper edges, auto-inject checkpoint nodes at phase boundaries, and finalize the context_schema.
|
|
|
|
## Workflow
|
|
|
|
### Step 3.1 — Load Nodes
|
|
|
|
Read `design-session/nodes.json`. Get nodes[] list.
|
|
|
|
### Step 3.2 — Build Sequential Edges
|
|
|
|
Start with a linear chain: N-001 → N-002 → N-003 → ...
|
|
|
|
For nodes with the same `parallel_group`:
|
|
- Remove edges between them
|
|
- Add fan-out from the last non-parallel node to all group members
|
|
- Add fan-in from all group members to the next non-parallel node
|
|
|
|
### Step 3.3 — Auto-Inject Checkpoint Nodes
|
|
|
|
Scan the edge list and inject a `checkpoint` node between edges that cross a phase boundary.
|
|
|
|
**Phase boundary detection rules** (inject checkpoint if ANY rule triggers):
|
|
|
|
| Rule | Condition |
|
|
|------|-----------|
|
|
| **Artifact boundary** | Source node has output_ports containing `plan`, `spec`, `analysis`, `review-findings` |
|
|
| **Execution gate** | Target node type is `skill` with executor containing `execute` |
|
|
| **Agent spawn** | Target node type is `agent` |
|
|
| **Long-running** | Target node executor is `workflow-plan`, `spec-generator`, `collaborative-plan-with-file` |
|
|
| **User-defined** | Intent step had `type_hint: checkpoint` |
|
|
| **Post-testing** | Source node executor contains `test-fix` or `integration-test` |
|
|
|
|
**Checkpoint node template**:
|
|
```json
|
|
{
|
|
"id": "CP-<seq>",
|
|
"name": "Checkpoint: <description>",
|
|
"type": "checkpoint",
|
|
"description": "<what was just completed>",
|
|
"auto_continue": true,
|
|
"save_fields": ["session_id", "artifacts", "output_path"]
|
|
}
|
|
```
|
|
|
|
Set `auto_continue: false` for checkpoints that:
|
|
- Precede a user-facing deliverable (spec, plan, review report)
|
|
- Are explicitly requested by the user ("pause and show me")
|
|
|
|
### Step 3.4 — Insert Checkpoint Edges
|
|
|
|
For each injected checkpoint CP-X between edge (A → B):
|
|
- Remove edge A → B
|
|
- Add edges: A → CP-X, CP-X → B
|
|
|
|
### Step 3.5 — Finalize context_schema
|
|
|
|
Aggregate all `{variable}` references found in nodes' args_template strings.
|
|
|
|
For each unique variable name found:
|
|
- Look up from `intent.json#variables` if already defined
|
|
- Otherwise infer: type=string, required=true, description="<variable name>"
|
|
|
|
Produce final `context_schema{}` map.
|
|
|
|
### Step 3.6 — Validate DAG
|
|
|
|
Check:
|
|
- No cycles (topological sort must succeed)
|
|
- No orphan nodes (every node reachable from start)
|
|
- Every non-start node has at least one incoming edge
|
|
- Every non-terminal node has at least one outgoing edge
|
|
|
|
On cycle detection: report error, ask user to resolve.
|
|
|
|
### Step 3.7 — Write Output
|
|
|
|
Write `design-session/dag.json`:
|
|
```json
|
|
{
|
|
"session_id": "<WFD-id>",
|
|
"nodes": [ /* all nodes including injected checkpoints */ ],
|
|
"edges": [
|
|
{ "from": "N-001", "to": "CP-01" },
|
|
{ "from": "CP-01", "to": "N-002" }
|
|
],
|
|
"checkpoints": ["CP-01", "CP-02"],
|
|
"parallel_groups": { "<group-name>": ["N-003", "N-004"] },
|
|
"context_schema": {
|
|
"goal": { "type": "string", "required": true, "description": "..." }
|
|
},
|
|
"topological_order": ["N-001", "CP-01", "N-002"]
|
|
}
|
|
```
|
|
|
|
## Success Criteria
|
|
|
|
- dag.json exists and is valid (no cycles)
|
|
- At least one checkpoint exists (or user explicitly opted out)
|
|
- context_schema contains all variables referenced in args_templates
|
|
- topological_order covers all nodes
|