/rune:devise — Multi-Agent Planning Workflow

Load skills: roundtable-circle, context-weaving, rune-orchestration, elicitation, team-sdk

Orchestrates a planning pipeline using Agent Teams with dependency-aware task scheduling.

Usage

/rune:devise                              # Full pipeline (brainstorm + research + validate + synthesize + shatter? + forge + review)
/rune:devise --quick                      # Quick: research + synthesize + review only (skip brainstorm, forge, shatter)
/rune:devise --brainstorm-context PATH    # Skip Phase 0, use existing brainstorm workspace for rich research context

Legacy Flags (still functional, undocumented)

/rune:devise --no-brainstorm              # Skip brainstorm only (granular)
/rune:devise --no-forge                   # Skip forge only (granular)
/rune:devise --no-arena                   # Skip Arena only (granular)
/rune:devise --no-verify-research          # Skip research output verification (Phase 1C.5)
/rune:devise --exhaustive                 # Exhaustive forge mode (lower threshold, research-budget agents)
/rune:devise --brainstorm                 # No-op (brainstorm is already default)
/rune:devise --forge                      # No-op (forge is already default)

Pipeline Overview

Phase -1: Team Bootstrap (TeamCreate + state file — enables ATE-1 enforcement)
    ↓
Phase 0: Gather Input (3 paths: --brainstorm-context → read workspace, --quick → skip, default → delegate to brainstorm protocol)
    ↓
Phase 0.2: Source Image Analysis (conditional — fetch + vision describe source_images from plan frontmatter)
    ↓
Phase 1: Research (up to 10 agents, conditional — join existing team)
    ├─ Phase 1A: LOCAL RESEARCH (always — repo-surveyor, echo-reader, git-miner, wiring-cartographer, activation-pathfinder)
    ├─ Phase 1B: RESEARCH DECISION (talisman plan config bypass, risk + local sufficiency scoring, URL sanitization)
    ├─ Phase 1C: EXTERNAL RESEARCH (conditional — practice-seeker + Context7 MCP, lore-scholar + Context7)
    ├─ Phase 1C.5: RESEARCH VERIFICATION (conditional — research-verifier, serial/blocking)
    └─ Phase 1D: SPEC VALIDATION (always — flow-seer)
    ↓ (all research tasks converge)
Phase 1.5: Research Consolidation Validation (AskUserQuestion checkpoint)
    ↓
Phase 1.8: Solution Arena (competitive evaluation — skip with --quick or --no-arena)
    ↓
Phase 2: Synthesize (lead consolidates findings, detail level selection)
    ↓
Phase 2.3: Predictive Goldmask (risk scoring + wisdom advisories — skip with --quick)
    ↓
Phase 2.5: Shatter Assessment (complexity scoring → optional decomposition)
    ↓
Phase 3: Forge (default — skipped with --quick)
    ↓
Phase 4: Plan Review (scroll review + optional iterative refinement)
    ↓
Phase 4.5: Technical Review (optional — decree-arbiter + knowledge-keeper)
    ↓
Phase 4D: Grounding Gate (ALWAYS — evidence-verifier + assumption-slayer, even with --quick)
    ↓
Phase 6: Cleanup & Present (shutdown teammates, TeamDelete, present plan)
    ↓
Output: plans/YYYY-MM-DD-{type}-{name}-plan.md
        (or plans/YYYY-MM-DD-{type}-{name}-shard-N-plan.md if shattered)

Workflow Lock (planner)

const lockConflicts = Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_check_conflicts "planner"`)
// Planner conflicts are ADVISORY only — inform, never block
if (lockConflicts.includes("CONFLICT") || lockConflicts.includes("ADVISORY")) {
  warn(`Active workflow(s) detected:\n${lockConflicts}`)
}
Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_acquire_lock "devise" "planner"`)

Phase -1: Team Bootstrap

Creates the Agent Team before any agents spawn using the teamTransition protocol (6-step: validate → TeamDelete with retry → filesystem fallback → TeamCreate with "Already leading" recovery → post-create verification → state file write). Enables ATE-1 enforcement for all subsequent phases.

See team-bootstrap.md for the full protocol.

Phase 0: Gather Input

Three paths based on flags:

1. `--brainstorm-context PATH`: Read existing brainstorm workspace. Skip brainstorm entirely. Inject workspace context (advisor research, decisions, quality score, scope classification, effort estimate) into Phase 1 research agents. Quality score from workspace-meta.json determines confidence level (>= 0.70: high-confidence, < 0.70: flag as "exploratory"). New frontmatter fields consumed: scope_classification (auto-selects plan detail level: STRATEGIC → Comprehensive, TACTICAL → Standard, QUICK-WIN → Minimal), effort_estimate (pre-populates plan effort field). Both use optional field access: meta?.scope_classification ?? null.

1. `--quick`: Skip brainstorm entirely. Ask user for a feature description via AskUserQuestion. Proceed directly to Phase 1.

1. Default: Delegate to the brainstorm protocol defined in skills/brainstorm/SKILL.md. Brainstorm runs with these devise-specific overrides: advisors join existing rune-plan-{timestamp} team (not a separate team), workspace co-located at tmp/brainstorm-{timestamp}/, also writes to tmp/plans/{timestamp}/brainstorm-decisions.md (legacy location), skips the brainstorm handoff phase (devise continues to research). After decisions are captured, sends shutdown_request to brainstorm advisors and sages before Phase 1 (mid-pipeline cleanup — they have no role in subsequent phases).

Elicitation: After approach selection, summons 1-3 elicitation-sage teammates (keyword-count fan-out, 15-keyword list). Always enabled in v3.x.

Output: tmp/plans/{timestamp}/brainstorm-decisions.md with mandatory sections: Non-Goals, Constraint Classification, Success Criteria, Scope Boundary.

See brainstorm-phase.md for the delegation protocol, --brainstorm-context workspace reading, and devise-specific overrides.

Read and execute when Phase 0 runs.

Phase 0.2: Source Image Analysis (conditional)

When the plan frontmatter contains source_images (populated by /rune:arc-issues), fetch and analyze each image to extract visual context for downstream agents.

Skip condition: No source_images in plan frontmatter, or source_images is empty.

Algorithm:

1. Parse plan frontmatter for source_images array
2. For each image (capped at 5):

a. Attempt WebFetch(img.url) to retrieve the image b. If WebFetch succeeds, Claude's multimodal vision describes the visual content c. If WebFetch fails (expired URL, unsupported format), record [Image unavailable] fallback

1. Write analysis to tmp/plans/{timestamp}/research/visual-context.md
2. Inject brainstormContext.visual_context for downstream research agents

Fallback strategy: Vision analysis via WebFetch is best-effort. If image URLs are expired or WebFetch cannot process the format, the feature degrades gracefully — URLs are still preserved in the plan frontmatter (source_images) for manual inspection. The primary value of image extraction (Tasks 1-3) does not depend on successful vision analysis. WebFetch follows redirects by default. GitHub CDN URLs may redirect — this is expected behavior. Non-image responses degrade gracefully.

Output: tmp/plans/{timestamp}/research/visual-context.md — one section per image with source URL, alt text, and visual description (or unavailability notice).

Downstream consumers: Research agents (repo-surveyor, wiring-cartographer) receive brainstormContext.visual_context in their spawn prompts when available.

Phase 0.8: Dependency-Aware Issue Discovery (conditional)

Before researching solutions, scan affected code areas for existing bugs, gaps, and risks.

Skip condition: --quick mode or no affected files detected in Phase 0.

Issue inventory categories:

• Bugs: Signature violations, undefined references, stale patterns, contract violations
• Gaps: Missing tests, orphaned references, missing error handling, undocumented behavior, field persistence — fields that don't flow through all CRUD layers (model→serializer→handler→form)
• Risks: High-fanout files, shared state, implicit contracts, fragile tests

Dependency chain tracing: For each discovered issue, trace upstream (where does the wrong value come from?) and downstream (what's impacted?). Classify fix_location as "upstream" or "local".

Feed into downstream phases:

• Phase 1 research agents receive: "also look for these known issues"
• Phase 2 synthesis includes: "## Existing Issues" section (Must Fix / Should Fix / Acknowledged)
• Phase 2.3 Goldmask receives issue inventory for cross-reference

Phase 1: Research (Conditional, up to 10 agents)

Spawns local research agents (repo-surveyor, echo-reader, git-miner, wiring-cartographer, activation-pathfinder), evaluates risk/sufficiency scores to decide on external research (practice-seeker, lore-scholar), optionally verifies external research outputs for trustworthiness (research-verifier, Phase 1C.5), then runs spec validation (flow-seer). Includes research consolidation validation checkpoint. Phase 1B reads talisman.plan config for external_research bypass modes (always/auto/never) and research_urls with SSRF-defensive URL sanitization. External research agents use Context7 MCP for framework documentation alongside WebSearch. Phase 1C.5 scores findings across 5 dimensions (relevance, accuracy, freshness, cross-validation, security) and maps verdicts (TRUSTED/CAUTION/UNTRUSTED/FLAGGED) — skipped with --quick, --no-verify-research, or when no external research ran.

MCP-First Research Agent Discovery (v1.171.0+)

Research agents are discovered via agent-search MCP before spawning, enabling user-defined research agents (e.g., "compliance-researcher" for regulated projects) to participate alongside built-in researchers. Falls back to hardcoded agent list when MCP is unavailable.

Inputs: feature (sanitized string, from Phase 0), timestamp (validated identifier), talisman config (plan section for research control) Outputs: Research agent outputs in tmp/plans/{timestamp}/research/, inscription.json Error handling: TeamDelete fallback on cleanup, identifier validation before rm-rf, agent timeout (5 min) proceeds with partial findings

See research-phase.md for the full protocol.

Phase 1.8: Solution Arena

Generates competing solutions from research, evaluates on weighted dimensions, challenges with adversarial agents, and presents a decision matrix for approach selection.

Skip conditions: --quick, --no-arena, bug fixes, high-confidence refactors (confidence >= 0.9), sparse research (<2 viable approaches).

See solution-arena.md for full protocol (sub-steps 1.8A through 1.8D).

Inputs: Research outputs from tmp/plans/{timestamp}/research/, brainstorm-decisions.md (optional) Outputs: tmp/plans/{timestamp}/arena/arena-selection.md (winning solution with rationale) Error handling: Complexity gate skip → log reason. Sparse research → skip Arena. Agent timeout → proceed with partial. All solutions killed → recovery protocol.

Phase 2: Synthesize

Tarnished consolidates research findings into a plan document. User selects detail level (Minimal/Standard/Comprehensive). Includes plan templates, formatting best practices, and the Plan Section Convention (contracts before pseudocode). Consolidates wiring-cartographer and activation-pathfinder outputs into ## Integration & Wiring Map section (Standard and Comprehensive only; omitted for Minimal).

Inputs: Research outputs from tmp/plans/{timestamp}/research/ (including wiring-map.md and activation-path.md from integration research), user detail level selection Outputs: plans/YYYY-MM-DD-{type}-{feature-name}-plan.md Error handling: Missing research files -> proceed with available data Comprehensive only: Re-runs flow-seer on the drafted plan for a second SpecFlow pass

See synthesize.md for the full protocol.

Phase 2.3: Predictive Goldmask

Runs predictive risk analysis on files likely affected by the plan. Supports 3 depth modes (basic/enhanced/full); v3.x defaults to basic (see references/v3-defaults.md).

Skip conditions: --quick mode, non-git repo. (Goldmask + devise predictive layer are always enabled in v3.x.)

See goldmask-prediction.md for the full protocol — depth modes, agent spawning, plan injection, and error handling.

Phase 2.5: Shatter Assessment

Skipped when --quick is passed. Assesses plan complexity and optionally decomposes into shards or hierarchical children.

Complexity Scoring

Score >= 0.65: Offer shatter. Score < 0.65: Skip to forge.

See shatter-assessment.md for the full protocol — shard generation, hierarchical decomposition, and coherence checks.

## Phase 3: Forge (Default — skipped with `--quick`)

Forge runs by default. Uses **Forge Gaze** (topic-aware agent matching) to select the best specialized agents for each plan section.

**Auto-trigger**: If user message contains ultrathink keywords (ULTRATHINK, DEEP, ARCHITECT), auto-enable `--exhaustive` forge mode.

### Default `--forge` Mode

- Parse plan into sections (## headings)
- Run Forge Gaze matching: threshold 0.30, max 3 agents/section, enrichment-budget agents only
- Summon throttle: max 5 concurrent, max 8 total agents
- Elicitation sages: up to MAX_FORGE_SAGES=6 per eligible section (keyword pre-filter)

### `--exhaustive` Mode

- Threshold: 0.15, max 5 agents/section, max 12 total
- Includes research-budget agents
- Two-tier aggregation
- Cost warning before summoning

**Fallback**: If no agent scores above threshold, use inline generic Task prompt for standard enrichment.

**Truthbinding**: All forge prompts include ANCHOR/RE-ANCHOR blocks. Plan content sanitized before injection (strip HTML comments, code fences, headings, HTML entities, zero-width chars).

See [forge-gaze.md](../roundtable-circle/references/forge-gaze.md) for the full topic registry and matching algorithm.

## Phase 4: Plan Review (Iterative)

Runs scroll-reviewer for document quality (with Truth-Telling Mandate), then automated verification gate (deterministic checks including talisman patterns, universal checks, CommonMark compliance, measurability, filler detection). Optionally summons decree-arbiter and knowledge-keeper for technical review.

**Truth-Telling Mandate** (appended to scroll-reviewer prompt in Phase 4): Ensures `--quick` path users get critical thinking benefit even without full brainstorm:
- If a plan section is weak, say it's weak — explain WHY with evidence
- Label every claim: [FACT] (cite file:line), [INFERENCE] (cite reasoning), or [OPINION] (state confidence)
- If you lack data to judge, say "INSUFFICIENT DATA" — never hedge without evidence

**Inputs**: Plan document from Phase 2/3, talisman config
**Outputs**: `tmp/plans/{timestamp}/scroll-review.md`, `tmp/plans/{timestamp}/decree-review.md`, `tmp/plans/{timestamp}/knowledge-review.md`
**Error handling**: BLOCK verdict -> address before presenting; CONCERN verdicts -> include as warnings
**Iterative**: Max 2 refinement passes for HIGH severity issues

See [plan-review.md](references/plan-review.md) for the full protocol.

### Phase 4D: Grounding Gate (ALWAYS runs)

**Mandatory** anti-hallucination gate. Runs evidence-verifier + assumption-slayer to verify plan solutions are grounded in codebase reality. Even with `--quick`, this phase runs — a fast-but-wrong plan wastes more time than a slower-but-correct one.

**Inputs**: Plan document, timestamp
**Outputs**: `tmp/plans/{timestamp}/grounding-evidence.md`, `tmp/plans/{timestamp}/grounding-assumptions.md`
**Error handling**: BLOCK verdict (grounding < 0.80 or invalid assumptions) -> auto-fix + 1 retry; still BLOCK -> present with warnings
**Agents**: `grounding-evidence-verifier`, `grounding-assumption-slayer`

See [plan-review.md](references/plan-review.md) Phase 4D section for the full protocol.

## Phase 6: Cleanup & Present

Standard 5-component team cleanup: dynamic member discovery (with 30+ member fallback array covering all conditional phases), shutdown_request broadcast, grace period, retry-with-backoff TeamDelete (4 attempts), process-level kill + filesystem fallback (QUAL-012 gated), workflow lock release, then present plan to user.

See [phase6-cleanup.md](references/phase6-cleanup.md) for the full cleanup protocol.

## Output

Plan file written to: `plans/YYYY-MM-DD-{type}-{feature-name}-plan.md`

**Filename convention**: `plans/YYYY-MM-DD-{type}-{feature-name}-plan.md`

**Type options**: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`

**Filename examples**:
- `plans/2026-02-12-feat-user-authentication-plan.md`
- `plans/2026-02-12-fix-checkout-race-condition-plan.md`
- `plans/2026-02-12-refactor-api-client-plan.md`
- `plans/2026-02-12-docs-api-reference-plan.md`
- `plans/2026-02-12-test-auth-flow-plan.md`
- `plans/2026-02-12-chore-deps-update-plan.md`

After presenting the plan, offer next steps using AskUserQuestion:
- `/rune:strive` → `Skill("rune:strive", plan_path)`
- `/rune:forge` → `Skill("rune:forge", plan_path)`
- Open in editor → `Bash("open plans/${path}")` (macOS)
- Create issue → See [issue-creation.md](../rune-orchestration/references/issue-creation.md)

## Issue Creation

See [issue-creation.md](../rune-orchestration/references/issue-creation.md) for the full algorithm.

Read and execute when user selects "Create issue".

## Error Handling

| Error | Recovery |
|-------|----------|
| Research agent timeout (>5 min) | Proceed with partial research |
| Research verification timeout (>5 min) | Proceed with unverified research + warning |
| No git history (git-miner) | Skip, report gap |
| No echoes (echo-reader) | Skip, proceed without history |
| Solution Arena: all solutions killed | Recovery protocol — relax constraints, re-evaluate (see solution-arena.md) |
| Solution Arena: sparse research (<2 approaches) | Skip Arena, proceed to synthesize |
| Forge agent timeout (>5 min) | Proceed with partial enrichment |
| Forge: no agent above threshold | Use inline generic Task prompt for standard enrichment |
| Predictive Goldmask agent failure | Non-blocking — proceed with partial data or skip injection |
| Predictive Goldmask: enhanced budget exceeded | Fallback to basic mode (2 agents) |
| TeamCreate failure ("Already leading") | Catch-and-recover via teamTransition protocol |
| TeamDelete failure (cleanup) | Retry-with-backoff (4 attempts), filesystem fallback |
| Scroll review finds critical gaps | Address before presenting |
| Plan review BLOCK verdict | Address blocking issues before presenting plan |
| Grounding Gate: evidence score < 0.80 | BLOCK — auto-fix false claims, retry once |
| Grounding Gate: invalid assumptions found | BLOCK — revise solution approach, retry once |
| Grounding Gate: agent timeout (>5 min) | Proceed with warning "Plan not grounding-verified" |

## Guardrails

Do not generate implementation code, test files, or configuration changes. This command produces research and plan documents only. If a research agent or forge agent starts writing implementation code, stop it and redirect to plan documentation. Code examples in plans are illustrative pseudocode only.