arcane-cli 0.22.5 → 0.22.7

package/dist/assets/.arcane/governance/development-methodology.md

@@ -89,13 +89,23 @@ Persist tracking configuration in PRD frontmatter (and in `.arcane.json` when av
 ```yaml
 tracking:
   tracking_mode: external # internal | external
-  external_provider: ado  # ado | jira | other
+  external_provider: ado  # ado | github | jira | other
   ado:
     org: "{ADO_ORG}"
     project: "{ADO_PROJECT}"
     process_template: "Agile"
 ```
 
+Or, for a GitHub-tracked repo:
+
+```yaml
+tracking:
+  tracking_mode: external
+  external_provider: github
+  github:
+    repo: "{owner}/{repo}"
+```
+
 ### Process-Template-Aware ADO Hierarchy Rules
 
 When `tracking_mode=external` and `external_provider=ado`, do not hardcode work item types. Resolve types from the project's process template and currently enabled types first:
@@ -131,6 +141,19 @@ Child linkage rules:
 3. If the selected fallback type combination cannot be linked as parent/child in that process template, use `Related` links and prefix titles with logical level tags (for example: `[EPIC]`, `[FEATURE]`) to preserve intent.
 4. Never silently flatten hierarchy. Document fallback/link decisions in `execution-plan.md` notes.
 
+### GitHub Issues Conventions
+
+When `tracking_mode=external` and `external_provider=github`, resolve `{owner}/{repo}` from `git remote get-url origin` (or `.arcane.json`'s `github.repo` field if set) rather than assuming it matches the working directory name.
+
+GitHub Issues has no configurable work-item-type hierarchy the way Azure DevOps does — there is no process-template discovery step, and no equivalent to `az boards work-item-type list`. Use these substitutes instead:
+
+- **Categorization** — labels, not types. Resolve the repo's actual labels first (`gh label list`) rather than assuming `bug`/`enhancement`/`epic` exist; a fresh repo may have only GitHub's defaults, or none. Apply a label with `--label <name>` on create, or omit it rather than inventing one.
+- **Hierarchy** — GitHub Issues has no native parent/child API field reachable from `gh`. Simulate logical hierarchy with a task-list in the parent issue's body (`- [ ] #43`, `- [ ] #44`) and `Related to #NN` / `Part of #NN` references in child issue bodies. This is a substitute, not true hierarchy — document the simulation in `execution-plan.md` notes the same way an ADO `Related`-link fallback gets documented (see the Child linkage rules above), so a reader doesn't mistake the checkbox list for a first-class relationship the platform enforces.
+- **Creation:** `gh issue create --title "{title}" --body "{body}" [--label <name>]` — prints the issue URL on success; the trailing path segment is the issue number.
+- **Fetching:** `gh issue view {id} --json title,body,labels`.
+- **Closing:** `gh issue close {id} --reason completed [--comment "{note}"]` (`--reason` also accepts `not planned` or `duplicate`).
+- **Commit/PR linkage:** `Fixes #{id}` / `Closes #{id}` in a commit message or PR body auto-closes the issue on merge (GitHub-native behavior, no extra command needed) — prefer this over a manual `gh issue close` call when the fix lands via a PR.
+
 ### External Provider TODOs
 
 - **Jira (`external_provider=jira`)** — TODO: define issue-type mapping, parent-child/epic linkage strategy, and command examples.
@@ -252,7 +275,7 @@ For features that should run end-to-end with minimal human intervention, use `sp
 spell-full-cycle = spell-plan → [spell-enchant] → spell-architect → [spell-implement → spell-test → spell-review]* → spell-ship
 ```
 
-The entire pipeline runs autonomously with a single human gate at PR approval. Includes optional PRD enchantment between Plan and Architect (runs automatically if any quality dimension scores Bronze, or if `--enchant` is specified). Requires three inputs: feature description, tracking configuration (`tracking_mode` and optional `external_provider`), and target repo. In ADO mode, include the ADO work item ID. Each phase has built-in quality gates that halt the pipeline on failure rather than producing garbage for downstream phases.
+The entire pipeline runs autonomously with a single human gate at PR approval. Includes optional PRD enchantment between Plan and Architect (runs automatically if any quality dimension scores Bronze, or if `--enchant` is specified). Requires three inputs: feature description, tracking configuration (`tracking_mode` and optional `external_provider`), and target repo. In ADO mode, include the ADO work item ID; in GitHub mode, include the issue number if one already exists. Each phase has built-in quality gates that halt the pipeline on failure rather than producing garbage for downstream phases.
 
 See [.github/prompts/spell-full-cycle.prompt.md](../.github/prompts/spell-full-cycle.prompt.md) for the complete prompt.
 

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

@@ -33,7 +33,7 @@ See also: [[README]], [[DECISIONS]], [[governance/git-conventions|Git Convention
 
 7. **Use wiki-links for cross-references** (e.g., `[[DECISIONS#ADR-NNN|Short Title]]`, `[[journal/YYYY-MM-DD-topic-slug|Session Label]]`). This enables knowledge graph visualization.
 
-8. **Use Mermaid for diagrams** (` ```mermaid ` blocks) for all flow charts, architecture diagrams, and sequence diagrams. Directory trees stay as plain code blocks.
+8. **Use Mermaid for diagrams** (` ```mermaid ` blocks) for all flow charts, architecture diagrams, and sequence diagrams. Directory trees stay as plain code blocks. Spell output describing state the spell already computed — not authored, freehand explanatory content — additionally follows the **generated state diagrams** convention ([ARC-036](https://github.com/codemagicianhq/arcane/blob/main/DECISIONS.md#arc-036--generated-state-diagrams-deterministic-mermaid-for-computed-spell-state)): a deterministic, data-derived Mermaid diagram built only from values already in scope, never modeled or invented. Skip it for one-line outputs, speed-rule spells, or any state with only a single reading — the diagram exists to make relationships between multiple already-computed values legible, not to decorate simple output.
 
 9. **Journal files use date-prefix naming:** `journal/YYYY-MM-DD-topic-slug.md` for chronological sorting.
 

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

@@ -40,23 +40,27 @@ Produce output in this exact structure:
 | **Installed At** | `{installedAt}`               |
 | **Components**   | `{count}` installed           |
 
-### Update Check
+### Update Check (two-axis)
 
-- 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.
+This repo's `.arcane.json` version is one of three readings — check both axes, the same two as
+`spell-open-session`'s own version check:
 
-If up to date:
+- **Repo-files version** — already read in Step 1 (`.arcane.json`'s `version` field).
+- **Installed CLI version** — determine the version of the installed `arcane-cli` CLI (for example,
+  `npx arcane-cli --version`, or the locally installed package version).
+- **Npm-latest version** — fetch `https://registry.npmjs.org/arcane-cli/latest` and extract the
+  `version` field.
 
-```
-✔ You are on the latest version ({version}).
-```
-
-If behind:
+- **(a) Repo-files behind the installed CLI:** `⚠ Managed files out of date: files at {version} → CLI at {cli}. Run spell update to resync files.`
+- **(b) Installed CLI behind npm-latest:** `⚠ Update available: CLI at {cli} → latest {latest}. Upgrade the CLI, then run spell update.`
+- **If either axis drifts, emit the canonical version-drift diagram** — same template, same collapsing/
+  branching rule, same `:::mermaid`-for-ADO-wikis fencing as `spell-open-session.prompt.md`'s own
+  "Arcane version check (two-axis)" step; that file holds the canonical shape, referenced here rather
+  than repeated.
+- If both axes are current:
 
 ```
-⚠ Update available: {installed} → {latest}
-Run `spell update` to upgrade.
+✔ You are on the latest version ({version}).
 ```
 
 If the npm registry is unreachable, report:

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

@@ -53,6 +53,15 @@ Workflow:
        --output json
      ```
 
+     *GitHub is another — if and only if `.arcane.json` names `external_provider: github` (and the `gh` CLI is authenticated):*
+     ```bash
+     gh issue create \
+       --title "[Bug] {SUMMARY}" \
+       --body "{formatted description with repro steps}" \
+       --label bug
+     ```
+     `gh issue create` prints the created issue's URL on success; extract the trailing number as `{WORK_ITEM_ID}`. Omit `--label` if the repo has no `bug` label (`gh label list`) rather than guessing.
+
    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:
@@ -98,6 +107,10 @@ Workflow:
        --org https://dev.azure.com/{ADO_ORG} \
        --output json
      ```
+     For GitHub specifically:
+     ```bash
+     gh issue close {WORK_ITEM_ID} --reason completed --comment "Fixed by {commit SHA or PR URL}"
+     ```
      For other providers, follow [governance/development-methodology.md](../../.arcane/governance/development-methodology.md).
 
 Rules:

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

@@ -39,10 +39,11 @@ Before proceeding, confirm you have all three:
    - **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`)
+   - `external_provider: ado | github | 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.
+   - If `tracking_mode=external` and `external_provider=github`, a `githubIssueId` is used for commit/PR linkage when one exists (optional, unlike ADO).
+   - 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. In GitHub mode, use that same doc's GitHub Issues Conventions (labels, not configurable types).
 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.
@@ -57,7 +58,7 @@ 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`).
+3. Produce `PRD.md` with requirements, acceptance criteria, constraints, and tracking configuration (`tracking_mode`, optional `external_provider`, optional `adoWorkItemId`/`githubIssueId`).
 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.

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

@@ -86,8 +86,8 @@ Before anything else, check:
 - **Stale local branches:** Run `git branch --merged main` to list branches already merged that should be deleted — this session's own read-only candidate list (`--merged` also misses every branch landed via this repo's sanctioned rebase-and-fast-forward, so treat a *clean* result as "no ancestry-visible candidates," not "nothing to check"). Open-session only lists; it does not delete. Apply the [Content-Verified Branch Deletion](../../.arcane/governance/git-conventions.md#content-verified-branch-deletion-todomd-merged-branch-cleanup-finding) procedure (git-conventions.md) to any candidate before flagging it as safe, and leave the actual idempotent prune to `spell-close-session`'s sweep.
 - **Tracker configuration check (early):** resolve active tracking settings before planning, in this order: root `.arcane.json` (if present) -> the committed self-hosted source manifest (`src/assets/.arcane.json`, read only when it declares `selfHosted: true` -- this is EF-14's recorded self-hosting resolution tier, distinct from treating the mere presence of a self-host marker as license to infer other, unrelated config) -> the current feature PRD frontmatter -> ask. Persisted once at `spell init`/`spell update` (EF-14); do not re-ask when any of the first three sources already sets it.
   - `tracking_mode: internal | external`
-  - `external_provider: ado | jira | other`
-  - If all three sources are absent, ask: "Track work in this repo (TODO.md / PRDs)" [internal] vs "Track work in an external tracker (Azure DevOps / Jira / other)" [external]. Default to `external` + `ado` only when existing ADO context already exists (backward compatibility).
+  - `external_provider: ado | github | jira | other`
+  - If all three sources are absent, ask: "Track work in this repo (TODO.md / PRDs)" [internal] vs "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)" [external]. 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`:
@@ -96,7 +96,19 @@ Before anything else, check:
   - 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 either axis shows drift, emit the canonical version-drift diagram beside the warning(s)** — per the generated state diagrams convention (rule 8, ARC-036). One commit per *distinct* version value among the three readings, in the order repo-files → installed-CLI → npm-latest; collapse consecutive identical values into a single shared commit rather than repeating it. Branch off immediately after the commit for each axis that drifts — `repo-files` after the repo-files-version commit if axis A drifts, `installed-cli` after the installed-CLI-version commit if axis B drifts. Tag the final commit `"latest"`. The dangling branch(es) *are* the drifting axis/axes — no legend needed:
+    ```mermaid
+    gitGraph
+       commit id: "<repo-files version>"
+       branch repo-files
+       checkout main
+       commit id: "<installed-CLI version>"
+       branch installed-cli
+       checkout main
+       commit id: "<npm-latest version>" tag: "latest"
+    ```
+    (Shown here with both axes drifting — omit whichever `branch`/`checkout` pair belongs to a non-drifting axis, and collapse its commit into its neighbor's if the values are equal.) Use `:::mermaid` fencing instead of ` ```mermaid ` when the output surface is an Azure DevOps wiki — resolve `external_provider` from `.arcane.json` rather than assuming, the same as every other tracker-conditional step in this file; note for bare terminals that the fenced source is still readable without a renderer.
+  - If both axes are current, report current and continue — no diagram (the applicability guard: a single, matching reading has nothing to visualize).
   - If no `.arcane.json` exists, skip silently.
 
 ## State Snapshot

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

@@ -28,7 +28,7 @@ Workflow:
 
    ```yaml
    tracking_mode: internal | external
-   external_provider: ado | jira | other
+   external_provider: ado | github | jira | other
    ```
 
    Resolve in this order, matching spell-open-session's own resolution chain (EF-14): root
@@ -38,7 +38,7 @@ Workflow:
 
    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 none of the three sources above set it and no ADO context exists, ask: "Track work in this repo (TODO.md / PRDs)" [internal] vs "Track work in an external tracker (Azure DevOps / Jira / other)" [external].
+   - If none of the three sources above set it and no ADO context exists, ask: "Track work in this repo (TODO.md / PRDs)" [internal] vs "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)" [external].
    - 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
@@ -51,6 +51,7 @@ Workflow:
      - Story-level: `User Story → Issue → Task`
      - Task-level: `Task → Issue`
      - Defect-level: `Bug → Issue → Task`
+   - If `tracking_mode=external` and `external_provider=github`, collect the repo (`{owner}/{repo}`, resolve from `git remote get-url origin`; ask if ambiguous) and, if the PRD's scope is known to need one, an existing issue number. GitHub Issues has no configurable work-item-type hierarchy the way ADO does — see [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) → **GitHub Issues Conventions** for the labels-and-task-list substitute.
    - 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:
@@ -59,9 +60,10 @@ Workflow:
    |--------|--------|--------------|
    | **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` |
+   | **GitHub issue number** (external/github mode) | `#42` or `42` | Run: `gh issue view {id} --json title,body,labels` and extract `title` and `body` as the feature description |
    | **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.
+   If the input is an ADO work item ID or a GitHub issue number, fetch its content first, then use it as the feature description. If it has child work items (ADO) or a task-list of related issues (GitHub — see governance's GitHub Issues Conventions), fetch those too for additional context.
 
    Ask clarifying questions if the feature description is ambiguous. You need to understand:
    - What problem does this solve?
@@ -69,6 +71,7 @@ Workflow:
    - 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`.
+   - **If `tracking_mode=external` and `external_provider=github`: What is the GitHub issue number, if one already exists?** — optional (unlike ADO, a PRD doesn't require a pre-existing issue); store it as `githubIssueId` in PRD frontmatter when known.
 
 3. **Research context** — check the relevant business docs under `{BUSINESS_ROOT}/` (resolve from `.arcane.json`'s `business_root` field, default `ventures/` if unset) and any existing code repos.
 
@@ -79,8 +82,9 @@ Workflow:
    ---
    tracking:
      tracking_mode: [internal|external]
-     external_provider: [ado|jira|other|null]
+     external_provider: [ado|github|jira|other|null]
      adoWorkItemId: [number|null]
+     githubIssueId: [number|null]
    ---
 
    ## Problem Statement
@@ -130,19 +134,23 @@ Workflow:
    # external/ado example: adoWorkItemId=541, feature name="Phase 2A" → slug="phase-2a"
    # FEATURE_DIR="features/{adoWorkItemId}-{slug}"
 
-   # internal or non-ado external example:
+   # external/github example: githubIssueId=42, feature name="Phase 2A" → slug="phase-2a"
+   # FEATURE_DIR="features/{githubIssueId}-{slug}"
+
+   # internal or a provider without a known issue ID:
    # 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
+   - `features/{githubIssueId}-{slug}/PRD.md` when `tracking_mode=external`, `external_provider=github`, and a `githubIssueId` is known
+   - `features/{slug}/PRD.md` otherwise (internal mode, or an external provider without a known issue 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.
+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. `github` does not need this — it has a real, working flow (Step 1 above).
 
 Rules:
 - Every requirement must have at least one testable acceptance criterion.

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

@@ -54,7 +54,7 @@ If the input is an external work item ID:
 
 Resolve tracking settings from PRD frontmatter (preferred) or ask:
 - `tracking_mode: internal | external`
-- `external_provider: ado | jira | other`
+- `external_provider: ado | github | jira | other`
 
 If unset and ADO context already exists, default to `external` + `ado` for backward compatibility.
 
@@ -118,7 +118,7 @@ For each epic, define:
 
 Only applies when `tracking_mode=external`. Skip entirely for internal mode.
 
-Do **not** inline the work-item-type fallback order or the parent/child linkage rules here — they are the single source of truth in [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) → **Process-Template-Aware ADO Hierarchy Rules**. Detect the provider from `external_provider`, then apply those rules. *Fallback: if that doc is missing, record the tracker mapping as an Open Question and proceed without item-type assignment.*
+Do **not** inline the work-item-type fallback order or the parent/child linkage rules here — they are the single source of truth in [governance/development-methodology.md](../../.arcane/governance/development-methodology.md), under **Process-Template-Aware ADO Hierarchy Rules** (`external_provider=ado`) or **GitHub Issues Conventions** (`external_provider=github`). Detect the provider from `external_provider`, then apply the matching section's rules. *Fallback: if that doc is missing, record the tracker mapping as an Open Question and proceed without item-type assignment.*
 
 Scope-specific delta (the only thing this spell adds on top of those rules): each split **epic** maps to the **Epic-level** logical level — use the `Epic` work item type whenever the resolved provider/template offers it, and record the selected type per epic in `execution-plan.md`. All lower-level and linkage decisions defer to the governance rules above.
 

package/dist/assets/.github/prompts/spell-suggest-feature.prompt.md

@@ -55,7 +55,7 @@ Workflow:
    - Read `tracking_mode` / `external_provider` from `.arcane.json` or the active PRD frontmatter if available.
    - If missing, ask the user:
      - `tracking_mode: internal | external`
-     - `external_provider: ado | jira | other` (required only for external mode)
+     - `external_provider: ado | github | jira | other` (required only for external mode)
    - If ADO context is already active and no explicit choice is provided, default to `external` + `ado` for backward compatibility.
 
 5. **Create tracker item (conditional)**:
@@ -70,9 +70,17 @@ Workflow:
        --output json
      ```
      Extract the work item ID from the response.
+   - If `tracking_mode=external` and `external_provider=github`, create an issue:
+     ```bash
+     gh issue create \
+       --title "{title}" \
+       --body "{formatted user story + impact assessment}" \
+       --label enhancement
+     ```
+     `gh issue create` prints the created issue's URL; extract the trailing number as the issue ID. `--label` names must exist in the repo already (`gh label list`) — omit it rather than guessing a label that isn't there.
    - If `tracking_mode=internal`, skip external item creation and track in `TODO.md` only.
    - If `external_provider=jira` or `other`, add a TODO note for provider-specific automation and continue with `TODO.md` tracking.
-   - The ADO command above is illustrative; for the authoritative per-provider creation steps and field mappings, see [[.arcane/governance/development-methodology|Development Methodology]].
+   - The ADO and GitHub commands above are illustrative; for the authoritative per-provider creation steps and field mappings, see [[.arcane/governance/development-methodology|Development Methodology]].
 
 6. **Update backlog** — add a line to `TODO.md`:
    ```markdown

package/dist/index.js

@@ -97,7 +97,7 @@ var ManifestInvalidFieldError = class extends Error {
 };
 var MANIFEST_FILE = ".arcane.json";
 var VALID_TRACKING_MODES = ["internal", "external"];
-var VALID_EXTERNAL_PROVIDERS = ["ado", "jira", "other"];
+var VALID_EXTERNAL_PROVIDERS = ["ado", "github", "jira", "other"];
 var VALID_CONTENT_SENSITIVITY = ["standard", "sensitive"];
 var VALID_PUSH_POLICIES = ["open", "guarded", "blocked"];
 function isValidSubjectRoot(value) {
@@ -2677,7 +2677,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       message: "How will work be tracked in this repo?",
       choices: [
         { value: "internal", name: "Track work in this repo (TODO.md / PRDs)" },
-        { value: "external", name: "Track work in an external tracker (Azure DevOps / Jira / other)" }
+        { value: "external", name: "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)" }
       ]
     });
     if (tracking_mode === "external") {
@@ -2685,6 +2685,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
         message: "Which external tracker?",
         choices: [
           { value: "ado", name: "Azure DevOps" },
+          { value: "github", name: "GitHub Issues" },
           { value: "jira", name: "Jira" },
           { value: "other", name: "Other" }
         ]
@@ -2963,7 +2964,7 @@ var MANIFEST_RETROFITS = [
         message: "How will work be tracked in this repo?",
         choices: [
           { value: "internal", name: "Track work in this repo (TODO.md / PRDs)" },
-          { value: "external", name: "Track work in an external tracker (Azure DevOps / Jira / other)" }
+          { value: "external", name: "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)" }
         ]
       });
       if (tracking_mode === "external") {
@@ -2971,6 +2972,7 @@ var MANIFEST_RETROFITS = [
           message: "Which external tracker?",
           choices: [
             { value: "ado", name: "Azure DevOps" },
+            { value: "github", name: "GitHub Issues" },
             { value: "jira", name: "Jira" },
             { value: "other", name: "Other" }
           ]
@@ -3983,6 +3985,21 @@ var pkg = require3("../package.json");
 var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join12(dirname4(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
+  if (program.args.length > 0) {
+    const [attempted] = program.args;
+    console.error(`spell: unrecognized command '${attempted}'`);
+    console.error();
+    console.error(
+      `Spells are prompts, not CLI commands \u2014 run /spell-${attempted} in your agent client.`
+    );
+    console.error();
+    console.error("Real CLI commands:");
+    for (const cmd of program.commands) {
+      console.error(`  ${cmd.name().padEnd(14)} ${cmd.description()}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
   await printWelcome(pkg.version, process.cwd());
   program.outputHelp();
 });