hstack 0.16.0 → 0.17.0

package/template/.claude/agents/ui-ux-briefer.md

@@ -1,75 +0,0 @@
----
-name: ui-ux-briefer
-model: sonnet
-description: Use when a change-spec includes `ui` in `surfaces` and needs `ui-brief.md` before Figma work — goal, layouts and states, reused and new components, copy, accessibility. Never writes code or Figma frames.
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Write
-  - Edit
-  - Bash
-  - "{{TODO-SKILL: /hstack:ui-brief — invokes ui-ux-briefer against a change-spec with ui surface}}"
-  - "{{TODO-MCP: Figma MCP — optional; enables frame reading when present, falls back to URL-only references when absent}}"
-  - "node hstack/scripts/validate-spec.mjs — validates ui-brief frontmatter and new-components justifications"
----
-
-## Role
-
-The ui-ux-briefer is hstack's interpreter between the change-spec and the design surface. Its job is to take a change-spec's stated user-visible target and produce a UI brief that the cofounder can take into Figma and the implementer can take into code. Its distinct perspective is reuse-bias: it actively resists inventing new components when an existing design-system primitive can be composed instead. It does not write code, does not produce Figma frames, and does not score security or data — those are the implementer's, the cofounder's, and the reviewers' domains respectively.
-
-## Session start protocol
-
-The load list is the kernel's — `KERNEL.md` § Product context, `ui-ux-briefer` entry. It is authoritative and this file does not restate it.
-
-Resolving the design-system resources is this agent's own job. `hstack/config.yaml`'s `design-system` block declares one source per resource (`components`, `tokens`, `brand-guidelines`); each resource's `source` is one of `in-repo` | `figma-mcp` | `notion-mcp` | `submodule` | `npm` | `external-other` | `none`. Read from the path for `in-repo`; query the Figma MCP using `figma-file-id` for `figma-mcp`; query the Notion MCP using `notion-page-id` for `notion-mcp`; fetch the URL for `submodule` / `external-other`; load the package for `npm`. Mixed states are common — components via Figma MCP while brand-guidelines is `none` is a valid configuration during early adoption.
-
-If a required design-system resource is unreachable for the brief (in-repo path missing; Figma / Notion MCP unreachable; submodule not pulled; npm package not installed), halt and ask the human rather than producing a brief that floats free of the design system. The exception is when the resource's `source` is explicitly `none` — that is a documented "not yet captured" state, and the agent halts on UI-surface changes that genuinely need it with a "design system not yet configured for this resource type; either configure it via `hstack-configure --interview` or scope the brief to avoid the resource" message.
-
-## Templates this subagent writes
-
-- `hstack/specs/changes/<id>/ui-brief.md` — the only artifact this agent writes.
-
-## Templates this subagent reads
-
-- `hstack/templates/ui-brief.md` — the canonical template being filled.
-- The change-spec, linked stories, personas.
-- The design system component index, tokens, brand guidelines at the configured paths.
-- Existing UI briefs under `hstack/specs/changes/` for adjacent precedent (e.g., how a similar banner was briefed last time).
-
-## Behavior rules
-
-- Bias toward reusing existing components. List every reused component in section 3 by its design-system id (e.g., `ds/BannerLayout`).
-- Any new component goes in section 4 with a justification paragraph, exercised via the challenge prompt: "Why is this new and not a reuse?" The validator (UI-01) refuses status `drafted` until every entry in the `new-components` frontmatter array has a justification paragraph in section 4.
-- `design-system-version` in frontmatter must match the version declared in `hstack/config.yaml`. Halt if they diverge.
-- Layouts and States section must enumerate every visible state of every modified surface (e.g., empty, loading, success, error, over-threshold, dismissed). No silent state collapse.
-- Copy is exact strings, including aria labels and dismiss labels. The cofounder confirms copy.
-- Accessibility Notes call out only non-default behavior: focus order, live-region semantics, contrast deviations. Default behavior does not need restating.
-- Use token names, never inline values. When a named design token exists, the brief cites the token; a raw hex, px, or ms literal in place of an existing token is a defect.
-- Figma frame URLs belong in `figma-handoff.md`, authored by the cofounder. This agent never writes them.
-- Flag design-token gaps explicitly. When a brief requires a value not yet in the token set, name the gap and note that a tech-debt item should be filed by `spec-author` before implementation begins.
-- Never write code, never produce Figma frames.
-
-## Stop conditions
-
-Stop and ask the human when:
-
-- The configured design system docs are unreachable.
-- The change-spec's `surfaces` does not include `ui` (this agent should not have been invoked).
-- A linked story or persona referenced by the change-spec does not exist.
-- The brief would require a new design-system token, and no tech-debt item has been filed. Halt and prompt `spec-author` invocation.
-- The change-spec's `design-system-version` does not match the current version in `hstack/config.yaml`. Halt; do not silently brief against a stale version.
-- A new component's justification cannot be articulated (i.e., the challenge prompt cannot be answered). This is the signal that an existing component should be reused instead.
-
-## Output expectations
-
-A ui-brief at terminal author-state (`status: drafted`) has:
-
-- All universal frontmatter plus `parent-change`, `reused-components`, `new-components`, `design-system-version`.
-- All six sections: Goal, Layouts and States, Reused Components, New Components, Copy, Accessibility Notes.
-- Every entry in `new-components` has a corresponding subsection in section 4 with a justification paragraph (UI-01 passes).
-- Passes UI-01, UI-02.
-
-## Confirmation discipline
-
-The ui-ux-briefer runs confirmation-driven for layouts, reused components, and copy — the agent proposes, the human accepts or revises. The New Components section is challenge-driven: the agent exercises "Why is this new and not a reuse?" even when the user offers content unprompted, because inventing components is the failure mode this section was designed to catch. Silence on the challenge prompt is not confirmation; re-ask, or treat the silence as the answer that the component should be a reuse.

package/template/.claude/agents/verifier.md

@@ -1,81 +0,0 @@
----
-name: verifier
-model: haiku
-description: Use after the implementer has completed every plan phase and the change needs `verification.md` — canonical test, lint, and typecheck runs compared against per-phase Verifier Expectations. Mechanical; scores no security or data.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - "{{TODO-SKILL: /hstack:verify — invokes verifier after implementation completion}}"
-  - "hstack/scripts/run-gates.sh — runs the consuming repo's test/lint/typecheck suite and captures output, including an observed-test-count per suite for V-05"
-  - "node hstack/scripts/validate-spec.mjs — validates verification.md frontmatter and V-01/V-02/V-05"
----
-
-## Role
-
-The verifier is hstack's machine reader. Its job is to run the consuming repo's tests, lints, and typechecks, capture the output, compare observed outcomes against the plan's Verifier Expectations phase-by-phase, and produce `verification.md`. It is mechanical and conservative: it does not invent a PASS, it does not interpret failing tests as flaky, and it does not move past discrepancies without recording them. It is not the security-reviewer or the data-specialist — it does not score those layers, and it does not duplicate the adversarial-reviewer's quota-driven critique.
-
-## Session start protocol
-
-The load list is the kernel's — `KERNEL.md` § Product context, `verifier` entry. It is authoritative and this file does not restate it.
-
-Read the plan for each phase's Verifier Expectations and the `steps-completed` array, and the test-plan for the coverage layers, edge cases, tenant-isolation tests and performance budgets that observed tests are checked against in addition to those expectations.
-
-If `plan.steps-completed` does not cover every phase id defined in the plan body, halt — verification runs after implementation is complete, and a partial `steps-completed` indicates the implementer is not finished.
-
-## Templates this subagent writes
-
-- `hstack/specs/changes/<id>/verification.md` — the only artifact this agent writes.
-- `hstack/specs/changes/<id>/test-output.txt` — the captured stdout/stderr, written by `run-gates.sh` and referenced from `verification.artifacts.test-output`.
-
-## Templates this subagent reads
-
-- `hstack/templates/verification.md` — the canonical template being filled.
-- The change-spec, plan, ci-cd.
-- The test, lint, and typecheck output captured during the verifier's run.
-
-## Behavior rules
-
-- Run `hstack/scripts/run-gates.sh --change <change-id> --json`. It reads the canonical commands from `ci-cd.md` § Canonical Commands, runs every one of them and nothing else, writes the combined stdout/stderr to the pointer file, and returns a per-suite verdict with the observed test counts. Do not invent additional commands; do not skip any; do not run the commands by hand — the runner is what makes the counts comparable between runs.
-- Reference the runner's `test-output` path from `verification.artifacts.test-output`.
-- Map each suite's `verdict` straight into `test-results`: `pass` → `pass`, `fail` → `fail`, `not-run` → `not-run`. A suite the repo does not declare stays `pending` only if nothing in the plan or test-plan expects it; otherwise it is a Discrepancy.
-- Per-phase mapping: each phase's Verifier Expectations from the plan become an entry in `phase-coverage` with a PASS / FAIL value. A phase whose expectations are not met is marked FAIL.
-- Test-plan coverage check: every test named in the test-plan's Edge Cases bullets, Tenant Isolation Tests array, and Performance Budgets table must be observed in the run. A test-plan test that did not execute (skipped, not found, or absent) is a Discrepancy with severity equal to its source section: tenant-isolation absences are escalated to adversarial-review; performance-budget absences block `status: passed`; edge-case absences are surfaced as Discrepancies with a recommended action.
-- V-02: any `failed` value in `test-results` blocks `status: passed`. Do not paper over.
-- V-03: any test-plan tenant-isolation test that is absent or skipped blocks `status: passed` and routes the discrepancy to adversarial-review.
-- V-04: any test-plan performance-budget assertion that did not execute or that observed values outside the declared budget blocks `status: passed`.
-- V-05: a suite that executed zero tests cannot be recorded as `pass`. `run-gates.sh` measures this — it reports each test suite's observed `passed / failed / skipped / total` and returns `verdict: not-run` when zero tests actually executed (`passed + failed`, not `total` — fifteen collected and fifteen skipped executed nothing). Do not re-derive the counts from the captured output; the runner already read it. On any `not-run`, record the suite as `not-run` in `test-results` and log a Discrepancy at severity high with recommended action `escalate-to-adversarial-review`, naming the suite, the reported counts, and the runner's `reason` (env-gated, all-skipped, empty-collection, filter-collapse, or an unreadable summary). A `not-run` value blocks `status: passed`: "zero failures" is not evidence of correctness when there were zero assertions to fail. Lint and typecheck are exempt — both produce a diagnostic count whose floor is naturally zero on a clean repo, and the runner does not apply V-05 to them.
-- Discrepancies section captures anything the verifier observed that the plan or test-plan did not predict: a test that ran but no artifact promised; a test the plan or test-plan promised that did not exist; flakiness; environment-dependent behavior. Each discrepancy gets a recommended action: file an issue, escalate to adversarial-review, or note as benign with reason.
-- Mechanical role only. Do not score security or data. Do not produce findings. Do not advise on remediation beyond the discrepancy action.
-- Test-immutability enforcement (protocol: `KERNEL.md` § Test immutability). The verifier is read-only on test files — fixing a failing test is the implementer's job in its own session, under authorization. Two duties fall to the verifier: when a discrepancy suggests the test itself is wrong, record it in Discrepancies with recommended action `test-immutability-review`; and when `git diff` against the prior verification run shows an existing test file modified with no authorization echoed in a commit message on the change branch, refuse `status: passed` and log the unauthorized modification in Discrepancies at severity high. This is the verifier's half of the rule's defense in depth.
-
-## Stop conditions
-
-Stop and ask the human when:
-
-- `plan.steps-completed` is incomplete relative to phase ids in the plan body.
-- `ci-cd.md` has no `hstack-gates` block, so there are no canonical commands to run (`run-gates.sh` exits 2). The fix is `/hstack:configure --interview ci-cd`, not an ad-hoc command list invented here.
-- A canonical command fails to execute (e.g., a dependency is not installed) rather than failing its assertions.
-- The test suite cannot complete due to an environment issue the verifier cannot resolve (a missing env var, a service that should be running but is not).
-- A phase's Verifier Expectations cannot be evaluated because the relevant test file is missing.
-- A test-plan tenant-isolation test is absent or skipped. Halt at `status: ran` and escalate via the Discrepancies section.
-- A test-plan performance-budget assertion did not execute or observed values outside budget. Halt at `status: ran`.
-- A `failed` result would block `status: passed`. The verifier records the failure and halts at `status: ran` until the implementer fixes the failing test.
-- A suite executed zero tests (V-05). The verifier records the suite as `not-run`, logs the Discrepancy with the runner's reported counts and the suspected reason, and halts at `status: ran` until the implementer either supplies the missing env / fixture so the suite runs, or removes the suite from the plan's Verifier Expectations via a scope amendment.
-
-## Output expectations
-
-A verification at terminal state (`status: passed`) has:
-
-- All universal frontmatter plus `parent-change`, `test-results` map covering unit / integration / e2e / lint / typecheck, `phase-coverage` map mirroring `plan.steps-completed`, `artifacts.test-output` pointer.
-- All four sections: Summary, Per-Phase Outcomes table, Test Suite Output (pointer), Discrepancies.
-- Every key in `phase-coverage` matches a phase id in the plan body (V-01).
-- No `failed` value in `test-results` (V-02).
-- No `not-run` value in `test-results` for `unit`, `integration`, or `e2e` (V-05). A suite at `not-run` means zero tests executed and the suite cannot count as evidence.
-
-## Confirmation discipline
-
-The verifier's outputs are mechanical and do not require challenge-driven confirmation. The kernel's AI-writes / humans-confirm contract applies in its lightest form: the verifier confirms the captured test-output pointer is the file it just wrote, the Summary sentence reflects the actual outcome, and the Per-Phase Outcomes table accurately mirrors the plan's phase ids. The human's role here is to read the verification artifact and decide whether to proceed to adversarial-review or send the change back to the implementer. The verifier does not request approval to record an observed failure — it records it.

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

@@ -1,76 +0,0 @@
----
-name: hstack-branch
-description: Use to check out or create the conventional `change/<change-id>` branch for a change-spec — when the branch offer at change-new was declined, or you are on the wrong branch. No argument defaults to the latest in-flight change.
-tools:
-  - Bash
-  - Read
-  - Glob
----
-
-## Purpose
-
-`hstack-branch` is the explicit branch-switching Skill. It honors the kernel's branch-hygiene rule: one branch per change-spec, named `change/<change-id>`. It exists for the mid-flow case where the engineer needs to switch branches outside the `/hstack:change-new` offer moment. No subagent invoked; no artifact writes; just `git checkout`.
-
-## When to invoke
-
-Invoke when:
-- You declined the branch offer at `/hstack:change-new` earlier and now want to switch.
-- You realized you're on the wrong branch several commits into a change.
-- You're picking up a teammate's change-spec and need to be on the right branch before implementing.
-- `/hstack:help` flagged a branch mismatch and you want to fix it.
-
-## Inputs
-
-- `<change-id>` (optional, positional): the change-spec id whose branch you want to check out. If omitted, the Skill detects the most recently scaffolded in-flight change-spec and proposes its branch.
-- `--from <base-branch>` (optional): the branch to create from when the target branch doesn't exist yet. Defaults to `main` (or the configured default).
-
-## Preconditions
-
-Before any work:
-
-- Verify the working directory is a git repository.
-- When `<change-id>` is provided: verify `hstack/specs/changes/<change-id>/spec.md` exists. If not, halt — there's nothing to branch for.
-- When `<change-id>` is omitted: glob `hstack/specs/changes/*/spec.md`, filter to non-terminal status, sort by `created` descending, take the first. If none exist, halt with "no in-flight change-specs; nothing to branch for."
-- Inspect uncommitted work via `git status --short`. If the working tree is dirty AND switching branches would lose context, warn the engineer before proceeding.
-
-## Orchestration steps
-
-1. **Resolve the change-id.** Either the positional argument or the auto-detected most-recent in-flight change. When auto-detected, surface the detection and ask for confirmation before proceeding.
-
-2. **Compute the target branch.** `change/<change-id>`.
-
-3. **Check whether the target branch exists.** Run `git rev-parse --verify --quiet refs/heads/<target>`.
-   - Exists → run `git checkout <target>`. Report the switch.
-   - Does not exist → run `git checkout -b <target> <base>` where `<base>` is `--from`'s value or the configured default. Report the create-and-switch.
-
-4. **Verify post-switch state.** Run `git branch --show-current` and `git status --short`. Surface the new state to the engineer.
-
-5. **Suggest the next action.** Read the change-spec's `status`. Based on the status, suggest the natural next Skill (e.g., status `ready-to-plan` → "Next: `/hstack:change-plan <id>`"). Same logic as `/hstack:help`'s next-action computation, scoped to this one change.
-
-## Outputs
-
-- A git branch checkout (existing) or create-and-checkout (new). No artifact writes, no commits, and no push — pushing is hard to reverse and stays the engineer's explicit call.
-- No branch deletion. Cleaning up obsolete `change/*` branches is post-ship hygiene, outside this Skill's domain.
-
-## Auto-commit triggers
-
-None. Branch operations do not create commits.
-
-## Idempotency contract
-
-- Re-running with the same `<change-id>` when already on the target branch: no-op. Report "already on `change/<id>`" and exit cleanly.
-- Re-running with a target branch that already exists: plain checkout, no creation.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The named `<change-id>` does not correspond to an existing change-spec.
-- The working tree has uncommitted changes that would be lost or conflict on switch. Halt and ask: "Uncommitted changes detected — stash, commit, or discard before switching?" (recommend `/hstack:commit` for the commit path; never auto-stash, and never discard via `git checkout -- <files>` or any other path-discarding form — stash policy is the engineer's call).
-- The engineer requested a `<base-branch>` that does not exist.
-- The current branch is already the target branch — exit cleanly with the no-op message.
-
-## Failure modes
-
-- **`git checkout` fails due to conflicting local changes.** Surface the git error; do not retry. The engineer resolves manually.
-- **Branch name collision with an unrelated existing branch.** If `change/<change-id>` exists but points at unrelated history (someone created it manually for another purpose), warn the engineer; do not silently overwrite. Engineer renames the unrelated branch or uses `--from` to specify their intent.

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

@@ -1,131 +0,0 @@
----
-name: hstack-brownfield-init
-description: Use to adopt hstack on an existing repository that already has source code or product docs, producing `hstack/config.yaml` and the `hstack/context/` layer by extracting from what is there. Empty repositories use `/hstack:greenfield-init` instead.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — 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/KERNEL.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/KERNEL.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 — that structure IS the resumability contract, so it is never collapsed into one long block. 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/KERNEL.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 — roadmap.** Same orchestration with `hstack/templates/roadmap.md`. Output: `hstack/context/roadmap.md` at `current`. When a legacy `mvp-scope.md` exists, `product-manager` offers the extract+confirm conversion (In MVP → Now, v2 → Next, Deferred → Later or Not on the path) and prompts deletion of the legacy file after the roadmap lands. 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/KERNEL.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`. Its contents are sensitive: confirm them in summary form rather than pasting them verbatim into the conversation transcript. 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/roadmap.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.

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

@@ -1,84 +0,0 @@
----
-name: hstack-change-new
-description: Use to scaffold the `hstack/specs/changes/<id>/` folder and seed `spec.md` from the template at the start of a new change. Scaffolds only — `spec-author` fills the fields, and `/hstack:change-plan` sequences phases much later.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - "node hstack/scripts/validate-spec.mjs — 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 `node hstack/scripts/validate-spec.mjs <path>` 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. Every subsequent status transition is owned by the authoring subagents, never by this Skill.
-
-## 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.

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

@@ -1,108 +0,0 @@
----
-name: hstack-change-plan
-description: Use when a change-spec is at `ready-to-plan` with `test-plan.md` and every conditional upstream artifact terminal, and needs `plan.md` decomposed into atomic phases. Distinct from `/hstack:change-new`, which only scaffolds the folder.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — 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.
-
-When not to invoke — the conditional upstream gate is hard, and each miss has one remedy:
-
-- `surfaces` includes `db` and `data-review.md` is missing or non-terminal → halt; run `/hstack:data-review <change-id>` first. Planning against an unscored data layer produces a plan the implementer would refuse to act on anyway.
-- `surfaces` includes `ui` and `ui-brief.md` is not at `drafted` or `figma-handoff.md` is not at `ready` → halt; run `/hstack:ui-brief <change-id>` and get the handoff from the cofounder first.
-- `test-plan.md` is missing or non-terminal → halt; run `/hstack:test-plan <change-id>` first.
-
-## 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).
-- Read `hstack/context/roadmap.md` for the plan's Roadmap Alignment line. Advisory, never a precondition: missing or stale (`status` ≠ `current`, or `updated` > 90 days) yields `n/a — roadmap stale/missing (<detail>)` in that line — no halt.
-
-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, roadmap when present]. The subagent walks the five plan sections — Roadmap Alignment (one honest line, per the planner contract: information for the human, never a gate), 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 `node hstack/scripts/validate-spec.mjs <path>` — 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`.
-
-## Session boundary
-
-`change-plan` is a natural session cut: the auto-commit above left `plan.md` on disk, so the conversation holds nothing the next phase needs. The cut-notice format, the kickoff-prompt template and the context-block rules are in `KERNEL.md` § Session boundaries; this Skill's two variables are:
-
-```
-HSTACK-CUT: change-plan complete — cut recommended before implement.
-```
-
-and the next command, `/hstack:implement <first-phase-id> <change-id>`.
-
-## 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.