arcane-cli 0.22.4 → 0.22.6

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/git-conventions.md

@@ -567,13 +567,15 @@ See also: [Agent Workflow — Sync with main before opening a PR](#agent-workflo
 | **Description**    | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable                                                                                                                                     |
 | **Pre-PR sync**    | **Mandatory rebase on latest `origin/<target>` before pushing.** See [🛑 Agent-mandatory pre-PR guard](#-agent-mandatory-pre-pr-guard) above — this applies even when opening PRs via raw `az repos pr create` / `gh pr create` / MCP tools. |
 | **Branch cleanup** | After merge, delete the source branch (local and remote).                                                                                                                                                                                    |
-| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`.                                                                                                                                        |
+| **PR link format** | All PR references in agent output **must** be clickable markdown links to the PR, not a bare `PR #NNN`.                                                                                                                                     |
+| **Doc-ID link format** | The same rule extends to `ADR-NNN`/`ARC-NNN`/`EF-NN`/journal entries/named governance docs — never a bare ID. See `.github/instructions/agent-output.instructions.md` → Doc-ID Link Format for the full rule and required formats per context. |
 
 ### Agent PR Workflow
 
 1. **Create a work item** (if one doesn't exist) using `spell-suggest-feature` or `spell-bug`.
 2. **Open PR** with proper title, description, and work-item link.
-3. **Notify the human** through your configured channel with: `[PR #{number}] {repo} — {title} (#{workItemId})`.
+3. **Notify the human** through your configured channel with a clickable link, not a bare number:
+   `[PR #{number} — {title}]({url}) — {repo} (#{workItemId})`.
 4. **Address review feedback** if a reviewer requests changes.
 5. **After merge**, delete the branch (local + remote) and confirm cleanup.
 

package/dist/assets/.arcane/governance/new-business-setup.md

@@ -113,12 +113,12 @@ See [[agents/installation|Runtime Installation]].
 
 ### Step 3.3 — Agent Git Identity Setup
 
-Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[governance/git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
+Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
 
 For each agent assigned to this business:
 
 1. **Confirm persona name** is registered in [[naming-conventions|Naming Conventions]] agent roster.
-2. **Confirm Git identity** exists in the registered identities table in [[governance/git-conventions#agent-email-convention|Git Conventions]].
+2. **Confirm Git identity** exists in the registered identities table in [[git-conventions#agent-email-convention|Git Conventions]].
 3. **Add agent to `.mailmap`** in every repo the agent will commit to:
    ```
    {AGENT_NAME} <{AGENT_EMAIL}>

package/dist/assets/.arcane/governance/spell-authoring-standards.md

@@ -15,7 +15,13 @@ against a consistent bar. This is the spell-prompt analogue of [[product-excelle
 grades PRDs, not prompts). It is an **authoring-time standard** — a checklist for contributors writing
 or reviewing spells. It is **not** meant to be read at runtime by the spells it grades.
 
-See [ARC-014](../../../DECISIONS.md#arc-014) for the decision that established this standard.
+See [ARC-014](https://github.com/codemagicianhq/arcane/blob/main/DECISIONS.md#arc-014--spell-authoring-standards-a-quality-rubric-for-spell-prompts)
+for the decision that established this standard. **Full canonical URL, not a same-repo
+wiki-link** (corrected 2026-08-31, BC-06) — this file ships to consumer repos, and
+`DECISIONS.md` does not: `src/assets/DECISIONS.md` (what consumers actually receive via
+`spell init`) is an empty starter template for the *consumer's own* decisions, so a
+same-repo wiki-link to a specific ARC id would resolve to the wrong document once
+installed, not simply fail to resolve.
 
 ## The Spell Quality Rubric
 

package/dist/assets/.github/instructions/agent-output.instructions.md

@@ -4,7 +4,7 @@ applyTo: "**"
 
 # Agent Output Formatting Rules
 
-Source of truth: `.arcane/governance/git-conventions.md` → PR Standards section.
+Source of truth: `.arcane/governance/git-conventions.md` → PR Standards → PR Requirements.
 
 ## PR Link Format
 
@@ -20,9 +20,60 @@ All PR references in agent output **must** be clickable markdown links. Never wr
 [PR #270 — fix: remove Unix-only preinstall script and approve esbuild builds](https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/270)
 ```
 
+## Doc-ID Link Format
+
+The same rule extends to every other identifier class this framework uses to reference
+a decision or record: `ADR-NNN`, `ARC-NNN`, `EF-NN`, venture decision IDs, journal
+entries, and named governance docs. A bare decision ID in agent output is the same
+defect as a bare `PR #NNN` — the reader has to go find it themselves, and a typo or
+stale number is invisible until someone tries.
+
+**Required format, by context:**
+- **Inside a repo's own local markdown** (e.g. this repo's `journal/`, `PLAN.md`, or
+  `DECISIONS.md` cross-referencing itself): a wiki-link (`[[DECISIONS#ARC-NNN|ARC-NNN]]`)
+  or a relative markdown link that actually resolves from that file's own location.
+- **Chat or PR output:** a clickable markdown link to the canonical file/anchor.
+- **Governance docs this framework ships** (`.arcane/governance/*.md`): the full
+  canonical-repo URL. A file here lives in *this* repo today but ships into every
+  consumer repo's own tree, where a wiki-link or relative path to Arcane's own
+  `DECISIONS.md` either fails to resolve, or worse, silently resolves to the
+  *consumer's own* `DECISIONS.md` (an empty per-consumer starter template, not
+  Arcane's real decision record) — wrong content, not just a dead link.
+- **Spell prompts and instructions this framework ships**
+  (`.github/prompts/*.prompt.md`, `.github/instructions/*.md`): **plain text only —
+  cite the bare ID, no link at all** (`ARC-035`, not `[ARC-035](...)`). A full
+  canonical URL is *also* unsafe here, not just a same-repo link: it bakes
+  `github.com/codemagicianhq/arcane` — this project's own org and repo name — into
+  content the org-token portability gate (`scripts/org-token-lint.ts`, D2 in
+  `spell-authoring-standards.md`) exists specifically to keep out of distributed
+  spells. **Confirmed live 2026-08-31 (BC-06):** the build's `Org-token lint` failed
+  on exactly this pattern in three prompt files, including two this same correction
+  pass had introduced minutes earlier while fixing the *other* link defect. Known
+  gap: the portability scan today only walks `.github/prompts/`, so a full URL in a
+  `.github/instructions/*.md` file — like this one's own Merge Strategy section, two
+  paragraphs down — ships uncaught; tracked in `TODO.md`.
+- **Cross-repo references from anywhere else** (chat, PR output, another repo
+  entirely): the full canonical-repo URL.
+
+**Never fabricate an unresolvable link.** If you cannot confirm the ID exists and where
+it resolves to, say so and cite the ID as plain text rather than inventing a link that
+looks real but goes nowhere.
+
 ## Merge Strategy
 
-All PRs must use **Rebase and fast-forward**. Never squash. Never merge commit. See ADR-048.
+All PRs must use **Rebase and fast-forward**. Never squash. Never merge commit. See
+ARC-009 §7 (Arcane's own framework decision — cited as plain text, not linked, per
+Doc-ID Link Format above: this file ships). **Corrected 2026-08-31 (BC-06), three
+times over:** this file previously cited `ADR-048`, which does exist in the shipped
+`framework-decisions.md` reference — but its actual topic ("Code Versus Docs Branch
+Policy") has nothing to do with merge strategy, a topical miscitation rather than a
+missing one. The first fix replaced it with a same-repo wiki-link to this repo's own
+`DECISIONS.md` — itself the exact cross-repo defect this section warns about
+(`DECISIONS.md` doesn't ship). The second fix replaced that with a full canonical
+URL, which held up locally but failed the build's org-token portability gate: a
+`github.com/codemagicianhq/arcane` URL bakes this project's own org into a file the
+gate treats as distributed content (see Doc-ID Link Format above). Settled on the
+bare ID — the gate's own documented safe form.
 
 When completing a PR via `az repos pr update`, do **not** pass `--squash true`. The correct command:
 

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-bump.prompt.md

@@ -9,7 +9,10 @@ agent: agent
 
 - This spell determines whether a version bump is required and applies the correct semver type.
 - Use it whenever you've changed `src/assets/`, `registry.ts`, or `profiles.ts` in the arcane repo.
-- It enforces the rule from CLAUDE.md: "Version bump required for any change to `src/assets/`."
+- It enforces the rule from `project.md` → Constraints → Self-hosting: "Anything touching
+  `src/assets/` requires a version bump." (Corrected 2026-08-31, BC-06 — this previously cited
+  CLAUDE.md, which now carries only the working protocol; the rule's live prose home moved to
+  `project.md:56-58`.)
 
 ---
 

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`:

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-review-batch.prompt.md

@@ -51,7 +51,7 @@ For each PR in the batch, independently:
 1. Fetch the PR diff and metadata (`gh pr diff <n>` / `az repos pr show --id <n>` + diff). If a PR can't be fetched (deleted, no access, network error), **skip it, record it as `SKIPPED` with the reason, and continue** — never abort the whole batch for one bad PR.
 2. Run the `spell-review` workflow against that diff — the full dimension-coverage sweep (correctness, security, performance, tests, naming/clarity, architecture), severity-ranked findings (`HIGH` / `MEDIUM` / `LOW`, matching the `spell-review` ladder) with stable IDs, and the PASS/WARN/FAIL coverage table.
 3. Record a per-PR result: verdict (**approve** / **request-changes**), finding counts by severity, and the coverage table.
-4. **Post the formal round state per PR** — apply `spell-review`'s step 10 ([ARC-035](../../DECISIONS.md#arc-035--auto-merge-requires-a-clear-review-round) decision 3) to *this* PR's number, not just this workflow's own single-run PR: a **request-changes** verdict posts `gh pr review <n> --request-changes` (or `az repos pr set-vote --id <n> --vote reject`); a re-review that clears a round this batch previously blocked dismisses/supersedes that prior review. An **approve** verdict posts nothing. Never let a posting failure (unauthenticated CLI, PR closed mid-batch) skip or abort the remaining PRs in the batch — record the result already computed and continue.
+4. **Post the formal round state per PR** — apply `spell-review`'s step 10 (ARC-035 decision 3 — cited as plain text, not linked; see `agent-output.instructions.md` → Doc-ID Link Format) to *this* PR's number, not just this workflow's own single-run PR: a **request-changes** verdict posts `gh pr review <n> --request-changes` (or `az repos pr set-vote --id <n> --vote reject`); a re-review that clears a round this batch previously blocked dismisses/supersedes that prior review. An **approve** verdict posts nothing. Never let a posting failure (unauthenticated CLI, PR closed mid-batch) skip or abort the remaining PRs in the batch — record the result already computed and continue.
 
 Reviews are adversarial — actively look for problems, do not just confirm quality. Apply the same no-fabrication coverage mandate as `spell-review`: a clean lens is reported as "no issues," never padded.
 
@@ -68,11 +68,11 @@ Build one report:
 
 | PR | Repo | Title | Verdict | High | Med | Low |
 | -- | ---- | ----- | ------- | ---- | --- | --- |
-| #n | repo | …     | approve / request-changes | 0 | 1 | 2 |
-| #n | repo | …     | SKIPPED — {reason}        | —  | —  | —  |
+| [#n]({url}) | repo | …     | approve / request-changes | 0 | 1 | 2 |
+| [#n]({url}) | repo | …     | SKIPPED — {reason}        | —  | —  | —  |
 
 ## Per-PR detail
-### PR #n — {title}
+### [PR #n]({url}) — {title}
 - Verdict: …
 - Coverage: {PASS/WARN/FAIL per lens}
 - Findings: {R1 …}

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

@@ -122,7 +122,7 @@ Workflow:
 
 9. **Write back to the pull request** — when a PR exists for these changes, sync a short verdict plus a findings summary (verdict + finding counts/IDs + a pointer to the saved report) into the PR body/description. Use provider-agnostic phrasing that works for either GitHub or Azure DevOps. Mark it clearly as a snapshot at review time, and fall back to a top-level PR comment if the description can't be updated.
 
-10. **Post the formal round state** ([ARC-035](../../DECISIONS.md#arc-035--auto-merge-requires-a-clear-review-round) decision 3) — step 9's write-back is a human-readable summary; this is the separate, machine-readable signal the `Review round clear` required check actually reads. Only a confirmed blocker posts a formal review — an `APPROVE` or `DEFER` verdict posts nothing here, preserving the zero-friction path for PRs nobody formally blocks:
+10. **Post the formal round state** (ARC-035 decision 3 — Arcane's own framework decision, cited as plain text, not linked, since this file ships; see `agent-output.instructions.md` → Doc-ID Link Format) — step 9's write-back is a human-readable summary; this is the separate, machine-readable signal the `Review round clear` required check actually reads. Only a confirmed blocker posts a formal review — an `APPROVE` or `DEFER` verdict posts nothing here, preserving the zero-friction path for PRs nobody formally blocks:
     - **REQUEST CHANGES verdict:**
       - GitHub: `gh pr review <n> --request-changes --body "<one-line blocker summary + pointer to the saved report>"`.
       - Azure DevOps: `az repos pr set-vote --id <n> --vote reject` — the same primitive `spell-commit-work.prompt.md`'s author-side self-approval step already uses (`az repos pr set-vote --vote approve`), applied to the reviewer side.

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/assets/.github/prompts/spell-summon-venture.prompt.md

@@ -11,7 +11,7 @@ agent: agent
 - **Hub-gated:** requires `role: "hub"` in `.arcane.json`. Refuses cleanly in a consumer repo, pointing at the right place to capture the idea instead.
 - Use this when starting a new venture (business, product, or personal project) that the hub should track.
 - Input format is: `Venture Name | Venture Type | Description` — prompt will ask for missing fields.
-- Renamed from `spell-bootstrap-business` — venture books and the registry didn't exist when that spell was named. Clean rename, no compatibility alias, per [[DECISIONS#ARC-008|ARC-008]]'s precedent.
+- Renamed from `spell-bootstrap-business` — venture books and the registry didn't exist when that spell was named. Clean rename, no compatibility alias, per ARC-008's precedent (cited as plain text, not linked — this file ships; see `agent-output.instructions.md` → Doc-ID Link Format).
 
 ---
 

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();
 });