@haposoft/cafekit 0.8.6 → 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.6",
+  "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.
@@ -197,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
 

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

@@ -56,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
@@ -190,7 +215,7 @@ 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
@@ -502,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/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: