arcane-cli 0.14.0

package/dist/assets/.github/prompts/spell-address-review.prompt.md

@@ -0,0 +1,114 @@
+---
+name: Spell — Address Review
+description: Respond to code-review feedback on a pull request — fetch comment threads, triage each, implement fixes or reply with rationale, and resolve every thread.
+argument-hint: --pr <number> (required) [--fix-all] — the PR to address; --fix-all treats all suggestions/nitpicks as fix-now
+agent: agent
+---
+
+## Executive Summary
+
+- This spell handles inbound code-review feedback: read comments, act on them, and resolve the threads.
+- Each comment is triaged — must-fix / suggestion / question / nitpick — and given a disposition.
+- Must-fix items are implemented, committed, and pushed; others are implemented or answered with rationale.
+- Every thread is resolved at the end (many providers require all threads resolved before merge).
+- This is the author-side counterpart to `spell-review` (the reviewer side). Provider-agnostic.
+
+---
+
+Respond to review feedback for the specified pull request.
+
+Context to consult:
+
+- `.arcane/governance/git-conventions.md` — commit format, agent attribution trailers, PR policy, and the interactive-session commit gate.
+- `.arcane/governance/development-methodology.md` — workflow phases.
+
+Related spells:
+
+- `spell-review` — the reviewer side. If review was run here, its findings carry stable IDs (`R1`, `R2`, …); reference those IDs when replying so each thread maps to the original finding.
+- `spell-create-pull-request` — opens the PR this spell responds to. Run it first if no PR exists yet.
+
+## Arguments
+
+- `--pr <number>` — **required.** The PR to address. If omitted, check the current branch for an associated PR or ask the user.
+- `--fix-all` — optional. Treat all suggestions and nitpicks as fix-now (no deferrals).
+
+## Step 0 — Setup
+
+1. **Resolve the PR.** If `--pr` is given, use it. If omitted, look up the PR for the current branch (`gh pr view --json number` / `az repos pr list --source-branch <branch>`). If still none, **stop** and ask the user for the PR number — do not guess.
+2. **Working tree must be clean.** Run `git status`. If dirty, **stop** and ask the user to commit or stash first — never stash silently, since uncommitted work can get tangled into the review-fix commits below.
+3. **Detect the provider** from the git remote:
+
+   | Remote URL contains | Provider |
+   | --- | --- |
+   | `github.com` | GitHub (`gh`) |
+   | `dev.azure.com` / `visualstudio.com` | Azure DevOps (`az repos`) |
+   | anything else | unknown — **stop** and ask the user |
+
+4. **Fetch the PR plus all comment threads:**
+   - **GitHub:** `gh pr view <PR> --comments`
+   - **Azure DevOps:** `az repos pr thread list --id <PR>`
+
+## Step 1 — Parse threads
+
+For each thread extract: thread ID, author, file + line (if inline), comment text, status, existing replies. Keep only **active** threads; ignore already-resolved ones. If a comment references a `spell-review` finding ID (`R1`, …), carry it through so the reply can cite it.
+
+**If zero active threads remain:** report "No active review threads to address — nothing to do" and stop. Do not create commits or push.
+
+## Step 2 — Categorize each comment
+
+| Category | Criteria | Action |
+| --- | --- | --- |
+| must-fix | bug, security issue, logic error, broken behavior, standards violation | implement, commit, push |
+| suggestion | better approach, refactor, optional improvement | implement OR reply with rationale |
+| question | clarification / "why did you…?" | answer in the thread |
+| nitpick | minor style / naming preference | implement OR reply with rationale |
+
+Heuristics: "must"/"should"/"required"/"blocking" → must-fix; ends with "?" or starts "why/how/what" → question; "nit"/"minor"/"optional"/"consider" → nitpick; alternative offered without requiring → suggestion. When unsure, escalate to suggestion (not nitpick).
+
+## Step 3 — Disposition
+
+| Disposition | When |
+| --- | --- |
+| Fix Now | all must-fix; suggestions/nitpicks < ~30 min effort AND within files the PR already touches |
+| Defer | scope-expanding items: new features, infra/tooling, cross-file refactors, > ~1 hr effort |
+| Decline | the current approach is intentional — reply with rationale |
+
+`--fix-all` forces all suggestions/nitpicks to Fix Now. Deferred items get a `TODO.md` entry with a `(PR #<n> feedback)` note **and** a reply on the thread pointing to that TODO before the thread is resolved — never resolve a deferred thread silently, or the reviewer cannot tell it was tracked vs. ignored.
+
+## Step 4 — Present the plan, then wait
+
+Show a table (`# | category | disposition | author | file:line | summary | planned action`) plus counts. Wait for confirmation; let the user reclassify any item before proceeding.
+
+## Step 5 — Execute
+
+Commits in this spell follow `.arcane/governance/git-conventions.md`: Conventional Commits format, agent attribution (`--author` + required `Agent`/`Model`/`Provider` trailers) when an agent authors the change, and — because this is an **interactive session** — present each proposed commit message and **wait for the human's approval before committing** (the Step 4 plan approval covers *what* to do, not the commit itself). Never squash.
+
+For **must-fix** (one thread at a time): read the code → implement → run the relevant tests.
+- **If tests pass:** commit (e.g. `fix(scope): address review — <desc>`) → reply `Fixed in <hash>. <what changed>` (cite the `R#` finding ID if one exists) → resolve the thread immediately.
+- **If tests fail:** do **not** commit. Either fix the regression and re-run, or — if the fix is wrong or larger than expected — revert the change, reply on the thread explaining what blocked it, and reclassify to Defer (TODO + thread note). A broken must-fix must never land.
+
+For **suggestions/nitpicks**: if implementing, make the change, run tests, and batch into one commit; reply and resolve. If declining, reply with specific, respectful rationale (reference an ADR or convention if relevant) and resolve as won't-fix.
+
+For **questions**: answer clearly in the thread; if the question reveals a real issue, reclassify and handle it; resolve after answering.
+
+Resolve threads via the provider:
+- **GitHub:** resolve the review thread (`gh` / GitHub MCP resolve-thread).
+- **Azure DevOps:** update the thread status (`Fixed` or `WontFix`).
+- **If a thread cannot be auto-resolved** (provider API error, insufficient permissions, or the reviewer must resolve it themselves): leave the reply in place, list the thread in the Step 6 report under "needs manual resolution," and do not treat the sweep as complete.
+
+## Step 6 — Sweep, push, report
+
+1. Re-fetch threads; resolve any still-active ones (this is the merge gate on many providers). Any thread that genuinely cannot be auto-resolved (see Step 5) is reported as "needs manual resolution," not silently left open.
+2. `git push` all commits.
+3. Print a summary table of actions taken (category, file, action, commit), thread status (resolved / deferred-with-TODO / needs manual resolution), commits pushed, and next steps (CI, notify reviewer, ready for re-review).
+4. Optionally post the summary back to the PR as a top-level comment for a durable record.
+
+## Rules
+
+- Always present the plan and wait for confirmation before changing code.
+- This is an interactive session: get human approval for each commit message before committing (per git-conventions Commit Governance).
+- Never commit a change whose tests fail — fix, revert, or defer instead.
+- Resolve each thread immediately after addressing it — do not batch resolution to the very end (except the final sweep).
+- Never dismiss feedback without reasoning, and never resolve a deferred thread without leaving a TODO pointer on it.
+- Follow `.arcane/governance/git-conventions.md` for commit format and attribution; do not squash.
+- Never include secrets or tokens in replies or commits.

package/dist/assets/.github/prompts/spell-arcane-version.prompt.md

@@ -0,0 +1,82 @@
+---
+name: Spell — Arcane Version
+description: Report the version of Arcane installed in this repository, the active profile, installed components, and whether an update is available.
+argument-hint: Optional flag — pass "components" to list all installed components in full detail
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt reads `.arcane.json` and reports the installed Arcane version for this repository.
+- It surfaces the install date, profile, and component count.
+- Optionally lists every installed component when the "components" argument is passed.
+- Use this any time you need to know which Arcane version a repo is running.
+
+---
+
+Report the Arcane installation state for this repository.
+
+## Step 1 — Read the Manifest
+
+Read [.arcane.json](.arcane.json) from the repository root.
+
+If the file does not exist, stop and output:
+
+```
+⚠ Arcane is not installed in this repository.
+Run `spell init` to install it.
+```
+
+## Step 2 — Output Installation Summary
+
+Produce output in this exact structure:
+
+### Arcane Installation
+
+| Field            | Value                         |
+| ---------------- | ----------------------------- |
+| **Version**      | `{version from .arcane.json}` |
+| **Profile**      | `{profile}`                   |
+| **Installed At** | `{installedAt}`               |
+| **Components**   | `{count}` installed           |
+
+### Update Check
+
+- Fetch the latest published version from the npm registry: `https://registry.npmjs.org/arcane-cli/latest`
+- Extract the `version` field from the JSON response.
+- Compare to the installed version.
+
+If up to date:
+
+```
+✔ You are on the latest version ({version}).
+```
+
+If behind:
+
+```
+⚠ Update available: {installed} → {latest}
+Run `spell update` to upgrade.
+```
+
+If the npm registry is unreachable, report:
+
+```
+ℹ Could not reach npm registry — update check skipped.
+```
+
+## Step 3 — Component Detail (optional)
+
+Only include this section when the user passed "components" as the prompt argument.
+
+List each entry from the `components` array in `.arcane.json` as a table:
+
+| Component | Installed Version | Files |
+| --------- | ----------------- | ----- |
+| ...       | ...               | ...   |
+
+## Rules
+
+- Do not modify any files.
+- Keep output factual — read directly from `.arcane.json`, do not infer or assume values.
+- If `installedAt` is an ISO 8601 timestamp, display it as a human-readable date (e.g., "26 May 2026").

package/dist/assets/.github/prompts/spell-architect.prompt.md

@@ -0,0 +1,116 @@
+---
+name: Spell — Architect
+description: Generate architecture decisions and story breakdown from a PRD, producing architecture.md and stories.json
+argument-hint: Path to PRD.md or paste the PRD content
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt takes a PRD and produces architecture decisions plus an implementable story breakdown.
+- It follows a structured solutioning pattern — progressive context chain from requirements to implementation plan.
+- Outputs `architecture.md` and `stories.json` that feed into `spell-implement`.
+- See [[governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Generate architecture decisions and story breakdown from the provided PRD.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology and stories.json format
+- [governance/testing-standards.md](../../governance/testing-standards.md) — Testing frameworks and coverage requirements
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect and extend
+
+Workflow:
+
+1. **Read the PRD** — understand requirements, constraints, and acceptance criteria.
+   - If no PRD exists for the feature, do not architect against assumptions — recommend the user run `spell-plan` first to produce one, then return here.
+
+2. **Verify PRD coverage** — before designing the architecture, confirm the PRD covers the scope needed to design against. Never guess to fill holes. If there are gaps or ambiguities (missing requirements, undefined constraints, unresolved acceptance criteria), list them explicitly and ask the user to resolve them — or loop back to `spell-plan` — before proceeding. Only continue once the gaps are resolved.
+
+3. **Make architecture decisions** — for each significant technical choice:
+   - What are the options?
+   - What are the tradeoffs?
+   - What does the decision depend on?
+   - Propose a recommendation with rationale.
+   - Flag decisions that need a new ADR in DECISIONS.md.
+
+4. **Generate architecture.md**:
+   ```markdown
+   # Architecture: [Feature Name]
+
+   ## Overview
+   [High-level approach in 2-3 sentences]
+
+   ## Decisions
+   ### [Decision 1: e.g., API Design]
+   - **Options:** [A, B, C]
+   - **Decision:** [Chosen option]
+   - **Rationale:** [Why]
+   - **ADR:** [Existing ADR-NNN or "Needs new ADR"]
+
+   ## Component Diagram
+   [Mermaid diagram showing how components interact]
+
+   ## Data Flow
+   [Sequence diagram for key workflows]
+
+   ## Testing Strategy
+   - [Framework per governance/testing-standards.md]
+   - [Key test scenarios from acceptance criteria]
+   - [Coverage targets]
+
+   ## Security Considerations
+   - [Per threat model]
+
+   ## Implementation Notes
+   - [Tech stack specifics, package versions, patterns to follow]
+   ```
+
+5. **Break into stories** — generate `stories.json` per the format in development-methodology.md:
+   - Each story must be completable in one AI context window (one file change, one endpoint, one component).
+   - Order stories by dependency (infrastructure first, then API, then UI).
+   - Include acceptance criteria from the PRD mapped to specific stories.
+   - Mark all stories as `"passes": false`.
+
+5a. **Validate stories.json schema** — before outputting, self-check every field. Missing fields break `spell-implement`. Required top-level fields:
+   - `feature` (string)
+   - `branchName` (string, format: `agent/type/description`)
+   - `assignedAgent` (string, agent slug)
+   - `trackingMode` (`internal` or `external`)
+   - `externalProvider` (required when `trackingMode=external`)
+   - `adoWorkItemId` (required only when `trackingMode=external` and `externalProvider=ado`)
+
+   Required per-story fields:
+   - `id` (string, e.g. `FEAT-001`)
+   - `title` (string)
+   - `description` (string — detailed enough for implementation without additional context)
+   - `acceptanceCriteria` (array of strings)
+   - `priority` (number, 1 = highest)
+   - `passes` (boolean, always `false` on output)
+   - `assignedTo` (string, agent slug)
+   - `testEvidence` (null on output)
+
+   If any required field is missing, regenerate before outputting. Do not present incomplete stories.json.
+
+6. **Implementation readiness check** — verify:
+   - Every PRD requirement maps to at least one story.
+   - No story depends on an unresolved Open Question from the PRD.
+   - Testing strategy covers all acceptance criteria.
+   - No architecture decision contradicts existing ADRs.
+
+7. **Save to disk** — write both outputs to the feature folder:
+   - `features/{adoWorkItemId}-{slug}/architecture.md` and `features/{adoWorkItemId}-{slug}/stories.json` when `trackingMode=external` and `externalProvider=ado`
+   - `features/{slug}/architecture.md` and `features/{slug}/stories.json` when `trackingMode=internal` (or non-ADO external providers without an ADO ID)
+
+   Resolve `trackingMode`, `externalProvider`, optional `adoWorkItemId`, and slug from PRD frontmatter first. If the folder does not exist, create it with `mkdir -p`.
+   Confirm the paths to the user after writing.
+
+8. **Present for review** — show the architecture and story breakdown to the user.
+
+Rules:
+- Stories must be right-sized per the methodology doc (not "build the entire dashboard").
+- Architecture decisions must reference existing ADRs when relevant.
+- Use Mermaid for all diagrams.
+- If PRD scope is too large, recommend splitting before proceeding.

package/dist/assets/.github/prompts/spell-bootstrap-business.prompt.md

@@ -0,0 +1,73 @@
+---
+name: Spell — Bootstrap Business
+description: Create a new business documentation starter in Arcane using the template, naming rules, and setup playbook.
+argument-hint: Business Name | Business Type | One-line description
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt scaffolds a new business documentation package from the template automatically.
+- It applies naming conventions, creates required files, and initializes checklists per business type.
+- Use this when starting a new business to ensure consistent structure and avoid missing setup steps.
+- Input format is: `Business Name | Business Type | Description` — prompt will ask for missing fields.
+
+---
+
+Bootstrap a new business in this repository.
+
+Parse prompt argument as:
+`<Business Name> | <Business Type> | <One-line Description>`
+
+If any required value is missing, ask only for missing fields.
+
+Use these files first (each is optional — if missing, proceed as noted):
+
+- [playbooks/new-business-setup.md](../../playbooks/new-business-setup.md) — setup playbook. If `playbooks/` doesn't exist, skip and derive steps from the business-type checklist below.
+- [naming-conventions.md](../../naming-conventions.md) — slug/file naming rules. If missing, default to lowercase-with-dashes slugs.
+- [ventures/\_template/overview.md](../../ventures/_template/overview.md) — overview template. If missing, generate a minimal overview from the fields below.
+- [README.md](../../README.md) — repo navigation. If missing, skip cross-linking.
+- [project.md](../../project.md) — project context. If missing, skip.
+
+> **Business root.** `{BUSINESS_ROOT}` is the directory that holds business/venture folders (default: `ventures/`). Resolve from `.arcane.json` or repo frontmatter; if `ventures/` doesn't exist and no business root is configured, ask the user where business folders live before creating anything.
+
+Workflow:
+
+1. Create `{BUSINESS_ROOT}/<slug>/` using existing repo style (lowercase with dashes). If the business root doesn't exist yet, create it at the configured location (or the path the user provided).
+2. Create these files:
+   - `overview.md` from template, filled with provided business details and current date.
+   - `config.md` with placeholders for `{PLATFORM_NAME}` configuration, data paths, and platform integrations. (`{PLATFORM_NAME}` is the org's operating platform — resolve from `.arcane.json`/frontmatter; ask if unset.)
+   - `legal.md` with baseline legal checklist and links to relevant repo docs.
+3. Add a startup checklist tailored to the business type (`e-commerce`, `app`, `protocol`, or `service`).
+4. Add cross-links only when appropriate:
+   - Update [README.md](../../README.md) only if there is a clear place for business navigation.
+   - Update [TODO.md](../../TODO.md) only with concrete, actionable next tasks.
+5. Return a ready-to-start summary.
+
+Output format:
+
+## Created
+
+- File and folder paths created.
+
+## Defaults Applied
+
+- Slug, naming decisions, and template assumptions used.
+
+## Immediate Next Actions
+
+1. Action one.
+2. Action two.
+3. Action three.
+4. Action four.
+5. Action five.
+
+## Questions To Finalize
+
+- Up to 3 targeted questions, or `None`.
+
+Rules:
+
+- Follow repository frontmatter conventions.
+- Do not create Azure resources directly; document steps only.
+- Keep generated docs editable and operational, not verbose.

package/dist/assets/.github/prompts/spell-brainstorm.prompt.md

@@ -0,0 +1,124 @@
+---
+name: Spell — Brainstorm
+description: Divergent ideation — explore multiple solutions to a problem space before committing to a plan
+argument-hint: "Problem space or opportunity (e.g., 'How should we handle multi-tenant billing?')"
+agent: agent
+---
+
+## Executive Summary
+
+- This spell generates multiple solution options for a problem space before narrowing to a plan.
+- It produces divergent ideas, evaluates trade-offs, and surfaces hidden constraints — without committing to implementation.
+- Use this BEFORE `spell-plan` when you're unsure which direction to take, or when the problem is ambiguous.
+- Output: structured options with trade-off matrix, recommended path, and open questions.
+
+---
+
+Explore the given problem space and generate solution options.
+
+Use these files for context. Each is **optional** — if a file is missing, proceed without it and note the gap in your output so the user knows what wasn't consulted:
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology. _If missing:_ proceed with general SDLC reasoning.
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs (to avoid contradicting decided patterns). _If missing:_ assume no decided patterns and state that ADR conflicts could not be checked.
+- [project.md](../../project.md) — Project goals and business context. _If missing:_ infer context from the problem statement and ask a clarifying question if goals are unclear.
+- [naming-conventions.md](../../naming-conventions.md) — Agent roster and roles. _If missing:_ proceed without role references.
+- [TODO.md](../../../TODO.md) — In-progress work (referenced in step 4). _If missing:_ skip the in-progress-work cross-check and note it.
+
+---
+
+## Workflow
+
+### 1. Problem Framing
+
+Accept the problem from one of these sources:
+
+| Source | Format | How to fetch |
+|--------|--------|--------------|
+| **Description in prompt** | Inline text | Use as-is |
+| **ADO work item ID** | `#507` or `507` with org name | Run: `az boards work-item show --id {id} --org https://dev.azure.com/{org} --output json` |
+| **File path** | Path to existing doc | Read the file |
+
+Clarify the problem by identifying:
+- **What is the core tension?** — competing goals, missing capability, or scaling pain
+- **Who is affected?** — users, operators, downstream systems
+- **What constraints exist?** — budget, timeline, tech stack, ADRs already decided
+- **What does "good enough" look like?** — minimum viable outcome vs. ideal outcome
+
+If the problem is too vague, ask up to 3 clarifying questions before proceeding.
+
+### 2. Divergent Ideation
+
+Generate **3–5 distinct approaches** to the problem. Each must be meaningfully different — not just parameter variations of the same idea.
+
+For each option:
+
+```markdown
+### Option N: [Name]
+**One-liner:** [What this approach does in ≤15 words]
+**How it works:** [2-3 sentences on mechanism]
+**Strengths:** [What this gets right]
+**Weaknesses:** [What this sacrifices or risks]
+**Effort:** S (< 1 sprint) / M (1-2 sprints) / L (3+ sprints)
+**Prerequisite ADRs:** [Decisions that must be made first, or "none"]
+```
+
+Guidelines for generating options:
+- Include at least one **simple/minimal** option (the "just do the simplest thing" path)
+- Include at least one **ambitious** option (the ideal-world approach)
+- Include at least one **unconventional** option (reframe the problem, challenge assumptions)
+- Do NOT include options that violate existing ADRs unless you explicitly flag the conflict
+
+### 3. Trade-off Matrix
+
+Produce a comparison table:
+
+| Dimension | Option 1 | Option 2 | Option 3 | ... |
+|-----------|----------|----------|----------|-----|
+| **Complexity** | Low/Med/High | | | |
+| **Time to value** | Days/Weeks/Months | | | |
+| **Scalability** | Poor/Good/Excellent | | | |
+| **Reversibility** | Easy/Hard/Irreversible | | | |
+| **Risk** | Low/Med/High | | | |
+| **Alignment with goals** | Weak/Moderate/Strong | | | |
+
+### 4. Hidden Constraints & Risks
+
+Surface things the user might not have considered:
+- Dependencies on decisions not yet made
+- Interaction with other in-progress work (check `TODO.md`)
+- Security or compliance implications
+- Data migration or backwards-compatibility concerns
+- Skills or tooling gaps
+
+### 5. Recommendation
+
+State your recommended path clearly:
+
+```markdown
+## Recommended Path
+
+**Option [N]: [Name]**
+
+**Why:** [1-2 sentences on why this balances trade-offs best for the current context]
+
+**Immediate next step:** [One concrete action — likely "run `spell-plan` with this direction"]
+```
+
+If no single option is clearly best, say so and identify what additional information would break the tie.
+
+### 6. Open Questions
+
+List up to 5 questions that would refine the decision:
+- Questions whose answers would change the recommendation
+- Questions about constraints not visible in the docs
+- Questions about user preferences or business priorities
+
+---
+
+## Rules
+
+- **Never commit to implementation.** This spell produces options, not plans. The output **feeds into `spell-plan`** (run it with the recommended direction). For a large idea spanning multiple features or sprints, hand off to `spell-scope` first to break it into deliverables, then `spell-plan` each.
+- **Quantity over polish.** Brainstorming favors breadth. Options don't need to be fully fleshed out — just distinct enough to compare.
+- **Challenge assumptions.** If the user's framing seems to constrain solutions unnecessarily, say so explicitly.
+- **Respect decided ADRs.** Flag conflicts but don't silently ignore existing decisions.
+- **Stay grounded.** Options must be feasible given the tech stack and team size. No "hire 5 engineers" solutions for a solo operation.

package/dist/assets/.github/prompts/spell-bug.prompt.md

@@ -0,0 +1,109 @@
+---
+name: Spell — Bug
+description: Document, diagnose, and fix a bug — files a tracker work item (per tracking_mode), traces root cause, implements fix, verifies, and commits
+argument-hint: Bug description (e.g., "Session detail dialog shows 404 when clicking a mock session")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt handles the full bug lifecycle: document → track → diagnose → fix → verify → close.
+- It records the bug in your configured tracker (external provider) or `TODO.md` (internal mode) and links the fix commit to it.
+- Output is a working fix with tests, committed using Conventional Commits format.
+- **When to use:** you have a concrete defect — wrong/broken behavior versus expected. If the report is actually a request for *new* behavior, route to `spell-suggest-feature` instead. For small non-blocking cleanups discovered along the way, capture them with `spell-todo`.
+- See [[governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Document, diagnose, and fix the described bug.
+
+Use these files for context (each is optional — if a file is missing, proceed and note the assumption you fell back on):
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology **and tracker-provider specifics** (which tracker, work-item types, commit-link syntax). If missing, default to `tracking_mode: internal` and track in `TODO.md`.
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect. If missing, proceed without ADR constraints.
+- [governance/testing-standards.md](../../governance/testing-standards.md) — Coverage thresholds. If missing, match the test conventions already present in the repo.
+
+Workflow:
+
+1. **Capture the bug** — gather these details from the user (ask if missing):
+
+   | Field | Description |
+   |-------|-------------|
+   | **Summary** | One-line description of the bug |
+   | **Reproduction steps** | Numbered steps to reproduce |
+   | **Expected behavior** | What should happen |
+   | **Actual behavior** | What actually happens (include error messages, HTTP codes, screenshots) |
+   | **Severity** | Critical / High / Medium / Low |
+   | **Affected component** | File path, page, API route, or module |
+   | **Discovery context** | How was this found? (smoke test, user report, monitoring) |
+
+2. **Record the bug** — file it in whatever tracker this repo uses. Resolve `tracking_mode` from `.arcane.json` (or the repo's feature/PRD frontmatter); if unset, **ask** rather than assuming.
+
+   - **`tracking_mode: internal`** (or no tracker configured) — append the bug to `TODO.md` (create it if absent) using the captured fields from Step 1. Use the `TODO.md` entry's identifier as `{WORK_ITEM_ID}`. No external tooling required.
+   - **`tracking_mode: external`** — file a work item in the configured provider. Read [governance/development-methodology.md](../../governance/development-methodology.md) for the provider, work-item type, and required fields; do **not** assume Azure DevOps. Extract the returned id as `{WORK_ITEM_ID}`.
+
+     *Azure DevOps is one such provider — if and only if `.arcane.json` / methodology names it (and the `az` CLI is available), file it like so. Resolve `{ADO_ORG}` and `{ADO_PROJECT}` from `.arcane.json`; ask if unset:*
+     ```bash
+     az boards work-item create \
+       --type Bug \
+       --title "[Bug] {SUMMARY}" \
+       --description "{formatted description with repro steps}" \
+       --org https://dev.azure.com/{ADO_ORG} \
+       --project {ADO_PROJECT} \
+       --output json
+     ```
+
+   If the configured tooling is unavailable or the user prefers manual tracking, fall back to the `TODO.md` entry above and continue.
+
+3. **Diagnose** — trace the code path to find the root cause:
+   - Read the affected component and its dependencies.
+   - Identify the exact line(s) where the bug manifests.
+   - Determine *why* the bug exists (data mismatch, missing case, race condition, etc.).
+   - Document the root cause concisely.
+
+4. **Implement the fix** — write the minimal code change:
+   - Fix only the bug — no refactoring, no feature additions.
+   - Follow existing code patterns and conventions.
+   - If the fix touches a public interface, check all callers.
+
+5. **Add or update tests** — ensure the bug cannot regress:
+   - Write a test that reproduces the bug (fails without the fix).
+   - Verify existing tests still pass.
+   - Run the full test suite: `npx vitest run` (or project-specific command).
+
+6. **Verify the fix** — confirm the bug is resolved:
+   - Run the reproduction steps from Step 1 — they should now succeed.
+   - Check for side effects in related functionality.
+   - If applicable, rebuild and restart: `npm run build`.
+
+7. **Commit** — stage and propose a commit message for approval:
+   ```
+   fix({scope}): {SUMMARY}
+
+   {Root cause explanation}
+
+   {What was changed and why}
+
+   {WORK_ITEM_LINK}
+   ```
+   Follow Conventional Commits format. For `{WORK_ITEM_LINK}`, use the commit-link convention your tracker expects (per [governance/development-methodology.md](../../governance/development-methodology.md)) — e.g. `Fixes AB#{WORK_ITEM_ID}` for Azure DevOps, `Fixes #{WORK_ITEM_ID}` for GitHub Issues, or a plain `Refs TODO.md` for internal mode. Wait for user approval before executing `git commit`.
+
+8. **Close out the tracker** — update the work item's state to reflect the fix:
+   - **`internal`** — mark the `TODO.md` entry as resolved (check it off / move to a Done section).
+   - **`external`** — transition the work item to its resolved/done state via the provider. For Azure DevOps specifically (resolve `{ADO_ORG}` from `.arcane.json`):
+     ```bash
+     az boards work-item update \
+       --id {WORK_ITEM_ID} \
+       --state Resolved \
+       --org https://dev.azure.com/{ADO_ORG} \
+       --output json
+     ```
+     For other providers, follow [governance/development-methodology.md](../../governance/development-methodology.md).
+
+Rules:
+- Fix only the reported bug. Do not bundle unrelated improvements.
+- If the report turns out to describe *new* or *changed* behavior rather than a defect, stop and route the user to `spell-suggest-feature`. Capture any non-blocking follow-ups you notice via `spell-todo` rather than expanding this fix.
+- Every fix must have a test that would have caught the bug.
+- Present the commit message for human approval — never auto-commit.
+- If the root cause is unclear, present your diagnosis and ask for confirmation before implementing.
+- If the fix is risky (touches shared infrastructure, auth, or data), flag it explicitly.