ktg-plugin-marketplace/plugins/ultraplan-local/commands/ultraplan-local.md

---
name: ultraplan-local
description: Deep implementation planning with interview, parallel specialized agents, external research, and optional background execution
argument-hint: "[--spec spec.md | --fg] <task description>"
model: opus
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
---

# Ultraplan Local v1.0

Deep, multi-phase implementation planning. Uses an interview to gather requirements,
adaptive specialized agent swarms for exploration, external research for unfamiliar
technologies, and adversarial review to stress-test the plan.

## Phase 1 — Parse mode and validate input

Parse `$ARGUMENTS` for mode flags:

1. If arguments start with `--spec `: extract the file path after `--spec`.
   Set **mode = spec-driven**. Read the spec file. If it does not exist, report
   the error and stop.

2. If arguments start with `--fg `: extract the task description after `--fg`.
   Set **mode = foreground**.

3. If arguments start with `--quick `: extract the task description after `--quick`.
   Set **mode = quick**.

4. If arguments start with `--export `: extract the remainder as `{format} {plan-path}`.
   Split on the first space: format is the first token, plan path is the rest.
   Valid formats: `pr`, `issue`, `markdown`, `headless`.
   Set **mode = export**.

   If the format is not one of pr/issue/markdown/headless, report and stop:
   ```
   Error: unknown export format '{format}'. Valid: pr, issue, markdown, headless
   ```

   If the plan file does not exist, report and stop:
   ```
   Error: plan file not found: {path}
   ```

5. If arguments start with `--decompose `: extract the plan file path after `--decompose`.
   Set **mode = decompose**.

   If the plan file does not exist, report and stop:
   ```
   Error: plan file not found: {path}
   ```

6. If arguments contain `--research `: extract file path(s) after `--research`.
   Collect paths until encountering another `--` flag or a token that does not
   look like a file path (no `/` or `.md` extension). Maximum 3 briefs.
   Set **has_research_brief = true**. Validate each path exists — if any is
   missing, report and stop:
   ```
   Error: research brief not found: {path}
   ```
   The `--research` flag can combine with other flags:
   - `--research brief.md <task>` — default mode with research brief
   - `--research brief.md --fg <task>` — foreground with research brief
   - `--research brief.md --spec spec.md` — spec-driven with research brief
   Remove `--research` and its paths from the argument string before
   applying the other flag checks above.

7. Otherwise: the entire argument string is the task description.
   Set **mode = default**.

If no task description and no spec file, output usage and stop:

```
Usage: /ultraplan-local <task description>
       /ultraplan-local --spec <path-to-spec.md>
       /ultraplan-local --research <brief.md> [brief2.md] <task description>
       /ultraplan-local --fg <task description>
       /ultraplan-local --quick <task description>
       /ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
       /ultraplan-local --decompose <plan-path>

Modes:
  default       Interview (interactive) → background planning → notify when done
  --spec        Skip interview, use provided spec → background planning
  --research    Enrich planning with pre-built research brief(s) (up to 3)
  --fg          All phases in foreground (blocks session)
  --quick       Interview → plan directly (no agent swarm) → adversarial review
  --export      Generate shareable output from an existing plan (no new planning)
  --decompose   Split an existing plan into self-contained headless sessions

  --research can combine with other flags:
    --research brief.md <task>              Default mode + research context
    --research brief.md --fg <task>         Foreground + research context
    --research brief.md --spec spec.md      Spec-driven + research context

Examples:
  /ultraplan-local Add user authentication with JWT tokens
  /ultraplan-local --spec .claude/ultraplan-spec-2026-04-05-jwt-auth.md
  /ultraplan-local --research .claude/research/ultraresearch-2026-04-08-oauth2.md Implement OAuth2 auth
  /ultraplan-local --fg Refactor the database layer to use connection pooling
  /ultraplan-local --quick Add rate limiting to the API
  /ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
  /ultraplan-local --export headless .claude/plans/ultraplan-2026-04-06-rate-limiting.md
  /ultraplan-local --decompose .claude/plans/ultraplan-2026-04-06-rate-limiting.md
```

Do not continue past this step if no task was provided.

Report the detected mode to the user:
```
Mode: {default | spec-driven | foreground}
Task: {task description or "from spec: {path}"}
```

## Phase 1.5 — Export (runs only when mode = export)

**Skip this phase entirely unless mode = export.**

Read the plan file. Extract these sections from the plan content:
- Task description (from Context section)
- Implementation steps (from Implementation Plan section)
- Risks (from Risks and Mitigations section)
- Test strategy (from Test Strategy section, if present)
- Scope estimate (from Estimated Scope section)

### Format: `pr`

Output a markdown block formatted as a PR description:

```
## Summary

{2–3 sentence summary of what this change does and why}

## Changes

{Bulleted list of implementation steps, one line each}

## Test plan

{Bulleted checklist from test strategy, formatted as - [ ] items}

## Risks

{Risks from plan, abbreviated to 1 line each}

---
*Generated by ultraplan-local from {plan filename}*
```

### Format: `issue`

Output a markdown block formatted as an issue comment:

```
## Implementation plan summary

**Task:** {task description}
**Plan file:** {plan path}
**Scope:** {N files, complexity}

### Proposed approach
{3–5 bullet points from key implementation steps}

### Open questions / risks
{Top 2–3 risks from plan}

---
*Generated by ultraplan-local*
```

### Format: `markdown`

Output the plan content with internal metadata stripped:
- Remove the "Revisions" section
- Remove plan-critic and scope-guardian scores/verdicts
- Remove `[ASSUMPTION]` markers (but keep the surrounding sentence)
- Keep everything else verbatim

### Format: `headless`

This is a shortcut for `--decompose`. It runs the full session decomposition
pipeline and is equivalent to `--decompose {plan-path}`. Proceed to
Phase 1.6 (Decompose) below.

---

After outputting the formatted block (for pr/issue/markdown), say:
```
Export complete ({format}). Copy the block above.
```

Then **stop**. Do not continue to Phase 2 or any subsequent phase.

## Phase 1.6 — Decompose (runs only when mode = decompose or export headless)

**Skip this phase entirely unless mode = decompose or export format = headless.**

Read the plan file. Verify it contains an Implementation Plan section with
numbered steps. If no steps are found, report and stop:
```
Error: plan has no implementation steps. Run /ultraplan-local first to generate a plan.
```

Determine the output directory from the plan slug:
- Extract the slug from the plan filename (e.g., `ultraplan-2026-04-06-auth-refactor` → `auth-refactor`)
- Output directory: `.claude/ultraplan-sessions/{slug}/`

Launch the **session-decomposer** agent:

```
Plan file: {plan path}
Plugin root: ${CLAUDE_PLUGIN_ROOT}
Output directory: .claude/ultraplan-sessions/{slug}/
```

The session-decomposer will:
1. Parse the plan's steps and their file dependencies
2. Build a dependency graph between steps
3. Group steps into sessions of 3–5 steps each
4. Identify which sessions can run in parallel (waves)
5. Generate one session spec file per session
6. Generate a dependency diagram (mermaid)
7. Generate a launch script (`launch.sh`)

When the session-decomposer completes, present the summary to the user:

```
## Decomposition Complete

**Master plan:** {plan path}
**Sessions:** {N} across {W} waves
**Output:** .claude/ultraplan-sessions/{slug}/

### Sessions

| # | Title | Steps | Wave | Parallel |
|---|-------|-------|------|----------|
{session table from decomposer}

### Files generated

- Session specs: .claude/ultraplan-sessions/{slug}/session-*.md
- Dependency graph: .claude/ultraplan-sessions/{slug}/dependency-graph.md
- Launch script: .claude/ultraplan-sessions/{slug}/launch.sh

You can:
- Review individual session specs before running
- Run all sessions: `bash .claude/ultraplan-sessions/{slug}/launch.sh`
- Run a single session: `claude -p "$(cat .claude/ultraplan-sessions/{slug}/session-1-*.md)"`
- Say **"launch"** to start headless execution from here
```

If the user says **"launch"**: run the launch script via Bash.

Then **stop**. Do not continue to Phase 2 or any subsequent phase.

## Phase 2 — Requirements gathering (interview)

**Skip this phase entirely if mode = spec-driven.** Proceed to Phase 3.

### Research-enriched interview

If **has_research_brief = true**: read each research brief file before starting the
interview. Then adjust the interview:

1. Tell the user: "I've read {N} research brief(s). The interview will focus on
   decisions and implementation details — skipping topics already covered."
2. Skip questions about technologies, patterns, or approaches already researched.
3. Focus on: implementation preferences, non-functional requirements, scope decisions.
4. Reference brief findings in questions where relevant:
   > "The research brief found that {finding}. Does this affect your approach?"
   > "The brief identified {risk}. Should the plan account for this?"

If **has_research_brief = false**: proceed with the standard interview below.

Use `AskUserQuestion` to interview the user about the task. Ask **one question at
a time** — never dump all questions at once. Follow up based on answers.

### Interview flow

**Start with the most important question:**
> What is the goal of this task? What does success look like?

**Then ask follow-ups based on the answer. Choose from these topics:**
- What is explicitly NOT in scope? (non-goals)
- Are there technical constraints? (specific versions, compatibility, no new dependencies)
- Do you have preferences? (library X over Y, specific patterns, architectural style)
- Are there non-functional requirements? (performance targets, security needs, accessibility)
- Has anything been tried before? What worked or failed?

**Rules:**
- Ask 3–5 questions for typical tasks. Maximum 8 for complex tasks.
- If the user says "skip", "proceed", "just plan it", or similar — stop interviewing
  immediately. Write a minimal spec from the task description alone.
- Adapt your questions to what the user tells you. If they give a detailed task
  description, skip obvious questions.
- Never ask about things you can discover from the codebase.

### Adaptive depth

After each answer, assess the response length and vocabulary:

- **Detailed answer** (2+ sentences, technical terminology, specific examples):
  - Treat the user as senior — they know the codebase
  - Skip obvious follow-ups they already answered
  - Ask more targeted questions: constraints, edge cases, specific technical choices
  - Reduce question count: aim for 3–4 total instead of 5

- **Short or uncertain answer** (1 sentence or less, "I don't know", "not sure", vague):
  - Treat the user as unfamiliar with the problem space
  - Simplify follow-up questions — avoid open-ended technical questions
  - Offer alternatives instead of asking open questions:
    > "Should this be synchronous or asynchronous? (synchronous is simpler; async handles more concurrent users)"
  - For bugs: focus on reproduction before requirements:
    > "What do you see? What did you expect to see?"
  - Allow "I don't know" as a valid answer — record it as an open assumption in the spec

Never change your question count based on impatience. Only change depth based
on answer quality.

### Write the spec file

After gathering requirements, read the spec template:
@${CLAUDE_PLUGIN_ROOT}/templates/spec-template.md

Generate a slug from the task (first 3-4 meaningful words, lowercase, hyphens).
Write the spec to: `.claude/ultraplan-spec-{YYYY-MM-DD}-{slug}.md`

Create the `.claude/` directory if it does not exist.

Fill in all sections based on interview answers. Mark unanswered sections with
"Not discussed — no constraints assumed."

Tell the user:
```
Spec saved: .claude/ultraplan-spec-{date}-{slug}.md
```

## Phase 3 — Background transition

**If mode = foreground or quick:** Skip this phase. Continue to Phase 4 inline.

**If mode = default or spec-driven:**

Launch the **planning-orchestrator** agent with this prompt:

```
Spec file: {spec path}
Task: {task description}
Mode: {default | spec | quick}
Plan destination: .claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md
Plugin root: ${CLAUDE_PLUGIN_ROOT}
Research briefs: {path1, path2, ...}  ← include ONLY if has_research_brief = true

Read the spec file and execute your full planning workflow.
Write the plan to the destination path.
```

Launch the planning-orchestrator via the Agent tool with `run_in_background: true`.
The agent runs autonomously while you continue working — you will be notified
when the plan is ready.

Then output to the user and **stop your response**:
```
Background planning started via planning-orchestrator.

  Spec: .claude/ultraplan-spec-{date}-{slug}.md
  Plan: .claude/plans/ultraplan-{date}-{slug}.md

You will be notified when the plan is ready.
You can continue working on other tasks in the meantime.
```

Do not wait for the orchestrator. Do not continue to Phase 4.
The planning-orchestrator handles Phases 4 through 10 autonomously.

---

**Everything below this line runs either in foreground mode or inside the
background agent. The instructions are identical regardless of context.**

---

## Phase 4 — Codebase sizing

Determine codebase scale to calibrate agent turns (not agent count).

Run via Bash:
```
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.c" -o -name "*.cpp" -o -name "*.h" -o -name "*.cs" -o -name "*.swift" -o -name "*.kt" -o -name "*.sh" -o -name "*.md" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" -not -path "*/build/*" | wc -l
```

Classify:
- **Small** (< 50 files)
- **Medium** (50–500 files)
- **Large** (> 500 files)

Report:
```
Codebase: {N} source files ({scale}). Deploying exploration agents.
```

## Phase 4b — Spec review

Launch the **spec-reviewer** agent:
Prompt: "Review this spec for quality: {spec path}. Check completeness, consistency,
testability, and scope clarity."

Handle the verdict:
- **PROCEED** — continue to Phase 5.
- **PROCEED_WITH_RISKS** — continue, carry flagged risks as `[ASSUMPTION]` in the plan.
- **REVISE** — in foreground mode, present findings and ask the user for clarification.
  In background mode, carry all findings as `[ASSUMPTION]` entries.

## Phase 5 — Parallel exploration (specialized agents + research)

**If mode = quick:** Do NOT launch any exploration agents. Instead, run a
lightweight file check:
- `Glob` for files matching key terms from the task description (up to 3 patterns)
- `Grep` for function/type definitions matching key terms (up to 3 patterns)

Report findings as:
```
Quick scan: {N} potentially relevant files found via Glob/Grep.
No agent swarm — proceeding directly to planning.
```

Then skip Phase 6 (deep-dives) and proceed to Phase 7 (Synthesis) with only
the quick-scan results.

---

**All other modes:** Launch exploration agents **in parallel** (all in a single
message). Use the specialized agents from the `agents/` directory.

**All agents run for all codebase sizes.** Scale `maxTurns` by size (small: halved,
medium: default, large: default) instead of dropping agents.

| Agent | Small | Medium | Large | Purpose |
|-------|-------|--------|-------|---------|
| `architecture-mapper` | Yes | Yes | Yes | Codebase structure, patterns, anti-patterns |
| `dependency-tracer` | Yes | Yes | Yes | Module connections, data flow, side effects |
| `risk-assessor` | Yes | Yes | Yes | Risks, edge cases, failure modes |
| `task-finder` | Yes | Yes | Yes | Task-relevant files, functions, types, reuse candidates |
| `test-strategist` | Yes | Yes | Yes | Test patterns, coverage gaps, strategy |
| `git-historian` | Yes | Yes | Yes | Recent changes, ownership, hot files, active branches |
| `research-scout` | Conditional | Conditional | Conditional | External docs (only when unfamiliar tech detected) |
| `convention-scanner` | No | Yes | Yes | Coding conventions, naming, style, test patterns |

### Always launch (all codebase sizes):

**architecture-mapper** — full codebase structure, tech stack, patterns, anti-patterns.
Prompt: "Analyze the architecture of this codebase. The task being planned is: {task}"

**dependency-tracer** — module connections, data flow, side effects for task-relevant code.
Prompt: "Trace dependencies and data flow relevant to this task: {task}. Focus on modules
that will be affected by the implementation."

**risk-assessor** — risks, edge cases, failure modes, technical debt near task area.
Prompt: "Assess risks and failure modes for implementing this task: {task}. Check for
complexity hotspots, security boundaries, and technical debt in the relevant code."

**task-finder** — all files, functions, types, and interfaces directly related to the task.
Prompt: "Find all code relevant to this task: {task}. Include existing implementations
that solve similar problems, API boundaries, database models, configuration files.
Report file paths and line numbers for every finding."

**test-strategist** — existing test patterns, coverage gaps, test strategy.
Prompt: "Analyze the test infrastructure and design a test strategy for this task: {task}.
Discover existing patterns and identify coverage gaps."

**git-historian** — recent changes, code ownership, hot files, active branches.
Prompt: "Analyze git history relevant to this task: {task}. Report recent changes,
ownership, hot files, and active branches that may affect planning."

### Launch for medium+ codebases (50+ files):

**Convention Scanner** — use the `convention-scanner` plugin agent (model: "sonnet")
for medium+ codebases only.
Provide concrete examples from the codebase, not generic advice."

### Conditional: External research

After reading the task description and spec (if available), determine if the task
involves technologies, APIs, or libraries that are:
- Not clearly present in the codebase
- Being upgraded to a new major version
- Being used in an unfamiliar way

If yes: launch **research-scout** in parallel with the other agents.
Prompt: "Research the following technologies for this task: {task}.
Specific questions: {list specific questions about the technology}.
Technologies to research: {list}."

If no external technology is involved: skip research-scout and note:
"No external research needed — all technologies are well-represented in the codebase."

## Phase 6 — Targeted deep-dives

After all Phase 5 agents complete, review their results and identify **knowledge gaps**
— areas where exploration was too shallow to plan confidently.

Common reasons for deep-dives:
- A critical function was found but its implementation details are unclear
- A dependency chain needs tracing to understand side effects
- A test pattern was identified but the test infrastructure needs more detail
- A risk was flagged but the actual impact needs verification

For each significant gap, spawn a targeted deep-dive agent (model: "sonnet",
subagent_type: "Explore") with a narrow, specific brief.

Launch up to 3 deep-dive agents in parallel. If no gaps exist, skip this phase
and note: "Initial exploration was sufficient — no deep-dives needed."

## Phase 7 — Synthesis

After all agents complete (initial + deep-dives + research), synthesize:

1. Read all agent results carefully
2. Identify overlaps and contradictions between agents
3. Build a mental model of the codebase architecture
4. Catalog reusable code: existing functions, utilities, patterns
5. Integrate research findings with codebase analysis
6. Note remaining gaps — things you cannot determine from code or research
   (these become assumptions in the plan, marked explicitly)
7. For each finding, track whether it came from **codebase analysis** or
   **external research** — the plan must distinguish these sources

Do NOT write this synthesis to disk. It is internal working context only.

## Phase 8 — Deep planning

Read the spec file (from Phase 2 or provided via --spec).
Read the plan template: @${CLAUDE_PLUGIN_ROOT}/templates/plan-template.md

Write the plan following the template structure. The plan MUST include:

### Required sections

1. **Context** — Why this change is needed. Reference the spec's goal and constraints.
2. **Codebase Analysis** — Tech stack, patterns, relevant files, reusable code,
   external tech researched. Every file path must be real (verified during exploration).
3. **Research Sources** — If research-scout was used: table of technologies, sources,
   findings, and confidence levels. Omit if no research was conducted.
4. **Implementation Plan** — Ordered steps. Each step specifies:
   - Exact files to modify or create (with paths)
   - What changes to make and why
   - Which existing code to reuse
   - Dependencies on other steps
   - Whether the step is based on codebase analysis or external research
   - **On failure:** — recovery action (revert/retry/skip/escalate)
   - **Checkpoint:** — git commit command after success
10. **Execution Strategy** — For plans with > 5 steps: group steps into sessions
    (3–5 steps each), organize sessions into waves (parallel where independent),
    specify scope fences per session. Omit for plans with ≤ 5 steps.
5. **Alternatives Considered** — At least one alternative approach with
   pros/cons and reason for rejection.
6. **Risks and Mitigations** — From the risk-assessor findings. What could go
   wrong and how to handle it.
7. **Test Strategy** — From the test-strategist findings (if available).
   What tests to write and which patterns to follow.
8. **Verification** — Testable criteria. Not "check that it works" but
   specific commands to run and expected outputs.
9. **Estimated Scope** — File counts and complexity rating.

### Quality standards

- Every file path in the plan must exist in the codebase (or be explicitly
  marked as "new file to create")
- Every "reuses" reference must point to a real function/pattern found during
  exploration
- Steps must be ordered by dependency (not by file path or importance)
- Verification criteria must be concrete and executable
- The plan must be implementable by someone who has not seen the exploration
  results — it must stand on its own
- Research-based decisions must cite their source

### Write the plan

Generate the slug from the task description (or reuse the spec slug).
Write the plan to: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
Create the `.claude/plans/` directory if it does not exist.

## Phase 9 — Adversarial review

Launch two review agents **in parallel**:

**plan-critic** — adversarial review of the plan.
Prompt: "Review this implementation plan for the task: {task}.
Plan file: {plan path}. Read it and find every problem — missing steps,
wrong ordering, fragile assumptions, missing error handling, scope creep,
underspecified steps. Rate each finding as blocker, major, or minor."

**scope-guardian** — scope alignment check.
Prompt: "Check this implementation plan against the requirements.
Task: {task}. Spec file: {spec path}. Plan file: {plan path}.
Find scope creep (plan does more than asked) and scope gaps (plan misses
requirements). Check that referenced files and functions exist."

After both complete:
- If **blockers** are found: revise the plan to address them. Add a "Revisions"
  note at the bottom of the plan listing what changed and why.
- If only **major** issues: revise to address them. Add revisions note.
- If only **minor** issues or clean: proceed without changes. Note the
  review result in the plan.

## Phase 10 — Present and refine

Present a summary to the user:

```
## Ultraplan Complete

**Task:** {task description}
**Mode:** {default | spec-driven | foreground}
**Spec:** {spec file path, or "none (foreground mode)"}
**Plan:** .claude/plans/ultraplan-{date}-{slug}.md
**Exploration:** {N} agents deployed ({N} specialized + {N} deep-dives + {research status})
**Scope:** {N} files to modify, {N} to create — {complexity}

### Key decisions
- {Decision 1 and rationale}
- {Decision 2 and rationale}

### Implementation steps ({N} total)
1. {Step 1 summary}
2. {Step 2 summary}
...

### Research findings
{Summary of external research, or "No external research conducted."}

### Adversarial review
**Plan critic:** {Summary — blockers/majors/minors found, how addressed}
**Scope guardian:** {Summary — creep/gaps found, how addressed}

You can:
- Ask questions or request changes to refine the plan
- Say **"execute"** to start implementing
- Say **"execute with team"** to implement with parallel Agent Team (if eligible)
- Say **"save"** to keep the plan for later
```

If the user asks questions or requests changes:
- Update the plan file in-place
- Show what changed
- Re-present the summary

## Phase 11 — Handoff

### "save" / "later" / "done"

Confirm the plan and spec file locations and exit.

### "execute" / "go" / "start"

Begin implementing the plan step by step in this session. Follow the plan exactly.
Mark each step complete as you go.

### "execute with team" / "team"

Before creating a team, verify eligibility:
1. Count implementation steps that are **independent** (no dependency on each other)
   AND touch **different files/modules**
2. If fewer than 3 independent steps: inform the user and fall back to sequential
   execution. "The plan has fewer than 3 independent steps — sequential execution
   is more efficient."

If eligible:
1. Present the proposed team split: which steps go to which team member
2. Ask for confirmation: "Create Agent Team with {N} members? (yes/no)"
3. If confirmed: create the team with `TeamCreate`, assign step clusters to
   each member. Use `isolation: "worktree"` on each team member agent so they
   work in isolated git worktrees — this prevents file conflicts during parallel
   implementation. Coordinate execution and clean up with `TeamDelete` when done.
4. If `TeamCreate` fails (tool not available): fall back to sequential execution
   and notify the user

## Phase 12 — Session tracking

After the plan is presented (Phase 10) or after handoff (Phase 11), write a
session record to `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl` (create the file
if it does not exist).

Record format (one JSON line):
```json
{
  "ts": "{ISO-8601 timestamp}",
  "task": "{task description (first 100 chars)}",
  "mode": "{default|spec|fg}",
  "slug": "{plan slug}",
  "codebase_size": "{small|medium|large}",
  "codebase_files": {N},
  "agents_deployed": {N},
  "deep_dives": {N},
  "research": {true|false},
  "critic_verdict": "{BLOCK|REVISE|PASS}",
  "guardian_verdict": "{ALIGNED|CREEP|GAP|MIXED}",
  "outcome": "{execute|execute_team|save|refine}"
}
```

If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
Never let tracking failures block the main workflow.

## Hard rules

- **Scope**: Only explore the current working directory and its subdirectories.
  Never read files outside the repo (no ~/.env, no credentials, no other repos).
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).
  Opus only runs in the main thread for synthesis and planning.
- **Privacy**: Never log, store, or repeat file contents that look like
  secrets, tokens, or credentials. Never log prompt text.
- **No premature execution**: Do not modify any project files until the user
  explicitly approves the plan.
- **Plan stands alone**: The plan file must be understandable without access
  to the exploration results. Include all necessary context.
- **Honesty**: If exploration reveals the task is trivial (single file, obvious
  change), say so. Do not inflate the plan to justify the process. Suggest
  the user just implements it directly.
- **Adaptive**: Never spawn more agents than the codebase warrants. A 10-file
  project does not need 7 exploration agents. Scale down.
- **Research transparency**: Always distinguish codebase-derived decisions from
  research-derived decisions in the plan.