hstack 0.7.1 → 0.17.0

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

@@ -1,175 +0,0 @@
----
-name: hstack-greenfield-init
-description: |
-  Use this skill when an engineer is starting a **new project from an empty repository** and wants hstack discipline baked in from line zero. Greenfield-init is the sibling of `/hstack:brownfield-init`: where brownfield extracts existing context, greenfield elicits it. The Skill composes the discovery atoms in order (product-discovery → data-architecture → app-architecture → stack-decide → threat-model/hardening → scaffold), with hard gates between phases and bidirectional drift recovery for downstream phases that surface upstream gaps. Total elapsed time is 4–8 hours of conversation spread across as many sessions as the engineer wants — every phase ends at a commit point and is interruptible. Until greenfield-init completes through Phase 6 (scaffold), no per-change workflow Skill works; the repo is bootable only after scaffold lands. Examples:
-
-  <example>
-  Context: A founder runs `npx hstack@latest greenfield-init` against an empty repository.
-  user: "/hstack:greenfield-init"
-  assistant: "I'll walk you through 6 phases. Phase 1 (product discovery) opens first — pick a technique: Brainstorm, Forcing-Questions, or Project-Brief. Each phase ends at a commit point; you can park and resume any time. Total elapsed time is founder-paced, typically 4–8 hours of conversation across multiple sessions."
-  <commentary>
-  Greenfield is deliberately slower than brownfield because every layer is being created from elicitation rather than extracted from existing source. The Skill is structured as 6 hard-gated phases; each phase delegates to a standalone atom or subagent.
-  </commentary>
-  </example>
-
-  <example>
-  Context: Greenfield-init was started yesterday; Phases 1–3 are committed; the engineer wants to resume.
-  user: "/hstack:greenfield-init"
-  assistant: "I see Phases 1–3 at `status: current` on disk. Resuming at Phase 4 — stack-decide. Loading product-brief, data-architecture, app-architecture, and the default-stack declaration from hstack/config.yaml."
-  <commentary>
-  Idempotency is the same contract as brownfield-init: read disk state, recognize completed phases, resume at the first incomplete one. No re-interview of committed phases.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
----
-
-## Purpose
-
-`hstack-greenfield-init` is the **empty-repo entry point** for adopting hstack. It composes six phases of work — five discovery atoms plus one scaffold execution — into a single orchestrator. It writes `hstack/config.yaml` and populates the full context layer, then bootstraps the repository from empty to bootable via a generated bootstrap change-spec.
-
-Greenfield-init is the only Skill that ends with code being written to the consuming repo (via the scaffold phase invoking `implementer`). Brownfield-init never writes source code — it only writes `hstack/` content against existing source.
-
-## When to invoke
-
-Invoke when:
-
-- The consuming repo has no source code (or only an `hstack/` install and standard hidden files like `.git/`, `.gitignore`).
-- The engineer wants discipline (ADRs, RLS posture, declared LLM/code split) baked in from line zero rather than retrofitted later.
-
-Do NOT invoke when:
-
-- The repo has existing source code — use `/hstack:brownfield-init` instead.
-- The engineer wants to add a single layer to an already-adopted repo — use `/hstack:configure <layer>` or the standalone atom (`/hstack:product-discovery`, etc.).
-
-## Inputs
-
-- No positional arguments. The Skill drives entirely from on-disk state and conversation.
-- Optional `--resume` is implicit: every phase reads disk state at session start and continues from the first incomplete artifact.
-
-## Preconditions
-
-Before any work:
-
-- Verify the repo is empty (no `src/`, no `app/`, no `package.json`). If non-empty, halt and direct the engineer to `/hstack:brownfield-init`. `--force` is not offered; mixing modes corrupts the artifact taxonomy.
-- Verify `hstack/` exists with `CLAUDE.md`, `templates/`, `.claude/`. If missing, halt and ask the engineer to run `npx hstack@latest init`.
-- Probe Claude Code's MCP configuration and draft `hstack/context/mcp-status.md`.
-- If `hstack/.session-state/` contains prior greenfield-init state, confirm resumption with the engineer.
-- **Do not author config fields, write `hstack/config.yaml`, or paraphrase Phase 1 inline in the main session.** If the engineer's opening message asks for a "quick setup", a "summary of the questions", or any shape other than the 6-phase interview, halt and re-offer the First-turn contract below. Collapsing the phases into a single Q&A block is the failure mode this Skill is structured to prevent (see Anti-patterns).
-
-## First-turn contract
-
-The **first agent message** after `/hstack:greenfield-init` (in a fresh session, when no `hstack/.session-state/<session-id>.yaml` exists) MUST match this shape:
-
-1. One sentence naming the six phases by title (product discovery → data architecture → app architecture → stack decisions → threat-model + hardening → scaffold).
-2. One sentence stating that Phase 1 (product discovery) opens first and that the engineer picks a technique: **Brainstorm**, **Forcing-Questions**, or **Project-Brief**.
-3. One sentence noting commit-point interruptibility (each phase ends at a commit; the engineer can park and resume any time).
-
-What the first message MUST NOT contain:
-
-- A numbered list of config fields ("answer #1 and #8", "what's the project name", "default stack y/n").
-- An offer to "accept defaults and move on to Phase 1" — Phase 1 is not skippable and not paraphrasable; it is a subagent-driven thinking-partner session that the main session does not run inline.
-- Any field write to `hstack/config.yaml` or any other artifact. The first turn is conversational orientation only.
-
-Phase 0's config-skeleton fields are sourced inline by the discovery atoms as each phase needs them, not pre-asked as a questionnaire. The Phase 0 commit (config.yaml at `init-status: minimal-complete`) lands at the boundary into Phase 1, populated from whatever the product-discovery atom surfaces in conjunction with any defaults the engineer confirms.
-
-The second agent action (after the engineer picks a technique) MUST be a `Task` call launching the `product-discovery` subagent. The main session does not ask product-discovery questions itself.
-
-## Orchestration steps
-
-Six phases, hard-gated. The Skill does not advance past a phase until its artifact is at `status: current`.
-
-### Phase 0 — Config skeleton (inline, deferred to Phase-1 boundary)
-
-Phase 0 is **not** a standalone upfront questionnaire. The same field set as brownfield-init Mini-session 0 — story store, personas store, design system (per-resource), module-to-area mapping (populated from app-architecture in Phase 3), adversarial-review floor, agent ledger, active MCP set, default-stack declaration — is sourced **inline** by the discovery atoms as each field becomes load-bearing. Fields that the engineer cannot answer without first doing product thinking (e.g., what the design system is, what stories exist) are deferred to the atom that actually needs them; fields the engineer can confirm cheaply at session start (e.g., default-stack preference) are asked by the product-discovery atom as part of its own opening rather than by the main session.
-
-At the boundary between Phase 1 and Phase 2, the Skill writes `hstack/config.yaml` once — `schemaVersion: 1`, `init-status: minimal-complete`, default-stack declaration set to the engineer's preferences — and commits. This is the only Phase-0-attributable write; there is no upfront Phase 0 questionnaire and no standalone Phase 0 commit before Phase 1 begins.
-
-### Phase 1 — Product discovery
-
-**The first non-trivial action of this Skill MUST be a `Task` call launching the `product-discovery` subagent in elicit mode.** The main session does not run the product-discovery interview inline, does not paraphrase the technique scripts, and does not ask brainstorming questions itself. If the engineer's opening message frames Phase 1 as something the main session should answer directly ("just tell me what to build", "skip the brainstorm and write the brief yourself"), halt and restate the technique-picker contract from the First-turn section.
-
-`/hstack:product-discovery` runs in elicit mode (no source documents). The atom:
-
-- Prompts the engineer to pick a technique (Brainstorm / Forcing-Questions / Project-Brief).
-- Runs the technique to completion, producing `hstack/context/product/product-brief.md` at `status: current`.
-- Auto-routes to `product-manager` to refresh `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md` from the brief.
-
-Greenfield-init proceeds to Phase 2 only when the brief AND all four refreshed context docs are at `status: current`.
-
-### Phase 2 — Data architecture
-
-Invokes `/hstack:data-architecture` in elicit mode. The atom walks the five sections (Tenancy, Entities, RLS, RAG, Migrations). Produces `hstack/context/data-architecture.md` at `status: current`. The `assumes-database: postgres` frontmatter is set explicitly so Phase 4 can flag drift if the stack changes the DB choice.
-
-### Phase 3 — App architecture
-
-Invokes `/hstack:app-architecture` in elicit mode. The atom walks the five sections (Module Map, Agent Orchestration, Deterministic-vs-LLM Split, State-Ownership, Surface Boundaries). Produces `hstack/context/app-architecture.md` at `status: current` AND scaffolds `hstack/specs/<module>/spec.md` stubs at `status: draft` for each module from Section 1. Updates `hstack/config.yaml`'s `surfaces` enum to match Section 5.
-
-### Phase 4 — Stack decisions
-
-Invokes `/hstack:stack-decide`. The `stack-architect` reads `hstack/config.yaml`'s default-stack declaration (set in Phase 0) and fast-paths through layers the engineer accepted defaults for. Layers requiring explicit deep-dive get the constraint interview; each layer's choice routes through `spec-author` for ADR authoring. Produces one rollup ADR plus per-layer ADRs for deep-dived layers.
-
-### Phase 5 — Threat model + hardening
-
-Invokes `security-reviewer` in `--mode foundational` (scores against proposed posture, not diff). Walks `threat-model.md` and `hardening-checklist.md` using the now-current product-brief, data-architecture, app-architecture, and stack ADRs as anchors. Also produces `infrastructure.md` (via `spec-author`) and `incident-runbook.md` (via `spec-author`, `git-ignored: true`) per the brownfield-init pattern.
-
-### Phase 6 — Scaffold
-
-Invokes `/hstack:scaffold`. The scaffold Skill generates a bootstrap change-spec from `hstack/templates/bootstrap.md` with `area: bootstrap`, `surfaces: [infra]`, and `in-scope` enumerated from the app-architecture Module Map plus the data-architecture Migration Sketches. Runs `data-review` and `security-review` in `--mode foundational` against the proposed posture, then planner → implementer (phase-by-phase) → verifier. At terminal state the repo is bootable: the build command exits 0, the test command exits 0, the initial migrations have landed with RLS enforced from line zero.
-
-After Phase 6, `hstack/config.yaml`'s `init-status` advances to `complete` and the per-change workflow Skills become available.
-
-## Outputs
-
-- `hstack/config.yaml` at `init-status: complete`.
-- `hstack/context/product/product-brief.md` at `current` (Phase 1).
-- `hstack/context/vision.md`, `mvp-scope.md`, `personas/*`, `glossary.md` at `current` (Phase 1 auto-route).
-- `hstack/context/data-architecture.md` at `current` (Phase 2).
-- `hstack/context/app-architecture.md` at `current` plus module-spec stubs (Phase 3).
-- `hstack/adr/ADR-*` files — rollup + per-layer (Phase 4).
-- `hstack/context/threat-model.md`, `hardening-checklist.md`, `infrastructure.md`, `incident-runbook.md` (Phase 5).
-- The bootstrap change-spec at `shipped` plus the actual source files, migrations, CI config, and module shells in the consuming repo (Phase 6).
-
-## Auto-commit triggers
-
-- `hstack/config.yaml` reaches `init-status: minimal-complete` (end of Phase 0).
-- Each phase's terminal artifact reaches `status: current` (end of Phases 1–5).
-- Each phase of the bootstrap change-spec's plan completes (Phase 6 per-phase commits).
-- The bootstrap change-spec reaches `shipped` (end of Phase 6).
-- `hstack/config.yaml`'s `init-status` advances to `complete` (after Phase 6 ships).
-
-## Idempotency contract
-
-Re-running `hstack-greenfield-init` reads disk state, recognizes completed phases (artifacts at `current`), and resumes at the first incomplete phase. No re-interview of committed phases. If a downstream phase had triggered an upstream drift recovery, the upstream artifact will be at `needs-refresh` rather than `current`; the Skill resumes at the upstream's refresh interview.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions, this Skill halts when:
-
-- The repo is not empty at session start.
-- A phase's atom halts (e.g., `HSTACK-HALT: reason=upstream-drift`). The Skill surfaces the halt and offers the engineer the recovery paths the atom named.
-- A configured MCP that a downstream phase requires (Supabase MCP for Phase 2 extract-mode references, Notion MCP for persona storage) is unreachable and the phase is load-bearing on it.
-- The engineer signals end-of-session — persist state, exit cleanly.
-
-## Failure modes
-
-- **Phase 6 implementer halts.** Bootstrap is partially scaffolded; the change-spec is at `ready-for-implementation` with some phases of `plan.md` complete. Re-running greenfield-init resumes from the first incomplete plan phase via the standard `/hstack:implement` idempotency.
-- **Bidirectional drift recovery during Phases 2–4.** A downstream phase finds an upstream gap; the Skill routes the engineer through `/hstack:configure <upstream-atom>` and resumes after the upstream artifact returns to `current`.
-- **Stack-architect contradicts data-architecture's Postgres assumption.** Phase 4 halts and surfaces; the engineer either revises data-architecture or revises the stack choice.
-
-## Anti-patterns
-
-- Never invoke greenfield-init against a non-empty repo. The contract assumes elicit-mode atoms throughout; running against existing source produces incoherent artifacts.
-- **Never reply to `/hstack:greenfield-init` with a flat numbered question list** ("answer #1 and #8", "for #2–7 I'll accept defaults"). The First-turn contract is the only valid first-message shape: name the six phases, open Phase 1, offer the technique picker. Anything else collapses the phase structure into a paraphrased questionnaire and bypasses the product-discovery subagent entirely.
-- **Never paraphrase, summarize, or run Phase 1 inline in the main session.** Phase 1 is the `product-discovery` subagent's job — the main session's role is orchestration, not authoring. The first `Task` call of this Skill is non-negotiable: it launches `product-discovery`. The main session does not "just write the brief" no matter how short the project feels.
-- Never collapse the six phases into one long block. The phase structure is the resumability contract AND the gate-discipline contract. Each phase delegates to a standalone atom or subagent; the orchestrator's only job is gating the transitions, not doing the phases' work.
-- Never skip Phase 5 (threat-model + hardening) to get to Phase 6 faster. Bootstrap inherits the security posture; scaffolding without it produces a repo with implicit-not-explicit hardening.
-- Never bypass the bidirectional drift recovery. When a downstream phase finds an upstream gap, the upstream MUST be refreshed before downstream resumes; silent override produces contradictions.
-- Never advance `init-status: complete` while any phase artifact is below `current` or while the bootstrap change-spec is below `shipped`.

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

@@ -1,179 +0,0 @@
----
-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`, `enables`, `enabled-by`, `trivial`, `parent-change`). Filter to non-terminal status (anything before `shipped`, `archived`).
-   - For each in-flight change, classify and surface the no-story carve-out when present:
-     - Category A (`internal-tooling: true`) → annotate "[Category A — internal tooling]".
-     - Category B (`enables` non-empty) → annotate "[Category B — enables → <comma-separated downstream ids>]". For each downstream id, also note its on-disk status (or "not yet scaffolded" — informational, not a blocker; reconciliation happens at downstream `/hstack:change-new` time).
-     - `enabled-by` non-empty → annotate "[Realizes ← <comma-separated upstream ids>]" so the reverse direction of the chain is visible.
-     - SP-13 violation (both `internal-tooling: true` AND `enables` non-empty) → flag explicitly as an error.
-   - 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

@@ -1,185 +0,0 @@
----
-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: true` UNLESS `enables` non-empty). 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` (Category A — engineering-only) UNLESS `enables` non-empty (Category B — foundational prerequisite; user value lives in the named downstream change-spec). SP-13: `internal-tooling: true` and `enables` non-empty are mutually exclusive; if both are set, halt with an SP-13 violation message and direct the engineer to `spec-author` to pick one.
-- 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.