feat(plugin): per-unit workflows with design discipline support

Units can now specify their own workflow via a `workflow:` frontmatter
field that overrides the intent-level workflow. This enables different
hat sequences for different types of work within the same intent.

Added `design` workflow (planner -> designer -> reviewer) for UI/UX
units that produce design artifacts before implementation. Design as
its own disciplined unit means a human can own design while AI handles
other units.

Changes:
- Add `design` workflow to workflows.yml
- Add `workflow:` field to unit frontmatter template
- Construct resolves per-unit workflow at spawn time, stores in
  unitStates for hat advancement
- Advance/fail skills use unit's workflow instead of global
- Elaborate suggests workflows per discipline (design, adversarial,
  default) during decomposition

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

plugin/skills/advance/SKILL.md

@@ -38,16 +38,20 @@ STATE=$(han keep load iteration.json --quiet)
 ### Step 2: Determine Next Hat (or Handle Completion)
 
 ```javascript
-const workflow = state.workflow || ["planner", "builder", "reviewer"];
-const currentIndex = workflow.indexOf(state.hat);
+// Resolve workflow for this unit: per-unit workflow takes priority, then intent-level fallback
+const currentUnit = state.currentUnit;
+const unitWorkflow = (currentUnit && state.unitStates?.[currentUnit]?.workflow)
+  || state.workflow
+  || ["planner", "builder", "reviewer"];
+const currentIndex = unitWorkflow.indexOf(state.hat);
 const nextIndex = currentIndex + 1;
 
-if (nextIndex >= workflow.length) {
+if (nextIndex >= unitWorkflow.length) {
   // At last hat - check DAG status to determine next action
   // See Steps 2b-2d below
 }
 
-const nextHat = workflow[nextIndex];
+const nextHat = unitWorkflow[nextIndex];
 ```
 
 ### Step 2b: Last Hat Logic (Completion/Loop/Block)
@@ -304,20 +308,26 @@ The integrator specifies which units need rework. For each rejected unit:
 
 ```bash
 source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
-WORKFLOW_HATS=$(echo "$STATE" | han parse json workflow)
-FIRST_HAT=$(echo "$WORKFLOW_HATS" | jq -r '.[0]')
+INTENT_WORKFLOW_HATS=$(echo "$STATE" | han parse json workflow)
 
 # Re-queue each rejected unit
 for UNIT_FILE in $REJECTED_UNITS; do
   update_unit_status "$UNIT_FILE" "pending"
 
-  # Reset hat to first workflow hat in unitStates (teams mode)
+  # Reset hat to first hat of this unit's workflow (per-unit or intent-level fallback)
   UNIT_NAME=$(basename "$UNIT_FILE" .md)
-  STATE=$(echo "$STATE" | han parse json --set "unitStates.${UNIT_NAME}.hat=${FIRST_HAT}" --set "unitStates.${UNIT_NAME}.retries=0")
+  UNIT_WORKFLOW=$(echo "$STATE" | han parse json "unitStates.${UNIT_NAME}.workflow" 2>/dev/null || echo "")
+  [ -z "$UNIT_WORKFLOW" ] || [ "$UNIT_WORKFLOW" = "null" ] && UNIT_WORKFLOW="$INTENT_WORKFLOW_HATS"
+  FIRST_HAT=$(echo "$UNIT_WORKFLOW" | jq -r '.[0]')
+  STATE=$(echo "$STATE" | han parse json \
+    --set "unitStates.${UNIT_NAME}.hat=${FIRST_HAT}" \
+    --set "unitStates.${UNIT_NAME}.retries=0" \
+    --set "unitStates.${UNIT_NAME}.workflow=${UNIT_WORKFLOW}")
 done
 
 # Reset integrator state
-STATE=$(echo "$STATE" | han parse json --set "hat=${FIRST_HAT}" --set "integratorComplete=false")
+GLOBAL_FIRST_HAT=$(echo "$INTENT_WORKFLOW_HATS" | jq -r '.[0]')
+STATE=$(echo "$STATE" | han parse json --set "hat=${GLOBAL_FIRST_HAT}" --set "integratorComplete=false")
 han keep save iteration.json "$STATE"
 
 # Output: "Integrator rejected. Re-queued units: {list}. Run /construct to continue."

plugin/skills/construct/SKILL.md

@@ -393,9 +393,8 @@ Loop over ALL ready units from the DAG (not just one):
 source "${CLAUDE_PLUGIN_ROOT}/lib/dag.sh"
 READY_UNITS=$(find_ready_units "$INTENT_DIR")
 
-# Determine first construction hat
-WORKFLOW_HATS=$(echo "$STATE" | han parse json workflow)
-FIRST_HAT=$(echo "$WORKFLOW_HATS" | jq -r '.[0]')
+# Intent-level workflow (default fallback)
+INTENT_WORKFLOW_HATS=$(echo "$STATE" | han parse json workflow)
 ```
 
 **Include repo URL for cowork**: If operating in a cloned workspace, include the repo URL in each teammate's prompt: "Repository: `<remote-url>`. Clone and checkout `ai-dlc/<intent-slug>` if you don't have local access." This enables teammates to clone independently in cowork mode.
@@ -426,10 +425,35 @@ fi
 update_unit_status "$UNIT_FILE" "in_progress"
 ```
 
-3. **Initialize unit state in `unitStates`**:
+3. **Resolve per-unit workflow** — read the unit's `workflow:` frontmatter field. If present, resolve it to a hat sequence. If absent, fall back to the intent-level workflow:
+
+```bash
+UNIT_WORKFLOW_NAME=$(han parse yaml workflow -r --default "" < "$UNIT_FILE" 2>/dev/null || echo "")
+
+if [ -n "$UNIT_WORKFLOW_NAME" ]; then
+  # Resolve unit-specific workflow
+  UNIT_WORKFLOW_HATS=""
+  if [ -f ".ai-dlc/workflows.yml" ]; then
+    UNIT_WORKFLOW_HATS=$(han parse yaml "${UNIT_WORKFLOW_NAME}.hats" < ".ai-dlc/workflows.yml" 2>/dev/null || echo "")
+  fi
+  if [ -z "$UNIT_WORKFLOW_HATS" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/workflows.yml" ]; then
+    UNIT_WORKFLOW_HATS=$(han parse yaml "${UNIT_WORKFLOW_NAME}.hats" < "${CLAUDE_PLUGIN_ROOT}/workflows.yml" 2>/dev/null || echo "")
+  fi
+  [ -z "$UNIT_WORKFLOW_HATS" ] && UNIT_WORKFLOW_HATS="$INTENT_WORKFLOW_HATS"
+else
+  UNIT_WORKFLOW_HATS="$INTENT_WORKFLOW_HATS"
+fi
+
+FIRST_HAT=$(echo "$UNIT_WORKFLOW_HATS" | jq -r '.[0]')
+```
+
+4. **Initialize unit state in `unitStates`** (includes the resolved workflow):
 
 ```bash
-STATE=$(echo "$STATE" | han parse json --set "unitStates.${UNIT_NAME}.hat=${FIRST_HAT}" --set "unitStates.${UNIT_NAME}.retries=0")
+STATE=$(echo "$STATE" | han parse json \
+  --set "unitStates.${UNIT_NAME}.hat=${FIRST_HAT}" \
+  --set "unitStates.${UNIT_NAME}.retries=0" \
+  --set "unitStates.${UNIT_NAME}.workflow=${UNIT_WORKFLOW_HATS}")
 han keep save iteration.json "$STATE"
 ```
 
@@ -523,8 +547,9 @@ The lead processes auto-delivered teammate messages. Handle each event type:
 When a teammate reports successful completion:
 
 1. Read current hat for this unit from `unitStates.{unit}.hat`
-2. Find current hat's index in the `workflow` array
-3. Determine next hat: `workflow[currentIndex + 1]`
+2. Read this unit's workflow from `unitStates.{unit}.workflow` (per-unit workflow, already resolved at spawn time)
+3. Find current hat's index in the unit's workflow array
+4. Determine next hat: `unitWorkflow[currentIndex + 1]`
 
 **If next hat exists** (not at end of workflow):
 
@@ -878,14 +903,16 @@ The `iteration.json` is extended with `unitStates` for parallel hat tracking:
   "workflow": ["planner", "builder", "reviewer"],
   "teamName": "ai-dlc-my-intent",
   "unitStates": {
-    "unit-01-foundation": { "hat": "reviewer", "retries": 0 },
-    "unit-02-dag-view": { "hat": "builder", "retries": 1 }
+    "unit-01-foundation": { "hat": "reviewer", "retries": 0, "workflow": ["planner", "builder", "reviewer"] },
+    "unit-02-design-dashboard": { "hat": "designer", "retries": 0, "workflow": ["planner", "designer", "reviewer"] },
+    "unit-03-dag-view": { "hat": "builder", "retries": 1, "workflow": ["planner", "builder", "reviewer"] }
   }
 }
 ```
 
 - `hat`: Current hat for this specific unit
 - `retries`: Number of reviewer rejection cycles (max 3 before escalating to blocked)
+- `workflow`: The hat sequence for this unit (resolved from unit frontmatter `workflow:` field, falling back to intent-level workflow)
 - Units are added when spawned, removed when completed
 
 ---

plugin/skills/elaborate/SKILL.md

@@ -480,7 +480,20 @@ Do NOT ask the user whether to decompose. Assess the complexity from the domain
 
 1. **Units MUST NOT span dependency boundaries.** If a piece of work depends on another piece being done first, those are two separate units with an explicit `depends_on` edge. This applies regardless of change strategy (`unit` or `intent`). A unit that contains both "set up the database schema" and "build the API that uses it" is a bad unit — those are two units where the API unit depends on the schema unit.
 
-2. **Units MUST NOT span domains.** A unit has exactly one discipline (frontend, backend, api, documentation, devops, etc.). No unit should mix frontend and backend work, or API and documentation, etc. If a feature needs both a backend endpoint and a frontend view, those are two units — the frontend unit `depends_on` the backend unit.
+2. **Units MUST NOT span domains.** A unit has exactly one discipline (frontend, backend, api, documentation, devops, design, etc.). No unit should mix frontend and backend work, or API and documentation, etc. If a feature needs both a backend endpoint and a frontend view, those are two units — the frontend unit `depends_on` the backend unit.
+
+3. **Design work is its own unit.** If a feature needs UI/UX design work (mockups, component design, interaction flows), create a separate unit with `discipline: design` and `workflow: design`. The design workflow runs `planner → designer → reviewer`. Frontend implementation units should `depends_on` the design unit so builders have finalized designs to implement against. This also enables a human to own the design unit while AI handles other units.
+
+**Per-unit workflow suggestions:** Different units may benefit from different workflows based on their discipline or risk profile. When decomposing, suggest an appropriate workflow for each unit:
+
+| Discipline / Concern | Suggested Workflow | Rationale |
+|---|---|---|
+| `backend`, `api`, `devops`, `documentation` | `default` (planner → builder → reviewer) | Standard implementation cycle |
+| `design` | `design` (planner → designer → reviewer) | Design artifacts need design hat, not builder |
+| Security-sensitive units | `adversarial` (planner → builder → red-team → blue-team → reviewer) | Adversarial testing for auth, crypto, data handling |
+| Units without a clear workflow need | (omit `workflow:` field) | Inherits the intent-level workflow |
+
+Set the `workflow:` frontmatter field on units that need a non-default workflow. Omit it (or leave empty) for units that should use the intent-level workflow.
 
 Define each unit with **enough detail that a builder with zero prior context builds the right thing**:
 
@@ -777,7 +790,8 @@ problem space.}
 status: pending
 depends_on: []
 branch: ai-dlc/{intent-slug}/NN-{unit-slug}
-discipline: {discipline}  # frontend, backend, api, documentation, devops, etc.
+discipline: {discipline}  # frontend, backend, api, documentation, devops, design, etc.
+workflow: ""  # Per-unit workflow override (optional — omit or leave empty to use intent-level workflow)
 ticket: ""  # Ticketing provider ticket key (auto-populated if ticketing provider configured)
 ---
 

plugin/skills/fail/SKILL.md

@@ -35,16 +35,20 @@ STATE=$(han keep load iteration.json --quiet)
 ### Step 2: Determine Previous Hat
 
 ```javascript
-const workflow = state.workflow || ["planner", "builder", "reviewer"];
-const currentIndex = workflow.indexOf(state.hat);
+// Resolve workflow for this unit: per-unit workflow takes priority, then intent-level fallback
+const currentUnit = state.currentUnit;
+const unitWorkflow = (currentUnit && state.unitStates?.[currentUnit]?.workflow)
+  || state.workflow
+  || ["planner", "builder", "reviewer"];
+const currentIndex = unitWorkflow.indexOf(state.hat);
 const prevIndex = currentIndex - 1;
 
 if (prevIndex < 0) {
   // Already at first hat - cannot go back
-  return "Cannot fail before the first hat (planner).";
+  return "Cannot fail before the first hat.";
 }
 
-const prevHat = workflow[prevIndex];
+const prevHat = unitWorkflow[prevIndex];
 ```
 
 ### Step 3: Document Why

plugin/workflows.yml

@@ -16,6 +16,10 @@ adversarial:
   description: Security-focused with Red/Blue team phases
   hats: [planner, builder, red-team, blue-team, reviewer]
 
+design:
+  description: Design workflow for UI/UX units that produce design artifacts
+  hats: [planner, designer, reviewer]
+
 hypothesis:
   description: Scientific debugging for investigating bugs
   hats: [observer, hypothesizer, experimenter, analyst]