Skip to content

Commit 4e448dd

Browse files
jwaldripclaude
jwaldrip
and
claude
committed
feat: add NFR prompts, cross-cutting concerns, integrator hat, delivery prompts, and /refine skill
- Add non-functional requirements prompt in elaboration Phase 4 - Add cross-cutting concern analysis as Phase 5.5 in elaboration - Replace Phase 7 handoff with fork: construct now or open spec PR - Add integrator hat for intent-level verification after all units merge - Add integrator logic to advance (Step 2e) and construct (Step 5a) - Add delivery prompt (PR/MR or manual) at end of construction - Add /refine skill for mid-construction spec amendment without losing progress Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 38c6440 commit 4e448dd

File tree

5 files changed

+844
-11
lines changed

5 files changed

+844
-11
lines changed

‎plugin/hats/integrator.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
name: "Integrator"
3+
description: Final intent-level validation that verifies all units work together on the merged intent branch
4+
---
5+
6+
# Integrator
7+
8+
## Overview
9+
10+
The Integrator performs final validation on the **merged intent branch** after all units have been completed and merged. Unlike the Reviewer (which validates individual units), the Integrator verifies that all units work together as a cohesive whole and that intent-level success criteria are satisfied.
11+
12+
## Parameters
13+
14+
- **Intent Criteria**: {criteria} - Intent-level success criteria to verify
15+
- **Units**: {units} - List of completed units and their individual criteria
16+
- **Intent Branch**: {branch} - The merged intent branch containing all unit work
17+
18+
## Prerequisites
19+
20+
### Required Context
21+
22+
- All units have been completed and approved by their Reviewers
23+
- All unit branches have been merged into the intent branch
24+
- The intent branch represents the combined state of all units
25+
26+
### Required State
27+
28+
- Intent branch checked out and accessible
29+
- All unit artifacts available in `.ai-dlc/{intent-slug}/`
30+
- Intent-level success criteria loaded from `intent.md`
31+
32+
## Steps
33+
34+
1. Verify merged state integrity
35+
- You MUST confirm you are on the intent branch (`ai-dlc/{intent-slug}/main`)
36+
- You MUST verify all unit branches have been merged
37+
- You MUST check for merge conflicts or incomplete merges
38+
- You MUST run `git log --oneline` to confirm all unit merge commits are present
39+
- **Validation**: Clean merged state with all units present
40+
41+
2. Run full backpressure suite
42+
- You MUST run the full test suite on the merged codebase
43+
- You MUST run lint checks across all changed files
44+
- You MUST run type checks if applicable
45+
- You MUST verify no regressions from unit interactions
46+
- **Validation**: All tests pass, no lint errors, no type errors
47+
48+
3. Verify intent-level success criteria
49+
- You MUST read intent-level success criteria from `intent.md`
50+
- You MUST check each intent-level criterion individually
51+
- You MUST run verification commands, not just read code
52+
- You MUST distinguish between unit-level criteria (already verified) and intent-level criteria (your responsibility)
53+
- **Validation**: Each intent-level criterion marked pass/fail with evidence
54+
55+
4. Verify cross-unit integration
56+
- You MUST check that units interact correctly at their boundaries
57+
- You MUST verify shared state, APIs, or data flows between units work end-to-end
58+
- You MUST check for conflicting patterns, duplicate code, or inconsistent conventions across units
59+
- You SHOULD run integration tests if they exist
60+
- You SHOULD verify that cross-cutting concerns (documented as intent-level criteria) are consistently applied
61+
- **Validation**: Units work together, no integration gaps
62+
63+
5. Check for emergent issues
64+
- You MUST look for problems that only appear when units are combined
65+
- You SHOULD check for performance regressions from combined changes
66+
- You SHOULD verify that the overall user experience flows correctly across unit boundaries
67+
- You MUST identify any missing glue code or wiring between units
68+
- **Validation**: No emergent issues from unit combination
69+
70+
6. Make decision
71+
- If all intent-level criteria pass, integration checks pass, and no emergent issues: **ACCEPT**
72+
- If issues found: **REJECT** with specific units that need rework and clear reasons
73+
- You MUST document decision clearly
74+
- You MUST NOT accept if intent-level criteria are not met
75+
- You MUST specify which units need rework when rejecting (not just "fix it")
76+
- **Validation**: Clear ACCEPT/REJECT with rationale
77+
78+
### On ACCEPT
79+
80+
Report to the orchestrator:
81+
```
82+
INTEGRATOR DECISION: ACCEPT
83+
84+
All intent-level criteria verified:
85+
- [x] {criterion 1} — {evidence}
86+
- [x] {criterion 2} — {evidence}
87+
88+
Cross-unit integration: PASS
89+
Backpressure suite: PASS
90+
```
91+
92+
### On REJECT
93+
94+
Report to the orchestrator with specific units to re-queue:
95+
```
96+
INTEGRATOR DECISION: REJECT
97+
98+
Failed criteria:
99+
- [ ] {criterion} — {what failed and why}
100+
101+
Units requiring rework:
102+
- {unit-NN-slug}: {specific issue to fix}
103+
- {unit-MM-slug}: {specific issue to fix}
104+
105+
Integration issues:
106+
- {description of cross-unit problem}
107+
```
108+
109+
## Success Criteria
110+
111+
- [ ] Merged intent branch is clean (no conflicts, all units present)
112+
- [ ] Full test suite passes on merged codebase
113+
- [ ] Lint and type checks pass
114+
- [ ] All intent-level success criteria verified (pass/fail for each)
115+
- [ ] Cross-unit integration verified (boundaries, shared state, data flows)
116+
- [ ] No emergent issues from unit combination
117+
- [ ] Clear decision: ACCEPT or REJECT
118+
- [ ] If REJECT: specific units identified for rework with actionable feedback
119+
120+
## Error Handling
121+
122+
### Error: Merge Conflicts on Intent Branch
123+
124+
**Symptoms**: Units merged but conflicts remain unresolved
125+
126+
**Resolution**:
127+
1. You MUST NOT attempt to resolve merge conflicts
128+
2. You MUST REJECT and identify the conflicting units
129+
3. Specify which units need to be re-built with awareness of each other's changes
130+
4. The orchestrator will re-queue those units
131+
132+
### Error: Tests Pass Individually But Fail Combined
133+
134+
**Symptoms**: Unit tests passed during review but fail on merged branch
135+
136+
**Resolution**:
137+
1. You MUST identify which units' tests are conflicting
138+
2. You MUST determine root cause (shared state, import conflicts, etc.)
139+
3. You MUST REJECT with the specific units that need rework
140+
4. Include the failing test output in your rejection feedback
141+
142+
### Error: Missing Integration Between Units
143+
144+
**Symptoms**: Units work independently but aren't wired together
145+
146+
**Resolution**:
147+
1. You MUST identify the missing wiring (e.g., component not imported, route not registered)
148+
2. You MUST REJECT and specify which unit should own the integration
149+
3. If the gap is a new concern, recommend it be added to the unit spec
150+
151+
## Related Hats
152+
153+
- **Reviewer**: Validates individual units; Integrator validates the combined result
154+
- **Builder**: May need to rework units if Integrator rejects
155+
- **Planner**: May need to re-plan units if integration issues require architectural changes

‎plugin/skills/advance/SKILL.md‎

Lines changed: 171 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,13 @@ READY_COUNT=$(echo "$DAG_SUMMARY" | han parse json readyCount -r)
111111

112112
```javascript
113113
if (dagSummary.allComplete) {
114-
// ALL UNITS COMPLETE - Mark intent as done
114+
// ALL UNITS COMPLETE - Check if integrator has run
115+
if (!state.integratorComplete) {
116+
// Spawn integrator on the intent branch
117+
// See Step 2e below
118+
return spawnIntegrator();
119+
}
120+
// Integrator passed - Mark intent as done
115121
state.status = "complete";
116122
// han keep save iteration.json '<updated JSON>'
117123
// Output completion summary (see Step 5)
@@ -157,6 +163,104 @@ This replaces the sequential "loop back to builder" behavior when Agent Teams is
157163

158164
**Without Agent Teams:** The existing behavior (reset hat to builder, let `/construct` pick next unit) continues unchanged.
159165

166+
### Step 2e: Integrator Spawning (When All Units Complete)
167+
168+
When `dagSummary.allComplete` is true and `state.integratorComplete` is not true, spawn the Integrator instead of marking the intent complete.
169+
170+
**The Integrator is NOT a per-unit hat** — it does not appear in the workflow sequence. It runs once on the merged intent branch after all units pass their per-unit workflows.
171+
172+
1. Set state to indicate integrator is running:
173+
174+
```bash
175+
STATE=$(echo "$STATE" | han parse json --set "hat=integrator")
176+
han keep save iteration.json "$STATE"
177+
```
178+
179+
2. Load integrator hat instructions:
180+
181+
```bash
182+
HAT_FILE=""
183+
if [ -f ".ai-dlc/hats/integrator.md" ]; then
184+
HAT_FILE=".ai-dlc/hats/integrator.md"
185+
elif [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/hats/integrator.md" ]; then
186+
HAT_FILE="${CLAUDE_PLUGIN_ROOT}/hats/integrator.md"
187+
fi
188+
189+
HAT_INSTRUCTIONS=""
190+
if [ -n "$HAT_FILE" ]; then
191+
HAT_INSTRUCTIONS=$(sed '1,/^---$/d' "$HAT_FILE" | sed '1,/^---$/d')
192+
fi
193+
```
194+
195+
3. Spawn integrator subagent on the **intent worktree** (not a unit worktree):
196+
197+
```javascript
198+
Task({
199+
subagent_type: "general-purpose",
200+
description: `integrator: ${intentSlug}`,
201+
prompt: `
202+
Execute the Integrator role for intent ${intentSlug}.
203+
204+
## Your Role: Integrator
205+
${HAT_INSTRUCTIONS}
206+
207+
## CRITICAL: Work on Intent Branch
208+
**Worktree path:** /tmp/ai-dlc-${intentSlug}/
209+
**Branch:** ai-dlc/${intentSlug}/main
210+
211+
You MUST:
212+
1. cd /tmp/ai-dlc-${intentSlug}/
213+
2. Verify you're on the intent branch (not a unit branch)
214+
3. This branch contains ALL merged unit work
215+
216+
## Intent-Level Success Criteria
217+
${intentCriteria}
218+
219+
## Completed Units
220+
${completedUnitsList}
221+
222+
Verify that all units work together and intent-level criteria are met.
223+
Report ACCEPT or REJECT with specific details.
224+
`
225+
})
226+
```
227+
228+
4. Handle integrator result:
229+
230+
**If ACCEPT:**
231+
```bash
232+
STATE=$(echo "$STATE" | han parse json --set "integratorComplete=true" --set "status=complete")
233+
han keep save iteration.json "$STATE"
234+
# Proceed to Step 5 (completion summary)
235+
```
236+
237+
**If REJECT:**
238+
239+
The integrator specifies which units need rework. For each rejected unit:
240+
241+
```bash
242+
source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
243+
WORKFLOW_HATS=$(echo "$STATE" | han parse json workflow)
244+
FIRST_HAT=$(echo "$WORKFLOW_HATS" | jq -r '.[0]')
245+
246+
# Re-queue each rejected unit
247+
for UNIT_FILE in $REJECTED_UNITS; do
248+
update_unit_status "$UNIT_FILE" "pending"
249+
250+
# Reset hat to first workflow hat in unitStates (teams mode)
251+
UNIT_NAME=$(basename "$UNIT_FILE" .md)
252+
STATE=$(echo "$STATE" | han parse json --set "unitStates.${UNIT_NAME}.hat=${FIRST_HAT}" --set "unitStates.${UNIT_NAME}.retries=0")
253+
done
254+
255+
# Reset integrator state
256+
STATE=$(echo "$STATE" | han parse json --set "hat=${FIRST_HAT}" --set "integratorComplete=false")
257+
han keep save iteration.json "$STATE"
258+
259+
# Output: "Integrator rejected. Re-queued units: {list}. Run /construct to continue."
260+
```
261+
262+
The re-queued units will be picked up on the next `/construct` cycle through the normal DAG-based unit selection.
263+
160264
### Step 3: Update State
161265

162266
```bash
@@ -210,10 +314,71 @@ Intent branch ready: ai-dlc/{intent-slug}/main → ${DEFAULT_BRANCH}
210314
Create PR: gh pr create --base ${DEFAULT_BRANCH} --head ai-dlc/{intent-slug}/main
211315
```
212316

213-
### Next Steps
317+
Then ask the user how to deliver using `AskUserQuestion`:
318+
319+
```json
320+
{
321+
"questions": [{
322+
"question": "How would you like to deliver this intent?",
323+
"header": "Delivery",
324+
"options": [
325+
{"label": "Open PR/MR for delivery", "description": "Create a pull/merge request to merge into the default branch"},
326+
{"label": "I'll handle it", "description": "Just show me the branch details"}
327+
],
328+
"multiSelect": false
329+
}]
330+
}
331+
```
332+
333+
### If PR/MR:
334+
335+
1. Push intent branch to remote (if not already):
336+
337+
```bash
338+
INTENT_BRANCH="ai-dlc/${INTENT_SLUG}/main"
339+
git push -u origin "$INTENT_BRANCH" 2>/dev/null || true
340+
```
341+
342+
2. Create PR/MR:
343+
344+
```bash
345+
gh pr create \
346+
--title "${INTENT_TITLE}" \
347+
--base "$DEFAULT_BRANCH" \
348+
--head "$INTENT_BRANCH" \
349+
--body "$(cat <<EOF
350+
## Summary
351+
${PROBLEM_SECTION}
352+
353+
${SOLUTION_SECTION}
354+
355+
## Test Plan
356+
${SUCCESS_CRITERIA_AS_CHECKLIST}
357+
358+
## Changes
359+
${COMPLETED_UNITS_AS_CHANGE_LIST}
360+
361+
---
362+
*Built with [AI-DLC](https://ai-dlc.dev)*
363+
EOF
364+
)"
365+
```
366+
367+
3. Output the PR URL.
368+
369+
### If manual:
370+
371+
```
372+
Intent branch ready: ai-dlc/{intent-slug}/main → ${DEFAULT_BRANCH}
373+
374+
To merge:
375+
git checkout ${DEFAULT_BRANCH}
376+
git merge --no-ff ai-dlc/{intent-slug}/main
377+
378+
To create PR manually:
379+
gh pr create --base ${DEFAULT_BRANCH} --head ai-dlc/{intent-slug}/main
214380
215-
1. **Review changes** - Check the work on branch `ai-dlc/{intent-slug}/main`
216-
2. **Create PR** - `gh pr create --base ${DEFAULT_BRANCH} --head ai-dlc/{intent-slug}/main`
217-
3. **Clean up worktrees** - `git worktree remove /tmp/ai-dlc-{intent-slug}`
218-
4. **Start new task** - Run `/reset` to clear state, then `/elaborate`
381+
To clean up:
382+
git worktree remove /tmp/ai-dlc-{intent-slug}
383+
/reset
219384
```

0 commit comments

Comments
 (0)