@davidbalzan/groundwork 0.3.1

package/payload/skills/add-data-layer/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: add-data-layer
+description: Add an optional Drizzle ORM + PostgreSQL data layer to a Groundwork project
+argument-hint: "[postgres|mysql|sqlite] (default: postgres)"
+---
+
+# Add Data Layer - Optional Persistence Module
+
+The Groundwork starter is intentionally **database-agnostic** — no ORM or DB is wired in.
+Run this only when a feature actually needs to store something (a foundation phase rarely
+does). It adds a type-safe Drizzle data layer and records the choice as an ADR. When
+updating docs, preserve frontmatter and use `[[wikilinks]]`.
+
+## Default Recipe: Drizzle + PostgreSQL
+
+### Stage 1: Confirm the choice
+
+Ask only if ambiguous:
+- **Engine?** PostgreSQL (default), MySQL, or SQLite.
+- **Driver?** Postgres → `postgres` (postgres.js). MySQL → `mysql2`. SQLite → `better-sqlite3`.
+
+### Stage 2: Install dependencies
+
+```bash
+pnpm --filter @<scope>/api add drizzle-orm postgres
+pnpm --filter @<scope>/api add -D drizzle-kit
+```
+
+(MySQL: swap `postgres` → `mysql2`. SQLite: `better-sqlite3`.)
+
+### Stage 3: Files to create (apps/api)
+
+```
+apps/api/
+├── drizzle.config.ts          # drizzle-kit config (schema path, out dir, dialect, dbCredentials)
+├── src/db/
+│   ├── client.ts              # drizzle(postgres(env.DATABASE_URL)) singleton
+│   ├── schema.ts              # table definitions (pgTable/...) — start small
+│   └── index.ts               # re-export client + schema
+└── migrations/                # generated SQL (drizzle-kit generate)
+```
+
+`src/db/client.ts` (Postgres):
+
+```ts
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import { env } from "../env";
+import * as schema from "./schema";
+
+const client = postgres(env.DATABASE_URL, { max: 10 });
+export const db = drizzle(client, { schema });
+```
+
+`drizzle.config.ts`:
+
+```ts
+import { defineConfig } from "drizzle-kit";
+export default defineConfig({
+  schema: "./src/db/schema.ts",
+  out: "./migrations",
+  dialect: "postgresql",
+  dbCredentials: { url: process.env.DATABASE_URL! },
+});
+```
+
+### Stage 4: Environment + validation
+
+Add to `apps/api/src/env.ts` (Zod schema) and `.env.example`:
+
+```
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
+```
+
+### Stage 5: docker-compose service
+
+Ensure `docker-compose.yml` has a Postgres service (most Groundwork starters already
+ship one — verify the port/credentials match `DATABASE_URL`):
+
+```yaml
+services:
+  db:
+    image: postgres:17
+    environment:
+      POSTGRES_PASSWORD: postgres
+    ports: ["5432:5432"]
+    volumes: ["pgdata:/var/lib/postgresql/data"]
+volumes: { pgdata: {} }
+```
+
+### Stage 6: Package scripts
+
+Add to `apps/api/package.json`:
+
+```json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  }
+}
+```
+
+### Stage 7: Record the decision
+
+1. `/log-decision "Use Drizzle ORM + PostgreSQL for persistence"` — capture why
+   (type-safety, migration story) and alternatives (Prisma, raw SQL, Kysely).
+2. Update `docs/STACK_MAP.md`: move Drizzle + the DB engine from the **Optional
+   modules** section into the active **Backend** table with pinned versions.
+3. Pin to **latest stable** versions (check the registry; do not copy versions from
+   memory).
+
+## Verify
+
+```bash
+docker compose up -d db
+pnpm --filter @<scope>/api db:generate
+pnpm --filter @<scope>/api db:migrate
+```
+
+Confirm the app boots and a trivial query against `db` works before closing the stream.
+
+## Notes
+
+- Keep `schema.ts` minimal at first — add tables as features need them, not upfront.
+- For MySQL use `drizzle-orm/mysql2` + `mysqlTable`; for SQLite `drizzle-orm/better-sqlite3` + `sqliteTable`, and set `dialect` accordingly.
+
+Engine requested: $ARGUMENTS

package/payload/skills/check-task/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: check-task
+description: Mark a task as complete in the phase tasks file and update progress
+argument-hint: "<task number or description>"
+---
+
+# Check Task - Progress Tracker
+
+Mark a task complete in the phase tasks file and update progress.
+
+## Fast path (preferred)
+
+If `docs/.groundwork/scripts/check-task.mjs` exists, use it — it flips the checkbox and
+recomputes progress deterministically (no hand-counting):
+
+```bash
+node docs/.groundwork/scripts/check-task.mjs "<task-id or text>"
+```
+
+It auto-detects the active phase tasks file (most open checkboxes), updates the
+`**Overall Progress**` line, and prints the new percentage. Fall back to the manual steps
+only if the script is absent or the match is ambiguous.
+
+## Manual fallback
+
+1. Find the phase tasks file (`docs/phases/phaseN/PHASEN_TASKS.md`) — current phase per
+   `docs/PRODUCTION_ROADMAP.md` (Current Status).
+2. Locate the task from `$ARGUMENTS` (number like `1.3`, description, or fuzzy match).
+3. Flip its checkbox `[ ]` → `[x]`.
+4. Update the `**Overall Progress**: X/Y tasks (Z%)` line if present.
+5. **Cascade**: if all sub-tasks of a group are done, mark the parent done; if all tasks in
+   the phase are done, suggest updating `PRODUCTION_ROADMAP.md`.
+6. Confirm which task was marked, the new percentage, and what's left in the group.
+
+Task to mark complete: $ARGUMENTS

package/payload/skills/check-versions/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: check-versions
+description: Check the project's dependencies against latest stable and flag drift
+argument-hint: "[--all | package names]"
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Check Versions - Dependency Freshness Audit
+
+Verify the project is on current, stable dependency versions and keep
+`docs/STACK_MAP.md` honest. Run this when bootstrapping a project and periodically
+afterwards — drift is silent otherwise.
+
+## Fast path (preferred)
+
+The project ships a deterministic helper that queries the npm registry:
+
+```bash
+node docs/.groundwork/scripts/check-versions.mjs        # curated stack present in package.json
+node docs/.groundwork/scripts/check-versions.mjs --all  # every dependency
+node docs/.groundwork/scripts/check-versions.mjs react vite   # specific packages
+```
+
+It prints `pinned vs latest` with a status column and exits non-zero if anything is a
+major behind. Run it and narrate the result.
+
+## Instructions
+
+1. **Run the script** above. If it is absent, read each `package.json` (root +
+   `apps/*` + `packages/*`) and check key deps with `npm view <pkg> version`.
+2. **Summarize drift** — group into:
+   - ✅ on latest stable
+   - 🟡 same major, newer minor/patch available (safe bumps)
+   - 🔴 one or more majors behind (needs a planned migration)
+3. **Reconcile with `docs/STACK_MAP.md`**:
+   - Update the `Latest stable` column and the `Last audited` date.
+   - For majors behind, add/refresh a row in the **Pending upgrades** section.
+4. **Do NOT bump inline.** Recommend each major bump as its own workstream
+   (`/update-workstreams`) on a dedicated branch with build + test verification.
+   Minor/patch bumps can be batched into one small stream.
+
+Run once right after `/kickstart` (whenever a `package.json` exists) so the first
+`STACK_MAP.md` reflects reality, and periodically after. Report the table, the drift
+summary, and the STACK_MAP edits you made (or propose); flag anything that should become an
+upgrade workstream.
+
+Packages/flags: $ARGUMENTS

package/payload/skills/create-prd/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: create-prd
+description: Define the product (problem, users, goals, scope, requirements) as a PRD. This is the FIRST step of the flow, right after install — run it before /kickstart, which scaffolds the project from this PRD.
+argument-hint: "<product name or idea>"
+---
+
+# Create PRD - Product Requirements Document Generator
+
+Generate a comprehensive PRD through a 6-stage discovery process.
+
+## This is step 1 of the flow
+
+**Run `/create-prd` first**, before `/kickstart`. The PRD is the single product-discovery
+interview (problem, users, goals, scope, functional + non-functional requirements,
+high-level phases). `/kickstart` then *consumes* it to scaffold the project docs **without
+re-asking** — running kickstart first duplicates this discovery. Only the `groundwork init`
+doc templates are needed; kickstart need not have run.
+
+**Who runs this:** the product-context holder (you, or a coordinator acting as your proxy) —
+this is a product-*definition* step, not execution. Don't delegate it to a narrow worker:
+a worker lacks the product context the interview depends on, and its answers become guesses
+baked into the spec. Workers run `/plan-phase` *tasks*; the spec is defined upstream.
+
+## Pin the vocabulary (avoid overloaded terms)
+
+Imprecise terms propagate into the schema and UI as contradictions. As you discover:
+
+- **Flag overloaded/dual-meaning terms** the moment they appear ("ADR *and* lesson",
+  "account", "user vs customer"). Pick the canonical term, or model the relationship
+  explicitly (one umbrella concept with a `kind` vs two separate concepts).
+- **Capture a `## Key Terms` section** in the PRD (one-line definitions). For anything
+  genuinely fuzzy, hand off to `/domain-model` (writes `docs/CONTEXT.md`).
+- **Run a consistency pass before finishing**: terms in the vision/value prop must match
+  those in scope, requirements, and data shapes. If the value prop says "X and Y" but
+  scope only covers X, resolve it now — don't ship the contradiction to `/kickstart`.
+  (This semantic check is yours — only you/the model can catch a contradiction.
+  `groundwork doctor` later catches the *structural* gaps: missing PRD sections, phases
+  with no tasks, orphaned links.)
+
+## Obsidian format (required)
+
+Copy `docs/templates/PRD_TEMPLATE.md` (already structured); update the frontmatter `title`
+to `"PRD: [Product Name]"` and `aliases`. Use `[[wikilinks]]` for cross-references
+(`[[TECH_STACK]]`, `[[ARCHITECTURE_GUIDE]]`, `[[DECISIONS]]`).
+
+## Instructions — 6-stage discovery
+
+### Stage 1: Problem Discovery
+Ask: what problem (concrete examples)? who experiences it (personas)? how solved today
+(workarounds/pain)? why now (business context)? → capture problem statement, affected
+segments, current alternatives, business impact.
+
+### Stage 2: Vision & Goals
+Ask: what does success look like? how measured (metrics + targets)? what are you NOT
+building? timeline/constraints? → capture vision statement, 3–5 measurable goals,
+non-goals/out-of-scope, timeline.
+
+### Stage 3: User Requirements
+Per persona: goals, pain points, technical level. Generate user stories
+(`As a [persona], I want [action] so that [benefit]`), prioritized MoSCoW
+(Must / Should / Could / Won't Have).
+
+### Stage 4: Functional Requirements
+For each Must-Have story: break into features; define testable acceptance criteria; map
+user flows; identify dependencies.
+
+### Stage 5: Non-Functional & Technical Requirements
+Ask: performance (response times, concurrency); security (auth, data protection,
+compliance); scalability (initial + growth); technology constraints (existing stack,
+skills, budget); integrations (external systems, APIs).
+
+### Stage 6: Risks & Planning
+Identify technical/business risks, dependencies, and assumptions. Produce a risk matrix
+with mitigations, a high-level phase breakdown, and key milestones.
+
+**Quality bar:** requirements must be specific and testable ("<200ms p95", not "fast");
+prioritize ruthlessly (not everything is Must-Have); capture the "why"; state non-goals.
+
+## Output
+
+Save the completed PRD (from `docs/templates/PRD_TEMPLATE.md`) to `docs/PRD.md` (or
+`docs/PRD_[ProductName].md` if specified). Review and iterate with the user.
+
+## Related Skills
+
+After the PRD, in order: `/kickstart` (scaffold docs **from this PRD**) → `/check-versions`
+→ `/plan-phase 1 [name]` → `/start-session`. (`/log-decision` whenever a technical
+decision is made.)
+
+## Product to document: $ARGUMENTS

package/payload/skills/domain-model/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: domain-model
+description: Build and sharpen the project's domain model — a ubiquitous-language glossary (and bounded-context map for larger systems). Use during system design (kickstart/plan-phase) or whenever terminology is fuzzy, conflicting, or being decided.
+argument-hint: "[term or area to model]"
+---
+
+# Domain Model - Ubiquitous Language & Bounded Contexts
+
+The *active* discipline of building the domain model as you design: challenge terms,
+invent edge-case scenarios, and write the glossary down the moment it crystallises. (Merely
+*reading* the glossary for vocabulary isn't this skill — this is for *changing* the model.)
+
+> Adapted (MIT) from Matt Pocock's `domain-modeling` skill
+> (github.com/mattpocock/skills), fitted to Groundwork's docs vault and `[[DECISIONS]]`.
+
+Outputs (created **lazily**, only when there's something to write):
+- **`docs/CONTEXT.md`** — the ubiquitous-language glossary (single context).
+- **`docs/CONTEXT-MAP.md`** — only for multiple **bounded contexts**: lists each context,
+  where it lives, and how they relate. A `CONTEXT.md` sits beside each context's code.
+
+Both start with YAML frontmatter and use `[[wikilinks]]`.
+
+**Who runs this:** the product-context holder (you, or a coordinator acting as your proxy) —
+defining the ubiquitous language is a spec decision, not execution. A narrow worker lacks the
+product context to settle term conflicts, so don't delegate the model itself; workers *consume*
+`CONTEXT.md`, they don't author it.
+
+## During a design session
+
+- **Challenge against the glossary.** If a term conflicts with `CONTEXT.md`, call it out:
+  "Your glossary defines 'cancellation' as X, but you mean Y — which is it?"
+- **Sharpen fuzzy language.** Propose a precise canonical term for vague/overloaded words.
+  "You said 'account' — Customer or User? Those differ."
+- **Stress-test with concrete scenarios** that force precision about boundaries between concepts.
+- **Cross-reference with code**; surface contradictions.
+- **Update `CONTEXT.md` inline** — capture each resolved term as it happens. Keep it
+  **devoid of implementation detail**: it's a glossary, not a spec.
+
+## CONTEXT.md format
+
+```markdown
+---
+title: "Domain Context"
+tags: [groundwork/core]
+aliases: ["Ubiquitous Language", "Glossary", "CONTEXT"]
+---
+
+# {Context Name}
+{One or two sentences: what this context is and why it exists.}
+
+## Language
+**Order**: A confirmed, priced customer request ready to fulfil.
+_Avoid_: Purchase, transaction
+**Customer**: A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+Rules: be opinionated (pick one term, list the rest under `_Avoid_`); tight definitions
+(1–2 sentences, what it *is* not what it *does*); only context-specific terms (no general
+programming concepts); group under subheadings when clusters emerge.
+
+## CONTEXT-MAP.md format (multi-context only)
+
+```markdown
+---
+title: "Context Map"
+tags: [groundwork/core]
+aliases: ["Context Map"]
+---
+
+# Context Map
+## Contexts
+- [[ordering/CONTEXT|Ordering]] — receives and tracks customer orders
+- [[billing/CONTEXT|Billing]] — generates invoices and processes payments
+## Relationships
+- **Ordering → Billing**: Ordering emits `OrderPlaced`; Billing consumes it to invoice
+- **Ordering ↔ Billing**: shared types `CustomerId`, `Money`
+```
+
+## Decisions
+
+When modeling surfaces a real architectural decision, record it with `/log-decision` — but
+**only when all three hold**: hard to reverse, surprising without context, a real trade-off.
+Boundary/ownership decisions ("Customer data is owned by the Customer context; others
+reference it by ID") are prime ADR material.
+
+`/kickstart` runs this during architecture design; `/plan-phase` uses the glossary to name
+tasks/types precisely.
+
+Term or area to model: $ARGUMENTS

package/payload/skills/kickstart/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: kickstart
+description: Scaffold a project's docs (tech stack, architecture, roadmap, phases) FROM an existing PRD. Run AFTER /create-prd. Use when a PRD exists and the project docs/structure still need generating.
+argument-hint: "<project name>"
+---
+
+# Kickstart - Project Initialization
+
+Scaffold a project's Groundwork docs **from its PRD**: tech stack, architecture, roadmap,
+and phase structure.
+
+## Obsidian format (required)
+
+Every generated file under `docs/`: (1) starts with YAML frontmatter (`title`; `tags` e.g.
+`groundwork/core`/`groundwork/reference`/`groundwork/phase`; `aliases`); (2) uses
+`[[wikilinks]]`, not `[text](path.md)`; (3) templates already include both — when copying,
+preserve frontmatter (update title/aliases) and keep wikilinks as-is.
+
+## Prerequisite: the PRD comes first
+
+`/create-prd` is the entry point, not kickstart. The PRD defines the *product*; kickstart
+turns it into the *scaffold* and must **not** re-interview on anything the PRD already
+answers. Before anything else, look for `docs/PRD.md` (or `docs/PRD_*.md`):
+
+- **PRD exists:** read it; derive project name, type, description, goals, scope, and phases
+  from it. Skip to what it doesn't cover (tech stack, architecture, design system).
+- **No PRD:** recommend `/create-prd` first. Use the full question flow below only if the
+  user chooses to skip the PRD (tiny throwaway project).
+
+**Who runs this (and only one agent):** run it as the product-context holder (you, or a
+coordinator acting as your proxy), not a narrow execution worker — kickstart makes
+stack/architecture choices that lean on the product understanding behind the PRD. And it is
+a **single-writer** step: never let two agents scaffold the same repo at once — they race on
+the same files. In a multi-agent setup the coordinator runs kickstart itself (or has David
+run it) and *then* seeds workers from the generated docs; workers run `/plan-phase` tasks.
+
+## Instructions
+
+Pull every answer from the PRD first; only ask for what's genuinely missing.
+
+### Stage 1: Project Setup (from the PRD)
+
+Take name/type/description from the PRD if present, else ask: project name; type (web app,
+API, CLI, library, mobile…); one-line description. Then create the structure:
+
+```
+project-root/
+├── docs/{phases/templates,templates}/
+├── client/src/   # if frontend
+└── server/src/   # if backend
+```
+
+### Stage 2: Tech Stack Discovery
+
+Ask per layer (skip if N/A):
+
+- **Frontend:** framework? build tool? styling? state management?
+- **Backend:** runtime? framework? database? ORM?
+- **Infra:** package manager? monorepo? deploy target?
+
+Generate `docs/TECH_STACK.md` from `docs/templates/TECH_STACK_TEMPLATE.md`.
+**Pin to latest stable — do not guess versions.** If a `package.json` exists, run
+`/check-versions`; otherwise look up each package's latest stable on the registry (memory
+drifts, the registry does not).
+
+### Stage 2b: Version source of truth
+
+Populate `docs/STACK_MAP.md` with pinned versions + latest-stable targets. **Version
+numbers live only here** — every other doc links to it. Set the `Last audited` date; note
+anything a major behind under **Pending upgrades**.
+
+### Stage 3: Architecture Decisions
+
+First, **establish the ubiquitous language** — run `/domain-model`: pull core domain terms
+from the PRD, sharpen fuzzy/overloaded ones, capture them in `docs/CONTEXT.md` (and
+`docs/CONTEXT-MAP.md` for multiple bounded contexts). Skip only for trivial projects.
+
+Then, for each major technology choice, capture: why this choice, alternatives considered,
+trade-offs. Generate:
+
+- `docs/ARCHITECTURE_GUIDE.md` - from `ARCHITECTURE_GUIDE_TEMPLATE.md`
+- `docs/DECISIONS.md` - initial ADRs, but **only when** a decision is hard to reverse,
+  surprising without context, and a real trade-off.
+
+### Stage 4: Project Phases (from the PRD)
+
+Derive phases from the PRD's scope/MoSCoW/milestones and **confirm** them with the user —
+don't re-interview. If no PRD: ask MVP scope, post-MVP, hard deadlines. Suggested shapes:
+
+```
+Web app: Foundation → Core Features → Polish → Launch
+API:     Foundation → Security → Features → Production
+```
+
+Generate `docs/PRODUCTION_ROADMAP.md`, `docs/phases/README.md`, and
+`docs/phases/phase1/README.md` from their templates.
+
+### Stage 5: Initialize Workstreams & Queue
+
+Generate `docs/WORKSTREAMS.md` from the `WORKSTREAMS.md` doc template — the live state of
+parallel work streams (one row per stream; the swarm-native replacement for a single
+"current focus" and the live counterpart to `[[QUEUE]]`). Start with one placeholder
+stream pointing at Phase 1; leave `Recently Closed` empty.
+
+Create `docs/QUEUE.md` from `docs/templates/QUEUE_TEMPLATE.md` (Queue empty at init;
+`/plan-phase` adds phases as they're planned) and `docs/DONE.md` from
+`docs/templates/DONE_TEMPLATE.md` (empty completion log).
+
+### Stage 6: Design System (optional)
+
+If the project has a frontend, ask color scheme, typography, and component style; generate
+`docs/DESIGN_SYSTEM.md` from `docs/templates/DESIGN_SYSTEM_TEMPLATE.md`.
+
+### Stage 7: Summary
+
+Summarise what was created (see Output Files), then give next steps:
+
+1. `/check-versions` - pin the stack to latest stable (if a `package.json` exists)
+2. `/plan-phase 1 [name]` - create detailed tasks
+3. `/start-session` - begin development
+
+## Output Files
+
+| File                           | Source Template                                 | Purpose                             |
+| ------------------------------ | ----------------------------------------------- | ----------------------------------- |
+| `docs/TECH_STACK.md`           | `docs/templates/TECH_STACK_TEMPLATE.md`         | Technology choices (versions → STACK_MAP) |
+| `docs/STACK_MAP.md`            | (shipped doc)                                    | Single source of truth for versions |
+| `docs/CONTEXT.md`              | (via `/domain-model`)                            | Ubiquitous-language glossary         |
+| `docs/ARCHITECTURE_GUIDE.md`   | `docs/templates/ARCHITECTURE_GUIDE_TEMPLATE.md` | System design and patterns          |
+| `docs/DECISIONS.md`            | (ADR template in existing file)                 | Architectural Decision Records      |
+| `docs/PRODUCTION_ROADMAP.md`   | `docs/templates/PRODUCTION_ROADMAP_TEMPLATE.md` | High-level phase overview           |
+| `docs/DESIGN_SYSTEM.md`        | `docs/templates/DESIGN_SYSTEM_TEMPLATE.md`      | Visual design guidelines (optional) |
+| `docs/phases/README.md`        | `docs/templates/PHASES_README_TEMPLATE.md`      | Phase navigation and progress       |
+| `docs/phases/phase1/README.md` | `docs/templates/PHASE_README_TEMPLATE.md`       | First phase overview                |
+| `docs/WORKSTREAMS.md`          | `WORKSTREAMS.md` doc template                    | Live state of parallel work streams |
+| `docs/QUEUE.md`                | `docs/templates/QUEUE_TEMPLATE.md`              | Inbound task queue                  |
+| `docs/DONE.md`                 | `docs/templates/DONE_TEMPLATE.md`               | Completion log (append-only)        |
+
+Pre-existing (not generated): `docs/templates/PRD_TEMPLATE.md` (used by `/create-prd`),
+`docs/phases/templates/TASK_TEMPLATE.md` + `task_template_prompt.md` (used by `/plan-phase`).
+
+## Logging convention (inherited)
+
+Projects ship structured logging: server (`apps/api`) uses pino → NDJSON to console **and**
+`logs/api.log` at the repo root; the browser (`apps/web`) logger mirrors to console and
+POSTs batched entries to `/api/logs`, which pino re-emits as `source: "client"` — so one
+tailable `logs/api.log` captures both sides. `LOG_LEVEL` controls verbosity (default
+`info`). Mention this in `ARCHITECTURE_GUIDE.md`/ADRs so it isn't lost. For other stacks
+(Python/Go/…), keep the pattern: structured logs to file + console, browser logs forwarded
+server-side, one tailable file.
+
+## Related Skills
+
+Runs **after** `/create-prd`. Then in order: `/check-versions` → `/plan-phase 1 [name]` →
+`/start-session`; `/log-decision` whenever a decision is made.
+
+## Project to initialize: $ARGUMENTS

package/payload/skills/log-decision/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: log-decision
+description: Create an Architectural Decision Record in DECISIONS.md
+argument-hint: "<decision title>"
+---
+
+# Log Decision - ADR Creator
+
+Append an Architectural Decision Record (ADR) to `docs/DECISIONS.md`.
+
+## When to log an ADR (the gate)
+
+Only record an ADR when **all three** hold — otherwise skip it (you'll just clutter the log):
+
+1. **Hard to reverse** — changing your mind later carries real cost.
+2. **Surprising without context** — a future reader will wonder "why did they do this?"
+3. **The result of a real trade-off** — there were genuine alternatives and you chose one.
+
+Prime material: architectural shape, integration patterns, lock-in tech choices (DB, auth,
+message bus), boundary/ownership decisions, deliberate deviations from the obvious path.
+Skip "we did the obvious thing." (For cross-project lessons, use `/remember` instead.)
+
+## Instructions
+
+1. **Read `docs/DECISIONS.md`** for the current format and the next ADR number (always increment).
+2. **Gather** Title, Context, Decision, Consequences (positive / negative / risks), and
+   Alternatives Considered — from `$ARGUMENTS` or by asking for what's missing.
+3. **Append the ADR** in the format below. Preserve the file's existing frontmatter.
+4. **Update the index table** at the top with `| ADR-XXX | [Title] | Accepted | YYYY-MM-DD |`.
+   Use `[[wikilinks]]` in the body where relevant (`[[TECH_STACK]]`, `[[DECISIONS#adr-003|ADR-003]]`).
+
+## ADR Format
+
+```markdown
+### ADR-XXX: [Decision Title]
+
+**Date**: YYYY-MM-DD
+**Status**: Accepted | Proposed | Superseded by ADR-XXX
+
+#### Context
+[The issue motivating this decision.]
+
+#### Decision
+[What we're doing.]
+
+#### Consequences
+**Positive:**
+- [Benefit]
+**Negative:**
+- [Trade-off]
+**Risks:**
+- [Risk to monitor]
+
+#### Alternatives Considered
+| Alternative | Pros | Cons | Why Not Chosen |
+| ----------- | ---- | ---- | -------------- |
+| [Option]    | ...  | ...  | ...            |
+```
+
+## Key Rules
+
+- ADRs are **immutable** — to change one, add a new ADR and mark the old "Superseded by ADR-XXX".
+- Always increment the ADR number.
+
+Decision to log: $ARGUMENTS