kracked-core 1.1.0 → 1.4.0

package/templates/project/sdd/epics/_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Epic <N> — <name>
+
+**Spec:** `../specs/<name>.md`
+**Status:** planning | in-progress | done
+**Date:** {{DATE}}
+
+## Goal
+
+What is true when this whole epic is finished? One or two sentences.
+
+## Stories
+
+Every story must be **independently shippable** — mergeable on its own, leaving the app working.
+If a story can't ship alone, split it.
+
+| ID | Story | File |
+|---|---|---|
+| <N>.1 | | `../stories/<N>.1-<slug>.md` |
+| <N>.2 | | `../stories/<N>.2-<slug>.md` |
+
+Status lives in `../tracker.md`, not here. One source of truth — don't track status in two places
+or they drift.
+
+## Order
+
+Which stories block others, and why. If they're all independent, say so explicitly.
+
+1. ...
+
+## Out of scope
+
+What belongs to a future epic, not this one.
+
+- ...

package/templates/project/sdd/specs/_TEMPLATE.md

@@ -0,0 +1,44 @@
+# Spec — <name>
+
+**Status:** draft | agreed | building | shipped
+**Date:** {{DATE}}
+
+## What
+
+One paragraph. What is being built, in plain language — no implementation detail.
+
+## Why
+
+The problem this solves, and for whom. If you can't name who is worse off without it, the spec
+isn't ready.
+
+## Acceptance criteria
+
+Concrete and checkable. Someone else must be able to read these and tell whether the thing works.
+
+- [ ] A user can ...
+- [ ] When X happens, the system ...
+- [ ] If the input is empty/invalid, it ...
+
+## Out of scope
+
+**Not optional.** Scope creep starts exactly where this section is skipped. List what this spec
+deliberately does NOT cover.
+
+- ...
+
+## Edge cases
+
+For every input involved, answer: what if it's empty, missing, or unexpected?
+
+| Case | Expected behaviour |
+|---|---|
+| Empty input | |
+| Already exists | |
+| Not authorised | |
+
+## Open questions
+
+Things that must be answered before or during the build. Delete this section once it's empty.
+
+- [ ] ...

package/templates/project/sdd/stories/_TEMPLATE.md

@@ -0,0 +1,33 @@
+# Story <N>.<M> — <name>
+
+**Epic:** `../epics/<N>-<slug>.md`
+**Status:** backlog | in-progress | review | done  ← mirror this in `../tracker.md`
+**Date:** {{DATE}}
+
+## What
+
+One slice of the epic. Small enough to build and verify in one sitting.
+
+## Acceptance criteria
+
+- [ ] ...
+- [ ] ...
+
+## Notes for the build
+
+Files likely to change, existing code to reuse, anything that would trip someone up.
+
+> Verify these claims before building on them. A story written from memory can name a file,
+> function, or column that doesn't exist — grep first, then build.
+
+- ...
+
+## Evidence
+
+**Fill this in before marking `done`.** Copy the summary line into `tracker.md`.
+
+- **Verified:** what you actually ran or checked, and what you saw
+- **Not verified:** what you did NOT check — untested paths, edge cases, anything left open
+
+A story marked `done` with an empty Evidence section is worse than one left at `review`: it hides
+risk instead of surfacing it.

package/templates/skills/kracked-boot/SKILL.md

@@ -43,6 +43,7 @@ If the current directory has a `.kracked/` folder, read:
 1. `.kracked/project.md` — what this project is (stack, conventions)
 2. `.kracked/session.md` — working memory: state + next steps
 3. `.kracked/decisions.md` — why things are the way they are
+4. `.kracked/sdd/tracker.md` — story status, if this project uses SDD (skip if absent)
 
 If there is no `.kracked/` folder here, this is a project that hasn't been set up yet. Say so
 plainly and suggest `npx kracked-core init` if the user wants project memory for it. Continue

package/templates/skills/kracked-sdd/SKILL.md

@@ -27,24 +27,59 @@ Classify before doing any ceremony. Say the classification out loud in one line,
 Over-ceremony on a small task is a failure mode, not thoroughness. Do not write a spec file for a
 typo fix.
 
+## Where documents live
+
+Copy the matching `_TEMPLATE.md` in each folder rather than inventing a structure.
+
+| Folder | Holds |
+|---|---|
+| `.kracked/sdd/specs/` | What to build and why |
+| `.kracked/sdd/epics/` | A group of related stories |
+| `.kracked/sdd/stories/` | One independently shippable slice |
+| `.kracked/sdd/architecture/` | How it's put together — large/risky work only |
+| `.kracked/sdd/architecture/decisions/` | ADRs, numbered `0001-`, never renumbered |
+| `.kracked/sdd/tracker.md` | Status + evidence for every story |
+
+Naming: `specs/login.md`, `epics/1-authentication.md`, `stories/1.1-email-login.md`. Story IDs are
+`<epic>.<story>` and MUST match the ID in `tracker.md` — that link is what makes the tracker
+trustworthy.
+
 ## 2. Spec stage
 
-Write to `.kracked/sdd/specs/<short-name>.md`. Include:
+Copy `.kracked/sdd/specs/_TEMPLATE.md` to `.kracked/sdd/specs/<short-name>.md` and fill it in:
 
 - **What** — the feature or change, in plain language
 - **Why** — the problem it solves, for whom
 - **Acceptance criteria** — concrete, checkable conditions for "this works"
 - **Out of scope** — explicitly list what this spec does NOT cover. This is not optional; scope
   creep starts where this section is skipped.
+- **Edge cases** — for every input: what if it's empty, missing, or unexpected?
 
 Confirm the spec with the user before moving on, unless the request was classified trivial/small
 and the spec is short enough that building it IS the confirmation.
 
+## 2b. Architecture — only when the work is large or risky
+
+If the job is **large or risky** (new service, data model change, auth, payments, anything
+touching money or user data), write an architecture doc from
+`.kracked/sdd/architecture/_TEMPLATE.md` BEFORE building — the shape, the data model, and the
+failure modes.
+
+For a decision someone would otherwise re-litigate later (why this database, why this pattern),
+add a numbered ADR from `architecture/decisions/_TEMPLATE.md`.
+
+**Do not write either for a small feature.** Ceremony on small work is why people abandon a
+process. Say plainly which you're writing and why, or say you're skipping them and why.
+
 ## 3. Docs stage
 
 Break the spec into stories. Each story must be independently shippable — a story that can't be
 merged and left in a working state on its own is too big; split it further.
 
+If there's more than one story, write an epic from `.kracked/sdd/epics/_TEMPLATE.md` and give each
+story its own file from `.kracked/sdd/stories/_TEMPLATE.md`. A single-story job needs neither —
+the spec is enough.
+
 Add every story to `.kracked/sdd/tracker.md` with status `backlog`. Use this exact table shape —
 do not invent columns: