hstack 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to hstack are documented here. Format follows [Keep a Change
 
 _Nothing yet._
 
+## [0.5.2] - 2026-06-26
+
+### Fixed
+
+- **Greenfield-init collapsed the six-phase discovery flow into a flat questionnaire.** `template/.claude/skills/hstack-greenfield-init/SKILL.md` described the right behavior but never pinned it in imperative, agent-readable terms, so a session could answer `/hstack:greenfield-init` with a numbered config-question list ("answer #1 and #8, I'll accept defaults for #2–7, then write the config and move to Phase 1") instead of launching the product-discovery thinking-partner session. Four contract-tightening edits: (1) a new Precondition bullet forbidding inline config authoring or Phase 1 paraphrase; (2) a new **First-turn contract** section pinning the exact first-message shape (name the six phases → open Phase 1 → offer the Brainstorm / Forcing-Questions / Project-Brief technique picker) and enumerating the forbidden numbered-question shape; (3) **Phase 0 reframed** from an upfront questionnaire to inline field-sourcing deferred to the Phase 1→2 boundary, removing the "fill the config first" hook; (4) **Phase 1 made imperative** — the first non-trivial action MUST be a `Task` call launching the `product-discovery` subagent — plus two sharpened anti-patterns against the flat-question-list shape and against running Phase 1 inline. No code change; Skill-contract text only. Reported from a consumer greenfield repo where init skipped discovery entirely.
+
 ## [0.5.1] - 2026-05-23
 
 ### Fixed

package/VERSION

@@ -1 +1 @@
-0.5.1
+0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hstack",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "A spec-driven engineering workflow that ships as Claude Code Skills and subagents.",
   "keywords": [
     "claude-code",

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

@@ -62,18 +62,41 @@ Before any work:
 - 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
+### Phase 0 — Config skeleton (inline, deferred to Phase-1 boundary)
 
-Same interview as brownfield-init Mini-session 0: story store, personas store, design system (per-resource), module-to-area mapping (will be populated from app-architecture in Phase 3), adversarial-review floor, agent ledger, active MCP set. Writes `hstack/config.yaml` with `schemaVersion: 1` and `init-status: minimal-complete`. Default-stack declaration is **set to the engineer's preferences** in this phase, so Phase 4 can fast-path. Commit.
+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
 
-Invokes `/hstack:product-discovery` in elicit mode (no source documents). The atom:
+**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`.
@@ -144,7 +167,9 @@ Beyond the kernel's general stop conditions, this Skill halts when:
 ## 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 collapse the six phases into one long block. The phase structure is the resumability contract AND the gate-discipline contract.
+- **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`.