arcane-cli 0.22.12 → 0.22.13

package/dist/assets/.arcane/governance/universal-agent-rules.md

@@ -53,6 +53,12 @@ See also: [[README]], [[DECISIONS]], [[governance/git-conventions|Git Convention
 
 ---
 
+## Spell Lifecycle
+
+22. **Lifecycle operations run through their spell when one is installed.** Committing, opening a PR, opening or closing a session, reviewing code, and shipping each have a dedicated spell (`spell-commit-work`, `spell-create-pull-request`, `spell-open-session`/`spell-close-session`, `spell-review`, `spell-ship`). When the installed component set includes the matching spell, invoke it for that operation rather than improvising the workflow from general knowledge — even when the user does not name the spell explicitly. The intent→spell routing table injected into each client's L1 instruction file (`CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`) is normative for this mapping, not illustrative.
+
+---
+
 ## Recommendation Guardrails (ADR-034)
 
 15. **Flag actionable recommendations.** Any recommendation that could lead to a purchase, subscription, account creation, or irreversible action must: (a) be flagged explicitly, (b) use verified current information — never assume or fabricate, (c) present free/no-cost alternatives when they exist, (d) state confidence level if based on general knowledge. For >$50 or contracts, require explicit confirmation. See [[agents/agent-policies#actionable-recommendation-policy-adr-034|Full Policy]].

package/dist/assets/.claude/commands/spell-address-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever responding to PR review comments — fetch threads, triage, fix or reply, resolve.
+---
+
 # Address Review
 
 Invoke the Arcane `spell-address-review` spell workflow.

package/dist/assets/.claude/commands/spell-adopt-docs.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when bringing an existing, ungoverned doc tree under Arcane governance.
+---
+
 # Adopt Docs
 
 Invoke the Arcane `spell-adopt-docs` spell workflow.

package/dist/assets/.claude/commands/spell-arcane-version.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when asked about the installed Arcane version, profile, or whether an update is available.
+---
+
 # Arcane Version
 
 Invoke the Arcane `spell-arcane-version` spell workflow.

package/dist/assets/.claude/commands/spell-architect.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY once a PRD exists and needs architecture decisions and a story breakdown before implementation starts.
+---
+
 # Architect
 
 Invoke the Arcane `spell-architect` spell workflow.

package/dist/assets/.claude/commands/spell-brainstorm.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when exploring multiple solutions to a problem before committing to one.
+---
+
 # Brainstorm
 
 Invoke the Arcane `spell-brainstorm` spell workflow.

package/dist/assets/.claude/commands/spell-bug.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever diagnosing and fixing a bug, even if the user just describes broken behavior.
+---
+
 # Bug
 
 Invoke the Arcane `spell-bug` spell workflow.

package/dist/assets/.claude/commands/spell-bump.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before shipping any change that touches distributable content, to determine and apply the correct version bump.
+---
+
 # Bump Version
 
 Invoke the Arcane `spell-bump` spell workflow.

package/dist/assets/.claude/commands/spell-check-drift.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to detect contradictions and stale statements across core docs, periodically or after major changes.
+---
+
 # Check Drift
 
 Invoke the Arcane `spell-check-drift` spell workflow.

package/dist/assets/.claude/commands/spell-close-session.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY at the end of any significant work session, even if the user just says 'wrap up' or 'done for now'.
+---
+
 # Close Session
 
 Invoke the Arcane `spell-close-session` spell workflow.

package/dist/assets/.claude/commands/spell-commit-work.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever committing work during a session, even if the user just says 'commit this'.
+---
+
 # Commit Work
 
 Invoke the Arcane `spell-commit-work` spell workflow.

package/dist/assets/.claude/commands/spell-create-pull-request.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever opening a pull request for the current branch, even if the user just says 'open a PR'.
+---
+
 # Create Pull Request
 
 Invoke the Arcane `spell-create-pull-request` spell workflow.

package/dist/assets/.claude/commands/spell-document.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when conversation content (an analysis, a decision, an investigation) should become a permanent reference doc.
+---
+
 # Document
 
 Invoke the Arcane `spell-document` spell workflow.

package/dist/assets/.claude/commands/spell-dotnet-expert.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when working on a .NET project and best-practice guidance is needed.
+---
+
 # Dotnet Expert
 
 Invoke the Arcane `spell-dotnet-expert` spell workflow.

package/dist/assets/.claude/commands/spell-enchant.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a PRD should be enhanced — UX, accessibility, security, performance — before implementation.
+---
+
 # Enchant
 
 Invoke the Arcane `spell-enchant` spell workflow.

package/dist/assets/.claude/commands/spell-explain-concept.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when the user needs a concept, architecture, or system behavior explained before deciding or building.
+---
+
 # Explain Concept
 
 Invoke the Arcane `spell-explain-concept` spell workflow.

package/dist/assets/.claude/commands/spell-feedback.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when the user reports friction with AI assistance or the workflow itself, not the product being built.
+---
+
 # Feedback
 
 Invoke the Arcane `spell-feedback` spell workflow.

package/dist/assets/.claude/commands/spell-full-cycle.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY for an end-to-end feature request that should chain plan, architect, implement, test, review, and ship.
+---
+
 # Full Cycle
 
 Invoke the Arcane `spell-full-cycle` spell workflow.

package/dist/assets/.claude/commands/spell-generate-bot-icons.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a bot/agent needs a Teams-ready avatar and icon set generated.
+---
+
 # Generate Bot Icons
 
 Invoke the Arcane `spell-generate-bot-icons` spell workflow.

package/dist/assets/.claude/commands/spell-implement.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to work through stories.json autonomously once architecture and stories exist.
+---
+
 # Implement
 
 Invoke the Arcane `spell-implement` spell workflow.

package/dist/assets/.claude/commands/spell-make-discoverable.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when auditing a web property's search/AI-assistant discoverability (metadata, robots, sitemap, indexing).
+---
+
 # Make Discoverable
 
 Invoke the Arcane `spell-make-discoverable` spell workflow.

package/dist/assets/.claude/commands/spell-manifest.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY in a hub repo to triage idea-book/todo-book entries downstream.
+---
+
 # Manifest
 
 Invoke the Arcane `spell-manifest` spell workflow.

package/dist/assets/.claude/commands/spell-open-session.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY at the start of any new session, even if the user just says 'let's start' or asks 'what's next'.
+---
+
 # Open Session
 
 Invoke the Arcane `spell-open-session` spell workflow.

package/dist/assets/.claude/commands/spell-plan.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a feature description needs to become a PRD before architecture or implementation.
+---
+
 # Plan
 
 Invoke the Arcane `spell-plan` spell workflow.

package/dist/assets/.claude/commands/spell-present-arcane.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when asked to present, demo, or explain Arcane itself to an audience.
+---
+
 # Present Arcane
 
 Invoke the Arcane `spell-present-arcane` spell workflow.

package/dist/assets/.claude/commands/spell-product-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when evaluating a shipped feature's real-world performance and deciding next actions.
+---
+
 # Product Review
 
 Invoke the Arcane `spell-product-review` spell workflow.

package/dist/assets/.claude/commands/spell-review-batch.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when multiple open PRs need an adversarial review pass and a consolidated go/no-go verdict.
+---
+
 # Review Batch
 
 Invoke the Arcane `spell-review-batch` spell workflow.

package/dist/assets/.claude/commands/spell-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before merging any nontrivial change, even if the user doesn't explicitly ask for review.
+---
+
 # Review
 
 Invoke the Arcane `spell-review` spell workflow.

package/dist/assets/.claude/commands/spell-save-idea.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to capture a fleeting idea immediately, even if the user just says 'note that' or 'don't forget'.
+---
+
 # Save Idea
 
 Invoke the Arcane `spell-save-idea` spell workflow.

package/dist/assets/.claude/commands/spell-scope.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a PRD is too large for one Spell Loop cycle and needs epic-splitting before architecture.
+---
+
 # Scope
 
 Invoke the Arcane `spell-scope` spell workflow.

package/dist/assets/.claude/commands/spell-security-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before shipping any change that introduces new attack surface, handles sensitive data, or changes trust boundaries.
+---
+
 # Security Review
 
 Invoke the Arcane `spell-security-review` spell workflow.

package/dist/assets/.claude/commands/spell-ship.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before any deploy, even if the user just says 'ship it'.
+---
+
 # Ship
 
 Invoke the Arcane `spell-ship` spell workflow.

package/dist/assets/.claude/commands/spell-status.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when asked for a quick snapshot of session/repo state — branch, TODOs, decisions, last journal.
+---
+
 # Status
 
 Invoke the Arcane `spell-status` spell workflow.

package/dist/assets/.claude/commands/spell-suggest-feature.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when smoke testing or usage surfaces a feature gap worth tracking.
+---
+
 # Suggest Feature
 
 Invoke the Arcane `spell-suggest-feature` spell workflow.

package/dist/assets/.claude/commands/spell-summon-venture.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY in a hub repo when creating a new venture from scratch.
+---
+
 # Summon Venture
 
 Invoke the Arcane `spell-summon-venture` spell workflow.

package/dist/assets/.claude/commands/spell-test.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to validate a completed story or feature against coverage thresholds before marking it done.
+---
+
 # Test
 
 Invoke the Arcane `spell-test` spell workflow.

package/dist/assets/.claude/commands/spell-todo.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever a raw idea needs to become one or more well-scoped TODO items, even if the user just says 'add a todo'.
+---
+
 # Todo
 
 Invoke the Arcane `spell-todo` spell workflow.

package/dist/index.js

@@ -1444,6 +1444,22 @@ ${rules}
 **Denied:** ${def.tools.denied.join(", ")}
 `;
 }
+function renderSpellRoutingSection() {
+  return `## Spell Routing
+
+| When you're about to... | Invoke |
+|---|---|
+| Commit work | \`spell-commit-work\` |
+| Open a session | \`spell-open-session\` |
+| Close a session | \`spell-close-session\` |
+| Open a pull request | \`spell-create-pull-request\` |
+| Ship a feature end-to-end | \`spell-full-cycle\` |
+| Fix a bug | \`spell-bug\` |
+| Review code or a PR | \`spell-review\` |
+
+If a spell exists for the workflow you are about to perform, invoke it \u2014 do not improvise the workflow from general knowledge, even when the user doesn't name the spell.
+`;
+}
 function renderAgentRosterSection(entries) {
   const rows = entries.map(
     ({ def, displayName }) => `| **${displayName}** | ${def.role} | ${def.category} |`
@@ -1564,32 +1580,35 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       }
       synced.push(`.github/agents/${fileName}`);
     }
-    const rosterSection = renderAgentRosterSection(resolved);
+    const copilotSection = `${renderSpellRoutingSection()}
+${renderAgentRosterSection(resolved)}`;
     const copilotMerged = await mergeIntoFile(
       targetDir,
       ".github/copilot-instructions.md",
-      rosterSection,
+      copilotSection,
       { force: true, dryRun: options.dryRun }
     );
     if (copilotMerged)
       synced.push(".github/copilot-instructions.md (agents section)");
   }
   if (options.claude !== false) {
-    const rosterSection = renderAgentRosterSection(resolved);
+    const claudeSection = `${renderSpellRoutingSection()}
+${renderAgentRosterSection(resolved)}`;
     const claudeMerged = await mergeIntoFile(
       targetDir,
       "CLAUDE.md",
-      rosterSection,
+      claudeSection,
       { force: true, dryRun: options.dryRun }
     );
     if (claudeMerged) synced.push("CLAUDE.md (agents section)");
   }
   if (options.codex !== false) {
-    const rosterSection = renderAgentRosterSection(resolved);
+    const codexSection = `${renderSpellRoutingSection()}
+${renderAgentRosterSection(resolved)}`;
     const codexMerged = await mergeIntoFile(
       targetDir,
       "AGENTS.md",
-      rosterSection,
+      codexSection,
       { force: true, dryRun: options.dryRun }
     );
     if (codexMerged) synced.push("AGENTS.md (agents section)");