valent-pipeline 0.5.0 → 0.5.1

package/bin/cli.js

@@ -41,6 +41,49 @@ program
     await upgrade(options);
   });
 
+// status command — board read-model (composes pipeline-state.json + backlog + artifacts)
+program
+  .command('status')
+  .description('Show pipeline status as a board read-model (human summary, or --json for the board-state contract)')
+  .option('--json', 'Emit the board-state JSON contract to stdout (for a board/notifier/CI)')
+  .option('--out <path>', 'Write the board-state JSON to a file (e.g. board-state.json for a board to watch)')
+  .option('--root <dir>', 'Project root to inspect (defaults to the current directory)')
+  .option('--no-audit', 'Skip merging the per-agent token/wall-clock audit trail into the board')
+  .action(async (options) => {
+    const { statusCmd } = await import('../src/commands/status.js');
+    await statusCmd(options);
+  });
+
+// board command — serves the read-only board SPA + read API (a projection, never a write path)
+program
+  .command('board')
+  .description('Serve a read-only board UI (Backlog + Kanban) over a local HTTP server')
+  .option('--port <n>', 'Port to listen on (default 7777)', '7777')
+  .option('--host <addr>', 'Host/interface to bind (default 127.0.0.1; 0.0.0.0 warns loudly)', '127.0.0.1')
+  .option('--root <dir>', 'Project root to project the board over (defaults to the current directory)')
+  .option('--open', 'Open the board in the default browser once it is listening')
+  .option('--no-audit', 'Skip merging the per-agent token/wall-clock cost trail into the board')
+  .action(async (options) => {
+    const { boardCmd } = await import('../src/commands/board.js');
+    await boardCmd(options);
+  });
+
+// audit command — per-agent, per-story token + wall-clock trail (reads Workflow journals)
+program
+  .command('audit')
+  .description('Per-agent, per-story audit trail (tokens + wall-clock), read from Workflow run journals')
+  .option('--story <id>', 'Filter to a single story')
+  .option('--run <runId>', 'Filter to a single workflow run')
+  .option('--json', 'Emit the audit JSON contract to stdout')
+  .option('--out <path>', 'Write the audit JSON to a file')
+  .option('--file <path>', 'Audit a single workflow journal file (wf_*.json)')
+  .option('--session-dir <dir>', 'Scan a specific session dir\'s workflows/ folder')
+  .option('--project-dir <dir>', 'Project dir whose ~/.claude/projects session journals to read (default: cwd)')
+  .action(async (options) => {
+    const { auditCmd } = await import('../src/commands/audit.js');
+    await auditCmd(options);
+  });
+
 // config validate command
 const configCmd = program
   .command('config')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/pipeline/orchestrators/claude-code/plan.workflow.js

@@ -166,10 +166,32 @@ const MODELS = buildModelMap(a.models)
 // undefined => the agent inherits the main-loop (session) model.
 const modelFor = (role) => MODELS[String(role).toUpperCase()]
 
+// --- per-agent reasoning effort (thinking budget) ----------------------------
+// Optional, config-driven, mirrors `models`. args.reasoning is a level->roles map inverted to
+// role->trigger-phrase. EMPTY default => no trigger injected unless the config opts in, so
+// behavior is unchanged out of the box. Static + args only => journal-replay safe.
+const REASONING_PHRASES = { think: 'think', 'think-hard': 'think hard', 'think-harder': 'think harder', ultrathink: 'ultrathink' }
+const DEFAULT_REASONING = {} // blank control surface — fill `reasoning` in pipeline-config.yaml to use it
+function buildReasoningMap(cfg) {
+  const map = { ...DEFAULT_REASONING }
+  if (cfg && typeof cfg === 'object' && !Array.isArray(cfg)) {
+    for (const level of Object.keys(REASONING_PHRASES)) {
+      for (const role of cfg[level] || []) {
+        if (typeof role === 'string') map[role.toUpperCase()] = REASONING_PHRASES[level]
+      }
+    }
+  }
+  return map
+}
+const REASONING = buildReasoningMap(a.reasoning)
+const reasoningFor = (role) => REASONING[String(role).toUpperCase()]
+
 function buildPrompt({ role, promptFile, storyId, taskSubject, trigger, returnContract }) {
   const outputDir = `stories/${storyId}/output`
+  const think = reasoningFor(role) // undefined unless config opts this role into a thinking tier
   return [
     `You are **${role}**, for story ${storyId} in the valent-pipeline (sprint ${sprintId} planning).`,
+    ...(think ? ['', `Before you act, ${think} about the hardest parts of this task.`] : []),
     '',
     '## Setup',
     `1. Read your core prompt: \`.valent-pipeline/prompts/${promptFile}\` — identity, protocols, step sequence.`,

package/pipeline/orchestrators/claude-code/retro.workflow.js

@@ -157,10 +157,33 @@ const MODELS = buildModelMap(a.models)
 // undefined => the agent inherits the main-loop (session) model.
 const modelFor = (role) => MODELS[String(role).toUpperCase()]
 
-const retroPrompt = (instruction, returnContract) =>
-  `You are **RETROSPECTIVE**, analyzing story batch ${batchNumber} in the valent-pipeline. ` +
-  `Read \`.valent-pipeline/prompts/retrospective.md\` and the step file named in the task. ${instruction} ` +
-  (returnContract || 'Return your findings as the JSON object specified.')
+// --- reasoning effort (thinking budget) --------------------------------------
+// Optional, config-driven, mirrors `models`. args.reasoning is a level->roles map inverted to
+// role->trigger-phrase. EMPTY default => nothing injected unless the config opts in. Every agent
+// here shares the RETROSPECTIVE identity, so the knob keys on that role. Static + args only.
+const REASONING_PHRASES = { think: 'think', 'think-hard': 'think hard', 'think-harder': 'think harder', ultrathink: 'ultrathink' }
+const DEFAULT_REASONING = {} // blank control surface — fill `reasoning` in pipeline-config.yaml to use it
+function buildReasoningMap(cfg) {
+  const map = { ...DEFAULT_REASONING }
+  if (cfg && typeof cfg === 'object' && !Array.isArray(cfg)) {
+    for (const level of Object.keys(REASONING_PHRASES)) {
+      for (const role of cfg[level] || []) {
+        if (typeof role === 'string') map[role.toUpperCase()] = REASONING_PHRASES[level]
+      }
+    }
+  }
+  return map
+}
+const REASONING = buildReasoningMap(a.reasoning)
+const reasoningFor = (role) => REASONING[String(role).toUpperCase()]
+
+const retroPrompt = (instruction, returnContract) => {
+  const think = reasoningFor('RETROSPECTIVE') // undefined unless config opts RETROSPECTIVE into a tier
+  return `You are **RETROSPECTIVE**, analyzing story batch ${batchNumber} in the valent-pipeline. ` +
+    (think ? `Before you act, ${think} about the hardest parts of this task. ` : '') +
+    `Read \`.valent-pipeline/prompts/retrospective.md\` and the step file named in the task. ${instruction} ` +
+    (returnContract || 'Return your findings as the JSON object specified.')
+}
 
 // A stable de-dup key so loop-until-dry converges (don't re-count the same finding).
 const findingKey = (f) => `${(f.summary || '').toLowerCase().trim().slice(0, 80)}`

package/pipeline/orchestrators/claude-code/sprint.workflow.js

@@ -35,12 +35,17 @@
  * their structured returns.
  *
  * args (either form):
- *   { stories: [{ storyId, projectType?, profiles? }, ...], projectType?, profiles?, maxRejectionCycles?, models? }
- *   { storyId, projectType, profiles?, maxRejectionCycles?, models? }   // single-story (back-compat)
+ *   { stories: [{ storyId, projectType?, profiles? }, ...], projectType?, profiles?, maxRejectionCycles?, models?, reasoning? }
+ *   { storyId, projectType, profiles?, maxRejectionCycles?, models?, reasoning? }   // single-story (back-compat)
  *
  * `models` is the pipeline-config.yaml `models` tier->roles map (e.g. { opus:[...], sonnet:[...],
  * haiku:[...] }); the invoking skill passes it through so per-agent model tiers stay config-driven
  * and editable via `valent configure`. Omit it to use the baked-in default assignment.
+ *
+ * `reasoning` is the pipeline-config.yaml `reasoning` level->roles map (e.g. { ultrathink:[...],
+ * 'think-harder':[...], 'think-hard':[...], think:[...] }); it injects a thinking-effort trigger
+ * into a role's prompt. BLANK by default — omit it (or leave the levels empty) and nothing is
+ * injected, behavior unchanged. It is a config-driven control surface, parallel to `models`.
  */
 
 export const meta = {
@@ -206,14 +211,39 @@ const MODELS = buildModelMap(a.models)
 // undefined => the agent inherits the main-loop (session) model.
 const modelFor = (role) => MODELS[String(role).toUpperCase()]
 
+// --- per-agent reasoning effort (thinking budget) ----------------------------
+// Optional, config-driven, mirrors `models`. args.reasoning is a level->roles map; we invert it
+// to role->trigger-phrase and overlay it on a baked-in default. The default is EMPTY — no role
+// gets a thinking trigger unless the config opts it in, so behavior is unchanged out of the box.
+// The phrase (when present) is injected into the agent prompt by buildPrompt; Claude Code
+// escalates the thinking budget on these triggers. Static + args only => journal-replay safe.
+const REASONING_PHRASES = { think: 'think', 'think-hard': 'think hard', 'think-harder': 'think harder', ultrathink: 'ultrathink' }
+const DEFAULT_REASONING = {} // blank control surface — fill `reasoning` in pipeline-config.yaml to use it
+function buildReasoningMap(cfg) {
+  const map = { ...DEFAULT_REASONING }
+  if (cfg && typeof cfg === 'object' && !Array.isArray(cfg)) {
+    for (const level of Object.keys(REASONING_PHRASES)) {
+      for (const role of cfg[level] || []) {
+        if (typeof role === 'string') map[role.toUpperCase()] = REASONING_PHRASES[level]
+      }
+    }
+  }
+  return map
+}
+const REASONING = buildReasoningMap(a.reasoning)
+// undefined => inject no thinking trigger for this role.
+const reasoningFor = (role) => REASONING[String(role).toUpperCase()]
+
 // --- prompt builder: mirrors providers/claude-code/spawn.template.md so spawned agents
 //     get full pipeline context (core prompt + shared context + step-at-execution + the
 //     handoff contract), not a terse one-liner. ------------------------------------------
 
 function buildPrompt({ role, promptFile, storyId, taskRef, taskSubject, trigger, completion, returnContract }) {
   const outputDir = `stories/${storyId}/output`
+  const think = reasoningFor(role) // undefined unless config opts this role into a thinking tier
   return [
     `You are **${role}**, for story ${storyId} in the valent-pipeline.`,
+    ...(think ? ['', `Before you act, ${think} about the hardest parts of this task.`] : []),
     '',
     '## Setup',
     `1. Read your core prompt: \`.valent-pipeline/prompts/${promptFile}\` — identity, protocols, step sequence.`,

package/skills/valent-configure/SKILL.md

@@ -141,6 +141,22 @@ Ask the user if they want to adjust any assignments. Common adjustments:
 
 Note: agents that were skipped due to project type (e.g., FEND for backend-api) should still appear in the model list -- they are inactive but remain configured.
 
+### Step 6b: Reasoning Effort (optional)
+
+The `reasoning` section is a per-agent thinking-budget control surface that mirrors `models`. It maps an effort level to a list of agent roles; at spawn time the Workflow orchestrators inject that level's thinking trigger into the role's prompt. Levels, increasing: `think` < `think-hard` < `think-harder` < `ultrathink`.
+
+It is **blank by default** — every level is an empty list, so nothing is injected and behavior is unchanged. Leave it blank unless the user wants to deepen specific agents' reasoning. Deeper thinking raises output quality but also token cost, so recommend the user re-check `/valent-review-cost` (or `valent audit`) after enabling it.
+
+```yaml
+reasoning:
+  ultrathink: []
+  think-harder: []   # e.g. ["CRITIC", "JUDGE"] to make the gates deliberate harder
+  think-hard: []
+  think: []
+```
+
+Common adjustments: add the quality gates (`CRITIC`, `JUDGE`, `READINESS`) under `think-harder` when a project keeps shipping subtle defects. This currently affects the **Workflow** orchestrators only (the `reasoning` arg); the prose Lead ignores it.
+
 ---
 
 ## Writing the Config File

package/skills/valent-help/SKILL.md

@@ -61,6 +61,9 @@ Read these as needed to answer questions:
 **"How do I change which model an agent uses?"**
 → Edit the `models` section in `.valent-pipeline/pipeline-config.yaml`. Agents are assigned to opus/sonnet/haiku tiers.
 
+**"Which agents cost the most / what's taking the most time?"**
+→ `/valent-review-cost` analyzes per-agent token and wall-clock spend across stories (from the Workflow run journals) and recommends model-tier changes. Or get the raw numbers with `node .valent-pipeline/bin/cli.js audit --json`.
+
 **"What happens when an agent gets rejected?"**
 → Peer-to-peer: READINESS rejects specs back to authors, CRITIC rejects code to devs, QA-B routes bugs to devs. Lead only handles JUDGE rejections and circuit breaker (after max_rejection_cycles). See `.valent-pipeline/docs/lead-lifecycle.md`.
 

package/skills/valent-review-cost/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: valent-review-cost
+description: 'Review per-agent token and wall-clock cost across stories and recommend model-tier (opus/sonnet/haiku) changes. Use when the user says "review cost", "what is taking the most time", "which agents cost the most", "tune model configs", or asks about pipeline token/time spend.'
+---
+
+# valent-review-cost
+
+Analyze where the pipeline spends tokens and wall-clock time, per agent and per story, then recommend concrete `models` tier changes. Read-only — you inspect run journals and config; you never modify the pipeline.
+
+## Data Sources
+
+1. **The audit trail** — per-agent tokens + wall-clock, read from the Workflow run journals the harness already writes (no instrumentation). Get it as JSON:
+
+   ```bash
+   node .valent-pipeline/bin/cli.js audit --json
+   ```
+
+   Or get the full board with cost merged onto each story card:
+
+   ```bash
+   node .valent-pipeline/bin/cli.js status --json
+   ```
+
+   Scope it when needed: `audit --story <id>` for one story, `audit --run <runId>` for one run.
+
+2. **The configured model tiers** — read the `models` section of `.valent-pipeline/pipeline-config.yaml`. It maps each tier to the roles assigned to it:
+
+   ```yaml
+   models:
+     opus:   [READINESS, CRITIC, JUDGE, ...]   # judgment-heavy
+     sonnet: [REQS, QA-A, QA-B, BEND, FEND, ...] # spec + build
+     haiku:  [RESOLVE, Embed, Help, ...]        # mechanical / CLI-runner
+   ```
+
+## How to Analyze
+
+Run `audit --json` and parse the contract:
+- `totals` — grand `tokens`, `agent_ms` (summed agent busy-time), `elapsed_ms` (true wall clock), `invocations`, `stories`, `runs`.
+- `stories[]` — each `{ story, tokens, agent_ms, invocations, roles[] }`, sorted by tokens.
+- `stories[].roles[]` — each `{ role, tokens, agent_ms, toolCalls, invocations, attempts, models[] }`, sorted by tokens. `models[]` is the model the role **actually ran on**.
+
+Then:
+
+1. **Rank the spend.** Identify the top token consumers and top time consumers, both per role (aggregated across stories) and per story. Name the 3–5 biggest.
+
+2. **Cross-reference actual model vs configured tier.** For each costly role, compare `roles[].models[]` (what it ran on) against the `models` map (what it's configured for). Flag mismatches loudly — a role running on a higher tier than configured usually means the per-role tiers weren't applied and everything used the session default model. That is the first and biggest lever.
+
+3. **Separate "expensive because of tier" from "expensive because of rework."** If a role's `invocations` (or `attempts`) is > 1, its cost is inflated by rejection/rework cycles, not just model tier. CRITIC especially fans out (3 passes + triage) and re-runs on rejection. For those, note that prompt/spec quality or rejection-cap tuning may cut cost more than a tier change.
+
+4. **Recommend tier changes** with reasoning:
+   - High-token, low-judgment roles (RESOLVE and other CLI-runners; mechanical IO) on opus/sonnet → propose dropping a tier.
+   - Spec/build roles (REQS, QA-A, QA-B, dev agents) on opus → consider sonnet unless quality data argues otherwise.
+   - Quality gates (READINESS, CRITIC, JUDGE) → judgment is the point; keep on opus unless they're cheap anyway.
+   - Always tie each recommendation to the numbers (e.g. "CRITIC = 47% of story spend, ran on opus, 8 invocations from the rejection loop").
+
+## Output Format
+
+Keep it short and decision-ready:
+
+1. **Headline** — total spend (tokens, true elapsed), top 3 cost drivers.
+2. **Per-role table** — role · tokens · agent-time · invocations · model-ran-on · configured-tier · mismatch?
+3. **Recommendations** — a short ordered list of specific `models` edits, each with the number that justifies it. Show the exact `pipeline-config.yaml` `models` change to make.
+4. **Caveats** — note that `agent_ms` is summed busy-time (exceeds `elapsed_ms` when agents run in parallel), and that rework-driven cost is fixed by prompt/spec quality, not tiers.
+
+## Notes
+
+- If `audit` finds no journals (`totals.stories == 0`), say so: cost data only exists after at least one Workflow run. Point the user at `--file` / `--session-dir` if their journals live elsewhere.
+- Audit covers the Claude Code (Workflow) provider. The Codex provider produces no journal, so there is no cost data for Codex runs yet.
+- Do not edit `pipeline-config.yaml` yourself — present the recommended changes and let the user (or `/valent-configure`) apply them.

package/skills/valent-run-epic-workflow/SKILL.md

@@ -29,7 +29,7 @@ Use the standard 200k context window. Workflow `agent()` calls run in their own
 
 ### Step 1: Load Pipeline Config
 
-Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Set `{epic_id}` from the argument. Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg to every Workflow call below so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflows use their baked-in default assignment.
+Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Set `{epic_id}` from the argument. Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg to every Workflow call below so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflows use their baked-in default assignment. Likewise capture the `reasoning` section (level→roles thinking-effort map) and pass it as the `reasoning` arg to every Workflow call; it is blank by default (injects nothing). Omit it if absent or all levels are empty.
 
 ### Step 2: Validate Epic
 
@@ -62,7 +62,7 @@ Invoke `plan.workflow.js` via the **Workflow tool**:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/plan.workflow.js',
-  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: '{epic_id}-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity}, models: <config.models or omit> }
+  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: '{epic_id}-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity}, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 
@@ -74,7 +74,7 @@ Feed the planned batch straight into `sprint.workflow.js`:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
-  args: { stories: <plan output .stories>, maxRejectionCycles: {quality.max_rejection_cycles or 5}, models: <config.models or omit> }
+  args: { stories: <plan output .stories>, maxRejectionCycles: {quality.max_rejection_cycles or 5}, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 
@@ -89,7 +89,7 @@ Invoke `retro.workflow.js`:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/retro.workflow.js',
-  args: { batchNumber: {n}, sprintId: '{epic_id}-sprint-{n}', models: <config.models or omit> }
+  args: { batchNumber: {n}, sprintId: '{epic_id}-sprint-{n}', models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 

package/skills/valent-run-project-workflow/SKILL.md

@@ -24,7 +24,7 @@ Use the standard 200k context window. Workflow `agent()` calls run in their own
 
 ### Step 1: Load Pipeline Config
 
-Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg to every Workflow call below so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflows use their baked-in default assignment.
+Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg to every Workflow call below so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflows use their baked-in default assignment. Likewise capture the `reasoning` section (level→roles thinking-effort map) and pass it as the `reasoning` arg to every Workflow call; it is blank by default (injects nothing). Omit it if absent or all levels are empty.
 
 ### Step 2: Build Cross-Epic Dependency Map
 
@@ -65,7 +65,7 @@ Invoke `plan.workflow.js` via the **Workflow tool**:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/plan.workflow.js',
-  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: 'project-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity}, models: <config.models or omit> }
+  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: 'project-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity}, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 
@@ -77,7 +77,7 @@ Feed the planned batch straight into `sprint.workflow.js`:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
-  args: { stories: <plan output .stories>, maxRejectionCycles: {quality.max_rejection_cycles or 5}, models: <config.models or omit> }
+  args: { stories: <plan output .stories>, maxRejectionCycles: {quality.max_rejection_cycles or 5}, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 
@@ -92,7 +92,7 @@ Invoke `retro.workflow.js`:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/retro.workflow.js',
-  args: { batchNumber: {n}, sprintId: 'project-sprint-{n}', models: <config.models or omit> }
+  args: { batchNumber: {n}, sprintId: 'project-sprint-{n}', models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 

package/skills/valent-run-story-workflow/SKILL.md

@@ -29,7 +29,7 @@ If no argument is provided, resolve the next work item from the backlog (see Ste
 
 ### Step 1: Load Pipeline Config
 
-Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Capture `project.type` and the story's `testing_profiles` — these become the Workflow's `projectType` and `profiles` args. Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflow uses its baked-in default assignment.
+Read and follow `.valent-pipeline/steps/orchestration/load-pipeline-config.md`. Capture `project.type` and the story's `testing_profiles` — these become the Workflow's `projectType` and `profiles` args. Also capture the entire `models` section (the `{ opus:[...], sonnet:[...], haiku:[...] }` tier→roles map) — pass it as the `models` arg so per-agent model tiers stay config-driven (editable via `/valent-configure`). If the config has no `models` section, omit the arg and the workflow uses its baked-in default assignment. Likewise capture the `reasoning` section (the `{ ultrathink:[...], 'think-harder':[...], 'think-hard':[...], think:[...] }` level→roles map) and pass it as the `reasoning` arg; it is blank by default (injects nothing). Omit the arg if the section is absent or all levels are empty.
 
 ### Step 1b: Resolve Next Work Item (when no argument provided)
 
@@ -52,7 +52,7 @@ Invoke the Workflow at `.valent-pipeline/orchestrators/claude-code/sprint.workfl
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/sprint.workflow.js',
-  args: { storyId: '<resolved story id>', projectType: '<project.type>', profiles: [/* testing_profiles */], maxRejectionCycles: <quality.max_rejection_cycles or 5>, models: <config.models or omit> }
+  args: { storyId: '<resolved story id>', projectType: '<project.type>', profiles: [/* testing_profiles */], maxRejectionCycles: <quality.max_rejection_cycles or 5>, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
 })
 ```
 
@@ -71,7 +71,8 @@ Every Workflow invocation returns a `runId`. If a run is interrupted — context
 ## Notes
 
 - **State model.** The **journal is the state of record.** `pipeline-state.json`, `sprint-{n}-status.yaml`, and the markdown handoffs are **derived, human-readable views** that agents write for visibility — the orchestrator never reads them back to make a control-flow decision (its state lives in JS variables the journal captures). The non-atomic multi-file desync the prose Lead can hit is structurally impossible here.
-- **Planned sprint batches.** To run a planned batch instead of one story, pass `args: { stories: [{ storyId, projectType, profiles }, ...], maxRejectionCycles, models }`. Produce that batch by running `plan.workflow.js` first (`args: { stories: [{ storyId, projectType }], sprintId, velocity, models }`), then feed its `{ sprintId, stories: [...] }` straight into `sprint.workflow.js`. After a batch ships, run `retro.workflow.js` (`args: { batchNumber, sprintId, models }`) to learn from it. Pass the same `config.models` map to all three. There is no `sprint-cycle` wrapper yet — run the three in sequence.
+- **Planned sprint batches.** To run a planned batch instead of one story, pass `args: { stories: [{ storyId, projectType, profiles }, ...], maxRejectionCycles, models, reasoning }`. Produce that batch by running `plan.workflow.js` first (`args: { stories: [{ storyId, projectType }], sprintId, velocity, models, reasoning }`), then feed its `{ sprintId, stories: [...] }` straight into `sprint.workflow.js`. After a batch ships, run `retro.workflow.js` (`args: { batchNumber, sprintId, models, reasoning }`) to learn from it. Pass the same `config.models` and `config.reasoning` maps to all three. There is no `sprint-cycle` wrapper yet — run the three in sequence.
+- **Per-agent reasoning effort.** The `reasoning` arg is a config-driven control surface (level→roles) that injects a thinking trigger into a role's prompt — blank by default, so it changes nothing until you fill it. Levels: `think` < `think-hard` < `think-harder` < `ultrathink`. Deeper thinking raises quality and token cost; check `valent audit` after enabling it. Edit it in `.valent-pipeline/pipeline-config.yaml` under `reasoning:`.
 - **Per-agent models.** Each workflow assigns a model tier per agent: gates (READINESS/CRITIC/JUDGE) → opus, spec/build → sonnet, CLI-runner/IO steps → haiku. This comes from `config.models` (passed as the `models` arg); edit it with `/valent-configure` → "Model Assignments". Omitting the arg falls back to the same assignment baked into the script.
 - **Known simplifications.** A CRITIC rejection currently re-runs ALL dev agents (not just the targeted one); there is no PMCP/visual-validation stage in the Workflow path yet. See `.valent-pipeline/orchestrators/claude-code/README.md`.
 - Do **not** adopt the Lead persona or read `lead.md` in this skill — that is the prose-Lead path. The orchestration here is the Workflow script.