hstack 0.7.1 → 0.17.0

package/template/.claude/skills/hstack-module-spec/SKILL.md

@@ -1,105 +0,0 @@
----
-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.

package/template/.claude/skills/hstack-product-discovery/SKILL.md

@@ -1,101 +0,0 @@
----
-name: hstack-product-discovery
-description: |
-  Use this skill when the engineer wants to produce or refresh `hstack/context/product/product-brief.md` — the durable thinking artifact that captures the project's product reasoning. The Skill is Phase 1 of `/hstack:greenfield-init` (elicit mode), an optional enrichment phase of `/hstack:brownfield-init` when source docs are thin (extract mode), or a standalone atom for retroactive brief authoring. It invokes the `product-discovery` subagent in one of three engineer-chosen techniques (Brainstorm, Forcing-Questions, Project-Brief), produces a single synthesis at `hstack/context/product/product-brief.md`, and auto-routes to `product-manager` for downstream context-doc refresh. Examples:
-
-  <example>
-  Context: Phase 1 of greenfield-init opens. The engineer types `/hstack:product-discovery` directly.
-  user: "/hstack:product-discovery"
-  assistant: "Pick a technique: [1] Brainstorm — facilitated ideation; [2] Forcing-Questions — reframe-driven probing (Gstack-style); [3] Project-Brief — structured walk. Default mode is elicit (no source docs). The brief lives at hstack/context/product/product-brief.md and is parkable any time."
-  <commentary>
-  The technique choice is the engineer's, not the agent's. Each technique's script is in hstack/templates/discovery/<technique>.md. Mid-technique switching is allowed but halts to confirm — mixing technique outputs produces an incoherent brief.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A brownfield repo's brief never landed during init; /hstack:help flagged the missing artifact.
-  user: "/hstack:product-discovery --mode extract"
-  assistant: "Extract mode. I'll read existing vision.md, README, and any product docs you point me at, propose the brief sections from what I find, and walk you through confirm-or-revise. The three required forcing prompts still run — extract mode does not bypass blind-spot probes."
-  <commentary>
-  Extract+confirm mode is how brownfield enrichment works. The unification of modes is load-bearing: the brief produced is the same artifact whether elicited or extracted, so downstream phases load it identically.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
----
-
-## Purpose
-
-`hstack-product-discovery` is the atom that produces `hstack/context/product/product-brief.md` via the `product-discovery` subagent. It is the canonical authoring path for the brief; the brief never lands via a generic spec-author interview.
-
-## When to invoke
-
-- Phase 1 of `/hstack:greenfield-init` (elicit mode, no source).
-- Optional enrichment within `/hstack:brownfield-init` when existing product docs are thin and the engineer wants the deeper reframe-style brief.
-- Standalone via `/hstack:product-discovery [--mode extract|elicit] [--section <name>]` for retroactive brief authoring on any repo.
-
-## Inputs
-
-- `--mode extract | elicit` — defaults: `elicit` if no source docs are reachable; `extract` if a `product-brief.md` exists or the engineer points at source documents.
-- `--section <name>` — optional, fast-jumps to a specific section for refresh. Re-runs the end-of-atom check across all sections before commit.
-
-## Preconditions
-
-- `hstack/config.yaml` exists and `init-status` is at least `minimal-complete` — the atom does not run standalone until config exists.
-- `hstack/CLAUDE.md` and `hstack/templates/product-brief.md` are present.
-- `hstack/templates/discovery/{brainstorm,forcing-questions,project-brief}.md` are present.
-- In extract mode, at least one source document must be reachable; otherwise halt and ask the engineer to either supply source pointers or fall back to elicit mode.
-
-## Orchestration steps
-
-1. **Detect mode.** Read disk state. If `hstack/context/product/product-brief.md` exists at `status: current` and no `--section` flag, this is a refresh confirmation — print summary and exit unless engineer opts into full re-interview.
-2. **Pick technique** (elicit mode only). Prompt the engineer to choose Brainstorm / Forcing-Questions / Project-Brief. Persist the choice as `technique-used` in the brief frontmatter.
-3. **Invoke `product-discovery` subagent.** Via the Task tool with `subagent_type: product-discovery`. Pass mode, technique, optional section, and the canonical session-start context (kernel, template, technique script, source docs in extract mode).
-4. **Walk sections.** The subagent runs the chosen technique's script and walks the brief sections with confirmation gates. Each confirmed section writes to disk and auto-commits.
-5. **Run forcing prompts.** The three required reframes (Who pays? What's the wedge? What would falsify this?) fire before terminal state regardless of technique.
-6. **Auto-route at terminal state.** When the brief reaches `status: current`, the Skill prints the auto-route message (with alternative-path commands) and hands off to `product-manager` via the Task tool with `subagent_type: product-manager` to refresh `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md`. If the engineer types `skip-routing`, the Skill commits the brief and exits cleanly — downstream Skills will halt on missing context docs.
-
-## Outputs
-
-- `hstack/context/product/product-brief.md` at `status: current`.
-- `hstack/.session-state/<session-id>.yaml` (transient).
-- Via auto-route: `vision.md`, `mvp-scope.md`, `personas/*`, `glossary.md` refreshed (unless skip-routing).
-
-## Auto-commit triggers
-
-- Each confirmed section writes immediately and auto-commits.
-- Brief reaches `status: current` → final commit with the auto-route message in the body.
-- Downstream refreshes by `product-manager` each auto-commit per the product-manager subagent's contract.
-
-## Idempotency contract
-
-- Brief at `current` + no `--section` + no `--force`: print summary, exit no-op.
-- Brief at `draft` or partial: read disk + session-state, resume at next non-confirmed section.
-- Brief at `needs-refresh` (flipped by `/hstack:configure` because upstream changed): walk all sections in confirm-or-revise mode.
-
-## Stop conditions
-
-- A required source document in extract mode is unreachable.
-- Forcing-prompt answer is too vague after one re-ask. The subagent halts with `HSTACK-HALT: reason=ambiguous-spec` or `missing-context`.
-- Mid-technique switch requested.
-- Engineer signals end-of-session.
-- Downstream auto-route fails (e.g., `product-manager` cannot reach the configured personas store). The Skill surfaces the failure; the brief stays at `current`, downstream context docs stay at their prior status until the engineer resolves.
-
-## Failure modes
-
-- **Subagent unreachable.** Persist session state; retry later.
-- **Auto-route partial failure.** If `product-manager` succeeds on vision but fails on personas (e.g., Notion MCP unreachable), the partial state is on disk; re-running auto-route via `/hstack:configure personas --from-brief` recovers.
-
-## Anti-patterns
-
-- Never write to `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md` from this Skill directly. Those refreshes belong to `product-manager` via the auto-route.
-- Never bypass the three required forcing prompts, even in Project-Brief mode (the lightest touch).
-- Never silently switch techniques mid-session.
-- Never advance the brief to `current` while the Explicitly NOT section has fewer than two bullets.

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

@@ -1,145 +0,0 @@
----
-name: hstack-research
-description: |
-  Use this skill when the engineer needs grounded research across one of five modes (API lookups, competitive scans, documentation, security CVEs, AI-native best practices) and wants a transient research session committed to `hstack/research/sessions/`. The Skill orchestrates the `researcher` subagent. A `--promote <session-id>` sub-mode elevates an existing session into an ADR (routes through `hstack-adr-new`), a tech-debt item (routes through `hstack-tech-debt-new`), or a durable note under `hstack/research/promoted/` (written by the researcher directly). Examples:
-
-  <example>
-  Context: The engineer is about to introduce a new HubSpot integration and needs to confirm current rate-limit and webhook signature behavior.
-  user: "/hstack:research HubSpot CRM v3 webhook signature verification and current rate limits."
-  assistant: "I'll invoke researcher in API-lookup mode. Canonical-source bias on HubSpot's docs over secondary tutorials; recency window pinned to the last 12 months. Session lands at hstack/research/sessions/<date>-hubspot-webhooks.md."
-  <commentary>
-  Mode classification drives source bias. API-lookup mode weights vendor docs over tutorials because tutorials are the most common cause of wrong-API integrations. Sessions are transient artifacts; the engineer chooses whether to promote.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A research session reached a decision point; the engineer wants to promote it to an ADR.
-  user: "/hstack:research --promote 2026-05-orchestration-patterns"
-  assistant: "I'll route through /hstack:adr-new with --from-research 2026-05-orchestration-patterns. spec-author will receive the session findings as the Context section seed and walk the remaining Nygard sections via interview."
-  <commentary>
-  Promotion routing preserves the conversational interview pattern. The researcher does not write ADRs or tech-debt directly; it hands off via the appropriate Skill so the templates' challenge prompts are exercised.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - WebSearch
-  - WebFetch
-  - "{{TODO-MCP: Notion MCP — optional; useful when research must include prior team decisions in Notion}}"
-  - "{{TODO-MCP: GitHub MCP — optional; useful for searching issues and PRs on third-party SDK repos}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates research session frontmatter}}"
-  - "{{TODO-SCRIPT: hstack/scripts/garbage-collect-research.sh — clears sessions past their garbage-collect-after date; promoted sessions exempt}}"
----
-
-## Purpose
-
-`hstack-research` produces grounded research outputs via the `researcher` subagent and routes explicit promotion to durable artifacts. The Skill has two modes:
-
-- **Default mode.** Invoke the researcher with a query; classify into one of five modes; write a transient session artifact under `hstack/research/sessions/` with sources, confidence markers, and proposed promotion targets.
-- **`--promote <session-id>` mode.** Elevate an existing session to a durable artifact: ADR (route through `hstack-adr-new`), tech-debt (route through `hstack-tech-debt-new`), or a durable note under `hstack/research/promoted/` (the researcher writes this directly).
-
-## When to invoke
-
-Invoke when the engineer wants to ground a decision or implementation choice in current external information rather than speculation. Common triggers: third-party API integration choices, competitive scans before an ADR, security-CVE checks against pinned dependencies, AI-native pattern lookups (prompt-caching, retrieval, orchestration).
-
-## Inputs
-
-Default mode:
-- `<query>` (required, positional): the research question, in natural language. The Skill does not require a pre-classified mode — the researcher classifies during the session.
-
-Promote mode:
-- `--promote <session-id>` (required): the session to elevate.
-- `--target adr | tech-debt | note` (optional): the promotion target. When omitted, the Skill asks the engineer based on the session's proposed promotion targets.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists at `init-status: complete`.
-- Default mode: verify `hstack/research/sessions/` exists; create if absent.
-- Promote mode: verify the named session exists at `hstack/research/sessions/<session-id>.md` and is at `status: current`. Verify the session is not already promoted.
-
-## Orchestration steps
-
-### Default mode
-
-1. **Invoke `researcher`.** Use the Task tool with `subagent_type: researcher` and context = [kernel, query, mode-relevant context docs per the researcher's contract — tech-stack for API/documentation modes, vision/mvp-scope for competitive/AI-native modes, threat-model/hardening-checklist for security-CVE mode]. The subagent classifies the query, applies the mode's source bias, and writes findings incrementally.
-
-2. **Source discipline.** Per the `researcher` contract:
-   - API-lookup: canonical vendor docs over tutorials; 12-month recency window.
-   - Competitive-scan: engineering-side sources over marketing pages; vendors named explicitly.
-   - Documentation: canonical sources only; contradictions surfaced rather than papered.
-   - Security-CVE: CVE databases and vendor advisories; recency window open; cross-checked against `tech-stack.md` pins.
-   - AI-native best practices: 6-month recency bias; engineering blogs and tooling repos over vendor marketing.
-   Every source is named with URL and access timestamp. Single-source claims marked explicitly.
-
-3. **Confidence markers.** Each finding lands with `high | medium | low` confidence per the researcher's contract.
-
-4. **Proposed promotion targets.** The session artifact closes with a Promotion Targets section: "Promote to ADR / tech-debt / research-note? Engineer decides." The Skill does not promote unilaterally.
-
-5. **Session artifact frontmatter.** Includes `garbage-collect-after: <today + 30 days>` per the architecture's retention rule. Promoted sessions are exempt; the `--promote` operation sets a flag that the garbage-collector honors.
-
-### Promote mode
-
-1. **Read the session.** Surface the proposed promotion targets to the engineer.
-
-2. **Route by `--target` value:**
-   - `--target adr`: invoke `hstack-adr-new` with `--from-research <session-id>` and a slug supplied by the engineer. The ADR's Context section is seeded from the session findings; `spec-author` walks the remaining Nygard sections via its conversational interview, exercising the Consequences challenge prompt.
-   - `--target tech-debt`: invoke `hstack-tech-debt-new` with the engineer-supplied slug and any `--origin <change-spec-id>` when applicable. `spec-author` walks the six tech-debt sections.
-   - `--target note`: the `researcher` writes a durable note at `hstack/research/promoted/<topic>.md` directly. Free-form structure; no template constraint. This is the only target where the researcher writes the promoted artifact directly — the kernel's promotion-routing rule explicitly permits this for free-form notes.
-
-3. **Mark the session as promoted.** Update the session's frontmatter with `promoted-to: adr:<ADR-NNNN>` (or `tech-debt:<TD-NNNN>` or `note:<path>`). Exempt from garbage collection.
-
-## Outputs
-
-Default mode:
-- `hstack/research/sessions/<YYYY-MM-DD>-<topic-slug>.md` at `status: current`, with query, classified mode(s), sources, findings, options, and proposed promotion targets.
-
-Promote mode (depending on `--target`):
-- A new ADR at `hstack/adr/ADR-NNNN-<slug>.md` (via `hstack-adr-new`).
-- A new tech-debt item at `hstack/tech-debt/TD-NNNN-<slug>.md` (via `hstack-tech-debt-new`).
-- A new durable note at `hstack/research/promoted/<topic>.md` (written by the researcher).
-- An edit to the source session marking it `promoted-to: ...`.
-
-## Auto-commit triggers
-
-- Default mode: one commit when the session artifact lands. Commit message: `research(<topic>): drafted`.
-- Promote mode: the destination Skill's auto-commit fires (ADR or tech-debt). For `--target note`, one commit when the note lands plus the session's `promoted-to` edit.
-
-## Idempotency contract
-
-- Default mode: re-running with an identical query produces a new session file with today's date in the filename — research is recency-sensitive and re-running is intentional. The engineer may delete the prior session manually, or let the garbage collector handle it after 30 days.
-- Promote mode: re-running on an already-promoted session is a no-op; the Skill detects the `promoted-to` field and exits.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- Query is too vague to classify into a mode. Ask for clarification.
-- A load-bearing context document is unreachable.
-- Sources are contradictory and the resolution requires a human call.
-- Promote mode: target is unspecified and the engineer has not chosen.
-- Promote mode: the named session does not exist or is already promoted.
-- Promote mode with `--target adr` or `--target tech-debt`: the routed Skill halts; surface the halt message.
-
-## Failure modes
-
-- **WebSearch / WebFetch rate-limited or unavailable.** Surface the limitation; the researcher proceeds with cached or partial results, naming confidence as `low` for affected findings.
-- **A vendor's docs have moved and the canonical URL no longer resolves.** Note the broken canonical source explicitly; do not silently switch to a tutorial.
-- **Promote-to-ADR or promote-to-tech-debt halts inside `spec-author`'s interview.** The session's `promoted-to` field is not written until the destination artifact is at terminal state. Resume by re-running the destination Skill directly.
-
-## Anti-patterns
-
-- Never paraphrase vendor marketing as fact.
-- Never assign `high` confidence to a single-source claim.
-- Never invent a CVE id or a version number.
-- Never advocate for an option beyond what the evidence supports — present options with pros / cons / source-backing; the engineer decides.
-- Never promote unilaterally. Promotion is engineer-driven via the explicit flag.
-- Never write ADRs or tech-debt items directly from this Skill. Route via `hstack-adr-new` / `hstack-tech-debt-new`. The exception is `--target note`, which the researcher writes directly because durable notes are free-form.
-- Never silently drop a contradiction between sources.
-- Never load implementer transcripts or per-change artifacts for context bleed; research is upstream of implementation.

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

@@ -1,140 +0,0 @@
----
-name: hstack-scaffold
-description: |
-  Use this skill as Phase 6 of `/hstack:greenfield-init` to bootstrap the consuming repository from empty to bootable. The Skill generates a **bootstrap change-spec** from `hstack/templates/bootstrap.md` (a change-spec variant with `area: bootstrap`, `surfaces: [infra]`), enumerates `in-scope` explicitly from the upstream artifacts (Module Map from app-architecture, Migration Sketches from data-architecture, stack ADRs from Phase 4), runs `data-review` and `security-review` in `--mode foundational` against the proposed posture, then drives the implementer through the planner's phased execution to produce the actual source files, migrations, CI config, and module shells. This is the only Skill (besides `/hstack:greenfield-init` which composes it) that ends with executable code landing in the consuming repo as part of init. Examples:
-
-  <example>
-  Context: Phases 1–5 of greenfield-init are complete; all context artifacts and stack ADRs are at terminal status.
-  user: "/hstack:scaffold"
-  assistant: "Generating bootstrap change-spec at hstack/specs/changes/<YYYY-MM>-bootstrap/spec.md. in-scope enumerated from app-architecture Section 1 (module shells) + data-architecture Section 5 (migration files) + standard infra files (package.json, tsconfig, CI workflow). Running foundational-mode security-review and data-review against the proposed posture. Then planner phases → implementer phase-by-phase → verifier. At terminal state the repo is bootable; build and test commands exit 0."
-  <commentary>
-  Scaffold's distinct property: it scores against a proposed posture (no diff yet) using --mode foundational on security-reviewer and data-specialist. After the bootstrap ships, those reviewers go back to per-change diff-scoring mode.
-  </commentary>
-  </example>
-
-  <example>
-  Context: Scaffold was started two days ago; phase-3 (module shells) landed but phase-4 (CI workflow) hit a verifier failure.
-  user: "/hstack:scaffold"
-  assistant: "Resuming the bootstrap change-spec. plan.md shows phase-3 complete; phase-4 had verifier discrepancies. Re-running /hstack:verify on phase-4 outputs to identify what failed; then either re-implementing phase-4 (if the implementer's output was incorrect) or revising the plan (if the expectation was wrong)."
-  <commentary>
-  Scaffold inherits the standard per-change idempotency contract because bootstrap IS a change-spec. The planner and implementer's existing resume semantics apply unchanged.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SKILL: /hstack:change-new — scaffolds the bootstrap change-spec folder}}"
-  - "{{TODO-SKILL: /hstack:test-plan — produces test-plan.md for the bootstrap}}"
-  - "{{TODO-SKILL: /hstack:security-review — invoked in --mode foundational}}"
-  - "{{TODO-SKILL: /hstack:data-review — invoked in --mode foundational}}"
-  - "{{TODO-SKILL: /hstack:change-plan — invokes planner}}"
-  - "{{TODO-SKILL: /hstack:implement — invokes implementer phase-by-phase}}"
-  - "{{TODO-SKILL: /hstack:verify — invokes verifier after the last implement phase}}"
-  - "{{TODO-SKILL: /hstack:adversarial-review — runs in a fresh session for the bootstrap}}"
-  - "{{TODO-SKILL: /hstack:ship — final scorecard; bootstrap ships with a PR like any change}}"
-  - "{{TODO-SKILL: /hstack:finalize — post-merge cleanup}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
----
-
-## Purpose
-
-`hstack-scaffold` is the Phase 6 execution Skill of `/hstack:greenfield-init`. It bridges discovery to working code: the upstream phases (product-brief, data-architecture, app-architecture, stack ADRs, threat-model, hardening-checklist, infrastructure, incident-runbook) declare the design; this Skill executes it. The execution path is the **standard per-change workflow** applied to a one-off change-spec with `area: bootstrap` — there is no special-cased "bootstrap workflow"; the kernel's per-change discipline applies in full, with two adjustments: (a) `security-review` and `data-review` run in `--mode foundational` (score against proposed posture, not diff), and (b) the change-spec uses the `hstack/templates/bootstrap.md` variant.
-
-## When to invoke
-
-- Phase 6 of `/hstack:greenfield-init` (the orchestrator calls this Skill after Phase 5 terminates).
-- Standalone is **not** supported in v1 — scaffold runs once per project lifetime and assumes the full upstream discovery layer is at terminal status. Standalone invocation halts with a directive to run `/hstack:greenfield-init` instead.
-
-## Inputs
-
-- No positional arguments. The Skill reads upstream artifacts and the bootstrap-change-spec scaffolding from disk.
-
-## Preconditions
-
-- All of the following at `status: current`:
-  - `hstack/context/product/product-brief.md`
-  - `hstack/context/data-architecture.md`
-  - `hstack/context/app-architecture.md`
-  - `hstack/context/threat-model.md`, `hardening-checklist.md`, `infrastructure.md`, `incident-runbook.md`
-  - `hstack/context/tech-stack.md`, `ci-cd.md`
-- Stack ADRs from Phase 4 at `status: accepted`.
-- `hstack/templates/bootstrap.md` present.
-- The consuming repo has no source code beyond `hstack/` and standard hidden files. If non-empty, halt — scaffold is a greenfield-only operation.
-
-## Orchestration steps
-
-1. **Generate the bootstrap change-spec.** Invoke `/hstack:change-new` with `area: bootstrap` and a derived id (`<YYYY-MM>-bootstrap`). The change-spec folder is scaffolded with `spec.md` pre-populated from `hstack/templates/bootstrap.md`. The Skill then performs mechanical writes to populate:
-   - `in-scope`: enumerated from app-architecture Module Map (one entry per module directory) + data-architecture Migration Sketches (one entry per `m_NNNN_*.sql`) + standard infra files (`package.json`, `tsconfig.json`, build config, CI workflow path, etc.). The enumeration is explicit; `["."]` is not permitted.
-   - `related-adrs`: the full list of Phase 4 stack ADRs.
-   - `threat-model-delta: true`.
-   The change-spec lands at `status: draft` after this step; `spec-author` walks it to `ready-to-plan` via a confirmation interview (the engineer reviews the enumerated `in-scope` and confirms or revises).
-
-2. **Test plan.** Invoke `/hstack:test-plan` for the bootstrap. The test-strategist produces `test-plan.md` covering build / lint / typecheck / migration / RLS-enforcement smoke tests. Bootstrap test plans bias toward operational-correctness assertions (build exits 0, migrations apply cleanly, RLS denies cross-tenant access) rather than feature behavior.
-
-3. **Foundational-mode security-review.** Invoke `/hstack:security-review` with the security-reviewer in `--mode foundational`. The reviewer scores against the proposed posture (threat-model + hardening-checklist + the stack ADRs) rather than against a diff. Output: `security-review.md` at `status: passed` or `concerns-noted` per the standard contract.
-
-4. **Foundational-mode data-review.** Invoke `/hstack:data-review` with the data-specialist in `--mode foundational`. The reviewer scores the migration sketches from data-architecture Section 5 against RLS coverage rules (DR-02) and tenant-isolation rules (DR-03), scoring proposed-DDL rather than live schema. Output: `data-review.md` at `status: passed` or `concerns-noted`.
-
-5. **Plan.** Invoke `/hstack:change-plan`. The planner produces `plan.md` with atomic phases. A typical bootstrap plan sequence:
-   - Phase 1: install dependencies (`npm install` / `pnpm install` / equivalent).
-   - Phase 2: initialize framework scaffold (e.g., Next.js boilerplate, tsconfig, eslint config).
-   - Phase 3: land migration files in `supabase/migrations/` per data-architecture Section 5.
-   - Phase 4: scaffold module shells per app-architecture Section 1 (one directory per module with index.ts plus any per-module config).
-   - Phase 5: wire CI workflow per `ci-cd.md`.
-   - Phase 6: smoke tests (build, lint, typecheck, run RLS-denial test).
-   Each phase declares its verifier expectations explicitly.
-
-6. **Implement.** Invoke `/hstack:implement <bootstrap-id> <phase-id>` once per plan phase. Each invocation runs the implementer scope-locked to the `in-scope` enumeration. The implementer creates files (no edits — bootstrap is greenfield) and auto-commits at phase completion.
-
-7. **Verify.** Invoke `/hstack:verify` after the last implement phase. The verifier runs the canonical commands from `ci-cd.md` and compares against per-phase Verifier Expectations.
-
-8. **Adversarial review.** Direct the engineer to open a fresh Claude Code session and run `/hstack:adversarial-review`. Bootstrap inherits the standard fresh-session contract (kernel rule).
-
-9. **Ship + finalize.** After adversarial review reaches `findings-resolved`, `/hstack:ship` produces the PR description. The engineer opens the PR, gets it merged, then runs `/hstack:finalize` to advance the bootstrap change-spec from `ready-to-ship` to `shipped` (no tech-debt resolution applies for bootstrap). `hstack/config.yaml`'s `init-status` flips to `complete` in the same finalize commit.
-
-## Outputs
-
-- A complete bootstrap change-spec folder at `hstack/specs/changes/<YYYY-MM>-bootstrap/` with `spec.md`, `test-plan.md`, `security-review.md`, `data-review.md`, `plan.md`, `verification.md`, `adversarial-review.md`, `pr-body.md`.
-- The consuming repo's actual source files, migrations, CI workflow, build config, and per-module shells.
-- `hstack/config.yaml` at `init-status: complete`.
-
-## Auto-commit triggers
-
-- Bootstrap change-spec advances through standard status transitions (`draft → ready-to-plan → ready-for-implementation → ready-for-review → ready-to-ship → shipped`); each transition auto-commits per the kernel.
-- Each plan phase auto-commits when implementer completes it.
-- `hstack/config.yaml` flips to `init-status: complete` in the finalize commit alongside the change-spec's advance to `shipped`.
-
-## Idempotency contract
-
-Scaffold inherits the standard per-change idempotency contract because bootstrap IS a change-spec:
-
-- Re-running `/hstack:scaffold` reads the bootstrap change-spec's status and resumes at the next non-terminal artifact.
-- Plan phases that have committed are skipped; only the first incomplete phase runs.
-- A failed verifier produces `verification.md` at `status: failed-with-discrepancies`; re-running `/hstack:scaffold` does NOT silently retry — it surfaces the discrepancies and waits for the engineer to either re-implement the failing phase or revise the plan.
-
-## Stop conditions
-
-- Any upstream artifact at non-terminal status.
-- The consuming repo is non-empty at scaffold start.
-- Foundational-mode security-review or data-review lands at `concerns-noted` with unresolved CONCERNS. The engineer either resolves the concerns (revises threat-model / hardening / migration sketches) or accepts them via the standard concerns-acknowledgement path.
-- Implementer halts mid-phase (file already exists outside in-scope, verifier expectation unsatisfiable, etc.). Standard implementer halt semantics apply.
-- The engineer signals end-of-session — the standard per-change idempotency picks up on resume.
-
-## Failure modes
-
-- **Foundational-mode reviewer halts.** Foundational mode is honor-system in v1 — the reviewer is asked to score a proposed posture, not a diff. If the reviewer cannot honestly score (e.g., the threat-model is too thin), the reviewer halts with `HSTACK-HALT: reason=upstream-non-terminal` and routes the engineer back to `/hstack:configure threat-model`.
-- **Implementer scope-lock fires on a path NOT in the enumerated in-scope.** This is a scaffold-spec gap, not an implementer bug. The Skill halts; the engineer revises `in-scope` (mechanical edit by the engineer per the kernel's scope-amendment path) and re-runs `/hstack:implement` for the affected phase.
-- **CI runs from `ci-cd.md` haven't been authored yet for fresh projects.** The bootstrap change-spec's test-plan must define the canonical commands; otherwise verifier has nothing to run. The Skill checks this at preconditions.
-
-## Anti-patterns
-
-- Never run scaffold against a non-empty repo. Scaffold is greenfield-only; mixing modes produces incoherent in-scope enumeration.
-- Never set `in-scope: ["."]`. Explicit file enumeration is the contract; the implementer's scope-lock does meaningful work only against an explicit list.
-- Never skip foundational-mode security-review / data-review to "save time." Those gates are the v1 substrate for getting hardening and RLS posture right from line zero.
-- Never bypass adversarial-review for the bootstrap. Bootstrap inherits the fresh-session contract from the kernel; ship without it is forbidden.
-- Never flip `init-status: complete` while the bootstrap change-spec is below `shipped`.