@jabworks/condux 0.2.0 → 0.3.0

package/skills/preflight/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: preflight
+description: "Lightweight \"am I actually done?\" checklist before calling /finalize. Prevents premature completion — catches skipped steps, missing behavior, and silent regressions. Runs before /finalize at the end of every /workflow tier (automatic on SMALL; the recommended CP-2 choice on MEDIUM/LARGE). Also trigger standalone on \"verify this\", \"am I done?\", or \"preflight\". Not for executing typecheck, lint, format, and tests; use finalize."
+argument-hint: "[task or feature name]"
+---
+
+# /preflight
+
+Before you call done — actually check that you're done.
+
+## Usage
+
+```
+/preflight              # check current task
+/preflight <task name>  # explicit scope
+```
+
+## How It Works
+
+Run through this checklist. Every item must be answered honestly — not optimistically.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                        PREFLIGHT                                │
+├──────────────────────────────────────────────────────────────────┤
+│  □ REQUIREMENTS MET                                             │
+│    Can I point to each requirement and show it's implemented?   │
+│    Not "I think so" — actually trace it.                        │
+│                                                                  │
+│  □ PLAN STEPS COMPLETE (LARGE tasks)                           │
+│    Is every task card in the plan marked done?                  │
+│    Any skipped or partially completed steps?                    │
+│                                                                  │
+│  □ EDGE CASES HANDLED                                           │
+│    What happens with: empty input, null, zero, max value,       │
+│    concurrent requests, missing permissions, expired tokens?    │
+│    Have the relevant ones been considered?                      │
+│                                                                  │
+│  □ SPEC DRIFT (when a spec exists)                              │
+│    Locate specs/<slug>/ (same lookup as the /workflow router).  │
+│    Compare the diff against each existing concern file —        │
+│    both directions count. No spec → N/A, no commentary.         │
+│                                                                  │
+│  □ NO REGRESSIONS INTRODUCED                                    │
+│    Did the change touch anything outside the stated scope?      │
+│    Could it affect adjacent features or shared utilities?       │
+│                                                                  │
+│  □ NOTHING LEFT BEHIND                                          │
+│    No console.log, no debug code, no TODO comments that         │
+│    weren't there before, no commented-out blocks.               │
+│                                                                  │
+│  □ READY FOR FINALIZE                                           │
+│    All the above are yes → call /finalize                       │
+│    Any are no → fix first, then re-check                        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Drift Check
+
+Runs only when the task has a spec. Locate it the way the `/workflow`
+router does: detect the package root, then check both scopes —
+`<package-root>/specs/<slug>/` and `<git-root>/specs/<slug>/` (fuzzy
+kebab-case match of the task subject; nearest match wins). No spec dir →
+mark `N/A` and move on, without comment.
+
+Compare the implementation against each concern file that exists — a
+missing or scaffold-only file makes no claim, skip it:
+
+| Concern file | Check the implementation against |
+|---|---|
+| `api.md` | contracts touched — shapes, error forms, external calls |
+| `fields.md` | source-to-UI mappings and transformations |
+| `quirks.md` | edge cases and failure modes the spec says are handled |
+| `implementation.md` | key files and patterns the spec says to follow |
+
+**Both directions count.** Code that violates a spec'd contract is drift;
+a spec gone stale because the implementation legitimately evolved is drift
+too. Scope stays at the *task's* spec dir — this is never a whole-`specs/`
+staleness audit.
+
+**Findings are a soft gate.** Report each divergence in the findings table
+(see Output) and let the user decide per finding — one batched question,
+not one at a time:
+
+- **fix code** — the spec is right; the implementation changes
+- **update spec** — reality is right; update the spec file visibly (never
+  silently — that's technical-spec's standing rule)
+- **accept** — knowingly ship the divergence; record it in the output
+
+Drift never blocks `/finalize` by itself — but an unreported divergence is
+a preflight failure like any other.
+
+## Common Rationalizations
+
+| Claim                                          | Reality                                                  |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| "I tested it manually, it works"               | Manual testing doesn't substitute for /finalize. Run it. |
+| "I'll clean up the debug logs in a follow-up"  | They ship. Clean up now.                                 |
+| "The edge cases are unlikely"                  | They happen in production. Consider them now.            |
+| "The plan steps were mostly done"              | Mostly done is not done.                                 |
+| "I only changed one line, nothing could break" | One-line changes cause regressions too.                  |
+
+## Output
+
+```
+## Preflight: [task name]
+
+□ Requirements met     ✓ / ✗ [notes]
+□ Plan steps complete  ✓ / ✗ [notes]  (or N/A for SMALL/MEDIUM)
+□ Edge cases handled   ✓ / ✗ [notes]
+□ Spec drift           ✓ / ✗ / N/A [notes]  (N/A = no spec for this task)
+□ No regressions       ✓ / ✗ [notes]
+□ Nothing left behind  ✓ / ✗ [notes]
+
+→ Ready for /finalize  [YES / NO — list blockers if NO]
+```
+
+When Spec drift is ✗, list the findings and collect one decision per row:
+
+```
+| concern file | spec says | implementation does | decision |
+|---|---|---|---|
+| api.md | error shape {code, msg} | throws bare string | fix code / update spec / accept |
+```
+
+Accepted findings stay in the output — they ship knowingly, not silently.
+
+If any item is NO: fix it first. Do not proceed to /finalize with known gaps.

package/skills/preflight/evals/trigger_eval.json

@@ -0,0 +1,26 @@
+[
+  { "query": "am I done?", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "verify this", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "did I miss anything before finalize", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "preflight check", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "is the feature actually complete", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "check all the requirements are met", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "any debug logs left behind?", "should_trigger": true, "expected_skill": "preflight", "accept": ["code-review"] },
+  { "query": "did we cover the edge cases", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "ready to finalize?", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "are all the plan steps done", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "I tested it manually, ship it", "should_trigger": true, "expected_skill": "preflight", "accept": ["finalize"] },
+  { "query": "only changed one line, can we skip the checks", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "done-ness check b4 finalize", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "double check my work on this feature", "should_trigger": true, "expected_skill": "preflight", "accept": ["code-review"] },
+  { "query": "run typecheck and the tests now", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "review the diff quality", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "am I done shipping this skill to the marketplace", "should_trigger": true, "expected_skill": "toolkit-change-control" },
+  { "query": "does the code still match the spec", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "check for spec drift", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "did the implementation diverge from what we specced", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "update the spec with what we built", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "verify the deployment is healthy in prod", "should_trigger": false, "expected_skill": null },
+  { "query": "airplane preflight checklist template", "should_trigger": false, "expected_skill": null },
+  { "query": "double check this math for me", "should_trigger": false, "expected_skill": null }
+]

package/skills/root-cause-analysis/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: root-cause-analysis
+description: "Enforces root-cause-first bug investigation — read the error, reproduce it, trace the data flow backward. Never propose a solution before the investigation phase completes. Trigger the moment debugging starts — never proactively — and always before any fix is proposed or any change is made."
+argument-hint: "<error message or bug description>"
+effort: high
+---
+
+# /root-cause-analysis
+
+Investigate first. Fix second. Always.
+
+## Usage
+
+```
+/root-cause-analysis $ARGUMENTS
+/root-cause-analysis "TypeError: cannot read property of undefined in checkout"
+```
+
+## The Four Phases
+
+Run in order. Don't skip ahead.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Phase 1: ROOT CAUSE INVESTIGATION                              │
+│  - Spec check FIRST: detect package root (walk up from CWD to  │
+│    git root, find nearest package manifest). Check:            │
+│      <package-root>/specs/ and <git-root>/specs/               │
+│    Match the failing feature/domain (fuzzy kebab-case).         │
+│    If found, read quirks.md, api.md, fields.md,               │
+│    implementation.md. Note any behavior contradicting the spec.│
+│  - Read the full error message and stack trace                  │
+│  - Reproduce the failure (confirm it's real, not stale)        │
+│  - Check recent changes: git log since last known good state    │
+│  - Trace data flow backward from the failure point             │
+│                                                                  │
+│  Phase 2: PATTERN ANALYSIS                                      │
+│  - Find working examples of the same pattern in the codebase   │
+│  - Compare broken path vs working path completely               │
+│  - Identify the single difference                               │
+│                                                                  │
+│  Phase 3: HYPOTHESIS + SINGLE-VARIABLE TEST                     │
+│  - Form one hypothesis                                          │
+│  - Design a test that proves or disproves it                    │
+│  - Change exactly one thing                                     │
+│                                                                  │
+│  Phase 4: IMPLEMENT THE FIX                                     │
+│  - Write a failing test first (if /test-first-development is active)              │
+│  - Apply the single targeted fix                                │
+│  - Verify the fix resolves the root cause, not symptoms        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Hard Rules
+
+**Never propose a solution in Phase 1.** Investigation comes first — no exceptions.
+
+**Three strikes.** If three independent fixes have all failed:
+- Stop patching.
+- Step back and question whether the problem is where you think it is.
+- Ask the user before continuing.
+
+**One variable at a time.** Multiple simultaneous changes make it impossible to know what fixed what.
+
+## Red Flags — Stop and Reassess
+
+```
+✗ Proposing solutions before reading the full stack trace
+✗ Changing multiple things at once "to see what works"
+✗ Continuing to patch after 3 failed attempts
+✗ Treating a symptom as the root cause
+✗ Skipping reproduction ("it's obvious what the problem is")
+```
+
+## Integration with Condux
+
+- **Phase 4 + /test-first-development active**: write a failing test before the fix
+- **After fixing**: run `/preflight` to confirm nothing regressed
+- **Bug reveals architectural issue**: escalate to `/discovery` before patching further
+- **Multiple unrelated failures**: if 2+ failures are independent (different
+  files, no shared cause), use `subagent-deployment` to fix them
+  concurrently instead of one at a time

package/skills/root-cause-analysis/evals/trigger_eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "checkout crashes on empty cart", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "TypeError: cannot read property of undefined in the orders page", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "why does this test fail intermittently", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "debug the 500 on the orders endpoint", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "the app broke after the last deploy", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "trace this bug to its root cause", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "3 fixes failed already, whats the next idea", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "reproduce this issue first before touching anything", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "just patch it quickly, we can investigate later", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "systematic debugging pls", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "regression after the refactor, find the cause", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "why is prod slower since tuesday", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "what does this stack trace mean", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "two unrelated failures showed up, split the work", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "add error handling to this function", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "fix the bug — I already know exactly whats wrong", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "my toolkit skill isnt triggering", "should_trigger": true, "expected_skill": "toolkit-debugging-playbook" },
+  { "query": "dist looks out of date vs skills/", "should_trigger": true, "expected_skill": "toolkit-debugging-playbook" },
+  { "query": "bug bounty writeup for the blog", "should_trigger": false, "expected_skill": null },
+  { "query": "debug my printer connection", "should_trigger": false, "expected_skill": null }
+]

package/skills/subagent-deployment/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: subagent-deployment
+description: "Fan out 2+ independent tasks across named agents (explorer/researcher/planner/coder) in a single message when they share no files and no dependencies. Use for ad-hoc independent work discovered outside a formal plan — unrelated bug fixes, parallel lookups, independent small tasks. Trigger when two or more genuinely independent tasks are on the table — nothing shared between them, no ordering — and any mix of named agents fits. Not for executing an ordered plan task-by-task (that's subagent-execution)."
+argument-hint: "<list of independent tasks>"
+---
+
+# /subagent-deployment
+
+Deploy independent agents at once, not one at a time. For genuinely unrelated work — not for executing an ordered plan.
+
+## Usage
+
+```
+/subagent-deployment $ARGUMENTS
+```
+
+## Core Principle
+
+**Deploy together only when genuinely independent.** Two tasks are independent when neither needs the other's output, they touch no shared files, and integrating both outcomes afterward is unambiguous. Check `references/safety-checklist.md` before every deployment — it's the one place this logic lives; nothing else in condux restates it.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                     SUBAGENT DEPLOYMENT                         │
+├──────────────────────────────────────────────────────────────────┤
+│  Step 1: IDENTIFY INDEPENDENT DOMAINS                           │
+│  Group the tasks in front of you by what's actually             │
+│  independent — different files, different subsystems,           │
+│  different unrelated bugs. Related tasks (fixing one might      │
+│  fix another) stay together as ONE task, not split.             │
+│                                                                  │
+│  Step 2: RUN THE CHECKLIST                                      │
+│  For each candidate pair/group, check                           │
+│  references/safety-checklist.md. Any box unchecked → that       │
+│  group runs sequentially, not together.                         │
+│                                                                  │
+│  Step 3: PICK THE AGENT PER TASK                                │
+│  Read-only lookup → explorer or researcher.                     │
+│  Isolated implementation/fix → coder.                           │
+│  Never a generic subagent with an injected prompt — only        │
+│  condux's four named agents.                                    │
+│                                                                  │
+│  Step 4: DISPATCH TOGETHER                                      │
+│  Issue every checklist-cleared dispatch in the SAME message —   │
+│  that's what makes them run concurrently. One dispatch per      │
+│  response = sequential, regardless of intent.                   │
+│                                                                  │
+│  Step 5: RETRIEVE AND INTEGRATE                                 │
+│  Read every result. Confirm no unexpected overlap or            │
+│  conflict before treating the batch as done. You are            │
+│  responsible for coherence — agents don't see each other's      │
+│  work.                                                          │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Constructing Deployment Prompts
+
+Each prompt in the batch needs the same rigor as any single dispatch:
+
+```
+Good prompt:
+  ✓ One clearly scoped problem/task, self-contained
+  ✓ All context needed to understand it (no shared session history)
+  ✓ Constraints (which files it may touch, what NOT to do)
+  ✓ Expected output format
+
+Bad prompt:
+  ✗ "Look into the failing tests" (too broad, not scoped to one domain)
+  ✗ Assumes the agent has seen the other tasks in the batch
+  ✗ No stated output format
+```
+
+## Example
+
+```
+Three unrelated test files failing after a refactor:
+  - agent-tool-abort.test.ts (timing issue)
+  - batch-completion-behavior.test.ts (event structure bug)
+  - tool-approval-race-conditions.test.ts (execution count wrong)
+
+Checklist: different files, nothing shared, no dependency between them → clear.
+
+Dispatch all three condux:coder agents in the same message:
+  Agent 1 (coder): "Fix the 3 failures in agent-tool-abort.test.ts: ..."
+  Agent 2 (coder): "Fix the 2 failures in batch-completion-behavior.test.ts: ..."
+  Agent 3 (coder): "Fix the 1 failure in tool-approval-race-conditions.test.ts: ..."
+```
+
+## What Does NOT Happen
+
+```
+✗ Splitting related tasks apart just to parallelize them
+✗ Dispatching a generic subagent instead of a named one
+✗ Issuing dispatches one response at a time and calling it "parallel"
+✗ Skipping the safety checklist because the tasks "look independent"
+✗ Using this to execute an ordered plan task-by-task (use
+  /subagent-execution instead — this skill is for ad-hoc,
+  not-yet-planned independent work)
+```
+
+## See Also
+
+- `references/safety-checklist.md` — the canonical parallel-dispatch safety checklist (also referenced by `subagent-execution` and `spawn-rules.md` — this is the one place it lives)
+- `subagent-execution` — for executing an ordered plan task-by-task; also uses this checklist internally when a plan's tasks are independent

package/skills/subagent-deployment/evals/trigger_eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "fix these 3 unrelated failing test files at once", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "in parallel: look up the stripe api and explore the auth module", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "two independent bugs in different packages, handle both", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "fan out this research across agents", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "batch these lookups together", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "run these together, theyre totally unrelated", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "is it safe to parallelize these two tasks", "should_trigger": true, "expected_skill": "subagent-deployment", "kind": "in-context" },
+  { "query": "spawn a generic subagent with this custom prompt", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "dispatch all three coders in the same message", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "these fixes are related, one might fix the other — split them anyway?", "should_trigger": true, "expected_skill": "subagent-deployment", "kind": "in-context" },
+  { "query": "kick off explorer and researcher while I keep working", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "whats the safety checklist for parallel dispatch", "should_trigger": true, "expected_skill": "subagent-deployment", "kind": "in-context" },
+  { "query": "integrate the results from the agent batch", "should_trigger": true, "expected_skill": "subagent-deployment", "kind": "in-context" },
+  { "query": "independant tasks, no shared files, go", "should_trigger": true, "expected_skill": "subagent-deployment" },
+  { "query": "execute plan tasks 1 through 6 in order with agents", "should_trigger": true, "expected_skill": "subagent-execution" },
+  { "query": "one small task, just do it yourself", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "deploy the app to production", "should_trigger": false, "expected_skill": null },
+  { "query": "set up the deployment pipeline for staging", "should_trigger": false, "expected_skill": null },
+  { "query": "parallelize the test suite in ci", "should_trigger": false, "expected_skill": null },
+  { "query": "map reduce over these records", "should_trigger": false, "expected_skill": null }
+]

package/skills/subagent-deployment/references/safety-checklist.md

@@ -0,0 +1,54 @@
+# Parallel Dispatch Safety Checklist
+
+The one place this logic lives. `subagent-deployment`,
+`subagent-execution`, and `spawn-rules.md` all point here instead
+of restating it.
+
+## Is it safe to dispatch these together?
+
+```
+□ Read-only combination? (explorer + explorer, researcher + researcher, or
+  explorer + researcher)
+  → Always safe. Nothing writes, nothing to conflict. Skip the rest of
+    this checklist.
+
+□ Any task in the group uses coder (or planner writing a doc)?
+  → All of the following must hold:
+    □ Every write-capable task in the group writes to different files
+      than every other task in the group
+    □ No task depends on another task's output
+    □ No task needs another task's file to exist first
+    □ You (the controller) can integrate every result without conflicts
+
+If any box is unchecked → that group runs sequentially, not together.
+```
+
+## Constructing the batch
+
+- Issue every cleared dispatch in the **same message** — one Agent tool call
+  per task, all in one response. Multiple calls in one message run
+  concurrently; one call per response runs sequentially, regardless of
+  intent.
+- Each dispatch prompt is self-contained — no dispatch should assume the
+  agent has seen any other task in the batch, or your session's history.
+- Never dispatch two tasks together just because they're both quick — the
+  checklist is about safety (file/dependency conflicts), not speed.
+
+## Known limitation
+
+No filesystem isolation (no git worktrees) backs this — safety rests
+entirely on the disjoint-files check above, not on the environment
+enforcing it. This is a deliberate, accepted tradeoff, not an oversight: two
+agents genuinely writing to different files carries no real conflict risk
+at the filesystem level; the residual risk is agents running overlapping
+git commands against the same `.git` concurrently, which none of condux's
+current dispatch prompts do (no task is asked to commit — committing is
+always a separate, explicit, controller-only step per this repo's own
+convention).
+
+## Model selection
+
+Same tiering as sequential dispatch — see
+`subagent-execution/references/spawn-rules.md` → Model Selection.
+Parallelizing doesn't change which model tier a given task needs; it only
+changes how many run at once.

package/skills/subagent-execution/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: subagent-execution
+description: "Execute a plan using named specialist agents. Default is to implement yourself — only spawn when there is a concrete justification. Agents must be pre-defined; never create generic subagents with injected system prompts. Trigger when implementing a LARGE plan with tasks that benefit from agent specialization or parallel exploration — including task briefs, review packages, spawn rules, and resuming an interrupted plan from the `.condux/progress/` ledger (not session-handoff). Not for ad-hoc independent tasks outside a plan (that's subagent-deployment)."
+argument-hint: "<plan file path>"
+---
+
+# /subagent-execution
+
+Execute a plan using specialist agents. Default is to do the work yourself. Spawn only when justified.
+
+## Usage
+
+```
+/subagent-execution .condux/plans/YYYY-MM-DD-<feature>.md
+```
+
+## Core Principle
+
+**You implement by default.** Spawning is an explicit decision with a stated reason — not the default mode of operation.
+
+```
+Before spawning any agent, answer:
+  1. Why can't I do this task myself?
+  2. Which named agent is right for this task?
+  3. Is this task independent enough to parallelize?
+  4. What exactly will I pass to the agent?
+```
+
+If you can't answer all four, don't spawn.
+
+## Progress Ledger
+
+Conversation memory does not survive compaction. Track task completion in a
+ledger file, not only in todos.
+
+- At skill start, check for a ledger: `.condux/progress/<feature-slug>.md`
+  (slug inferred kebab-case from the plan's feature name — the same
+  convention `draft-plan` uses for its own filename). Tasks listed there as
+  complete are DONE — do not re-dispatch them; resume at the first task not
+  marked complete.
+- If no ledger exists, create it with a header naming the plan file:
+  ```
+  # Subagent Execution Progress: <feature-slug>
+
+  Plan: .condux/plans/<plan-file>.md
+
+  ```
+- When a task's review comes back clean, append one line in the same
+  message as other bookkeeping: `- [x] Task N: <name> — commits
+  <base7>..<head7>, review clean`.
+- The ledger is a recovery aid, not the source of truth — the commits it
+  names exist in git even if context no longer remembers creating them.
+  After compaction or a new session, trust the ledger and `git log` over
+  your own recollection.
+- `.condux/` is gitignored working state (see `/workflow` → Artifacts). If
+  it's ever deleted, recover progress from `git log` against the plan's task
+  list — and note the plan itself lived there too, so re-derive scope from
+  the spec in `specs/` if the plan is gone as well.
+
+## How It Works
+
+Before Step 1, check the **Progress Ledger** (above) for already-completed tasks and resume there if any exist.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    SUBAGENT EXECUTION                           │
+├──────────────────────────────────────────────────────────────────┤
+│  Step 1: READ THE PLAN                                          │
+│  Load the plan file. Map out task dependencies.                 │
+│  Identify which tasks are unblocked (all dependencies complete).│
+│                                                                  │
+│  Step 2: FOR EACH TASK                                          │
+│  Ask: can I implement this myself?                              │
+│    YES → implement directly                                     │
+│    NO  → consult spawn-rules.md, pick the right agent,         │
+│           construct the delegation prompt, spawn                │
+│                                                                  │
+│  Step 3: GROUP INTO A WAVE                                      │
+│  Among this round's unblocked tasks needing an agent, check     │
+│  references/safety-checklist.md (subagent-deployment skill);    │
+│  tasks that clear it form one wave.                             │
+│                                                                  │
+│  Step 4: DISPATCH THE WAVE                                      │
+│  Checklist-cleared tasks get dispatched together in one message;│
+│  otherwise dispatch one at a time. Either way, don't mix in     │
+│  unrelated off-plan work until the current wave finishes.       │
+│                                                                  │
+│  Step 5: RETRIEVE AND INTEGRATE                                 │
+│  Read agent output. Integrate into the codebase.               │
+│  You are responsible for coherence — agents don't see each     │
+│  other's work.                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Step 5's "mark task complete" also means appending the ledger line described in **Progress Ledger** — do this in the same message as marking the todo complete.
+
+## Parallel Spawning Rules
+
+For the full safety checklist (which combinations are safe, why, and how
+to construct the batch), see
+`subagent-deployment/references/safety-checklist.md` — the one place
+this logic lives. Do not restate it here.
+
+## Model Selection
+
+Before dispatching any `coder` subagent, choose its model explicitly based
+on task complexity — see `references/spawn-rules.md` → Model Selection for
+the tiering table. Never omit the model on a dispatch call; an omitted
+model inherits the session's own model, which defeats the point of
+tiering.
+
+## Delegation Prompt Quality
+
+When spawning, construct the delegation prompt carefully. The agent gets only what you give it.
+
+```
+Good delegation prompt includes:
+  ✓ The specific task from the plan (full text, not a reference)
+  ✓ Relevant file paths and their current state
+  ✓ Constraints ("read-only", "no bash", "don't touch auth middleware")
+  ✓ Expected output format ("return a summary of findings + file paths")
+  ✓ What NOT to do
+
+Bad delegation prompt:
+  ✗ "Look into the auth stuff"
+  ✗ A file reference without the content
+  ✗ No stated output format
+  ✗ No constraints
+```
+
+## File Handoffs
+
+Pasted plan content and diffs stay resident in context for the rest of the
+session and get re-read on every later turn. Hand them over as files
+instead:
+
+- **Task brief:** before dispatching an implementer, run
+  `references/task-brief.sh <plan-file> <task-number>` — it extracts the
+  task's full text to a scratch file and prints the path. Reference that
+  path in the dispatch prompt ("read this first — it is your
+  requirements"), plus any interfaces/decisions from earlier tasks the
+  brief can't know.
+- **Review package:** record the commit SHA before dispatching the
+  implementer (this is BASE — never `HEAD~1`, which silently drops all
+  but the last commit of a multi-commit task). After the implementer
+  reports DONE, run `references/review-package.sh <BASE> <HEAD>` and pass
+  the printed path to the task reviewer instead of pasting the diff.
+- For the final whole-branch review, BASE is the branch's merge-base with
+  its parent (e.g. `git merge-base main HEAD`), not the per-task BASE.
+
+## Non-Blocking Research Pattern
+
+For research/exploration tasks, prefer non-blocking delegation:
+
+1. Spawn the `researcher` or `explorer` agent with a clear question
+2. Continue implementing other tasks while it runs
+3. Retrieve the result when you need it
+
+Don't block the main session waiting for research that isn't on the critical path.
+
+## Codex: Installing the Named Agents
+
+Codex plugins cannot bundle agents (the Codex plugin format has no `agents/`
+component) — custom agents live as standalone TOML files under
+`$CODEX_HOME/agents/` (personal) or `<repo>/.codex/agents/` (project).
+Generate or refresh them from the canonical definitions here:
+
+```bash
+node "$(find ~/.claude ~/.codex ~/.agents -name install-codex-agents.mjs -path '*subagent-execution*' 2>/dev/null | head -1)"
+```
+
+Re-run after any agent-definition change (agents ship inside the condux
+plugin, but Codex won't load them from there). Existing TOMLs are backed up
+to `*.bak`; your `model` / `model_reasoning_effort` / `sandbox_mode` /
+`nickname_candidates` tuning is preserved. A custom agent named `explorer`
+takes precedence over Codex's built-in `explorer` (documented behavior).
+
+## See Also
+
+- `references/spawn-rules.md` — agent cost tiers, capability boundaries, decision tree
+- `references/task-brief.sh`, `references/review-package.sh` — file-handoff scripts (see File Handoffs above)
+- `references/install-codex-agents.mjs` — regenerate Codex agent TOMLs from the canonical `agents/*.md`