Strive

Runtime context (preprocessor snapshot):

• Active workflows: !find tmp -maxdepth 1 -name '.rune-*-*.json' -exec grep -l '"running"' {} + 2>/dev/null | wc -l | tr -d ' '
• Current branch: !git branch --show-current 2>/dev/null || echo "unknown"

/rune:strive — Multi-Agent Work Execution

Parses a plan into tasks with dependencies, summons swarm workers, and coordinates parallel implementation.

Load skills: roundtable-circle, context-weaving, rune-orchestration, team-sdk, git-worktree (when worktree mode active)

Usage

/rune:strive plans/feat-user-auth-plan.md              # Execute a specific plan
/rune:strive plans/feat-user-auth-plan.md --approve    # Require plan approval per task
/rune:strive plans/feat-user-auth-plan.md --worktree   # Use git worktree isolation (experimental)
/rune:strive plans/feat-user-auth-plan.md --background # Background dispatch (workers run across sessions)
/rune:strive --collect [timestamp]                      # Gather results from a background dispatch
/rune:strive plans/feat-user-auth-plan.md --resume      # Resume from last checkpoint (skip completed tasks)
/rune:strive --resume                                   # Auto-detect latest checkpoint and resume
/rune:strive                                            # Auto-detect recent plan

Pipeline Overview

Phase 0: Parse Plan -> Extract tasks, clarify ambiguities, detect --worktree flag
    |
Phase 0.3: Task Decomposition -> LLM classification + decomposition of complex tasks (optional)
    |
Phase 0.5: Environment Setup -> Branch check, stash dirty files, SDK canary (worktree)
    |
Phase 1: Forge Team -> TeamCreate + TaskCreate pool
    1. Task Pool Creation (complexity ordering, time estimation)
    1.1. Task Decomposition (LLM classification + subtask expansion, conditional)
    1.4. Design Context Discovery (conditional, zero cost if no artifacts)
    1.6. MCP Integration Discovery (conditional, zero cost if no integrations)
    1.7. File Ownership and Task Pool (static serialization via blockedBy)
    2. Signal Directory Setup (event-driven fast-path infrastructure)
    → TeamCreate + TaskCreate pool
    |
Phase 2: Summon Workers -> Self-organizing swarm
    | (workers claim -> implement -> complete -> repeat)
Phase 3: Monitor -> TaskList polling, stale detection
    |
Phase 3.5: Commit/Merge Broker -> Apply patches or merge worktree branches (orchestrator-only)
    |
Phase 3.6: Mini Test Phase -> Lightweight unit test verification (orchestrator-only)
    |
Phase 4: Ward Check -> Quality gates + verification checklist
    |
Phase 4.1: Todo Summary -> Generate worker-logs/_summary.md from per-worker log files (orchestrator-only)
    |
Phase 4.3: Doc-Consistency -> Non-blocking version/count drift detection (orchestrator-only)
    |
Phase 4.4: Quick Goldmask -> Compare predicted CRITICAL files vs committed (orchestrator-only)
    |
Phase 4.6: Blind AC Verification -> AC-only verification by blind agent (optional, gated by blind_verification.enabled)
    |
Phase 4.7: Drift Signals -> Workers write drift signal files to tmp/work/{timestamp}/drift-signals/ when plan-reality mismatches are detected
    |
Phase 6: Cleanup -> Shutdown workers, TeamDelete
    |
Phase 6.5: Ship -> Push + PR creation (optional)
    |
Output: Feature branch with commits + PR (optional)

Phase 0: Parse Plan

See parse-plan.md for detailed task extraction, shard context, ambiguity detection, and user confirmation flow.

Summary: Read plan file, validate path, extract tasks with dependencies, classify as impl/test, detect ambiguities, confirm with user.

Resume Detection (Phase 0, after plan path validation)

When --resume is passed, the orchestrator scans for a valid checkpoint from a prior crashed or interrupted session and reconstructs the task pool with completed tasks pre-marked. Handles session isolation, plan modification detection, artifact verification, and dependency graph pruning.

See resume-detection.md for the full implementation code and edge case table.

Worktree Mode Detection (Phase 0)

Parse --worktree flag and talisman config. When active: loads git-worktree skill, uses wave-aware monitoring, and replaces commit broker with merge broker.

See worktree-and-mcp.md for the full detection code and mode effects.

Task Decomposition (Phase 0.3, optional)

After parsing, optionally decompose complex tasks (5+ files, multi-layer) into 2-4 atomic subtasks. See task-decomposition.md.

Gate: work.task_decomposition.enabled (default: true). Fast-path: tasks with ≤2 files skip LLM entirely.

Sibling Context Injection (Phase 2 enhancement)

Workers receive context about concurrent sibling tasks to prevent duplication. See sibling-context.md.

Gate: work.sibling_awareness.enabled (default: true).

Phase 0.5: Environment Setup

Before forging the team, verify the git environment is safe for work. Checks branch safety (warns on main/master), handles dirty working trees with stash UX, and validates worktree prerequisites when in worktree mode.

Skip conditions: Invoked via /rune:arc (arc handles COMMIT-1), or work.skip_branch_check: true in talisman.

See env-setup.md for the full protocol — branch check, dirty tree detection, stash UX, and worktree validation.

Phase 0.7: Workflow Lock (writer)

const lockConflicts = Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_check_conflicts "writer"`)
if (lockConflicts.includes("CONFLICT")) {
  AskUserQuestion({ question: `Active workflow conflict:\n${lockConflicts}\nProceed anyway?` })
}
Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_acquire_lock "strive" "writer"`)

Phase 1: Forge Team

Creates the team, signal directories, applies complexity-aware task ordering, estimates task time, computes wave configuration, and writes the session state file.

Key steps: teamTransition pre-create guard → signal directory + inscription.json → output directories → complexity scoring + sort → time estimation → wave computation → state file with session isolation fields.

See forge-team.md for the full implementation code.

Task Decomposition — Phase 1.1 (conditional, gated by work.task_decomposition.enabled)

Runs after extractFileTargets() and scoreTaskComplexity(), before detectAndResolveConflicts(). Classifies tasks as ATOMIC or COMPOSITE via LLM (haiku model), then splits COMPOSITE tasks into 2-4 subtasks with non-overlapping fileTargets. Tasks with ≤2 targets skip LLM entirely (fast-path ATOMIC).

See task-decomposition.md for runTaskDecomposition(), classifyTask(), decomposeTask(), detectMultipleLayers(), and validateSubtaskFileOverlap().

Summary: extractedTasks = runTaskDecomposition(extractedTasks, workConfig). After expansion, inscription.json is re-written with subtask entries (EC-9). Disabled via work.task_decomposition.enabled: false.

MCP Integration Discovery (conditional, zero cost if no integrations)

Summary: Triple-gated (integrations.mcp_tools exists in talisman + phase match for "strive" + trigger match against task files/description). When active, loads companion skills via loadMCPSkillBindings() and passes buildMCPContextBlock() output to worker prompt builder.

See mcp-integration.md for the resolver algorithm and worktree-and-mcp.md for the inline integration code.

File Ownership and Task Pool

See file-ownership.md for file target extraction, risk classification, SEC-STRIVE-001 enforcement via inscription.json, quality contract, and subtask ownership handling.

Summary: Extract file targets per task → detect overlaps → serialize via blockedBy → create task pool with quality contract → write task_ownership to inscription.json. Flat-union allowlist enforced by validate-strive-worker-paths.sh hook. Subtasks from Phase 1.1 decomposition are treated as first-class tasks — no special-casing needed.

Task File Creation (MANDATORY)

The orchestrator MUST physically execute the Write() calls from forge-team.md. This is not reference documentation — execution is required before Phase 2 begins (AC-1, AC-2, AC-3, AC-6).

Required files after Phase 1:

Verification step (run after file creation, before spawning workers):

const taskFileCount = Glob(`tmp/work/${timestamp}/tasks/*.md`).length
if (taskFileCount !== extractedTasks.length) {
  warn(`Task file creation incomplete: expected ${extractedTasks.length}, got ${taskFileCount}. Proceeding with ${taskFileCount} available task files — workers have inline prompts as fallback.`)
  // AC-8: Graceful degradation — do NOT throw. Workers can operate with partial file sets
  // because worker-prompts.md embeds full task specs inline.
}

If the count check shows missing files, the warning is logged and workers proceed with available files. Workers receive full task specs via inline prompts as a fallback path (AC-8 backward compatibility).

Phase 2: Summon Swarm Workers

See worker-prompts.md for full worker prompt templates, scaling logic, and the scaling table.

Summary: Summon rune-smith (implementation) and trial-forger (test) workers. Workers receive pre-assigned task lists via inline prompts. Commits are handled through the Tarnished's commit broker. Do not run git add or git commit directly.

See todo-protocol.md for the worker todo file protocol that MUST be included in all spawn prompts.

Wave-Based Execution

See wave-execution.md for the wave loop algorithm, SEC-002 sanitization, non-goals extraction, and worktree mode spawning.

Summary: Tasks split into bounded waves (maxWorkers × tasksPerWorker). Each wave: distribute → spawn → monitor → commit broker → shutdown → next wave. Single-wave optimization skips overhead when totalWaves === 1.

Phase 3: Monitor

Poll TaskList with timeout guard to track progress. See monitor-utility.md for the shared polling utility.

ANTI-PATTERN — NEVER DO THIS: Bash("sleep 60 && echo poll check") — This skips TaskList entirely. You MUST call TaskList every cycle.

// CDX-GAP-002 FIX: Discipline-aware timeout scaling.
// When criteria-driven convergence is active, scale timeout by max iterations.
const hasCriteria = extractedTasks.some(t => t.criteria && t.criteria.length > 0)
const maxConvergenceIterations = 3
const baseTimeoutMs = 1_800_000  // 30 minutes base
const disciplineTimeoutMs = hasCriteria
  ? Math.min(maxConvergenceIterations * baseTimeoutMs, 5_400_000)  // Cap at 90 min
  : baseTimeoutMs

const result = waitForCompletion(teamName, taskCount, {
  timeoutMs: disciplineTimeoutMs,  // 30 min (no criteria) or scaled (with criteria)
  staleWarnMs: 300_000,      // 5 minutes — warn about stalled worker
  autoReleaseMs: 600_000,    // 10 minutes — release task for reclaim
  pollIntervalMs: 30_000,
  label: "Work",
  onCheckpoint: (cp) => { ... }
})

Phase 3 Inline Monitoring Blocks

Four inline blocks run each poll cycle in sequence: signal checks → smart reassignment → stale lock scan → stuck worker detection.

• Signal checks: Context-critical shutdown (Layer 1), all-tasks-done (Layer 4), force shutdown (Layer 3)
• Smart reassignment: Tasks exceeding multiplier × estimated_minutes get warned, then force-released after grace period. Max 2 reassignments per task. Gated by work.reassignment.enabled.
• Stale file lock scan: Removes lock signals older than stale_threshold_ms (default: 600s)
• Stuck worker detection: Workers exceeding max_runtime_minutes (default: 20) receive shutdown_request and have tasks released

See monitor-inline.md for the full implementation code and configuration.

Question Relay Detection (Phase 3 — Inline)

During Phase 3, the orchestrator handles worker questions reactively. Worker questions arrive via SendMessage (auto-delivered — no polling required). Compaction recovery uses a fast-path signal scan.

See question-relay.md for full protocol details — relayQuestionToUser(), compaction recovery (ASYNC-004), SEC-002/SEC-006 enforcement, live vs recovery paths, and talisman configuration.

Talisman gate: Check question_relay.enabled (default: true) before activating. If disabled, workers proceed on best-effort without question surfacing.

Discipline Work Loop (8-Phase Convergence Cycle)

When a plan contains YAML acceptance criteria (AC-* blocks), strive activates the Discipline Work Loop — an 8-phase convergence cycle that replaces linear task execution with iterative verification.

Activation gate: hasCriteria — plan has at least one AC-* block in code fences. Plans without criteria degrade to current behavior (backward compatibility).

Reference: See discipline-work-loop.md for the full 8-phase protocol. Convergence detail: See work-loop-convergence.md for the Phase 5 convergence protocol — entry conditions, iteration logic, exit conditions, gap task creation, and report format. Task format: See task-file-format.md for the task file YAML schema.

Phases: Decompose → Review Tasks → Assign → Execute → Monitor → Review Work → Converge → Quality

Convergence: max_convergence_iterations = 3 (v3.x baked-in). Stagnation detection escalates to human after 2+ iterations with same failing criteria.

Backward compatibility: Plans without YAML criteria skip Phase 1.5 (cross-reference), Phase 4.5 (completion matrix), and Phase 5 (convergence loop). SOW contracts use file-based scope instead of criteria-based scope.

Discipline Phase 4.5 — Completion Matrix (after monitoring completes, before quality gates):

// Wire: after Phase 3 monitoring loop exits, before Phase 4 ward check
if (hasCriteria) {
  const matrixResult = generateCompletionMatrix(timestamp, planCriteriaMap)
  log(`Completion Matrix: SCR=${matrixResult.scr.toFixed(1)}% ` +
      `(${matrixResult.passCount}/${matrixResult.totalCount} criteria PASS)`)

  // Phase 5: Convergence (if SCR < 100)
  if (matrixResult.scr < 100) {
    convergenceLoop(timestamp, matrixResult, planCriteriaMap)
  }
}

See discipline-work-loop.md Phase 4.5 for generateCompletionMatrix() and parseYAMLFrontmatter() implementation. See work-loop-convergence.md for the full convergenceLoop() executable pseudocode — entry guards (FLAW-002, FLAW-003), stagnation detection (FLAW-006), gap task creation from original plan source (FLAW-004), and wave-based gap worker execution (FLAW-007).

Discipline Escalation Chain (Phase 3 — Planned)

Status: Planned — not yet implemented. 4-attempt recovery chain (retry → decompose → reassign → human escalation) when discipline proof hook blocks task completion.

See discipline-escalation.md for the full escalation protocol and configuration.

Phase 3.5: Commit Broker (Orchestrator-Only, Patch Mode)

The Tarnished is the sole committer — workers generate patches, the orchestrator applies and commits them. Serializes all git index operations through a single writer, eliminating .git/index.lock contention.

Key steps: validate patch path, read patch + metadata, skip empty patches, dedup by taskId, apply with --3way fallback, reset staging area, stage specific files via --pathspec-from-file, commit with -F message file.

Recovery on restart: Scan tmp/work/{timestamp}/patches/ for metadata JSON with no recorded commit SHA — re-apply unapplied patches.

Phase 3.5: Merge Broker (Worktree Mode, Orchestrator-Only)

Replaces the commit broker when worktreeMode === true. Called between waves. See worktree-merge.md for the complete algorithm, conflict resolution flow, and cleanup procedures.

Key guarantees: sorted by task ID for deterministic merge order, dedup guard, --no-ff merge, file-based commit message, escalate conflicts to user via AskUserQuestion (NEVER auto-resolve), worktree cleanup on completion.

Phase 3.6: Mini Test Phase (Lightweight Verification)

After the commit/merge broker finishes, optionally run a lightweight test phase to catch obvious regressions before quality gates. Non-blocking — failures create fix tasks but don't block the pipeline.

Pre-flight: Check testing.strive_test.enabled (default: true). Worker drain gate waits for ALL active workers before running tests.

Scope detection: Uses resolveTestScope("") from testing skill — empty string = current branch diff (no PR number in strive context).

Test discovery: Uses discoverUnitTests(changedFiles) from testing references — maps changed files to test counterparts by convention.

Execution: Spawns unit-test-runner on existing team with 3-minute timeout. Runs diff-scoped unit tests only (not full testing pipeline).

Failure handling: If failures >= testing.strive_test.failure_analysis_threshold (default: 3), spawns test-failure-analyst for root cause analysis. Creates fix task for workers.

See test-phase.md for the full protocol — pre-flight gates, scope detection, test discovery, runner spawning, failure analysis, and cleanup integration.

Phase 4: Quality Gates

Read and execute quality-gates.md before proceeding.

Phase 4 — Ward Check: Discover wards from Makefile/package.json/pyproject.toml, execute each with SAFE_WARD validation, run 10-point verification checklist. On ward failure, create fix task and summon worker.

Phase 4.1 — Todo Summary: Orchestrator generates worker-logs/_summary.md after all workers exit. See todo-protocol.md for full algorithm.

Phase 4.3 — Doc-Consistency: Non-blocking version/count drift detection. See doc-consistency.md.

Phase 4.4 — Quick Goldmask: Compare plan-time CRITICAL file predictions against committed files. Emits WARNINGs only. Non-blocking.

Phase 6: Cleanup & Report

Standard cleanup: cache TaskList → dynamic member discovery → shutdown → grace period → artifact finalization (non-blocking) → retry-with-backoff TeamDelete → stale worker log fixup (FLAW-008) → worktree GC (if applicable) → stash restore → state file update → workflow lock release.

See phase-6-cleanup.md for the full cleanup pseudocode and completion report template. See engines.md § cleanup for the shared pattern.

Phase 6 — Per-Task Status Table (discipline-enabled plans only): Reads task files to build per-task status breakdown with criteria pass/fail counts and convergence metrics. See phase-6-cleanup.md § Per-Task Status Table.

Phase 6.5: Ship (Optional)

See ship-phase.md for gh CLI pre-check, ship decision flow, PR template generation, and smart next steps.

Summary: Offer to push branch and create PR. Generates PR body from plan metadata, task list, ward results, verification warnings, and todo summary. See todo-protocol.md for PR body Work Session format.

--approve Flag (Plan Approval Per Task)

When --approve is set, each worker proposes an implementation plan before coding.

Flow: Worker reads task → writes proposal to tmp/work/{timestamp}/proposals/{task-id}.md → sends to leader → leader presents via AskUserQuestion → user approves/rejects/skips → max 2 rejection cycles → timeout 3 minutes → auto-REJECT (fail-closed).

Proposal format: Markdown with ## Approach, ## Files to Modify, ## Files to Create, ## Risks sections.

Arc integration: When used via /rune:arc --approve, the flag applies ONLY to Phase 5 (WORK), not to Phase 7 (MEND).

Incremental Commits

Each task produces exactly one commit via the commit broker: rune: <task-subject> [ward-checked].

Task subjects are sanitized: strip newlines + control chars, limit to 72 chars, use git commit -F <message-file> (not inline -m).

Only the Tarnished (orchestrator) updates plan checkboxes — workers do not edit the plan file.

Key Principles

For the Tarnished (Orchestrator)

• Ship complete features: Verify wards pass, plan checkboxes are checked, and offer to create a PR.
• Fail fast on ambiguity: Ask clarifying questions in Phase 0, not after workers have started implementing.
• Branch safety first: Do not let workers commit to main without explicit user confirmation.
• Serialize git operations: All commits go through the commit broker.

For Workers (Rune Smiths & Trial Forgers)

• Match existing patterns: Read similar code before writing new code.
• Test as you go: Run wards after each task, not just at the end. Fix failures immediately.
• One task, one patch: Each task produces exactly one patch.
• Self-review before ward: Re-read every changed file before running quality gates.
• Exit cleanly: No tasks after 3 retries → idle notification → exit. Approve shutdown requests immediately.

Error Handling

Common Pitfalls