arcane-cli 0.14.0

package/dist/assets/.github/prompts/spell-full-cycle.prompt.md

@@ -0,0 +1,201 @@
+---
+name: Spell — Full Cycle
+description: End-to-end autonomous Spell Loop — chains plan, architect, implement, test, review, and ship into a single invocation with one human approval gate at merge time
+argument-hint: "Feature description, optional work item ID, target repo (e.g., 'Add user auth to the mobile app, #507, {REPO_ORG}/{REPO_NAME}')"
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt chains all Spell Loop phases into a single autonomous pipeline.
+- Includes optional PRD enchantment (spell-enchant) between Plan and Architect for quality enhancement.
+- Only one human touchpoint: approving the PR at ship time.
+- Delegates each phase to the appropriate specialized agent role (research, architecture, build, QA, marketing review). Resolve concrete personas from [agent-policies](../../governance/agent-policies.md) / [naming-conventions](../../governance/naming-conventions.md); if neither is present, proceed with role names directly.
+- If any phase fails, the pipeline halts and reports the blocker — no silent failures.
+
+---
+
+Run the complete Spell Loop end-to-end for the described feature.
+
+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
+- [governance/cicd-standards.md](../../governance/cicd-standards.md) — CI/CD pipeline and deployment gates
+- [governance/git-conventions.md](../../governance/git-conventions.md) — Branch discipline and commit format
+- [project.md](../../project.md) — Project goals and priorities
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect
+- [governance/product-excellence-standards.md](../../governance/product-excellence-standards.md) — PRD Quality Scorecard for enchantment
+
+---
+
+## Required Inputs
+
+Before proceeding, confirm you have all three:
+
+1. **Feature description** — what to build and why. Accepted formats:
+   - Inline text in the prompt
+   - Path to a PRD file (e.g., `PRD.md`)
+   - **Tracker work item ID** (e.g., `#507`) in `external` mode — fetch it using the detected provider's CLI/API. For an ADO provider, fetch via `az boards work-item show --id {id} --org https://dev.azure.com/{ADO_ORG} --output json` and extract `System.Title`, `System.Description`, and `Microsoft.VSTS.Common.AcceptanceCriteria`; for other providers, fetch the title, description, and acceptance criteria via that provider's equivalent. If the work item has child items, fetch those too. `{ADO_ORG}` resolves from `.arcane.json` or the PRD/feature frontmatter; ask if unset.
+2. **Tracking configuration** — required before execution:
+   - `tracking_mode: internal | external`
+   - `external_provider: ado | jira | other` (required when `tracking_mode=external`)
+   - If omitted and an ADO context is already present, default to `external` + `ado` (backward compatibility).
+   - If `tracking_mode=external` and `external_provider=ado`, an `adoWorkItemId` is required for commit/PR linkage.
+   - In ADO mode, resolve available work item types and apply process-template-aware fallback mapping from `governance/development-methodology.md` before creating/linking hierarchy items.
+3. **Target repo** — which repository and org (e.g., `{REPO_ORG}/{REPO_NAME}`). `{REPO_ORG}`/`{REPO_NAME}` resolve from `.arcane.json` or the PRD/feature frontmatter; if not provided, infer from context or ask.
+
+If `external_provider=jira` or `external_provider=other`, record TODO notes for provider-specific automation and continue with internal artifact flow unless explicit provider commands are supplied.
+
+---
+
+## Pipeline Phases
+
+### Phase 1 — Plan
+
+Execute the `spell-plan` workflow:
+
+1. Gather requirements from the feature description.
+2. Check existing ADRs and business docs for constraints.
+3. Produce `PRD.md` with requirements, acceptance criteria, constraints, and tracking configuration (`tracking_mode`, optional `external_provider`, optional `adoWorkItemId`).
+4. **Gate:** Validate every requirement has at least one testable acceptance criterion. If scope is too large for one sprint, halt and recommend splitting.
+
+Store the PRD in the working directory. Proceed automatically to Phase 1.5.
+
+### Phase 1.5 — Enchant (Optional)
+
+Run a quick quality audit of the PRD against the scorecard in `governance/product-excellence-standards.md`. Score each dimension as Bronze / Silver / Gold.
+
+**Decision logic:**
+- If the user specified `--enchant` or explicitly requested enchantment: run `spell-enchant` workflow fully.
+- If any dimension scores Bronze: recommend enchantment, but proceed without it if the user hasn't requested it.
+- If all dimensions score Silver or above: skip enchantment and proceed to Phase 2.
+
+When running enchantment:
+1. Conduct the research role's analysis (competitive analysis, UX patterns, accessibility audit).
+2. Conduct the marketing-review role's pass (first impressions, brand alignment, onboarding).
+3. Generate enhancement suggestions (Must-Add / Should-Add / Could-Add / Won't-Add).
+4. Check scope budget — if enchanted scope exceeds 2× original, flag prominently.
+5. Produce the enhanced PRD, preserving all original requirements and tagging additions with `[ENCHANTED]`.
+6. Replace the working PRD with the enchanted version.
+
+**Gate:** If scope budget exceeds 2× and the user hasn't pre-approved, halt and ask for confirmation before proceeding.
+
+Proceed automatically to Phase 2.
+
+### Phase 2 — Architect
+
+Execute the `spell-architect` workflow:
+
+1. Read the PRD from Phase 1.
+2. Make architecture decisions (framework, patterns, component structure).
+3. Produce `architecture.md` with decisions, component diagram, and testing strategy.
+4. Produce `stories.json` with the full schema:
+   - Top-level: `feature`, `branchName`, `assignedAgent`, `trackingMode`, optional `externalProvider`, optional `adoWorkItemId`
+   - Per story: `id`, `title`, `description`, `acceptanceCriteria`, `priority`, `passes: false`, `assignedTo`, `testEvidence: null`
+5. **Gate:** Self-validate `stories.json` schema completeness. If any required field is missing, regenerate before proceeding. Every PRD requirement must map to at least one story. No story may depend on an unresolved Open Question.
+
+Proceed automatically to Phase 3.
+
+### Phase 3 — Implement (Autonomous Loop)
+
+Execute the `spell-implement` workflow:
+
+0. **Sync workspace** — before any code changes, ensure the workspace is current:
+   ```bash
+   git fetch --prune origin
+   git checkout main && git pull --ff-only
+   ```
+   If `pull --ff-only` fails, halt and report — manual rebase is needed.
+1. Create the topic branch from `stories.json.branchName` (format: `{agent}/type/description`).
+2. Loop:
+   a. Pick the next story where `passes: false`, ordered by priority.
+   b. Implement the story — minimum code to satisfy acceptance criteria.
+   c. Write tests per `governance/testing-standards.md`.
+   d. Run tests. If passing:
+      - In `external/ado` mode, commit with `#{adoWorkItemId} type(scope): description` and agent attribution trailers (`Agent`, `Model`, `Provider`).
+      - In `internal` mode, commit with standard Conventional Commits format (no ADO prefix) plus attribution trailers.
+   e. Update `stories.json`: set `passes: true`, fill `testEvidence`.
+   f. Append learnings to `progress.txt`.
+   g. Repeat until all stories pass or a story fails 3 consecutive attempts.
+3. **Gate:** If any story is stuck after 3 attempts, halt the pipeline and report the blocker with error details. Do not proceed to Phase 4 with failing stories.
+
+Proceed automatically to Phase 4.
+
+### Phase 4 — Test
+
+Execute the `spell-test` workflow:
+
+1. Run the full test suite (not just per-story — full regression).
+2. Validate coverage: 80% line minimum, 95% critical path.
+3. Map each acceptance criterion from the PRD to a specific passing test.
+4. Update `stories.json` with consolidated test evidence.
+5. **Gate:** If coverage is below threshold or any acceptance criterion lacks a test, loop back to Phase 3 to add missing tests. Maximum 2 coverage-fix loops before halting.
+
+Proceed automatically to Phase 5.
+
+### Phase 5 — Review (Adversarial)
+
+Execute the `spell-review` workflow:
+
+1. Review the full diff (`git diff main...HEAD`).
+2. Check architecture compliance against `architecture.md`.
+3. Check for OWASP Top 10 security issues.
+4. Find a minimum of 3 issues or justify why fewer exist.
+5. Classify findings: HIGH / MEDIUM / LOW.
+6. **Gate:** If any HIGH severity finding exists, loop back to Phase 3 to fix it. MEDIUM and LOW findings are noted in the ship report but do not block. Maximum 2 review-fix loops before halting.
+
+Proceed automatically to Phase 6.
+
+### Phase 6 — Ship
+
+Execute the `spell-ship` workflow:
+
+1. Verify all prior phases passed (PRD, architecture, all stories, tests, review).
+2. Run pre-deploy checklist:
+   - No merge conflicts with target branch.
+   - No secrets or credentials in the diff.
+   - DECISIONS.md updated if new ADRs were created.
+   - Documentation updated for user-facing changes.
+3. Generate the ship report (phase status table, test evidence, review findings, recommendation).
+4. Create the PR:
+   - `external/ado` mode: `az repos pr create --repository {repo} --source-branch {branch} --target-branch main --title "{feature}" --work-items {adoWorkItemId}`
+   - `internal` mode (or provider TODO mode): create PR without `--work-items`.
+5. **HUMAN GATE:** Present the ship report and PR link. Wait for explicit human approval before merging.
+6. After approval: merge via `az repos pr update --id {prId} --status completed`.
+7. Pull merge to local, delete the topic branch.
+
+---
+
+## Error Handling
+
+- **Phase failure:** If any gate fails and exhausts its retry budget, halt immediately. Report which phase failed, what the error was, and what input is needed to unblock.
+- **Stuck story:** After 3 failed attempts on a single story, mark it in `stories.json` with the error and halt. Do not skip stories and continue — a failing story may indicate an architecture problem.
+- **Missing tooling:** If a required tool (test framework, SDK, CLI) is not installed, halt and report the prerequisite. Do not attempt to install system packages without confirmation.
+
+---
+
+## Progress Reporting
+
+After each phase completes, output a brief status line:
+
+```
+[Phase 1/6 — Plan] COMPLETE — PRD.md generated (5 requirements, 8 acceptance criteria)
+[Phase 2/6 — Architect] COMPLETE — 4 stories in stories.json, branch: lafayette/feat/feature-name
+[Phase 3/6 — Implement] COMPLETE — 4/4 stories passing, 12 tests, 87% coverage
+[Phase 4/6 — Test] COMPLETE — full regression green, 87% line / 96% critical path
+[Phase 5/6 — Review] COMPLETE — 0 HIGH, 2 MEDIUM, 1 LOW findings
+[Phase 6/6 — Ship] AWAITING APPROVAL — PR #77 created, ship report below
+```
+
+---
+
+## Rules
+
+- **One human gate only.** Everything before Phase 6 step 5 is autonomous. Do not ask for intermediate approvals unless a gate fails.
+- **No scope creep.** Only build what the feature description specifies.
+- **Fail fast.** If a phase cannot succeed, halt immediately rather than producing garbage for downstream phases.
+- **Attribution required.** Every commit must carry `Agent`, `Model`, and `Provider` trailers per ADR-028/ADR-029.
+- **Branch discipline.** All work on topic branches, never on main. Per ADR-048.
+- **Fresh context per story.** Do not carry assumptions between stories during Phase 3.
+- **Epic checkpointing.** When this spell is run as one epic in a multi-epic plan, recommend running `spell-commit-work` before starting the next epic.

package/dist/assets/.github/prompts/spell-generate-bot-icons.prompt.md

@@ -0,0 +1,84 @@
+---
+name: Spell — Generate Bot Icons
+description: Generate a bot avatar concept with an image-capable agent, then normalize it into Teams-ready color and outline icons.
+argument-hint: Bot concept (e.g., "{AGENT_NAME} for ecommerce ops, powerful + modern, flat vector")
+agent: agent
+---
+
+## Executive Summary
+
+- This spell standardizes bot icon creation for Teams deployments.
+- It separates creative generation (image-capable agent) from deterministic packaging (local script).
+- Output is always Teams-ready: `color.png` (192x192) + `outline.png` (32x32 transparent, white glyph).
+- Use this **after** agent setup (the agent's identity/role is defined) and **before** packaging `manifest.json` in the Teams setup flow.
+
+---
+
+Create a high-quality avatar concept for the bot, then prepare Teams-compliant icon files.
+
+## Inputs
+
+- Bot role and personality (from user argument)
+- Brand direction (if none provided): clean, modern, readable at small sizes
+
+## Rules
+
+- **Validate before processing.** After the source image is saved, confirm it exists and is **square** (equal width and height) before running the build script. If the file is missing, regenerate it; if it is non-square, regenerate or crop to a 1:1 ratio. Do **not** run the build step on a missing or non-square source — fail with a clear message (e.g. `source.png is 1024x768; Teams icons require a square source`).
+- Quick check: `python3 -c "from PIL import Image; w,h=Image.open('{TEMP_DIR}/source.png').size; print(w,h); assert w==h, 'source must be square'"` (or `file {TEMP_DIR}/source.png` to read the dimensions).
+- The image must contain no copyrighted logos, mascots, or trademarked characters.
+
+> **Placeholders.** `{TEMP_DIR}` resolves to a writable working directory — your OS temp dir (`os.tmpdir()` / `$TMPDIR` / `%TEMP%`) plus a `teams-app` subfolder, or a repo-local `.tmp/teams-app/`. `{REPO_ROOT}` is the consuming repository's root. Resolve from `.arcane.json` / your shell; ask if unset.
+
+## Image Generation Requirements
+
+Generate one **source image** with these constraints:
+
+- Square PNG
+- Transparent background preferred
+- High resolution (1024x1024 recommended)
+- Single strong subject, centered
+- Minimal detail that survives downscaling
+- No copyrighted logos, mascots, or trademarked characters
+
+Save as:
+
+- `{TEMP_DIR}/source.png`
+
+## Post-Process (Required)
+
+Run (the script path resolves relative to the repo root):
+
+```bash
+python3 {REPO_ROOT}/playbooks/scripts/build-teams-icons.py \
+  --input {TEMP_DIR}/source.png \
+  --output {TEMP_DIR}
+```
+
+If `playbooks/scripts/build-teams-icons.py` is **missing** under the repo root, do not improvise silently — tell the user the script is expected at `{REPO_ROOT}/playbooks/scripts/build-teams-icons.py` and either restore it or fall back to producing the two sizes manually (e.g. an equivalent PIL/ImageMagick resize: 192x192 `color.png`, and a 32x32 transparent `outline.png` with a white glyph).
+
+This creates:
+
+- `{TEMP_DIR}/color.png` (192x192)
+- `{TEMP_DIR}/outline.png` (32x32, transparent background, white glyph)
+
+## Validation
+
+Run:
+
+```bash
+file {TEMP_DIR}/color.png
+file {TEMP_DIR}/outline.png
+```
+
+Expected:
+
+- `color.png`: PNG image data, 192 x 192
+- `outline.png`: PNG image data, 32 x 32
+
+## Final Output
+
+Report:
+
+- Visual style chosen
+- Paths to generated files
+- Any readability concerns at 32x32 size

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

@@ -0,0 +1,101 @@
+---
+name: Spell — Implement
+description: Autonomous implementation loop — pick a story from stories.json, build it, test it, commit it, repeat until all stories pass
+argument-hint: Path to stories.json or paste story context (optional - uses current directory stories.json by default)
+agent: agent
+---
+
+## Executive Summary
+
+- This is the core autonomous loop of the Spell Loop methodology.
+- Each iteration: pick a story → implement → run tests → commit if passing → update stories.json → loop.
+- Uses fresh context per iteration — only stories.json, progress.txt, and git history carry forward.
+- See [[governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Run the autonomous implementation loop for the current feature.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology
+- [governance/testing-standards.md](../../governance/testing-standards.md) — Testing frameworks and coverage requirements
+- The feature's `architecture.md` — for tech decisions and patterns
+- The feature's `stories.json` — for the work breakdown
+- The feature's `progress.txt` (in `features/{slug}/`, if present) — accumulated learnings from prior iterations; read it before each iteration and append new learnings as the loop proceeds
+
+Workflow (loop until all stories pass):
+
+0. **Sync workspace** — before any code changes, ensure the workspace is current:
+   ```bash
+   git fetch --prune origin
+   git checkout main && git pull --ff-only
+   ```
+   If `pull --ff-only` fails, halt and report — manual rebase is needed.
+
+1. **Load stories.json** — locate the feature folder from the current branch:
+   ```bash
+   # Derive feature folder from branch name (works for lafayette/feat/541-phase-2a or lafayette/feat/phase-2a)
+   FEATURE_FOLDER="features/$(git symbolic-ref --short HEAD | sed 's|.*/feat/||')"
+   ```
+   Load `$FEATURE_FOLDER/stories.json` and `$FEATURE_FOLDER/architecture.md`. If the branch name doesn't follow the `feat/{slug}` or `feat/{id}-{slug}` pattern, look for the most recently modified `features/*/stories.json` or ask the operator for the path.
+
+   Find the next story where `"passes": false`, ordered by priority.
+
+2. **Read context** — load only what this story needs:
+   - The story's description and acceptance criteria from stories.json
+   - Relevant sections of architecture.md
+   - Latest entries in progress.txt (if exists) for learnings from previous iterations
+   - Files that will be modified (check git status)
+
+3. **Implement the story**:
+   - Follow the architecture decisions — do not deviate without flagging.
+   - Write the minimum code to satisfy acceptance criteria.
+   - Follow project coding conventions and patterns from existing code.
+   - Include tests per governance/testing-standards.md.
+
+4. **Run tests**:
+   - Run the test suite for the affected area.
+   - All existing tests must still pass (no regressions).
+   - New tests must pass.
+   - Check coverage against thresholds (80% line, 95% critical path).
+
+5. **Evaluate results**:
+   - **Tests pass:** proceed to commit.
+   - **Tests fail:** debug and fix. If stuck after 3 attempts, mark the story with the error in stories.json and move to the next story.
+
+6. **Commit the story**:
+   - Use Conventional Commits format (see spell-commit-work).
+   - One commit per story (squash if needed).
+   - Include the story ID in the commit body.
+
+7. **Update stories.json**:
+   - Set `"passes": true` for the completed story.
+   - Set `"testEvidence"` with coverage % and test count.
+
+8. **Append to `$FEATURE_FOLDER/progress.txt`**:
+   ```
+   ## Iteration N — [STORY-ID] — [timestamp]
+   ### What was done
+   - [summary of changes]
+   ### What was learned
+   - [patterns, gotchas, conventions discovered]
+   ### What to watch for
+   - [warnings for future iterations]
+   ```
+   File lives in the feature folder, not the repo root.
+
+9. **Loop** — go to step 1 and pick the next story.
+
+10. **Completion** — when all stories have `"passes": true`:
+    - Summarize what was built.
+    - Report total test count and coverage.
+    - Recommend running `spell-review` for adversarial review.
+
+Rules:
+- **Fresh context:** do not carry assumptions from previous stories. Re-read what you need.
+- **No scope creep:** only implement what the story specifies.
+- **Test first when possible:** write the test, see it fail, then implement.
+- **Commit atomically:** one story = one commit.
+- **Never skip tests:** if there's no test framework set up, set it up as the first story.
+- **Stuck threshold:** if a story fails 3 consecutive attempts, mark it and move on. Human intervention needed.

package/dist/assets/.github/prompts/spell-open-session.prompt.md

@@ -0,0 +1,116 @@
+---
+name: Spell — Open Session
+description: Open an Arcane session in a new chat by rebuilding context, identifying highest-priority unfinished work, and proposing concrete next actions.
+argument-hint: Optional focus area (e.g., security hardening, a specific feature, infrastructure setup)
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt opens a new session after chat reset by reading core docs and identifying unfinished work.
+- It produces a state snapshot, top priorities, and concrete next actions to minimize startup friction.
+- Use this when opening work in a new chat session to avoid re-reading full context manually.
+- Optional focus argument narrows scope to a specific domain (security, business, infrastructure).
+
+---
+
+Open work in this repository after context reset. Treat repository documents as source of truth. See [[README]] and [[CLAUDE]] for repo orientation.
+
+If the user provided a focus area in the prompt argument, prioritize that area. Otherwise perform a general session-opening pass.
+
+Use these files first:
+
+- [README.md](../../README.md)
+- [project.md](../../project.md)
+- [TODO.md](../../TODO.md)
+- [DECISIONS.md](../../DECISIONS.md)
+- [naming-conventions.md](../../naming-conventions.md)
+- [ai-context/system-prompt-context.md](../../ai-context/system-prompt-context.md)
+- [agents/agent-policies.md](../../agents/agent-policies.md)
+- Most recent journal file(s) in [journal/](../../journal/)
+- Relevant business overview(s) under [ventures/](../../ventures/)
+
+**Handoff Detection (run before anything else):**
+
+Check `ai-context/system-prompt-context.md` for a `## Next Session Handoff` section.
+
+- If present and **not yet marked consumed** (no `> ✓ Consumed:` line): surface it immediately as `## Picking Up From Last Session` at the very top of your output, before all other sections. Use the `Next concrete action` field as the first item in `## Next Session Plan`. Use the `Active task`, `Active files`, and `Branch` fields to pre-populate the State Snapshot.
+- After surfacing it, mark it consumed by appending `> ✓ Consumed: YYYY-MM-DD` (today's date) on a new line inside the block, then save the file.
+- If the section is absent or already marked consumed: skip this step and proceed with the normal workspace scan.
+
+**Drift Check (run before deep context gathering):**
+
+Run the `spell-check-drift` spell first, before building the state snapshot or gathering deep context. Drift compounds the longer a session runs, so catch it early.
+
+- If **HIGH** drift is found: list it under the `## Risks And Gaps` output section and ask the user whether to fix it before proceeding. Do not continue deep context gathering until they decide.
+- If **MEDIUM** or **LOW** drift is found: note it and suggest deferring it until after the session-opening pass.
+- If no drift is found: note `drift check passed` and continue.
+
+Then produce output in this exact structure:
+
+## Workspace Health Check
+
+Before anything else, check:
+
+- **Current branch:** Run `git branch --show-current` in the arcane repo. If not on `main`, run `git worktree list`:
+  - If this is a worktree-backed session, staying on the topic branch is expected (do not require switching to `main`).
+  - If not worktree-backed, warn the user and suggest switching back to `main`.
+- **Session branch naming compliance:** Branch names must be human-readable and policy-compliant:
+  - Interactive session default: `sessions/YYYY-MM-DD-<topic-slug>` (kebab-case topic from current task/session objective).
+  - Disallow random adjective-noun generator names (example: `ideal-disco`) as session defaults.
+  - If current branch is non-compliant and no active PR depends on it, rename branch to a compliant name. If it was already pushed, migrate remote tracking (`git push -u origin <new-name>` then `git push origin --delete <old-name>`), then continue.
+  - If an active PR uses the old branch name, do not force-delete the old remote branch; flag it and continue with a follow-up rename plan.
+- **Stale local branches:** Run `git branch --merged main` to list branches already merged that should be deleted.
+- **Tracker configuration check (early):** resolve active tracking settings before planning. Read `.arcane.json` first (if present), then the current feature PRD frontmatter if available:
+  - `tracking_mode: internal | external`
+  - `external_provider: ado | jira | other`
+  - If missing, ask the operator to choose now. Default to `external` + `ado` only when existing ADO context already exists (backward compatibility).
+- **Open PRs (external/ado mode only):** if tracking mode is `external` with provider `ado` and ADO MCP is available, list all open PRs across all repos in the configured repo list (resolve from `.arcane.json`; if unset, ask the operator which repos to scan). Flag PRs older than 3 days as stale, older than 7 days as overdue. Format each as a clickable markdown link: `[PR #{id} — {title}](https://dev.azure.com/{ADO_ORG}/{ADO_PROJECT}/_git/{repo}/pullrequest/{id})` — resolve `{ADO_ORG}` and `{ADO_PROJECT}` from `.arcane.json` / PRD frontmatter; ask if unset. Never list a bare `PR #NNN`.
+- **Uncommitted changes:** Run `git status` and report any uncommitted files.
+- **Arcane version check (two-axis):** If `.arcane.json` exists in the repo root, check both whether the repo's managed files are behind the installed CLI *and* whether the installed CLI is behind the latest published version of `arcane-cli`:
+  - Read the installed version from `.arcane.json` (field: `arcaneVersion` or `version`).
+  - Determine the version of the installed `arcane-cli` CLI (for example, `npx arcane-cli --version`, or the locally installed package version).
+  - Run `npm view arcane-cli version` to get the latest published version.
+  - **(a) Managed files behind the installed CLI** (installed CLI version is newer than the version recorded in `.arcane.json`): surface a warning: `⚠️ Managed files out of date: files at <installed> → CLI at <cli>. Run spell update to resync files.`
+  - **(b) Installed CLI behind the latest published version** (latest published is newer than the installed CLI): surface a warning: `⚠️ Arcane CLI update available: CLI at <cli> → latest <latest>. Upgrade the CLI, then run spell update.`
+  - If both axes are current, report current and continue.
+  - If no `.arcane.json` exists, skip silently.
+
+## State Snapshot
+
+- Short bullets by area: security, infrastructure, `{PRIMARY_VENTURE}` readiness, business readiness, and documentation maturity. Resolve `{PRIMARY_VENTURE}` from `.arcane.json` / venture frontmatter; if unset, substitute the active focus area (or omit that bullet).
+
+## Top Unfinished Work
+
+- Prioritized list with severity labels: Critical, High, Medium.
+- Every item must include a file reference.
+
+## Next Session Plan
+
+- 3 to 5 concrete actions to execute now.
+- Keep actions specific and immediately executable.
+- If moving from one completed epic to the next, include an explicit checkpoint action to run `spell-commit-work` first.
+
+## Suggested Session Name
+
+- **Required output field.**
+- Provide a 1–4 word, sentence-case, human-meaningful session name.
+- If a focus/task argument is provided, generate the name deterministically from that focus (never use the generic name `Open session`).
+- If no focus argument is provided, generate the name from the top recommended action in `## Next Session Plan`.
+- Optional helper line: `Branch helper: sessions/YYYY-MM-DD-<kebab-case-slug>`.
+
+## Risks And Gaps
+
+- Contradictions, stale assumptions, missing files, or draft documents that block progress.
+
+## Clarifications Needed
+
+- Up to 3 short questions only if they materially change priorities.
+
+Rules:
+
+- Prefer facts from docs over assumptions.
+- Keep output concise but actionable.
+- Include clickable file paths for claims.
+- If you find outdated statements (for example, docs that contradict the current state of the system), call them out explicitly as drift.
+- Never return a generic session name like `Open session` when a meaningful alternative can be derived from focus or the top next action.

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

@@ -0,0 +1,145 @@
+---
+name: Spell — Plan
+description: Generate a Product Requirements Document (PRD) from a feature description using structured planning
+argument-hint: Feature or initiative to plan (e.g., "user authentication for a mobile app")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt generates a PRD.md from a feature description or TODO item.
+- It follows a structured analysis pattern — requirements, acceptance criteria, and constraints.
+- Output feeds directly into `spell-architect` as the next phase of the Spell Loop.
+- See [[governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Generate a Product Requirements Document for the described feature or initiative.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology
+- [project.md](../../project.md) — Project goals and priorities
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect
+
+Workflow:
+
+1. **Configure tracking mode first** — decide how this work will be tracked before requirement intake:
+
+   ```yaml
+   tracking_mode: internal | external
+   external_provider: ado | jira | other
+   ```
+
+   Rules:
+   - If not explicitly set and ADO context is already present (work item ID + org/project), default to `tracking_mode: external`, `external_provider: ado` for backward compatibility.
+   - If `tracking_mode=internal`, do not require an external tracker ID.
+   - If `tracking_mode=external` and `external_provider=ado`, collect org/project and resolve process template + available work item types before planning:
+     ```bash
+     az devops project show --org https://dev.azure.com/{org} --project {project} --query "capabilities.processTemplate.templateName" --output tsv
+     az boards work-item-type list --org https://dev.azure.com/{org} --project {project} --output json --query "[].name"
+     ```
+     Then enforce level-to-type mapping using the first available type in order:
+     - Epic-level: `Epic → Feature → User Story → Issue`
+     - Feature-level: `Feature → User Story → Issue`
+     - Story-level: `User Story → Issue → Task`
+     - Task-level: `Task → Issue`
+     - Defect-level: `Bug → Issue → Task`
+   - If `external_provider=jira` or `other`, record as TODO and continue with internal artifacts unless the operator provides explicit provider workflow steps.
+
+2. **Gather requirements** — accept input from any of these sources:
+
+   | Source | Format | How to fetch |
+   |--------|--------|--------------|
+   | **Description in prompt** | Inline text | Use as-is |
+   | **ADO work item ID** (external/ado mode) | `#507` or `507` with org name | Run: `az boards work-item show --id {id} --org https://dev.azure.com/{org} --output json` and extract `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`, and `System.Title` |
+   | **File path** | Path to existing doc | Read the file |
+
+   If the input is an ADO work item ID, fetch its content first, then use it as the feature description. If it has child work items, fetch those too for additional context.
+
+   Ask clarifying questions if the feature description is ambiguous. You need to understand:
+   - What problem does this solve?
+   - Who is the user/audience?
+   - What business does this belong to?
+   - Are there existing ADRs or constraints?
+   - **If `tracking_mode=external` and `external_provider=ado`: What is the ADO work item ID?** — required before proceeding in ADO mode. Store it as `adoWorkItemId` in PRD frontmatter so it flows to `spell-architect` and `stories.json`.
+
+3. **Research context** — check the relevant business docs in `ventures/` and any existing code repos.
+
+4. **Generate PRD.md** with these sections:
+   ```markdown
+   # PRD: [Feature Name]
+
+   ---
+   tracking:
+     tracking_mode: [internal|external]
+     external_provider: [ado|jira|other|null]
+     adoWorkItemId: [number|null]
+   ---
+
+   ## Problem Statement
+   [What problem are we solving? Why now?]
+
+   ## Target Users
+   [Who benefits? Which business?]
+
+   ## Requirements
+   ### Must Have
+   - [Requirement with acceptance criteria]
+
+   ### Should Have
+   - [Requirement with acceptance criteria]
+
+   ### Won't Have (this iteration)
+   - [Explicitly excluded scope]
+
+   ## Constraints
+   - [Technical: frameworks, platforms, existing architecture]
+   - [Business: budget, timeline, dependencies]
+   - [Security: per threat model]
+
+   ## Acceptance Criteria
+   - [ ] [Testable criterion 1]
+   - [ ] [Testable criterion 2]
+
+   ## Dependencies
+   - [Other features, services, or decisions needed]
+
+   ## Open Questions
+   - [Unresolved items that need human decision]
+   ```
+
+   Include an **example config snippet** when presenting the draft:
+   ```yaml
+   tracking:
+     tracking_mode: external
+     external_provider: ado
+     adoWorkItemId: 541
+   ```
+
+5. **Validate against existing ADRs** — ensure the PRD doesn't contradict established decisions.
+
+6. **Save to disk** — derive the feature folder from the tracking configuration and slugified feature name, then write the PRD:
+   ```bash
+   # external/ado example: adoWorkItemId=541, feature name="Phase 2A" → slug="phase-2a"
+   # FEATURE_DIR="features/{adoWorkItemId}-{slug}"
+
+   # internal or non-ado external example:
+   # FEATURE_DIR="features/{slug}"
+   mkdir -p "$FEATURE_DIR"
+   # Write PRD.md to the feature folder
+   ```
+   Save the generated PRD.md using:
+   - `features/{adoWorkItemId}-{slug}/PRD.md` when `tracking_mode=external` and `external_provider=ado`
+   - `features/{slug}/PRD.md` when `tracking_mode=internal` or other providers without an ADO ID
+   Confirm the resolved path to the user.
+
+7. **Present for review** — show the PRD to the user for approval before proceeding to `spell-architect`.
+
+8. **Provider TODO handling** — if `external_provider=jira` or `external_provider=other`, add a TODO note in PRD open questions that provider-specific automation/linking is pending.
+
+Rules:
+- Every requirement must have at least one testable acceptance criterion.
+- Scope must be small enough for one sprint (1-2 weeks of agent work).
+- If the scope is too large, recommend splitting into multiple PRDs.
+- Flag any requirements that would need a new ADR decision.