kracked-core 1.1.0 → 1.5.0

package/templates/project/sdd/README.md

@@ -0,0 +1,46 @@
+# SDD — {{PROJECT_NAME}}
+
+Spec-driven development artifacts. Run `/kracked-sdd` to work through the flow; these folders are
+where it puts things.
+
+```
+idea → spec → epic → stories → build → review
+```
+
+| Folder | Holds | Written when |
+|---|---|---|
+| `specs/` | What to build and why | Start of any non-trivial job |
+| `epics/` | A group of related stories | When a spec is too big for one story |
+| `stories/` | One independently shippable slice | Broken out of a spec or epic |
+| `architecture/` | How the system is put together | Large or risky work only |
+| `tracker.md` | Status of every story + evidence | Continuously |
+
+## Naming
+
+Numbers first so files sort in the order you built them.
+
+```
+specs/login.md
+epics/1-authentication.md
+stories/1.1-email-login.md
+stories/1.2-password-reset.md
+architecture/data-model.md
+architecture/decisions/0001-use-postgres.md
+```
+
+Story IDs are `<epic>.<story>` and must match the ID in `tracker.md`. That's the link between a
+story's detail and its status — if they drift, the tracker stops being trustworthy.
+
+## The two rules that matter
+
+**1. Not everything needs the full flow.** A typo fix needs no spec. `/kracked-sdd` sizes the job
+first and skips straight to the build when ceremony would be waste. Over-documenting small work is
+the fastest way to abandon the system entirely.
+
+**2. A story isn't `done` without evidence.** The tracker's Evidence column must say what was
+actually verified — and what wasn't. "Tests pass" is not evidence of a working feature.
+
+## Commit these
+
+These docs belong in git. They're how the next person — including you in three months, and your
+agent on its next boot — finds out why the code looks the way it does.

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

@@ -0,0 +1,51 @@
+# Architecture — <area>
+
+**Date:** {{DATE}}
+**Status:** current | superseded by `<file>`
+
+Write one of these only for work that's **large or risky** — new services, data model changes,
+auth, anything touching money or user data. A small feature does not need an architecture doc,
+and writing one anyway is how the system becomes ceremony people skip.
+
+## The shape
+
+What the pieces are and how they talk to each other. A diagram in text is fine:
+
+```
+browser → api route → service → database
+                   ↘ queue → worker
+```
+
+## Data model
+
+Tables/collections, key fields, and the relationships that matter. Not every column — the ones a
+newcomer would get wrong.
+
+| Entity | Key fields | Related to |
+|---|---|---|
+| | | |
+
+## Key decisions
+
+The choices someone would otherwise re-litigate. Link to an ADR in `decisions/` for the big ones.
+
+| Decision | Why | Alternative rejected |
+|---|---|---|
+| | | |
+
+## Failure modes
+
+What breaks, and what happens when it does. Answer for each: does it fail loudly or silently?
+
+| What fails | Effect | Handling |
+|---|---|---|
+| Database unreachable | | |
+| Third-party API down | | |
+| Duplicate/retried request | | |
+
+## What this does NOT do
+
+Scope boundaries and deliberate limitations. Prevents someone assuming a capability that isn't
+there.
+
+- ...

package/templates/project/sdd/architecture/decisions/_TEMPLATE.md

@@ -0,0 +1,40 @@
+# <NNNN> — <the decision, as a statement>
+
+**Date:** {{DATE}}
+**Status:** accepted | superseded by `<NNNN>` | reversed
+
+> Example filename: `0001-use-postgres-not-mongo.md`
+> Number them in order. Never renumber or delete one — a reversed decision is still history worth
+> keeping, and the reasoning is often more valuable than the outcome.
+
+## Context
+
+What forced a choice here? The constraints, the pressures, what was true at the time. Someone
+reading this in six months has none of that context — this section is the whole point.
+
+## Decision
+
+What was decided, stated plainly and in the present tense. "We use X." Not "we should" or
+"we might."
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| | |
+
+## Consequences
+
+Both directions — honest about the costs.
+
+**Good:**
+- ...
+
+**Costs / things we now have to live with:**
+- ...
+
+## Revisit if
+
+The conditions that would make this decision wrong. If none, say "no expected trigger."
+
+- ...

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: