hstack 0.7.1 → 0.17.0

package/template/.claude/skills/hstack-brownfield-init/SKILL.md

@@ -1,158 +0,0 @@
----
-name: hstack-brownfield-init
-description: |
-  Use this skill when an engineer is adopting hstack on an **existing repository** (one with source code, documentation, or some product context already in place) and needs to produce `hstack/config.yaml` and populate every required document under `hstack/context/`. For empty repositories (no source yet), use `/hstack:greenfield-init` instead — that orchestrator composes the discovery atoms in elicit mode and ends with `/hstack:scaffold`. Until brownfield-init completes, no other hstack Skill works; every workflow Skill checks for init completion at session start and halts otherwise. Init is structured as discrete mini-sessions of ten-to-fifteen minutes each rather than one long block, so that an interruption costs at most one in-flight field. Mini-sessions for data and app architecture **delegate to the standalone atoms** (`/hstack:data-architecture`, `/hstack:app-architecture`), which can also be re-run later via `/hstack:configure` for enrichment when `/hstack:help` flags a layer as missing. Examples:
-
-  <example>
-  Context: A six-month-old codebase has thin docs and no hstack/. The engineer wants to adopt hstack against the existing source.
-  user: "Start /hstack:brownfield-init on this repo."
-  assistant: "I'll read CLAUDE.md, README, package.json, and the source tree to seed proposals. Then mini-session 0 (config), product context via product-manager (vision, glossary, mvp-scope, personas) reading existing docs in extract+confirm mode. For data-architecture and app-architecture I'll delegate to the standalone atoms running in extract mode against the live schema and src/ tree."
-  <commentary>
-  Brownfield init's distinct mode is extract+confirm against existing sources. Where source docs are thin, the engineer can opt into running /hstack:product-discovery as a follow-up enrichment step after init completes.
-  </commentary>
-  </example>
-
-  <example>
-  Context: Init was started two days ago, three documents were committed, and a session crash dropped the fourth. The engineer wants to resume rather than restart.
-  user: "Resume /hstack:brownfield-init — vision, glossary, and mvp-scope are already done."
-  assistant: "I'll read hstack/.session-state/<session-id>.yaml, confirm which documents are at status `current`, and resume with the next missing one — personas, based on what I see on disk."
-  <commentary>
-  Idempotency is load-bearing here: the Skill reads disk state, recognizes which documents are already terminal, and continues at the next empty mini-session boundary rather than re-running completed interviews.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator run after every confirmed field write}}"
-  - "{{TODO-SCRIPT: hstack/scripts/init-detect-mcps.sh — probes the consuming repo's Claude Code config for available MCPs and writes hstack/context/mcp-status.md}}"
----
-
-## Purpose
-
-`hstack-init` is the first-run, conversational bootstrap Skill. It writes `hstack/config.yaml` and populates the canonical product-context layer at `hstack/context/`. It is the longest Skill in the system by elapsed time, structured deliberately as a series of short mini-sessions so the user can stop and resume without losing work. It is not the workflow itself: it does not author change-specs, plans, or any per-change artifact. It is also not the editor of an existing config — that is `hstack-configure`'s role.
-
-## When to invoke
-
-Invoke when the consuming repo has no `hstack/config.yaml`, or when `hstack/config.yaml` exists but at least one required product-context document is missing or below `status: current`. Every other hstack Skill checks for init completion at session start; if init is incomplete, those Skills halt with a message directing the engineer here. Init runs once per repo lifetime, although `hstack-configure --migrate` may re-invoke targeted slices of it on schema-version upgrades.
-
-## Inputs
-
-- No positional arguments. The Skill drives entirely from on-disk state and conversation.
-- Optional flag `--resume` is implicit: the Skill always reads `hstack/.session-state/<session-id>.yaml` when present and continues from the next un-confirmed field.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/` directory exists at the repo root. If not, halt and ask the engineer to confirm they are in the right directory.
-- Read `hstack/CLAUDE.md` (kernel) and `hstack/templates/` — both must be present. If either is missing, halt and ask the engineer to install or restore the hstack source. **The kernel describes the framework, not the consuming repo's product.** Treat it as behavioral rules, never as content to be configured.
-- **Load the consuming-repo context layer.** Read every artifact in the consuming repo (the working directory, NOT `hstack/`) that hints at its product, stack, or design system: `CLAUDE.md`, `README.md`, `package.json`, `docs/` if present, `.claude/agents/` and `.claude/skills/` for sibling tooling. This is the product being configured. Every interview prompt below frames against THIS context, not against `hstack/CLAUDE.md`.
-- Probe Claude Code's MCP configuration for the consuming repo and write a draft `hstack/context/mcp-status.md` listing which MCPs are wired (Notion, Linear, GitHub, Figma, Supabase) and which are absent. Run `{{TODO-SCRIPT: hstack/scripts/init-detect-mcps.sh}}` for this; if absent, the Skill produces the file by interviewing the engineer instead.
-- If `hstack/.session-state/` contains a prior init session-state file, read it and confirm with the engineer that resumption is the intent.
-
-If the engineer signals "start fresh, abandon the prior partial init," archive the existing session-state file before proceeding.
-
-## Orchestration steps
-
-Init is split into discrete mini-sessions, each commitable independently. The order is fixed because later documents reference earlier ones.
-
-1. **Mini-session 0 — config skeleton.** Every prompt in this mini-session is about THE CONSUMING REPO (not about hstack itself). Interview the engineer for:
-   - **Story store** for this repo's user stories — Notion DB, Linear, GitHub Issues, or `hstack/stories/`.
-   - **Personas store** for this repo's personas — typically `hstack/context/personas/` or a Notion DB.
-   - **Design system** for this repo. The schema is per-resource because partial / external states are common (Figma MCP for components, Notion for brand-guidelines, in-repo for tokens later). For each of `components`, `tokens`, `brand-guidelines`, ask:
-     - `source` — controlled enum: `in-repo` | `figma-mcp` | `notion-mcp` | `submodule` | `npm` | `external-other` | `none`.
-     - Source-specific follow-up: `path` for `in-repo`; `figma-file-id` for `figma-mcp`; `notion-page-id` for `notion-mcp`; `package` name for `npm`; `repo-url` for `submodule` / `external-other`.
-     - Optional `notes` — especially useful for in-progress states like "via Figma MCP until vendored into the repo."
-     - The `none` value is honest when the resource genuinely isn't documented yet; the agent does not invent paths to fill the field.
-   - **Module-to-area mapping** for this repo — a list of module ids with their canonical path globs. Read `package.json` and the consuming repo's directory layout to propose a starting set; the engineer confirms or revises.
-   - **Adversarial-review floor** — default 3, 5 for `agent`/`auth`/`billing`.
-   - **Production-runtime agent ledger** — enabled or not. This logs the consuming repo's *runtime* AI agents (the orchestrator, tool calls into customer accounts, MCP-mediated actions) to `audit/agent-ledger/` at the consuming repo root. **It is NOT about hstack's own subagents** (`spec-author`, `planner`, `implementer`, etc.) — those are already audited via the kernel's auto-commit-at-status-transition rule and visible in `git log`. The v1 ledger is useful telemetry (debugging, cost attribution, per-tenant breakdowns), not defensible audit evidence; v2 substrate adds hash-chain integrity, signed records, and WORM storage. Frame the question to the engineer accordingly so the term "agent" isn't ambiguous.
-   - **Active MCP set** — pre-populated from the MCP probe above; the engineer confirms.
-
-   Write `hstack/config.yaml` with `schemaVersion: 1`. The `init-status` field starts at `minimal-complete` after this mini-session ends, advancing to `complete` only when every required context document is at `current`. Commit.
-
-2. **Mini-session 1 — vision.** Invoke `product-manager` via the Task tool with `subagent_type: product-manager` and context = [`hstack/CLAUDE.md`, `hstack/templates/vision.md`, any pointer the engineer offers to an existing vision source]. The subagent walks the five vision sections, confirms each, writes `hstack/context/vision.md` at `status: drafted` and advances to `current` at the end. Prompt cleanup of the source per the subagent's contract. Commit.
-
-3. **Mini-session 2 — glossary.** Same orchestration with `hstack/templates/glossary.md`. Output: `hstack/context/glossary.md` at `current`. Commit.
-
-4. **Mini-session 3 — mvp-scope.** Same orchestration with `hstack/templates/mvp-scope.md`. Output: `hstack/context/mvp-scope.md` at `current`. Commit.
-
-5. **Mini-session 4 — personas.** For each persona the engineer names, the `product-manager` subagent runs a persona sub-interview against `hstack/templates/persona.md`, including the challenge prompt "What is this persona explicitly not?" Personas are written to the configured store (typically `hstack/context/personas/<slug>.md`). Commit after each persona individually so partial completion is durable.
-
-6. **Mini-session 5 — tech-stack, ci-cd.** These two are interview-light because the engineer has often already documented them in `CLAUDE.md`, `package.json`, or `.github/workflows/`. The Skill orchestrates by handing each in turn to `product-manager` (or `spec-author` if the engineer prefers a more code-grounded read) with the relevant existing source plus the canonical template. Output: two files at `current`. Commit after each.
-
-7. **Mini-session 5a — data-architecture (delegated).** The Skill invokes `/hstack:data-architecture --mode extract`. The `data-architect` agent loads the live schema via Supabase MCP (when configured), scans `supabase/migrations/`, and proposes content for the five sections (Tenancy, Entities, RLS, RAG, Migration Sketches) in extract+confirm mode. The engineer confirms or revises section by section. This delegation is mandatory in v1 because the deeper five-section structure (with Tenancy as the load-bearing decision) is what downstream subagents rely on; the old interview-light path is no longer sufficient. The atom can also be re-run later via `/hstack:configure data-architecture [--section <name>]` for enrichment. Output: `hstack/context/data-architecture.md` at `current`. Commit.
-
-8. **Mini-session 5b — app-architecture (delegated).** The Skill invokes `/hstack:app-architecture --mode extract`. The `app-architect` agent scans `src/`, `app/`, or `lib/` via Glob, reads each module's exports and dependencies, and proposes the Module Map plus the four downstream sections (Agent Orchestration Model, Deterministic-vs-LLM Split, State-Ownership Map, Surface Boundaries). At terminal state the atom auto-scaffolds `hstack/specs/<module>/spec.md` stubs at `status: draft`; subsequent `/hstack:module-spec <module>` invocations reverse-engineer the stubs to `current`. Output: `hstack/context/app-architecture.md` at `current` plus one stub per module. Commit.
-
-7. **Mini-session 6 — infrastructure.** Invoke `spec-author` via the Task tool with `subagent_type: spec-author` and context = [`hstack/CLAUDE.md`, `hstack/templates/infrastructure.md`, `hstack/context/tech-stack.md`, `hstack/context/ci-cd.md`, `hstack/context/data-architecture.md`, any existing infra source the engineer points to — cloud console screenshots, Terraform / Pulumi / CDK files, GitHub Actions YAML, Dockerfile, supabase config]. The subagent walks every H2 section of the template via interview, biasing toward grounded truth-gathering rather than aspirational design. **For engineers unfamiliar with infrastructure concepts, the subagent is expected to explain each section's intent before asking, and to spawn the `researcher` subagent for unfamiliar terms (e.g., "what is point-in-time recovery?", "what does a CDN actually do?") rather than asking the engineer to guess.** This mini-session is interview-heavy and often the longest of init for pre-prod teams. Output: `hstack/context/infrastructure.md` at `current`. The Blast-Radius Matrix must have at least one row before status advances to `current` (INF-03); the Unknowns section must be present even when empty (INF-02). Honest "we don't have this yet" answers are explicitly preferred over fabricated content; the resulting gaps land as tech-debt items in the Known Gaps section. Commit.
-
-8. **Mini-session 7 — threat-model, hardening-checklist, incident-runbook.** The security-context triplet. By this point `infrastructure.md` is at `current`, so the security-reviewer has the operational ground truth it needs to model threats accurately. Author orchestration is per-document:
-   - `threat-model.md` and `hardening-checklist.md` are authored by `security-reviewer` via the Task tool with `subagent_type: security-reviewer`. The same subagent that scores per-change security-reviews at change time also authors the slow-changing policy these reviews score against — different cadence, same security framing (bias toward CONCERNS, challenge-driven prompts). Generalist subagents (spec-author, product-manager) are NOT offered here; the security-specific framing is load-bearing.
-   - `incident-runbook.md` is authored by `spec-author` from a founder-style interview — kill switches, revocation flows, comms templates are operational content, not threat-modeling.
-
-   `incident-runbook.md` is written with `git-ignored: true` in its frontmatter; the Skill verifies an entry exists in the repo's `.gitignore` before proceeding (creating the entry with confirmation if absent). The Skill warns the engineer at the start of this mini-session that incident-runbook content will not be committed to git and will need an out-of-band sync target named in `hstack/config.yaml`. Commit each context file as it lands.
-
-The Skill maintains `hstack/.session-state/<session-id>.yaml` continuously, updating after every confirmed field write. The state file captures which mini-session is in progress, which fields within it are confirmed, and what the next prompt should be.
-
-## Outputs
-
-- `hstack/config.yaml` (status field on the config carries `init-status: minimal-complete` once mini-session 0 ends, advancing to `complete` only when every required context document is at `current`).
-- `hstack/context/vision.md` at `current`.
-- `hstack/context/glossary.md` at `current`.
-- `hstack/context/mvp-scope.md` at `current`.
-- `hstack/context/personas/<slug>.md` per persona, or sync stubs when the store is Notion / Linear.
-- `hstack/context/tech-stack.md`, `ci-cd.md`, `infrastructure.md`, `threat-model.md`, `hardening-checklist.md` — all at `current`.
-- `hstack/context/data-architecture.md` at `current` (produced by the delegated `/hstack:data-architecture` atom, five-section structure).
-- `hstack/context/app-architecture.md` at `current` plus one `hstack/specs/<module>/spec.md` stub per module from Section 1 (produced by the delegated `/hstack:app-architecture` atom).
-- `hstack/context/incident-runbook.md` at `current` with `git-ignored: true`; corresponding `.gitignore` entry verified.
-- `hstack/context/mcp-status.md` documenting active and degraded MCPs.
-
-## Auto-commit triggers
-
-Each of the following emits an auto-commit on the active working branch:
-
-- `hstack/config.yaml` reaches `init-status: minimal-complete` (end of mini-session 0).
-- Each product-context document's status moves to `current` (end of each mini-session).
-- Each persona's status moves to `current` (end of each persona sub-interview).
-- `hstack/config.yaml`'s `init-status` advances to `complete` (end of mini-session 7).
-
-The commit message names the mini-session and the artifact. Aside from these, init does not auto-commit.
-
-## Idempotency contract
-
-Re-running `hstack-brownfield-init` on a repo where init has progressed partway through:
-
-- Reads `hstack/config.yaml` and every existing `hstack/context/*.md`. Any file at `status: current` is considered done; the Skill does not re-interview it.
-- Reads `hstack/.session-state/<session-id>.yaml` if present and resumes the in-flight mini-session at its next un-confirmed field.
-- Produces a no-op diff for completed mini-sessions; the only writes happen to the first incomplete document.
-- Re-running after all mini-sessions are complete is a no-op that prints the init-status summary.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions, this Skill halts when:
-
-- The `product-manager` subagent halts (e.g., because a persona answer is too vague, or because a referenced source document is unreachable). The Skill surfaces the subagent's halt message and waits.
-- A configured MCP the engineer named as the story store is not wired in Claude Code. The Skill does not silently fall back to a different store; it asks the engineer to wire the MCP or pick a different store, then re-runs the relevant config field.
-- The engineer signals end-of-session mid-mini-session. The Skill writes the session-state file, commits any field that has been confirmed and written, and exits cleanly.
-- `incident-runbook.md` would be committed to git. Halt; verify the gitignore entry first.
-
-## Failure modes
-
-- **Missing kernel or templates.** Halt with a clear message; this is a hstack installation problem, not an init problem.
-- **Subagent unreachable mid-mini-session.** Persist current state; instruct the engineer to retry in a moment.
-- **Notion/Linear/GitHub MCP unreachable but configured as the story store.** Halt and ask the engineer to wire it; do not silently fall back to `hstack/stories/`.
-- **`.gitignore` write refused.** The Skill cannot proceed past mini-session 7's incident-runbook step without it. Halt and surface the issue.
-
-## Anti-patterns
-
-- Never write `hstack/config.yaml` silently from inferred defaults. Every field passes through the engineer's confirmation gate via the `product-manager` subagent.
-- Never collapse the eight mini-sessions into one long block. The mini-session structure is the resumability contract.
-- Never advance `init-status: complete` while any required context document is below `current`.
-- Never write `incident-runbook.md` content to the conversation transcript more than necessary; the file's contents are sensitive and should be confirmed in summary form rather than pasted verbatim.
-- Never re-interview a completed mini-session on resume. Read the disk; trust the prior commit.

package/template/.claude/skills/hstack-change-new/SKILL.md

@@ -1,111 +0,0 @@
----
-name: hstack-change-new
-description: |
-  Use this skill when an engineer wants to start a new change and needs the `hstack/specs/changes/<id>/` folder scaffolded with templates pre-populated, before any spec-author or planner work begins. The Skill validates that the affected module has a current module-spec, derives the change id from the area and slug, scaffolds the folder, and seeds `spec.md` with the canonical template. Examples:
-
-  <example>
-  Context: The engineer is about to start work on the billing overage warning feature and needs the change folder before drafting the spec.
-  user: "/hstack:change-new billing overage-warning"
-  assistant: "I'll scaffold hstack/specs/changes/2026-05-billing-overage-warning/ with spec.md pre-populated from the template. spec-author runs separately when you're ready to fill the fields."
-  <commentary>
-  This Skill does not author content; it produces the empty folder shape so spec-author has a target to write into. Scaffold-only separation keeps the Skill cheap to re-run and idempotent on partial state.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The engineer tries to scaffold a change in an area that has no module-spec yet.
-  user: "/hstack:change-new playbook-runner inline-mode"
-  assistant: "I'll halt — there's no hstack/specs/playbook-runner/spec.md at status current. Run /hstack:module-spec playbook-runner first."
-  <commentary>
-  Scaffolding refuses when the module's baseline doesn't exist. This is a deliberate gate: a change-spec whose `area` points at a nonexistent module-spec fails SP-01 anyway, so the Skill halts before any folder is created rather than producing dead scaffolding.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates the seeded change-spec frontmatter}}"
----
-
-## Purpose
-
-`hstack-change-new` scaffolds the per-change folder under `hstack/specs/changes/<id>/` and seeds `spec.md` from the canonical template. It does no authoring — `spec-author` is invoked separately by the engineer once the folder exists. This Skill exists to keep id-generation, folder layout, and template seeding consistent across changes, and to enforce the module-spec precondition before any change work begins.
-
-## When to invoke
-
-Invoke at the start of any new change. The Skill is the conventional first step of the per-change workflow, run before `hstack-story-draft`, `hstack-change-plan`, or any other per-change Skill. Trivial changes (typo fixes, dependency bumps) that the engineer intends to tag with `trivial: true` may skip this Skill, though most engineers run it anyway for consistency.
-
-## Inputs
-
-- `<area>` (required, positional): the module key, must match an existing module-spec at `status: current`. Examples: `billing`, `orchestrator`, `knowledge-base`.
-- `<slug>` (required, positional): kebab-case short name for the change. Examples: `overage-warning`, `inline-mode`. The Skill validates the slug shape (kebab-case, no spaces, no leading numerics).
-
-The change `id` is derived as `YYYY-MM-<area>-<slug>` using the current month from `today`'s ISO date.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists at `init-status: complete`. If not, halt and direct the engineer to `hstack-init`.
-- Verify `hstack/specs/<area>/spec.md` exists at `status: current`. If absent or non-terminal, halt and direct the engineer to `hstack-module-spec <area>`.
-- Verify `hstack/specs/changes/<derived-id>/` does not already exist. If it does, halt and surface the existing folder — the engineer is either resuming (in which case no scaffold is needed) or has a slug collision (in which case they pick a different slug).
-- Verify the slug matches `^[a-z][a-z0-9-]*$`.
-
-## Orchestration steps
-
-1. **Derive the id.** Compute `<YYYY-MM>-<area>-<slug>` from today's date and the inputs. Surface the derived id to the engineer for confirmation before writing.
-
-2. **Create the folder.** `mkdir -p hstack/specs/changes/<id>/` via Bash.
-
-3. **Seed `spec.md`.** Read `hstack/templates/change-spec.md`, instantiate the frontmatter with `id`, `type: change-spec`, `status: draft`, `owner` (from `git config user.name` or `hstack/config.yaml`'s default owner), `area: <area>`, `related-spec: <area>`, `created` and `updated` set to today, `schema-version: 1`. Leave `surfaces`, `user-stories`, `in-scope`, `out-of-scope`, `related-adrs`, `creates-tech-debt`, `parent-change`, `threat-model-delta`, `internal-tooling`, `enables`, `enabled-by`, `trivial` as their template defaults (typically empty arrays or `null`). Leave every prose section empty, with the template's interview-prompt comments intact for `spec-author` to consume.
-
-4. **Forward-reference reconciliation for `enables` chains.** Grep every existing `hstack/specs/changes/*/spec.md` for the new `<id>` in `enables:` arrays. For each match: the matched (upstream) spec already declares this new (downstream) spec as a Category-B enabler. Per SP-14, write the reciprocal `enabled-by: [<upstream-id>, ...]` array on the newly-seeded spec in the same scaffold commit (this is the atomic-pair guarantee — both halves land together). When no match exists, leave `enabled-by: []`. Read-only on the upstream spec — its `enables` array was already written when the upstream was authored; no edit there. This is a mechanical operation per the kernel's Mechanical-operations section; no subagent is invoked. Surface the reconciliation to the engineer: "Detected upstream spec(s) declaring `enables: [<id>]` — populating `enabled-by` reciprocally."
-
-5. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the seeded file. Validation at `status: draft` is permissive — empty arrays and empty prose are allowed at draft — but the universal floor (FM-01) must pass.
-
-6. **Offer branch creation.** Run `git branch --show-current`. If the current branch is `main` (or the configured default), ask the engineer: "You're on `<current-branch>`. Convention is one branch per change-spec — create `change/<id>` from here and check out before the scaffold commits? [Y/n/type-different-name]". Default Yes. On confirmation, run `git checkout -b change/<id>` BEFORE step 7 so the scaffold commit lands on the correct branch from the start. If the engineer declines or names a different branch, honor the choice and continue on the chosen branch. If the current branch is anything other than the configured default (i.e., already on a feature branch), do nothing — the engineer has a deliberate branching strategy and the Skill respects it.
-
-7. **Auto-commit.** Commit message: `chore(change-new): scaffold <id>`.
-
-8. **Surface next steps.** Print a one-line instruction directing the engineer to invoke `spec-author` (or `hstack-story-draft` first if the change is user-facing and no story exists yet). If the change has Category-B `enabled-by` populated from step 4, also note the upstream linkage so the engineer is reminded which prerequisite this realizes.
-
-The Skill does not invoke any subagent. Scaffolding is mechanical and the engineer's subsequent moves vary by change.
-
-## Outputs
-
-- New directory `hstack/specs/changes/<id>/`.
-- New file `hstack/specs/changes/<id>/spec.md` at `status: draft`, with frontmatter populated to the floor and prose sections empty.
-
-## Auto-commit triggers
-
-- One commit at scaffold completion. No further commits from this Skill.
-
-## Idempotency contract
-
-- Re-running with the same `<area>` and `<slug>` when the derived folder exists is a no-op; the Skill detects the existing folder, surfaces it, and exits without writes.
-- Re-running with a different month (e.g., the engineer scaffolded in May, returns in June, and re-runs the same slug) produces a different id and a new folder; this is intentional — month-prefixed ids prevent slug-collision across long-running work.
-- If the folder exists but `spec.md` is absent (rare, indicates an interrupted scaffold), the Skill re-seeds `spec.md` only.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The `<area>` does not correspond to an existing module-spec at `status: current`. Halt.
-- The `<slug>` violates kebab-case shape. Halt.
-- The derived folder already exists with content. Halt and ask.
-
-## Failure modes
-
-- **Validator fails on the seeded spec.** The template itself is broken — halt and surface as a hstack installation issue.
-- **`git config user.name` returns empty and `hstack/config.yaml` has no default owner.** Halt and ask the engineer for their owner handle.
-
-## Anti-patterns
-
-- Never write prose content into the seeded `spec.md` beyond the template's existing prompts. The Skill scaffolds; `spec-author` authors.
-- Never derive the id from anything other than the current month, the area, and the slug. Hand-rolled ids break the kebab-case + chronological-prefix convention that other Skills depend on.
-- Never scaffold under an area whose module-spec is absent. The precondition is hard.
-- Never modify an existing change folder. Reruns are no-ops or refusals, never overwrites.
-- Never advance `status` past `draft` from this Skill. Subsequent transitions are owned by the authoring subagents.

package/template/.claude/skills/hstack-change-plan/SKILL.md

@@ -1,119 +0,0 @@
----
-name: hstack-change-plan
-description: |
-  Use this skill when a change-spec is at `status: ready-to-plan` (with its conditional upstream artifacts also at terminal status) and needs `plan.md` drafted as atomic phases. The Skill orchestrates the `planner` subagent. Examples:
-
-  <example>
-  Context: The billing-overage change-spec is at ready-to-plan, the ui-brief is drafted, the figma-handoff is ready, and the engineer is about to start implementation.
-  user: "/hstack:change-plan 2026-05-billing-overage-warning"
-  assistant: "I'll invoke planner with the change-spec, ui-brief, figma-handoff. Atomic phases with per-phase verifier expectations and a rollback strategy."
-  <commentary>
-  The planner is the only authoring path for plan.md. The Skill enforces that upstream conditional artifacts (ui-brief, figma-handoff for ui; data-review for db) are at terminal status before invoking — otherwise the planner halts.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A change touching ui and db is at ready-to-plan but data-review has not been run yet.
-  user: "/hstack:change-plan 2026-06-knowledge-citations"
-  assistant: "I'll halt — surfaces includes db and data-review.md is missing. Run /hstack:data-review first."
-  <commentary>
-  The conditional upstream gate is hard. Skipping the data-review and producing a plan against an unscored data layer produces a plan that the implementer would refuse to act on anyway.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates plan frontmatter and PL-01..PL-05}}"
----
-
-## Purpose
-
-`hstack-change-plan` produces `plan.md` for a change-spec by orchestrating the `planner` subagent. The plan decomposes the change into atomic phases with per-phase verifier expectations, names cross-phase risks, and articulates a rollback strategy. It is the artifact the implementer executes one phase at a time and the verifier checks phase-by-phase.
-
-## When to invoke
-
-Invoke when the change-spec reaches `status: ready-to-plan`, `test-plan.md` is at terminal status, and any conditional upstream artifacts required by the spec's `surfaces` are at terminal status. Re-invoke when the change-spec, the test-plan, or any conditional upstream artifact changes shape in ways that invalidate the existing plan.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-
-## Preconditions
-
-Before any work:
-
-- Verify the change-spec exists at `hstack/specs/changes/<id>/spec.md` and is at `status: ready-to-plan` or later.
-- Verify the change-spec's `Invariants` section has ≥ 3 bullets (SP-04) and `Scope Boundaries` is non-empty (SP-05/SP-06). If empty, halt — the planner refuses.
-- **Verify `test-plan.md` is at `status: passed` or `concerns-acknowledged`.** This is the hard upstream gate; the planner refuses to sequence phases without a terminal test strategy. Halt otherwise and direct the engineer to `/hstack:test-plan`.
-- When `surfaces` includes `ui`: verify `ui-brief.md` at `status: drafted` and `figma-handoff.md` at `status: ready`. Halt otherwise.
-- When `surfaces` includes `db`: verify `data-review.md` at `status: passed` or `concerns-acknowledged`. Halt otherwise.
-- Verify the relevant module-spec at `status: current`.
-- Read `hstack/context/tech-stack.md` (loaded by `planner` for pinned runtime constraints).
-
-The security-review is not a planner precondition — security-review and the plan can be produced in either order, since neither depends on the other's content (the implementer reads both at session start). The test-plan, by contrast, IS a planner precondition: the planner's phase ordering and per-phase Test Strategy entries reference test-plan sections, so the test-plan must already be terminal.
-
-## Orchestration steps
-
-1. **Invoke `planner`.** Use the Task tool with `subagent_type: planner` and context = [kernel, `hstack/templates/plan.md`, change-spec, test-plan, ui-brief and figma-handoff if applicable, data-review if applicable, module-spec, tech-stack]. The subagent walks the four plan sections — Phase Overview, Per-Phase Detail, Cross-Phase Risks, Rollback. Per-phase Test Strategy entries point at test-plan sections rather than re-stating tests inline.
-
-2. **Phase decomposition.** Per the `planner` contract, typical plans hold 4–8 phases; > 12 phases requires an `oversized-plan-justification` frontmatter field. Each phase has a `step-id`, one-line summary, `depends-on` list, Files Touched (subset of `change-spec.in-scope`), Test Strategy, Risk sentence, and Verifier Expectations.
-
-3. **Scope subset enforcement.** Per PL-04, every "Files Touched" entry across the plan must be a subset of `change-spec.in-scope`. The subagent verifies during authoring; the Skill verifies post-write via the validator. If a phase requires a file outside `in-scope`, the planner halts with a scope-amendment request.
-
-4. **Exercise the Cross-Phase Risks challenge.** Per the `planner` contract, the Cross-Phase Risks section uses the challenge prompt "What could go wrong across phase boundaries that no single phase catches?" Minimum one bullet for multi-phase plans.
-
-5. **Rollback discipline.** Section 4 names what to flip, revert, or feature-gate if a partial rollout breaks something. If the engineer cannot answer, the planner halts rather than writing a plausible default.
-
-6. **Leave `steps-completed: []`.** Per architecture amendment A3 and the planner's contract, `steps-completed` is owned by the implementer; the planner never populates it.
-
-7. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — PL-01 (parent-change matches), PL-02 (phase count), PL-03 (steps-completed entries match plan phase ids), PL-04 (Files Touched is subset of in-scope), PL-05 (status advance gating).
-
-8. **Transition.** When the validator passes, `planner` advances status from `draft` to `ready`. Auto-commit fires.
-
-## Outputs
-
-- `hstack/specs/changes/<change-id>/plan.md` at `status: ready`.
-
-## Auto-commit triggers
-
-- Status transition to `draft` after the Phase Overview table lands.
-- Status transition to `ready` at end of authoring. Commit message: `plan(<change-id>): ready`.
-
-## Idempotency contract
-
-- Re-running on an existing `ready` plan without spec changes: the subagent reads the existing plan as the proposal layer; identical re-confirmation is a no-op.
-- Re-running mid-authoring after a halt: `planner` reads the partial file and resumes at the next un-confirmed section.
-- Re-running after the change-spec's `in-scope` has been amended: the planner re-validates every Files Touched entry against the new in-scope, halts if any phase drifted, and prompts the engineer to reshape phases.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- Change-spec Invariants empty (< 3 bullets) or Scope Boundaries empty.
-- `test-plan.md` missing or non-terminal. Halt and direct the engineer to `/hstack:test-plan`.
-- Conditional upstream artifact missing or non-terminal.
-- A Files Touched entry would drift outside `in-scope`. Halt and request a scope amendment via `spec-author`.
-- > 12 phases without `oversized-plan-justification` in frontmatter.
-- The Cross-Phase Risks challenge prompt cannot be answered with at least one bullet on a multi-phase change.
-- The engineer cannot answer the rollback prompt.
-
-## Failure modes
-
-- **Module-spec missing or `needs-refresh`.** Halt; refresh via `hstack-module-spec` first.
-- **`ui-brief.md` exists at `draft` rather than `drafted`.** Halt; the brief is incomplete.
-- **Validator fails PL-04.** The planner halts immediately at the offending phase; the engineer either reshapes the phase or amends in-scope.
-- **`planner` halts on cross-phase risk surfacing an invariant gap.** Halt; the engineer amends the change-spec via `spec-author`, then re-runs this Skill.
-
-## Anti-patterns
-
-- Never write code. Plans are prose plus YAML.
-- Never silently accept a non-terminal upstream artifact.
-- Never invent invariants or modify the change-spec's Invariants section — that is `spec-author`'s domain.
-- Never write `steps-completed` values; the field belongs to the implementer.
-- Never produce a multi-phase plan with empty Cross-Phase Risks without exercising the challenge prompt.
-- Never write a rollback section with a plausible-sounding default the engineer did not endorse.

package/template/.claude/skills/hstack-configure/SKILL.md

@@ -1,126 +0,0 @@
----
-name: hstack-configure
-description: |
-  Use this skill when an engineer needs to update `hstack/config.yaml` after init has already completed, re-run the interview for a single product-context document, or migrate the schema-version when hstack itself ships a structural change. This is the editor counterpart to `hstack-init`; it never bootstraps from nothing and never advances the global `init-status` field. Examples:
-
-  <example>
-  Context: The team has decided to move their personas store from `hstack/context/personas/` to a Notion database now that the Notion MCP is wired up.
-  user: "Re-configure hstack to use the Notion personas store."
-  assistant: "I'll run /hstack:configure and walk the personas-store config field. Existing personas in hstack/context/personas/ stay on disk as sync stubs pointing at the new Notion records."
-  <commentary>
-  Configure is the right entry point because init has already produced a complete config; the change is scoped to one field and its downstream side effects. Re-running init would re-interview every product-context document, which is wasted work.
-  </commentary>
-  </example>
-
-  <example>
-  Context: An hstack point release introduces a new required frontmatter field on `change-spec.md` and bumps `schemaVersion` from 1 to 2.
-  user: "Run /hstack:configure --migrate."
-  assistant: "I'll detect the schema-version delta, walk through the field-level migration plan, and re-stamp every existing artifact's frontmatter under the new schema."
-  <commentary>
-  Migration is the one mode of configure that can touch many files at once. The Skill plans the migration first, presents the planned edits to the engineer, and executes only on confirmation — never silently rewrites artifact frontmatter.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates frontmatter after every migration write}}"
-  - "{{TODO-SCRIPT: hstack/scripts/migrate-schema.ts — applies declarative migration steps between schema-version values}}"
----
-
-## Purpose
-
-`hstack-configure` is the post-init editor of `hstack/config.yaml` and the product-context layer. It runs in three modes: edit a single config field, re-run the interview for a single product-context document via `--interview <doc-name>`, or migrate every artifact's `schema-version` via `--migrate` when an hstack upgrade introduces a structural change. It does not bootstrap from nothing (that is `hstack-init`'s role) and does not write per-change artifacts.
-
-## When to invoke
-
-Invoke when the engineer wants to change a config field after init has completed, refresh a single context document (e.g., quarterly threat-model review), wire up a previously-absent MCP, or migrate after an hstack release bumps `schemaVersion`. If init has not completed, halt and direct the engineer to `hstack-init`.
-
-## Inputs
-
-- `--interview <doc-name>` (optional): re-run the conversational interview for one of `vision`, `glossary`, `mvp-scope`, `personas`, `data-architecture`, `tech-stack`, `ci-cd`, `infrastructure`, `threat-model`, `hardening-checklist`, `incident-runbook`.
-- `--migrate` (optional): detect the gap between `hstack/config.yaml`'s `schemaVersion` and the version declared by the current hstack release, and apply the declarative migration steps.
-- No flag: open an interactive config editor that walks the engineer through `hstack/config.yaml` field by field, confirming or correcting each.
-
-`--interview` and `--migrate` are mutually exclusive.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists and contains a valid `init-status: complete` value. If init has not completed, halt and surface the message to run `hstack-init` first.
-- Read `hstack/CLAUDE.md` (kernel) and `hstack/templates/`.
-- For `--interview <doc-name>`: verify the named document template exists under `hstack/templates/` and the corresponding instance exists under `hstack/context/`. Read the existing instance's current state to seed the interview.
-- For `--migrate`: read the current `hstack/config.yaml schemaVersion` and the target version declared by the installed hstack release. If they match, halt with a "no migration needed" message.
-
-## Orchestration steps
-
-### Edit-config mode (no flag)
-
-1. Read `hstack/config.yaml` and walk every field with the engineer using the `product-manager` subagent via Task. For each field, the subagent proposes the current value, the engineer accepts or corrects, the subagent writes the field to disk immediately.
-2. For fields with downstream effects (e.g., changing the configured story store), emit an explicit warning naming the affected workflow Skills before writing.
-3. On completion, commit. Update `hstack/config.yaml`'s `updated` field.
-
-### `--interview <doc-name>` mode
-
-1. Read the existing `hstack/context/<doc-name>.md`.
-2. Invoke the doc's canonical author via Task with `subagent_type` set per the routing table below. Context = [kernel, template, existing instance]. The subagent walks the document's fields, treating the existing values as the proposal layer and the engineer's responses as accept-or-correct. The routing must match the authoring agent used by `hstack-init` for the same document — same author at init time and at refresh time, different cadence:
-   - `vision`, `glossary`, `mvp-scope`, `personas`, `data-architecture`, `tech-stack`, `ci-cd` → `product-manager`.
-   - `infrastructure`, `incident-runbook` → `spec-author`.
-   - `threat-model`, `hardening-checklist` → `security-reviewer`.
-3. Updated document is written incrementally per the kernel's per-field write rule. Status moves to `drafted` if it had been `current`, then back to `current` at the end. Prompt source-cleanup per the subagent's contract.
-4. Commit.
-
-### `--migrate` mode
-
-1. Read `hstack/scripts/migrate-schema.ts` (or its current location) for the declarative migration steps between the current and target `schemaVersion`. Each step names: which artifact types it touches, which frontmatter fields it adds/renames/removes, and any prose-section structural changes.
-2. Run a dry-run scan over `hstack/` and produce a written migration plan that lists every artifact file the migration would touch and the specific edits per file. Present the plan to the engineer for confirmation.
-3. On confirmation, execute the migration step by step. After each artifact file is edited, run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against it; if validation fails, halt and surface the failure rather than continuing.
-4. Update `hstack/config.yaml`'s `schemaVersion` to the target value on a successful migration. Commit.
-
-For destructive or ambiguous migrations (renames of frontmatter fields, status enum changes), the Skill presents each ambiguity to the engineer rather than guessing.
-
-## Outputs
-
-- Edits to `hstack/config.yaml` (any mode).
-- Edits to one `hstack/context/<doc-name>.md` (`--interview` mode).
-- Edits to many artifact files under `hstack/specs/`, `hstack/context/`, `hstack/adr/`, `hstack/tech-debt/` (`--migrate` mode).
-- An optional migration log file at `hstack/.migrations/<from>-to-<to>.md` capturing the dry-run plan and per-file outcomes.
-
-## Auto-commit triggers
-
-- End of edit-config interview: one commit summarizing the edited fields.
-- End of `--interview <doc-name>` session: status transition back to `current` triggers a commit.
-- End of successful `--migrate`: one commit per migrated artifact (so a partial migration is partly reversible), plus a final commit advancing `schemaVersion`.
-
-## Idempotency contract
-
-- Re-running edit-config mode is safe; the Skill reads current values, walks every field, and produces a no-op commit when the engineer accepts all current values unchanged.
-- Re-running `--interview <doc-name>` is safe; the existing instance is the proposal layer, identical re-confirmation is a no-op.
-- Re-running `--migrate` after a successful migration is a no-op; the version check at the start short-circuits. Re-running `--migrate` mid-migration (after a halt) resumes by reading the migration log file and processing the next un-migrated artifact.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- A `--migrate` step would touch an artifact whose current frontmatter does not match the source `schemaVersion`. Halt and ask; do not migrate inconsistent state.
-- A `--interview` document is referenced by an in-flight change-spec at a non-terminal status. The Skill warns about cascade effects but proceeds on engineer confirmation; the cascade is the engineer's call.
-- A config field change would invalidate existing artifacts (e.g., removing a module from the module-to-area mapping when change-specs still reference it). Halt and surface the affected files.
-
-## Failure modes
-
-- **`migrate-schema.ts` absent or malformed.** Halt and surface as a hstack installation issue.
-- **Validator failure on a migrated artifact.** Halt the migration; previous artifacts are already committed and represent a stable partial state.
-- **Subagent halts mid-interview.** Persist current state; partial fields are already written per the kernel's incremental-write rule.
-
-## Anti-patterns
-
-- Never silently advance `schemaVersion` without a corresponding migration run.
-- Never write context document content without invoking `product-manager`. This Skill orchestrates; it does not author.
-- Never edit per-change artifacts (specs, plans, reviews) from this Skill. Those belong to their authoring subagents.
-- Never apply a `--migrate` plan without the engineer's explicit confirmation of the dry-run output.
-- Never re-run `hstack-init` semantics from this Skill. If the engineer wants to start over, they delete and re-init explicitly.