@haposoft/cafekit 0.8.5 → 0.8.7

package/bin/install.js

@@ -424,8 +424,15 @@ function copyPlatformFiles(platformKey, results, options = {}) {
 
     // Keep templates in sync for claude command runtime copies under .claude/skills/specs
     if (platformKey === 'claude') {
+      const legacyInitTemplate = path.join(platform.skillsDir, 'specs', 'templates', 'init.json');
+      if (fs.existsSync(legacyInitTemplate)) {
+        fs.rmSync(legacyInitTemplate, { force: true });
+        console.log(`  ↻ Removed legacy template: ${legacyInitTemplate}`);
+        results.updated++;
+      }
+
       const specTemplates = [
-        'init.json',
+        'spec-state.json',
         'requirements-init.md',
         'requirements.md',
         'design.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/agents/spec-maker.md

@@ -15,6 +15,23 @@ You DO NOT write implementation code. You produce Specifications that downstream
 
 **Before ANY action**, you MUST read `.claude/skills/specs/SKILL.md` and follow it step-by-step. `SKILL.md` is the authoritative workflow. This agent file provides behavioral guidance; `SKILL.md` provides the execution protocol.
 
+## Artifact Contract (MANDATORY)
+
+Generate only the CafeKit spec artifacts defined by `hapo:specs`:
+
+```
+specs/<feature>/
+├── spec.json
+├── requirements.md
+├── research.md
+├── design.md
+└── tasks/task-R{N}-{SEQ}-<slug>.md
+```
+
+- `spec.json` is generated from `.claude/skills/specs/templates/spec-state.json`; never write `init.json` or `spec-state.json` into the spec directory.
+- Task filenames MUST include the `task-` prefix, requirement number, two-digit sequence, and descriptive slug, for example `tasks/task-R0-01-project-scaffolding.md`.
+- Do NOT write `hydration.md`; task hydration is session/task-state synchronization only.
+
 ## Mental Models (How You Think)
 
 - **Decomposition:** Break epics into concrete, testable tasks.
@@ -41,6 +58,8 @@ Init → Requirements → Design → Tasks
 ### Auto-Approval Behavior
 - When running the full pipeline end-to-end, follow the auto-approval rules defined in `SKILL.md`.
 - When running a single phase, stop and report status after completion.
+- Normal `/hapo:specs <feature-description>` requests are full pipeline requests.
+- If a pause is required after user review, tell the user to continue with `/hapo:specs resume <feature>` or `/hapo:specs <feature>`.
 
 ## Scope Lock Protocol (MANDATORY)
 
@@ -195,7 +214,7 @@ specs/<feature>/
 
 - Output format follows `hapo:specs` protocol (see `skills/specs/SKILL.md`)
 - Task files follow `skills/specs/templates/task.md` template
-- `spec.json` follows `skills/specs/templates/init.json` schema
+- `spec.json` follows the `skills/specs/templates/spec-state.json` schema; the generated file must still be named `spec.json`
 - Research output follows `skills/specs/templates/research.md` template
 - Requirements follow EARS format per `skills/specs/rules/ears-format.md`
 - Design follows principles per `skills/specs/rules/design-principles.md`

package/src/claude/archive-command/spec-init.md

@@ -69,7 +69,7 @@ Generate a unique feature name from the project description ($ARGUMENTS) and ini
 1. **Check Uniqueness**: Verify `.specs/` for naming conflicts (append number suffix if needed)
 2. **Create Directory**: `.specs/[feature-name]/`
 3. **Initialize Files Using Templates**:
-   - Read `{{SKILLS_DIR}}/specs/templates/init.json`
+   - Read `{{SKILLS_DIR}}/specs/templates/spec-state.json`
    - Read `{{SKILLS_DIR}}/specs/templates/requirements-init.md`
    - Replace placeholders:
      - `{{FEATURE_NAME}}` → generated feature name
@@ -92,7 +92,7 @@ Generate a unique feature name from the project description ($ARGUMENTS) and ini
 
 ## Tool Guidance
 - Use **Glob** to check existing spec directories for name uniqueness
-- Use **Read** to fetch templates: `init.json` and `requirements-init.md`
+- Use **Read** to fetch templates: `spec-state.json` and `requirements-init.md`
 - Use **Write** to create spec.json and requirements.md after placeholder replacement
 - Perform validation before any file write operation
 
@@ -102,8 +102,10 @@ Provide output in the language specified in `spec.json` with the following struc
 1. **Generated Feature Name**: `feature-name` format with 1-2 sentence rationale
 2. **Project Summary**: Brief summary (1 sentence)
 3. **Created Files**: Bullet list with full paths
-4. **Next Step**: Command block showing `/spec-requirements <feature-name>`
-5. **Notes**: Explain why only initialization was performed (2-3 sentences on phase separation)
+4. **Next Step**: Command block showing `/hapo:specs resume <feature-name>`
+5. **Notes**: Explain this legacy init command only initialized files. Recommend using `/hapo:specs <feature-description>` for the normal end-to-end CafeKit flow.
+
+**Command integrity:** CafeKit continuation uses `/hapo:specs resume <feature-name>`.
 
 **Format Requirements**:
 - Use Markdown headings (##, ###)

package/src/claude/skills/specs/SKILL.md

@@ -34,6 +34,7 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate
 - Each phase (Init → Requirements → Design → Tasks) must complete before the next begins
 - No skipping — don't write design without requirements
 - Exception: simple tasks may merge requirements + design into one step
+- A normal `/hapo:specs <feature-description>` run is an end-to-end spec creation workflow. Do not stop after Init unless the user explicitly asks for init-only behavior.
 
 ### Scope Rules
 - Respect `scope_lock` absolutely once user has confirmed
@@ -55,6 +56,31 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate
 - Insert code samples/pseudocode when needed to clarify flow
 - Comply with `./docs/development-rules.md` if it exists
 
+### Hard Output Contract
+For a normal `/hapo:specs <feature-description>` run, the persistent spec artifacts MUST use this shape:
+
+```
+specs/<feature>/
+├── spec.json
+├── requirements.md
+├── research.md
+├── design.md
+├── tasks/
+│   ├── task-R0-01-<slug>.md
+│   ├── task-R1-01-<slug>.md
+│   └── ...
+└── reports/
+    └── <optional-review-or-research-report>.md
+```
+
+Forbidden generated artifacts:
+- Do NOT create `specs/<feature>/init.json`.
+- Do NOT create `specs/<feature>/spec-state.json`.
+- Do NOT create `specs/<feature>/hydration.md`.
+- Do NOT create shorthand task files such as `tasks/task-R0-1.md`, `tasks/task-R1-1.md`, or `tasks/R0-1-<slug>.md`.
+- The template file name is never the output file name. `templates/spec-state.json` is only the schema source for generated `spec.json`.
+- Task hydration is session/task-state synchronization only; it MUST NOT be written as a markdown artifact.
+
 ### Writing Style
 - Concise, prefer bullet lists
 - Get straight to the point, no fluff
@@ -91,6 +117,8 @@ System auto-analyzes the description:
 - If task is simple (small bugfix, config change) → suggest "A spec may not be needed for this. Continue anyway?"
 - If task is complex (multi-module, security/migration related) → auto-activate deep research, ask user 3 scope questions
 - For non-trivial specs, execute the Step 5 Evidence Gate before writing final requirements. Do not design from memory when codebase or current external evidence can answer the question.
+- After user confirms scope, continue through Init → Evidence/Requirements → Design → Tasks → Finalization in the same workflow unless the user explicitly asks for "init only" or "pause after init".
+- If the workflow must pause for manual approval, the continuation command is `/hapo:specs resume <feature>` or `/hapo:specs <feature>`.
 
 ### When called WITH `--validate` argument
 
@@ -187,14 +215,14 @@ Load: `references/scope-inquiry.md`
 ### Step 4: Init
 - Check for duplicate slugs in `specs/` via Glob
 - Create directory `specs/<feature-name>/`
-- Create `spec.json` from template `templates/init.json`
+- Create `spec.json` from template `templates/spec-state.json`. The output file name MUST be `spec.json`; never write the template filename into the spec directory.
 - Create empty `requirements.md` from template `templates/requirements-init.md`
 - Initialize `scope_lock` in `spec.json`:
   - `source`: original description
   - `in_scope`: confirmed scope items
   - `out_of_scope`: excluded items
   - `expansion_policy`: `requires-user-approval`
-- Do NOT generate requirements, design, or tasks at this step
+- Step 4 itself only initializes files. In a normal `/hapo:specs <feature-description>` run, immediately continue to Step 5 after Init. Stop here only when the user explicitly requested init-only behavior.
 
 ### Step 5: Evidence Gate, Requirements & Research
 - Read `spec.json` — stop if init hasn't completed
@@ -499,7 +527,7 @@ Before finalizing any specification, assert all the following:
 ## Resources
 
 ### Templates (`templates/`)
-- `init.json` — Metadata schema for spec.json
+- `spec-state.json` — Metadata/state schema used to create `spec.json`
 - `requirements-init.md` — Empty requirements template
 - `requirements.md` — Full requirements template
 - `design.md` — Design document template

package/src/claude/skills/specs/references/review.md

@@ -43,7 +43,7 @@ These rules override any self-reasoning or optimization the system may attempt:
 5. **No false completion.** You MUST NOT set `validation.status = "completed"` or `ready_for_implementation = true` until a reconciliation audit proves the accepted findings and validation decisions are reflected in the physical spec artifacts.
 6. **Provider drift is a real defect.** If the scope changed away from Claude/Anthropic, stale strings like `Claude API`, `Haiku`, or `haiku_reachable` in `requirements.md`, `design.md`, or `tasks/*.md` are validation failures. `research.md` may mention them only as historical comparison.
 7. **Implementation-facing propagation is mandatory.** A decision that affects implementation is NOT considered applied if it only appears in `Risk Assessment`, `validate-log.md`, or `red-team-report.md`. It must update at least one of: `requirements.md`, `Canonical Contracts & Invariants`, `Objective`, `Constraints`, `Implementation Steps`, `Completion Criteria`, or `Task Test Plan & Verification Evidence`.
-8. **CafeKit command dialect only.** Validation output MUST use `/hapo:develop <feature>` as the implementation handoff. Never mention `/sdd:execute-spec`, `/sdd:*`, `/work`, `/code`, or non-CafeKit aliases.
+8. **CafeKit command dialect only.** Validation output MUST use `/hapo:develop <feature>` as the implementation handoff.
 9. **CafeKit task filename convention only.** Task files MUST use `tasks/task-R{N}-{SEQ}-<slug>.md` with two-digit `SEQ` (for example `tasks/task-R0-01-project-scaffolding.md`). Files like `tasks/R0-1-project-scaffolding.md` are legacy/foreign format; rename them and update `spec.json.task_files`, `spec.json.task_registry`, and dependency references before passing validation.
 
 ---
@@ -231,7 +231,6 @@ Before declaring validation complete:
    - stale provider strings remain after a provider change
    - delete-data/privacy artifacts mix multiple canonical policies
    - any task path fails the CafeKit `tasks/task-R{N}-{SEQ}-<slug>.md` naming convention
-   - any output or report suggests `/sdd:execute-spec`, `/sdd:*`, `/work`, `/code`, or any non-CafeKit implementation command
    - `spec.json.updated_at`, `timestamps.review_done`, or `timestamps.validation_done` do not reflect the final reviewed state
 4. Only after the audit passes may you:
    - set `spec.json.validation.status = "completed"`

package/src/claude/skills/sync/references/sync-protocols.md

@@ -6,7 +6,7 @@ The following guidelines dictate exactly how `hapo:sync` should interact with fi
 
 ## 1. Updating `spec.json`
 
-When requested to update a phase or change task configuration, `spec.json` must maintain its strict schema (defined in `hapo:specs/templates/init.json`).
+When requested to update a phase or change task configuration, `spec.json` must maintain its strict schema (defined in `hapo:specs/templates/spec-state.json`).
 
 *   **JSON Modification Rule:** Do not output whole files. Instead, load the JSON structure, apply the update to `status`, `current_phase`, `blocker` (if any), `task_files`, and the relevant `task_registry` entry, then overwrite the file cleanly.
 *   **Task Registry Rule:** Resolve the incoming task reference to a single relative path in `task_registry`. Accept either: