hstack 0.1.0

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

@@ -0,0 +1,174 @@
+---
+name: hstack-help
+description: |
+  Use this skill when the engineer (or a cofounder opening the repo cold) wants situation awareness — "where are we, what can I run, what's next." Read-only across every artifact; no subagents invoked, no disk writes, safe to run any time. Examples:
+
+  <example>
+  Context: The cofounder hasn't touched the repo in two weeks and wants to know what's in flight before starting work.
+  user: "/hstack:help"
+  assistant: "I'll read every change folder, the context layer, ADRs, tech-debt, research sessions, and the git state. You'll get a three-section report: where you are, health, commands you can run right now with READY / BLOCKED markers."
+  <commentary>
+  Default mode is the full status report. No arguments needed. Output is computed entirely from disk frontmatter — no subagent invocations, no MCP calls, fast even on a large repo.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer is mid-change and wants a focused view of one change-spec's phase progression.
+  user: "/hstack:help --change 2026-05-billing-overage-warning"
+  assistant: "I'll read every artifact for that change and render the phase DAG: spec → ui-brief / figma-handoff / data-review / security-review / plan → implement (N of M phases) → verify → adversarial-review → ship. Each phase shows status and the next action."
+  <commentary>
+  Detailed mode for one change. Useful when resuming work after an interruption — the DAG view shows exactly which phase is next and what artifact gates it.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — invoked in --validate sub-mode to surface any artifact drift}}"
+---
+
+## Purpose
+
+`hstack-help` is the read-only situation-awareness Skill. Its job is to answer three questions without writing anything: where is the team in their hstack-governed work, what is healthy / unhealthy, and what commands are available to run right now. It invokes no subagent. It writes no artifact. It is safe to run any time, by any team member, on any branch.
+
+## When to invoke
+
+Invoke when:
+- You open the repo after a break and need a refresher.
+- A cofounder or new contributor is orienting themselves.
+- Something feels off (a Skill halted, a status seems wrong) and you want a system-level view before debugging.
+- Mid-change, before invoking the next workflow Skill, when you want to confirm preconditions are met without trial-and-error halts.
+
+Safe to run repeatedly. Output is computed from current disk state.
+
+## Inputs
+
+- No flag (default): full three-section status report.
+- `--change <id>`: detailed view of one change-spec, including the phase DAG.
+- `--commands`: print only the Skills cheat sheet (no current-state computation).
+- `--explain <concept>`: look up a concept from the kernel, the template schemas, or the glossary. Examples: `--explain invariant`, `--explain tenant-isolation`, `--explain trivial-tag`.
+- `--validate`: run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against every artifact under `hstack/` and report violations.
+
+## Preconditions
+
+Minimal. The Skill is best-effort and degrades gracefully:
+
+- Verify `hstack/` exists. If not, print "hstack is not installed in this repo. See `hstack/README.md` if vendoring, or run the vendoring procedure from the framework source."
+- Verify `hstack/config.yaml` exists. If not (init not started), print "hstack is installed but not initialized. Run `/hstack:init` to bootstrap. Other Skills will halt until init completes."
+- Beyond that, the Skill tolerates missing or partial artifacts — they show up in the report as "not present" or "draft", which is useful information, not an error.
+
+## Orchestration steps
+
+No subagents are invoked. Every step is a direct file read or shell call.
+
+### Default mode (no flag)
+
+1. **Section 1 — Where you are.**
+   - Read `hstack/config.yaml` for `init-status` and the active MCP set.
+   - Glob `hstack/specs/changes/*/spec.md`. For each, read frontmatter (`id`, `status`, `surfaces`, `owner`, `internal-tooling`, `trivial`, `parent-change`). Filter to non-terminal status (anything before `shipped`, `archived`).
+   - For each in-flight change, compute the **next blocking action**:
+     - `status: draft` → "Author via `spec-author` directly (or run `/hstack:story-draft` first if user-facing)."
+     - `status: ready-to-plan` and missing conditional artifacts → name them; suggest the appropriate Skill (`/hstack:test-plan` first if missing — it gates the planner, `/hstack:security-review`, `/hstack:data-review` if db, `/hstack:ui-brief` if ui, `/hstack:change-plan`).
+     - `status: ready-for-implementation` and plan has un-completed phases → "/hstack:implement <id> <next-task-id>" with the next phase id computed from `plan.steps-completed`.
+     - `status: in-progress` → continue implementing remaining phases; verify after.
+     - `status: ready-for-review` and no `verification.md` at passed → "/hstack:verify <id>".
+     - `status: ready-for-review` and no `adversarial-review.md` at `findings-resolved` → "/hstack:adversarial-review <id> (FRESH SESSION REQUIRED)".
+     - `status: ready-to-ship` → "/hstack:ship <id>" (if pr-body not yet produced) or "open/merge the PR, then run /hstack:finalize <id>" (if pr-body exists).
+     - `status: shipped` and `resolves-tech-debt` is non-empty but referenced TDs are still at `in-progress` → "/hstack:finalize <id>" (finalize is incomplete; this is an inconsistent state).
+   - Glob `hstack/adr/ADR-*.md`, count those at `status: proposed`. List ids.
+   - Glob `hstack/tech-debt/TD-*.md`. For `status: open`: count and list the top 3 by severity, with the suggested command `/hstack:tech-debt-resolve <td-id>` for each. For `status: in-progress`: list each with its resolving change-spec id (from the Resolution Log) and the change-spec's current status — flag any inconsistency where the change-spec is `shipped` but the TD is still `in-progress` as "run /hstack:finalize <change-id> to complete resolution".
+   - Glob `hstack/research/sessions/*.md`, count those within the 30-day retention window. List the most recent 3.
+   - **Context docs.** Walk the canonical list from the kernel's "Product context" section: `vision`, `glossary`, `mvp-scope`, `personas/`, `data-architecture`, `tech-stack`, `ci-cd`, `infrastructure`, `threat-model`, `hardening-checklist`, `incident-runbook`. For each, classify:
+     - Missing entirely → "Run `/hstack:configure --interview <name>` (or `/hstack:init` if `init-status != complete`)."
+     - Status not `current` (e.g., `drafted`, `needs-refresh`) → flag with the same routing.
+     Author routing mirrors `/hstack:configure` §`--interview`:
+     - `vision`, `glossary`, `mvp-scope`, `personas`, `data-architecture`, `tech-stack`, `ci-cd` → `product-manager`.
+     - `infrastructure`, `incident-runbook` → `spec-author`.
+     - `threat-model`, `hardening-checklist` → `security-reviewer`.
+   - Glob `hstack/specs/*/spec.md`, list any module-spec at `status: needs-refresh`.
+
+2. **Section 2 — Health.**
+   - MCPs: read `hstack/context/mcp-status.md` for wired vs degraded.
+   - **Branch hygiene.** Run `git branch --show-current`. For each in-flight non-trivial change-spec, the expected branch is `change/<change-id>` per the kernel's branch-hygiene rule. Compare:
+     - Current branch is `main` AND ≥ 1 non-trivial in-flight change exists → flag explicitly: "On `main` with in-flight non-trivial change `<id>`; expected `change/<id>`. Run `/hstack:branch <id>` to switch."
+     - Current branch matches the expected `change/<id>` of one in-flight change → "Branch `change/<id>` matches in-flight change `<id>`."
+     - Current branch is `change/<other-id>` and `<other-id>` is no longer in-flight (shipped or archived) → "On `change/<other-id>` (shipped); ready to start something new."
+     - Trivial-only in-flight changes → no branch warning (trivial may commit on main).
+   - Git state: `git status --short` count. Flag uncommitted hstack-relevant files.
+   - Last hstack commit: `git log -1 --format='%h %s (%cr)' -- hstack/`. Shows when hstack-touching work last landed.
+   - Local-ahead-of-remote: `git rev-list --count @{u}..HEAD 2>/dev/null` (silently skip if no upstream).
+
+3. **Section 3 — Commands you can run right now.**
+   - List every Skill grouped by category (setup, workflow, cross-cutting).
+   - For each, compute a marker:
+     - `READY` — preconditions detectable as met.
+     - `BLOCKED: <reason>` — name the missing precondition.
+     - `N/A — context` — e.g., `/hstack:ui-brief` for a repo with no in-flight ui-surface change.
+   - For Skills that take arguments, show a parameterized example using the most likely current value (e.g., the active in-flight change-id).
+
+### `--change <id>` mode
+
+Read every artifact in `hstack/specs/changes/<id>/`. Render the phase DAG as ASCII with status per node:
+
+```
+spec [ready-for-implementation]
+  ├── test-plan [passed] ✓
+  ├── ui-brief [drafted] ✓
+  ├── figma-handoff [ready] ✓
+  ├── data-review [passed] ✓
+  ├── security-review [concerns-acknowledged] ✓
+  └── plan [in-progress]
+        steps-completed: phase-1, phase-2, phase-3 of phase-1..phase-5
+        next phase: phase-4-wire (depends on phase-3 ✓)
+verification [not present]
+adversarial-review [not present]
+```
+
+Below the DAG, the explicit next-action recommendation.
+
+### `--commands` mode
+
+Just the Skills cheat sheet. No state computation. Useful when typing in muscle memory.
+
+### `--explain <concept>` mode
+
+Grep `hstack/CLAUDE.md`, `hstack/context/glossary.md`, and (if available) the cached template schemas for the concept. Print the most relevant paragraph plus a pointer to the source file. If the concept is not found in any source, print: "Not in the kernel, glossary, or template schemas. Try the architecture doc at the URL in `hstack/README.md`, or ask in natural language and I'll pull from kernel context."
+
+### `--validate` mode
+
+Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against every artifact under `hstack/`. Group failures by validation-rule id (SP-*, PL-*, AR-*, etc.) and name the offending file. Read-only — does not auto-fix anything.
+
+## Outputs
+
+- Console-rendered status report. No disk writes. No commits.
+- No mutation of any artifact frontmatter.
+
+## Auto-commit triggers
+
+None. This Skill is strictly read-only.
+
+## Idempotency contract
+
+Trivially idempotent. Re-runs produce a fresh report from current disk state. No persisted state, no side effects.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- The `--explain <concept>` lookup finds no match in any canonical source. Print the "not found" message and exit cleanly — not a failure.
+- `--validate` mode requires the validator script. If absent, print a clear "validator not yet implemented" message (it's a known TODO) and skip the validation; the other modes still work.
+
+## Failure modes
+
+- **Cofounder runs the Skill before vendoring is complete.** Print the install pointer; do not try to compute a status report.
+- **Many in-flight change-specs with conflicting next-action recommendations.** Just list them all; let the engineer prioritize.
+- **Git state cannot be read (not a git repo).** Skip the git-related health lines; surface a "git not initialized" note.
+
+## Anti-patterns
+
+- Never write to any artifact, never auto-commit. The Skill's value is that it's safe to run any time.
+- Never invoke a subagent. Status awareness does not require the conversational interview machinery.
+- Never invent a "next action" for an artifact whose status is ambiguous — print the ambiguity, not a guess.
+- Never run the validators with `--fix` or any write flag (when the validator gains those).
+- Never call MCPs or perform network requests for the status report. Local file reads only.

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

@@ -0,0 +1,185 @@
+---
+name: hstack-implement
+description: |
+  Use this skill when a change-spec is at `ready-for-implementation` and the engineer wants to execute one task from the plan. This is the only Skill that causes code to be written, and it does so exclusively by invoking the `implementer` subagent against one `task-id` at a time, scope-locked to the change-spec's `in-scope` allowlist. Defense in depth: the Skill checks preconditions and forbidden surfaces before invoking the subagent, and the subagent re-checks at every Read / Edit / Write. Examples:
+
+  <example>
+  Context: A UI-only change-spec for the billing-overage banner is at ready-for-implementation; the plan has five phases and phase-3 is next.
+  user: "/hstack:implement 2026-05-billing-overage-warning phase-3-component"
+  assistant: "I'll verify upstream gates (security-review passed, ui-brief drafted, figma-handoff ready), then invoke implementer for phase-3. Files Touched is a strict subset of in-scope; the subagent refuses any path outside it."
+  <commentary>
+  The Skill enforces the scope-lock contract from the kernel — Reads as well as Writes are restricted to `in-scope` plus the canonical session-start context loads. Phase-3 is the only thing executed; the Skill does not anticipate phase-4.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A multi-surface change touching ui, db, and api is at ready-for-implementation; phase-2 lands a migration and regenerates types.
+  user: "/hstack:implement 2026-06-knowledge-citations phase-2-migration"
+  assistant: "I'll invoke implementer for phase-2. The migration runs against local Supabase only; types regen via `supabase gen types typescript --local`; no `supabase db push` against any remote project."
+  <commentary>
+  The kernel's database workflow is enforced both at the Skill level (the Skill refuses to invoke if the engineer attempts a remote-environment migration) and at the subagent level. Defense in depth on the highest-risk surface.
+  </commentary>
+  </example>
+
+  <example>
+  Context: Mid-phase, the implementer halts because lib/billing/queries.ts is needed but is not in `in-scope`.
+  user: "/hstack:implement 2026-05-billing-overage-warning phase-4-wire"
+  assistant: "The implementer halted at the queries.ts edit — that file is out-of-scope. Don't proceed; emit the scope-amendment request to the conversation, halt, and wait for the engineer to update the change-spec via spec-author."
+  <commentary>
+  This is the precondition-failure / scope-amendment case. The Skill does not unilaterally extend in-scope. The engineer invokes spec-author to amend the change-spec, the Skill re-runs, the implementer re-loads and continues.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates plan.steps-completed updates against PL-03/PL-04/PL-05}}"
+  - "{{TODO-OTHER: in-scope-enforcement guard — runtime check at every Edit/Write that refuses paths outside change-spec.in-scope; v1 implemented inside the implementer subagent's prompt; v2 substrate moves to a subagent-runtime hook}}"
+---
+
+## Purpose
+
+`hstack-implement` is the only Skill that causes code to be written. It orchestrates the `implementer` subagent against one named task from the plan, scope-locked to the change-spec's `in-scope` allowlist. It is the workflow's last line of gating before code lands on disk: it re-checks every upstream gate, enumerates the kernel's forbidden tools, and refuses to invoke the implementer when preconditions are not met.
+
+## When to invoke
+
+Invoke once the change-spec is at `status: ready-for-implementation` (which means every upstream gate is terminal: test-plan at `passed` or `concerns-acknowledged`, plan at `ready`, security-review at `passed` or `concerns-acknowledged`, data-review at `passed` or `concerns-acknowledged` when applicable, ui-brief at `drafted` and figma-handoff at `ready` when applicable, user-stories non-empty unless internal-tooling). One invocation per phase. Re-invoke for each subsequent phase.
+
+## Inputs
+
+- `<change-id>` (required, positional): the change-spec id.
+- `<task-id>` (required, positional): the phase id (e.g., `phase-3-component`). Must match an existing `step-id` in the plan body.
+
+## Preconditions
+
+Before any work — the Skill re-checks every gate even when the change-spec carries `status: ready-for-implementation`, because frontmatter can drift:
+
+- Change-spec at `hstack/specs/changes/<change-id>/spec.md`. `status` must be `ready-for-implementation` or `in-progress`. `Invariants` ≥ 3 bullets, `in-scope` non-empty, every `in-scope` glob resolves.
+- Plan at `hstack/specs/changes/<change-id>/plan.md` at `status: ready` or `in-progress`. `<task-id>` must match a phase id in the plan body. `Files Touched` for the phase must be a strict subset of `in-scope`.
+- **Test-plan at `hstack/specs/changes/<change-id>/test-plan.md` at `status: passed` or `concerns-acknowledged`.** The implementer reads it at session start and writes the tests it specifies; without a terminal test-plan, the implementer halts.
+- Security-review at `status: passed` or `concerns-acknowledged`.
+- Data-review at `status: passed` or `concerns-acknowledged` when `surfaces` includes `db`.
+- ui-brief at `status: drafted` and figma-handoff at `status: ready` when `surfaces` includes `ui`.
+- User-stories non-empty unless `internal-tooling: true`.
+- The relevant module-spec at `status: current`.
+- **Branch state.** Run `git branch --show-current`. If the current branch is `main` (or the configured default) AND `change-spec.trivial` is not `true`, HARD HALT with: "Refusing to implement on `main` — change-spec `<id>` is not marked trivial. Check out `change/<id>` first, or run `/hstack:branch <id>` to create-and-switch." Trivial changes (`trivial: true`) may proceed on main per the kernel's trivial-changes carve-out. This check enforces the kernel's branch-hygiene contract at the last moment before code lands.
+
+Enumerate the kernel's forbidden tool surfaces explicitly before invoking the subagent — defense in depth with the implementer's own check:
+
+- `service_role` Supabase keys in agent-touching code paths.
+- Raw shell (`psql`, `bash`, `sh`) executed against production or remote Supabase. Local Supabase only.
+- `supabase db push` / `supabase db reset` against any remote project. Local stack only.
+- Pipedream Connect against live customer accounts without per-invocation explicit human approval.
+- Any tool that mutates state outside the `in-scope` list.
+- MCPs not in the consuming repo's configured allow set.
+- `--no-verify` or other hook-bypassing git flags.
+- `--update-snapshots`, `jest --updateSnapshot`, `vitest -u`, or any equivalent bulk snapshot-update flag.
+- Destructive git operations (`git push --force`, `git reset --hard`, `git checkout .`) without explicit per-invocation authorization.
+- Modifications to existing test files without per-test authorization via the test-immutability protocol (`Ok to change test <name>`, `Ok to delete test <name>`, `Ok to update snapshot <name>`, `Ok to refresh fixture <name>`).
+
+If the named phase appears to require any of the above, halt before invoking — surface the violation, ask the engineer to either reshape the phase or authorize per-invocation.
+
+## Orchestration steps
+
+1. **Re-verify gates.** Run the precondition checks above. Any failure halts the Skill with a precise message naming the failing artifact and field.
+
+2. **Invoke `implementer`.** Use the Task tool with `subagent_type: implementer` and context = [kernel, change-spec, plan, test-plan, security-review, data-review when present, ui-brief and figma-handoff when present, module-spec, tech-stack]. The subagent loads only the In-Scope file list for code reading; everything outside the canonical session-start context plus In-Scope is refused per the kernel.
+
+3. **Phase execution.** The subagent executes one phase per invocation. It writes the code diff scoped to the phase's Files Touched, updates `plan.steps-completed` to include `<task-id>` when the phase completes, and writes the tests named in the test-plan sections the phase's Test Strategy references. Test names, file paths, and assertion shape come from the test-plan; the implementer does not rename or omit tests.
+
+4. **Database workflow enforcement.** For phases touching schema: the subagent creates migration files via `supabase migration new <descriptive_name>`; enables RLS in the same migration as a new table; regenerates types via `supabase gen types typescript --local > types/database.types.ts`. Never `supabase db push` / `supabase db reset` against a remote project.
+
+5. **Trigger.dev v4 only.** For phases touching trigger code, the subagent uses `@trigger.dev/sdk` task / schemaTask; never `client.defineJob` (v2 deprecated). `triggerAndWait` returns a `Result`; `result.ok` is checked before reading `result.output`.
+
+6. **Scope-amendment halt.** If the subagent would touch a file outside `in-scope`, it halts and emits a scope-amendment request to the conversation. The Skill does not extend `in-scope` unilaterally. The engineer invokes `spec-author` (typically via direct request, not a Skill) to amend the change-spec, the Skill re-runs, the subagent re-loads.
+
+7. **Hook failures.** If a pre-commit hook fails on the auto-commit, the subagent investigates and fixes the underlying issue; does not bypass via `--no-verify`. If the fix would require out-of-scope edits, halt with a scope-amendment request.
+
+8. **Test-immutability protocol.** When the subagent determines an existing test file must be modified, deleted, or have a snapshot updated, it halts before touching the file and runs the kernel's authorization protocol: surface the test name, the reason, the proposed change, and the alternatives; wait for the canonical phrase verbatim (`Ok to change test <name>`, `Ok to delete test <name>`, `Ok to update snapshot <name>`, `Ok to refresh fixture <name>`); echo the phrase in the commit message body and add a footnote under the relevant phase in `plan.md`. The Skill enforces this defense-in-depth — if a subagent's diff shows a modified pre-existing test file without a matching authorization in the conversation, the Skill blocks the commit.
+
+8. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the plan — PL-03 (every `steps-completed` entry matches a plan phase id), PL-04 (every Files Touched path is a subset of `in-scope`), PL-05 (plan status gating).
+
+## Outputs
+
+- Code diffs in the consuming repo, scoped to `change-spec.in-scope` and matching the phase's Files Touched.
+- Test files written or updated per the phase's Test Strategy.
+- `plan.md` updated with `<task-id>` appended to `steps-completed`; `blocked-on: null` (or set to a phase id when interactive blocker stops progress).
+- One git commit on the active working branch naming `<change-id>` and `<task-id>`.
+
+The change-spec is never written by the implementer or by this Skill (architecture amendment A3).
+
+## Auto-commit triggers
+
+- One commit when the phase completes and `steps-completed` advances. Commit message: `implement(<change-id>) <task-id>`.
+- An additional commit when `plan.status` advances to `completed` after the final phase.
+
+## Telemetry sidecar
+
+At the phase-completion auto-commit above, write `hstack/specs/changes/<change-id>/.telemetry/implement-<task-id>.json` in the same `git add && git commit` as the canonical phase commit. The sidecar is derivative of git + frontmatter (see `hstack/templates/telemetry-sidecar.md`). Schema:
+
+```json
+{
+  "schema_version": 1,
+  "skill": "hstack-implement",
+  "change_id": "<change-id>",
+  "phase_id": "<task-id>",
+  "started_at": "<ISO-8601, session start of this phase>",
+  "completed_at": "<ISO-8601, now>",
+  "files_touched_count": <int>,
+  "tests_written_count": <int, new test files only>,
+  "scope_amendment_emitted": <bool>,
+  "halt_reasons": [<kernel halt-sentinel enum values, if any>],
+  "test_immutability_authorizations": [<canonical phrase strings, if any>]
+}
+```
+
+`.telemetry/` is git-ignored in the consuming repo. The sidecar write must not introduce any new LLM turn or confirmation gate — it is a deterministic write bundled with the existing commit. If the sidecar write fails, log and continue; the canonical commit must still land.
+
+## Idempotency contract
+
+- Re-running with the same `<task-id>` after the phase already landed: the subagent reads `steps-completed`, recognizes the phase as done, and produces a no-op diff. Re-running on a partially applied phase: the subagent reads current file state and applies only the remaining diff.
+- Re-running on a phase whose dependencies are not yet complete (`depends-on` references a phase not in `steps-completed`): the subagent halts and surfaces the missing dependency.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- A modification outside `in-scope` is needed. Halt; emit scope-amendment request.
+- An invariant would be weakened, dropped, or modified.
+- A required upstream artifact is non-terminal.
+- A forbidden tool would be used (see enumeration above).
+- A load-bearing MCP is unreachable mid-phase.
+- The change requires a migration against a remote environment.
+- A pre-commit or pre-push hook fails after investigation — halt and surface; do not bypass.
+- An existing test would need to be modified, deleted, or have its snapshot updated, and the human has not yet typed the canonical authorization phrase.
+- The engineer has not authorized a destructive git operation that the situation seems to call for.
+- An ambiguity in the plan or change-spec would require the implementer to make a design call beyond its role.
+
+## Failure modes
+
+- **Phase depends-on a phase not yet in `steps-completed`.** Halt and surface the dependency.
+- **Type regen fails after a migration.** The phase is incomplete; `steps-completed` is not advanced; halt and surface.
+- **Tests written but failing.** Halt at `steps-completed` not advanced; the engineer either re-invokes after fixing or amends the plan via the planner.
+- **Validator fails PL-04.** A Files Touched path crept outside `in-scope` — halt; this should have been caught upstream.
+
+## Anti-patterns
+
+- Never bypass scope-lock by one file, even one line. Halt and amend.
+- Never modify the change-spec. `steps-completed` lives on the plan.
+- Never weaken or remove an invariant.
+- Never use `service_role` Supabase keys in agent code paths.
+- Never use raw shell or `supabase db push` against production or any remote project.
+- Never use Pipedream Connect against live customer accounts without explicit per-invocation approval.
+- Never skip a hook with `--no-verify`. Fix the failing check.
+- Never execute destructive git operations without explicit authorization in the current conversation.
+- Never anticipate the next phase. Execute the named task and stop.
+- Never use `client.defineJob` (Trigger.dev v2 deprecated).
+- Never invent a migration filename. Use `supabase migration new <descriptive_name>`.
+- Never claim a phase complete when tests fail or types are stale.
+- Never edit, delete, or neutralize an existing test without per-test authorization. The kernel's test-immutability rule is non-negotiable; the default fix for a failing test is to fix the code under test.
+- Never run bulk snapshot-update flags. Each snapshot update needs its own authorization.
+- Never accept a blanket "fix the tests" authorization. Per-test scope is mandatory.

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

@@ -0,0 +1,152 @@
+---
+name: hstack-init
+description: |
+  Use this skill when an engineer is adopting hstack on a fresh repository for the first time and needs to produce `hstack/config.yaml` and populate every required document under `hstack/context/`. Until init completes, no other hstack Skill works — every workflow Skill checks for init completion at session start and halts otherwise. Init is structured as six-to-eight mini-sessions of ten-to-fifteen minutes each (one per product-context document) rather than one ninety-minute block, so that an interruption costs at most one in-flight field. Examples:
+
+  <example>
+  Context: A fresh Moso clone has no `hstack/config.yaml` and no `hstack/context/` content; the engineer wants to bootstrap hstack from scratch.
+  user: "Start /hstack:init on this repo."
+  assistant: "I'll invoke the product-manager subagent for the first mini-session — vision.md. We'll commit when vision is done and resume with glossary next."
+  <commentary>
+  Init is the only Skill permitted to write `hstack/config.yaml` and to populate the product-context layer. It orchestrates the product-manager subagent across five-to-seven document interviews, each ending at a commit point. The "no other Skill works until init complete" rule is enforced by every downstream Skill's precondition checks.
+  </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: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 — data-architecture, 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 — data-architecture, tech-stack, ci-cd.** These three 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: three files at `current`. Commit after each.
+
+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/data-architecture.md`, `tech-stack.md`, `ci-cd.md`, `infrastructure.md`, `threat-model.md`, `hardening-checklist.md` — all at `current`.
+- `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-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-module-spec/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: hstack-module-spec
+description: |
+  Use this skill when an engineer needs a baseline `hstack/specs/<module>/spec.md` reverse-engineered for an existing module on a brownfield repo. Module-specs are foundational: every change-spec validates that `area` references an existing module-spec at `status: current`, and every per-change downstream subagent loads the relevant module-spec at session start. Examples:
+
+  <example>
+  Context: The team has just finished `hstack-init` and the engineer wants to produce a module-spec for the billing module before any change work begins there.
+  user: "Run /hstack:module-spec billing."
+  assistant: "I'll invoke spec-author with the billing paths from hstack/config.yaml, pack the module via RepoMix, and walk the seven module-spec sections through an interview."
+  <commentary>
+  Module-specs are the only artifact the `spec-author` reverse-engineers from existing code rather than authoring fresh. The Skill is run once per critical module on adoption; thereafter the spec is refreshed via `hstack-configure --interview` or by re-running this Skill when the cron flags it `needs-refresh`.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A 60-day refresh cron has flagged `hstack/specs/orchestrator/spec.md` as `needs-refresh` because the orchestrator module has been heavily modified.
+  user: "Refresh the orchestrator module-spec."
+  assistant: "I'll re-run /hstack:module-spec orchestrator. The existing spec is the proposal layer; spec-author walks each section, confirming or correcting against the current code."
+  <commentary>
+  Refresh mode is idempotent — when the existing module-spec is read in as the proposal layer, sections that remain accurate produce a no-op confirmation and the timestamp updates without churning the body.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-TOOL: RepoMix — packs the module slice (paths from hstack/config.yaml) into a single context bundle for spec-author}}"
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates module-spec frontmatter and MS-01/MS-02/MS-03}}"
+---
+
+## Purpose
+
+`hstack-module-spec` produces a baseline `hstack/specs/<module>/spec.md` for one named module by orchestrating the `spec-author` subagent against a packed module slice. It is the one Skill where `spec-author` is permitted to grep the code in service of authorship — the module-spec is the system's anchor between its `area` controlled enum and the actual codebase, and a module-spec disconnected from real paths is worthless.
+
+## When to invoke
+
+Invoke once per critical module after `hstack-init` completes, before any change-spec in that module's `area` can validate. Re-invoke when the 60-day `needs-refresh` cron flags the spec, when the module's shape materially changes (new owned table, new public surface, new dependency), or on demand when the engineer wants a refresh.
+
+## Inputs
+
+- `<module>` (required, positional): the module key as declared in `hstack/config.yaml`'s module-to-area mapping. Must match an existing entry.
+
+## Preconditions
+
+Before any work:
+
+- Verify `hstack/config.yaml` exists at `init-status: complete`. If not, halt and direct the engineer to `hstack-init`.
+- Verify the named module exists in the config's module-to-area mapping. If not, halt and ask the engineer to add it via `hstack-configure` first.
+- Read the module's declared `paths` globs from config and verify at least one path resolves to existing files. If none resolve, halt — the module-to-paths mapping is stale.
+- Check whether `hstack/specs/<module>/spec.md` already exists. If yes and at `status: current`, ask the engineer whether this is a refresh (proceed with the existing spec as the proposal layer) or a re-author (archive the existing spec first).
+- Read `hstack/context/glossary.md` and `hstack/context/tech-stack.md` (required by `spec-author`'s session-start protocol).
+
+## Orchestration steps
+
+1. **Pack the module slice.** Run `{{TODO-TOOL: RepoMix}}` over the module's `paths` globs and write the packed bundle to a temporary location. If RepoMix is unavailable, fall back to having `spec-author` grep the paths directly; flag the degraded read in the conversation.
+
+2. **Invoke `spec-author`.** Use the Task tool with `subagent_type: spec-author` and context = [kernel, `hstack/templates/module-spec.md`, glossary, tech-stack, packed module bundle, existing module-spec instance if refresh]. The subagent reads the bundle, walks the seven module-spec sections — Purpose, Public Surface, Data Owned, External Dependencies, Invariants, Known Tech-Debt and ADRs, Refresh Policy — with confirmation gates per field.
+
+3. **Exercise the Invariants challenge prompt.** Per the `spec-author` contract and MS-03, the Invariants section requires a minimum of three bullets, elicited via the challenge "What would a careless refactor in this module break that the tests would not catch?" The Skill does not bypass this even on refresh.
+
+4. **Validate.** After each confirmed field write, the subagent runs `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the in-progress file. The Skill verifies MS-01 (paths non-empty and resolve), MS-02 (no overlap with other module-specs' paths — important to surface mis-aligned module-to-paths mapping), MS-03 (Invariants ≥ 3 bullets).
+
+5. **Transition to `status: current`.** When every section is confirmed and the validator passes, `spec-author` advances status from `drafted` to `current` and updates `last-refreshed` to today. Auto-commit fires.
+
+## Outputs
+
+- `hstack/specs/<module>/spec.md` at `status: current`, with frontmatter including the module's `paths` array mirrored from `hstack/config.yaml`.
+
+## Auto-commit triggers
+
+- Status moves from absent to `drafted` after the first section is confirmed (so partial work survives).
+- Status moves from `drafted` to `current` when the full spec lands. Commit message: `module-spec(<module>): draft baseline` or `module-spec(<module>): refresh` depending on prior state.
+
+## Idempotency contract
+
+- Re-running on a `current` module-spec without specifying refresh intent: the Skill detects the existing spec and asks the engineer whether to refresh.
+- Re-running mid-authoring after a halt: `spec-author` reads the partial file, identifies the first un-confirmed section, and resumes the interview there.
+- Re-running on a refresh where the engineer accepts every section unchanged: a no-op diff body with only the `updated` and `last-refreshed` timestamps changing.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- The module's `paths` globs resolve to zero existing files. Halt; the module-to-paths mapping in config is wrong.
+- MS-02 fails — the module's paths overlap with another module's paths. Halt and ask the engineer to reconcile the mapping via `hstack-configure`.
+- The Invariants challenge prompt cannot produce three bullets after honest interview. Halt; either the module is too small to merit its own spec (fold into a parent module via `hstack-configure`) or the engineer needs more time to think.
+- `spec-author` halts because a referenced glossary term cannot be reconciled. Halt and surface; the engineer either updates the glossary via `hstack-configure --interview glossary` or rephrases.
+
+## Failure modes
+
+- **RepoMix unavailable.** Degraded mode — flag in the conversation, fall back to direct grep, continue.
+- **Existing module-spec frontmatter does not match config's paths.** Halt; the engineer reconciles before the refresh can proceed.
+- **Validator failure on a partial write.** `spec-author` halts at the field; the Skill surfaces the validator's message and waits.
+
+## Anti-patterns
+
+- Never invent paths. The module's `paths` come from `hstack/config.yaml`; the Skill never edits them and never substitutes.
+- Never skip the Invariants challenge. Three-or-more bullets is a hard validator rule, not a heuristic.
+- Never run this Skill against a module that does not appear in the config. The right move is to add the module to config first.
+- Never overwrite an existing `current` module-spec without explicit refresh-or-re-author confirmation from the engineer.
+- Never write code. `spec-author` is the only subagent invoked, and it reads code without modifying it.