@davidbalzan/groundwork 0.3.1

package/payload/skills/next/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: next
+description: Figure out where the project is in the Groundwork flow and recommend the next step. Use when the user asks "what's next", "where are we", "what should I do now", or seems unsure which Groundwork skill to run.
+argument-hint: "[optional: area to focus on]"
+allowed-tools: Read, Glob, Grep
+---
+
+# Next - Groundwork Flow Guide
+
+Act as the project's flow coach. Inspect the current state, tell the user exactly where
+they are in the Groundwork lifecycle, and recommend the single best next action (with a
+short why). This skill never edits files — it orients and points.
+
+## How to assess (read these, in order)
+
+1. `docs/TECH_STACK.md` / `docs/PRODUCTION_ROADMAP.md` — do the project docs exist yet?
+2. `docs/STACK_MAP.md` — are versions pinned and recently audited (`Last audited` date)?
+3. `docs/PRD.md` (or `docs/PRD_*.md`) — is there a PRD?
+4. `docs/phases/phase*/PHASE*_TASKS.md` — do task files exist, and how many checkboxes
+   are open vs done? (For exact counts, suggest `groundwork status` or
+   `docs/.groundwork/scripts/phase-status.mjs`.)
+5. `docs/WORKSTREAMS.md` — any active streams in flight?
+6. `docs/QUEUE.md` (or legacy `docs/BACKLOG.md`) — what is the next unblocked `- [ ]` item in `## Queue`?
+7. `docs/DECISIONS.md` — recent or pending ADRs.
+
+## Decision tree
+
+Pick the FIRST matching state and recommend its action:
+
+| State detected | Recommend |
+| -------------- | --------- |
+| No `PRD.md` (and no project docs) | `/create-prd "<idea>"` — **first step**: define the product before scaffolding |
+| PRD exists, but no `TECH_STACK.md` / `PRODUCTION_ROADMAP.md` | `/kickstart` — scaffold the project docs **from the PRD** |
+| Designing and terminology is fuzzy/conflicting, or no `CONTEXT.md` yet | `/domain-model` — pin the ubiquitous language (+ bounded contexts) |
+| Docs exist, a `package.json` is present, `STACK_MAP` never audited or stale | `/check-versions` — pin to latest stable before building |
+| Roadmap exists but no `PHASE*_TASKS.md` | `/plan-phase 1 "<name>"` — break the first phase into tasks |
+| Task file has open `- [ ]` items, no active stream | `/start-session`, then work the next task; `/check-task <id>` as you finish |
+| Work in progress | `/update-workstreams` to record state; `/log-decision` for any new choices |
+| All tasks in current phase done | `groundwork status` to confirm, then `/plan-phase N+1` for the next phase |
+| A reusable cross-project lesson surfaced, knowledge repo configured | `/remember` it (or `/remember --adr` if it's a real decision with trade-offs) |
+| A lesson surfaced but no knowledge repo set (no `$GROUNDWORK_KNOWLEDGE` and no `~/.config/groundwork/config.json`) | `groundwork knowledge init` first, then `/remember` |
+| A project-specific decision was made | `/log-decision` (writes this project's `docs/DECISIONS.md`) |
+| A feature now needs persistence and there's no DB | `/add-data-layer` |
+
+If several apply, choose the one earliest in the flow that is incomplete — finishing the
+foundation beats jumping ahead.
+
+## Output format
+
+```
+## Where you are
+<one or two sentences: current phase/task, what's done, what's open>
+
+## Recommended next step
+**`/<skill> <args>`** — <why this, now>
+
+## Also worth doing
+- <secondary suggestion, if any>
+- <blocker to clear, if any>
+```
+
+Keep it short and decisive — one clear recommendation, not a menu. If the user passed
+`$ARGUMENTS`, bias the recommendation toward that area.
+
+Focus area (optional): $ARGUMENTS

package/payload/skills/plan-phase/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: plan-phase
+description: Generate a new phase task document using the project template
+argument-hint: "<phase number> <phase name>"
+---
+
+# Plan Phase - Task Document Generator
+
+Generate a comprehensive phase task document following the Groundwork methodology.
+
+## Obsidian Format (Required)
+
+Both generated files start with YAML frontmatter and use `[[wikilinks]]` (to
+`[[PRODUCTION_ROADMAP]]`, `[[ARCHITECTURE_GUIDE]]`, `[[TECH_STACK]]`, `[[DECISIONS]]`,
+`[[WORKSTREAMS]]`, sibling phases). Frontmatter:
+
+```yaml
+# docs/phases/phaseN/README.md
+---
+title: "Phase N: [Name]"
+tags: [groundwork/phase]
+aliases: ["Phase N"]
+---
+# docs/phases/phaseN/PHASEN_TASKS.md
+---
+title: "Phase N Tasks"
+tags: [groundwork/phase, groundwork/tasks]
+aliases: ["Phase N Tasks"]
+---
+```
+
+Base the README on `docs/templates/PHASE_README_TEMPLATE.md` and the tasks file on
+`docs/phases/templates/TASK_TEMPLATE.md` (both already have frontmatter — keep it, update titles).
+
+## Instructions
+
+Follow the 6-stage approach from `docs/phases/templates/task_template_prompt.md`:
+
+1. **Discovery & scope** — read existing phase docs; review PRODUCTION_ROADMAP.md objectives.
+2. **Technical analysis** — explore relevant code + patterns; check ARCHITECTURE_GUIDE.md
+   (constraints) and TECH_STACK.md. Read `docs/CONTEXT.md` (if present) and use its
+   canonical terms for task names, types, and APIs; if the phase introduces/sharpens
+   domain terms, run `/domain-model`.
+3. **Impact & risk** — phase dependencies, risks + mitigations, blockers.
+4. **Component inventory** — components to create/modify, mapped to packages; shared types.
+5. **Task planning** — 4–6 major tasks, each 3–7 sub-steps, priorities
+   (CRITICAL/HIGH/MEDIUM/LOW), inter-task dependencies.
+6. **Success criteria** — functional, technical, and quality criteria.
+7. **Confidence report** — end the tasks file with a short `## Low-confidence decisions`
+   list: the choices in this plan you are least sure about and why (naming, boundaries,
+   library picks, ordering). Cheap to fix now, expensive after code exists.
+
+## Task format
+
+```markdown
+### Task N: [Task Name]
+
+**Priority**: [CRITICAL/HIGH/MEDIUM/LOW]
+**Package**: [client/server/shared]
+**Dependencies**: [Task numbers or "None"]
+
+#### Sub-tasks
+- [ ] N.1 [First sub-task]
+- [ ] N.2 [Second sub-task]
+
+#### Deliverables
+- [What this task produces]
+
+#### Interfaces / contracts (if the task introduces or changes any)
+```ts
+// signatures only — types, function/method signatures, endpoint shapes, table columns.
+// No bodies. This is the level a reviewer can skim before code exists.
+```
+
+#### Rollback Plan (if high-risk)
+- [How to revert if needed]
+```
+
+## Output
+
+1. Generate `docs/phases/phaseN/README.md` (overview) and `PHASEN_TASKS.md` (detailed tasks).
+2. Update PRODUCTION_ROADMAP.md to include the new phase.
+3. Update `docs/QUEUE.md` (see below).
+4. Summarize what was created.
+
+## QUEUE.md Integration
+
+After generating the tasks file, update `docs/QUEUE.md` — the inbound queue that bridges
+Groundwork phase planning and whoever executes (you solo, or a coordinator's live multi-agent
+dispatch). Completions land in `docs/DONE.md`, which this skill never writes.
+
+```markdown
+# QUEUE — <project>
+
+## Queue
+- [ ] (P1) Phase N: [Phase Name] — see [[phases/phaseN/PHASEN_TASKS]] for full breakdown · acceptance: all Phase N success criteria met
+- [ ] (P2) <ad-hoc task added by David>
+```
+
+Rules:
+- **One Queue item per phase** — reference the PHASEN_TASKS file, don't inline sub-tasks; the executor reads the linked file for the full contract.
+- **Priority mapping**: CRITICAL → P1, HIGH → P2, MEDIUM/LOW → P3. Default new phases to P1 unless the roadmap says otherwise.
+- **If `docs/QUEUE.md` doesn't exist**, create it from `docs/templates/QUEUE_TEMPLATE.md`; if it exists, append to `## Queue` — never overwrite or reorder existing items (David owns this file).
+- **Ad-hoc tasks** live alongside phase items in the Queue — don't remove or reorder them.
+- **Never touch `docs/DONE.md`** — executor-only, append-only.
+- **Legacy layout:** if the project still has a `docs/BACKLOG.md` with a `## Queue` section, append there instead and suggest migrating to the QUEUE/DONE split.
+
+Phase to plan: $ARGUMENTS

package/payload/skills/remember/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: remember
+description: Capture a cross-project lesson in the central git knowledge repo — a quick dated note by default, or a formal ADR when it's a real decision with trade-offs (use --adr). Use when the user says "remember that…" or a reusable lesson/decision surfaces worth keeping beyond this project.
+argument-hint: "[--adr] [tag:] <lesson>"
+---
+
+# Remember - Capture a Lesson (central, git-level)
+
+Persist cross-project lessons to the **central knowledge repo** so they live at git level
+(shared across projects, machines, and the swarm). Two modes:
+
+- **note** (default) — a quick dated one-liner in `notes/lessons.md`.
+- **ADR** (`--adr`, or when the lesson is a real decision) — a formal record in
+  `adr/NNNN-*.md` with rationale and trade-offs, indexed in `INDEX.md`.
+
+Use the ADR mode **only when** the lesson is *hard to reverse*, *surprising without
+context*, and *a real trade-off*. Otherwise a note is enough.
+
+## Resolve the knowledge repo (per-user — never hardcode)
+
+Order: `$GROUNDWORK_KNOWLEDGE` → `knowledgeRepo` in
+`${XDG_CONFIG_HOME:-$HOME/.config}/groundwork/config.json` → else stop and tell the user to
+run `groundwork knowledge init` (or `link <dir>`).
+
+```bash
+KB="$GROUNDWORK_KNOWLEDGE"
+[ -z "$KB" ] && KB=$(groundwork knowledge path 2>/dev/null | head -1)
+[ -z "$KB" ] && { echo "No knowledge repo configured — run: groundwork knowledge init"; exit 1; }
+```
+
+Always `git -C "$KB" pull --rebase --autostash 2>/dev/null || true` before writing (the
+swarm/other machines push here too), and commit + push after.
+
+## Note mode (default)
+
+1. Parse `$ARGUMENTS` into an optional `tag:` prefix (lowercase, e.g. `tooling:`) + the lesson; infer a tag if none.
+2. Resolve `$KB`. Pull.
+3. Append to `$KB/notes/lessons.md` (create with `# Lessons` if absent), today's date:
+   ```markdown
+   - [YYYY-MM-DD] (tag) <lesson>  ·  src: <project/repo, if relevant>
+   ```
+4. `git add notes/lessons.md && git commit -m "note: <summary>" && git push 2>/dev/null || true`.
+5. Confirm. If it reads like a real decision, offer to upgrade it with `--adr`.
+
+## ADR mode (`--adr`)
+
+1. Resolve `$KB`. Pull.
+2. Gather (briefly, from `$ARGUMENTS` + conversation): **Context**, **Decision**,
+   **Consequences** (positive + negative), **Alternatives considered**.
+3. Next number: scan `$KB/adr/` for the highest `NNNN`, increment, zero-pad to 4 digits.
+4. Write `$KB/adr/NNNN-kebab-title.md`:
+   ```markdown
+   # ADR-NNNN: <Title>
+
+   **Status**: Accepted
+   **Date**: YYYY-MM-DD
+   **Tags**: <comma-separated>
+   **Origin**: <project/repo, if relevant>
+
+   ## Context
+   ## Decision
+   ## Consequences
+   **Positive**
+   **Negative**
+   ## Alternatives Considered
+   ```
+5. Add a row to `$KB/INDEX.md` (ID, linked title, tags, date).
+6. `git add adr/ INDEX.md && git commit -m "adr: NNNN <title>" && git push 2>/dev/null || true`.
+7. If promoting an existing note, append `→ ADR-NNNN` to it in `notes/lessons.md`. Confirm and show the ADR.
+
+## Scope
+
+Cross-project lessons/decisions belong here. **Project-specific** decisions stay in that
+project's `docs/DECISIONS.md` via `/log-decision`. Tool-agnostic by design — just git +
+markdown, so any agent or human shares the repo.
+
+## Lesson to capture: $ARGUMENTS

package/payload/skills/start-session/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: start-session
+description: Load project context from Groundwork docs at the start of a session
+argument-hint: "[optional: specific area to focus on]"
+allowed-tools: Read, Glob, Grep
+---
+
+# Start Session - Groundwork Context Loader
+
+Load context from the Groundwork docs to understand current project state, then summarize.
+
+## Instructions
+
+Read, in order (skip any that are absent):
+
+1. **`docs/PRODUCTION_ROADMAP.md`** — the "Current Status" section is the primary entry point.
+2. **`docs/WORKSTREAMS.md`** — live state of parallel streams (what's in flight now).
+3. **Active phase** `docs/phases/phaseN/README.md` + `PHASEN_TASKS.md` — goals + task breakdown.
+4. **`docs/DECISIONS.md`** — recent/relevant ADRs.
+5. **`docs/CONTEXT.md`** — the ubiquitous language; use its canonical terms.
+6. **`docs/QUEUE.md`** (or legacy `docs/BACKLOG.md`) — next unblocked Queue item + ad-hoc tasks.
+7. **Summarize** (see format). `docs/ARTIFACTS.md` maps where everything lives if unsure.
+
+## Output Format
+
+```
+## Session Context
+**Active Phase**: Phase N - [Name]
+**Current Task**: [description]   **Status**: [In Progress / Blocked / …]
+
+### Recent Progress
+- [what was completed]
+
+### Recent Decisions
+- ADR-XXX: [Title] — [impact on current work]
+
+### Blockers
+- [blocking items]
+
+### Next Backlog Item
+- (P?) [next unblocked Queue item, or "No backlog found"]
+
+### Suggested Next Steps
+1. … 2. …
+```
+
+If `$ARGUMENTS` is given, focus the summary on that area.
+
+## Decision relevance
+
+Surface ADRs from the last 30 days, any related to the current phase, any "Proposed" ones
+awaiting confirmation, and any that constrain the current task.

package/payload/skills/update-workstreams/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: update-workstreams
+description: Update docs/WORKSTREAMS.md with the live state of parallel work streams
+argument-hint: "[stream id or summary of progress]"
+---
+
+# Update Workstreams - Live Parallel-Work Recorder
+
+Update `docs/WORKSTREAMS.md` to reflect the live state of every parallel stream of work —
+a table of **active streams**, not a single focus (the swarm-native replacement for
+"current focus"). It is the live counterpart to `[[QUEUE]]`:
+
+- **`QUEUE.md`** = the *inbound* queue (what to pick up next). Owned by the human + `/plan-phase`.
+- **`WORKSTREAMS.md`** = the *live* state (what's in flight). Written by whoever's working,
+  including an external coordinator that pulls from QUEUE and opens a stream here. See
+  `[[GROUNDWORK_METHODOLOGY#multi-agent-seam]]`.
+- **`DONE.md`** = the *completion log* (append-only, written by the executor).
+
+Working alone is just the one-row case — the model scales solo → fleet unchanged.
+
+Preserve the file's frontmatter; use `[[wikilinks]]` (`[[DECISIONS#adr-005|ADR-005]]`, `[[QUEUE]]`).
+
+**Write only the core; preserve coordinator extensions.** Under a multi-agent coordinator,
+`WORKSTREAMS.md` may carry coordinator-only sections after the `<!-- coordinator extensions -->`
+fence (Open PRs, Cutover Gates, Needs David, Risks, Rooms, Decisions Recorded). You edit
+**only** `## Active Streams` and `## Recently Closed`; copy everything from that fence onward
+through **verbatim** on every rewrite — never edit or drop it. Within Active Streams, touch
+only the row(s) you own, and if another agent may be writing, re-read immediately before
+writing (read-before-write) so you don't clobber a concurrent row.
+
+## Instructions
+
+1. Read `docs/WORKSTREAMS.md`.
+2. From `$ARGUMENTS`/context: new stream → add a row; progress → update its Status / Last
+   note; finished → move the row to `## Recently Closed` with an outcome.
+3. Keep one row per active stream; update the `Last Updated` timestamp; confirm the result.
+
+Write grammar is **`workstreams.v1`**: the 6-col Active Streams table below. Do not write a
+5-col Lanes table (`Lane | Owner | State | Current slice | Next GO`) — that shape is
+parse-only.
+
+## Format
+
+```markdown
+## Active Streams
+
+| Stream            | Owner / Agent | Branch · Worktree            | Status         | Blocker | Last note                       |
+| ----------------- | ------------- | ---------------------------- | -------------- | ------- | ------------------------------- |
+| Phase 2 · Auth    | agent-api     | `feat/phase2-auth` · wt-auth | 🚧 In Progress | None    | JWT done, RBAC next             |
+| Phase 3 · Search  | —             | —                            | ⏳ Queued      | Phase 2 | pulled from [[QUEUE]]           |
+
+## Recently Closed
+- ✅ Phase 1 · Foundation — agent-api · `feat/phase1` · merged YYYY-MM-DD
+```
+
+Guidelines: status = 🚧 In Progress · 🔍 In Review · ⏳ Queued · ⛔ Blocked · ✅ Done. Record
+branch + worktree so any agent can resume the exact context. `Blocker` names the dependency
+(another stream, a decision, a person), not just "yes". Dates `YYYY-MM-DD`.
+
+Progress to record: $ARGUMENTS

package/src/cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { init } from "./commands/init.mjs";
+import { update } from "./commands/update.mjs";
+import { add } from "./commands/add.mjs";
+import { list } from "./commands/list.mjs";
+import { status } from "./commands/status.mjs";
+import { knowledge } from "./commands/knowledge.mjs";
+import { artifacts } from "./commands/artifacts.mjs";
+import { doctor } from "./commands/doctor.mjs";
+import { log, bold, cyan, dim } from "./lib/log.mjs";
+
+const argv = process.argv.slice(2);
+
+/** Split flags (--foo) from positional args. */
+function parse(args) {
+  const flags = {};
+  const pos = [];
+  for (const a of args) {
+    if (a.startsWith("--")) flags[a.slice(2)] = true;
+    else pos.push(a);
+  }
+  return { flags, pos };
+}
+
+function version() {
+  const pkg = JSON.parse(
+    readFileSync(new URL("../package.json", import.meta.url), "utf8")
+  );
+  console.log(pkg.version);
+}
+
+function help() {
+  console.log(
+    [
+      bold("groundwork") + dim(" — bolt the Groundwork AI workflow onto any repo"),
+      "",
+      bold("Usage:") + "  groundwork <command> [dir] [flags]",
+      "",
+      bold("Commands:"),
+      `  ${cyan("init")} [dir]        Install skills + IDE mirrors + docs into a repo (default: .)`,
+      `  ${cyan("update")} [dir]      Upgrade skills + scripts in place (keeps your docs); ${dim("--all")} adds new skills, ${dim("--docs")} refreshes generic reference docs`,
+      `  ${cyan("add")} <skill> [dir] Add one optional skill (e.g. add-data-layer)`,
+      `  ${cyan("list")} [dir]        List available skills and install state`,
+      `  ${cyan("status")} [dir]      Show live workstreams, next backlog item, phase progress`,
+      `  ${cyan("doctor")} [dir]      Flag doc↔reality drift (orphan links, stale phases/versions)`,
+      `  ${cyan("knowledge")} <cmd>   Central ADR/lessons repo (init | link | sync [--push] | path)`,
+      `  ${cyan("artifacts")} [dir]   Regenerate docs/ARTIFACTS.md from the manifest`,
+      `  ${cyan("help")}             Show this help`,
+      `  ${cyan("version")}          Print version`,
+      "",
+      bold("Flags:"),
+      `  --minimal          init only the core 5 skills`,
+      `  --force            overwrite files that already exist`,
+      `  --json             machine-readable output (doctor / status / list)`,
+      "",
+      bold("Examples:"),
+      dim("  npx github:davidbalzan/groundwork init"),
+      dim("  groundwork init . --minimal"),
+      dim("  groundwork add data-layer"),
+      dim("  groundwork status"),
+    ].join("\n")
+  );
+}
+
+const [cmd, ...rest] = argv;
+const { flags, pos } = parse(rest);
+
+try {
+  switch (cmd) {
+    case "init":
+      init(pos[0], flags);
+      break;
+    case "update":
+      update(pos[0], flags);
+      break;
+    case "add":
+      add(pos[0], pos[1]);
+      break;
+    case "list":
+      list(pos[0], flags);
+      break;
+    case "status":
+      status(pos[0], flags);
+      break;
+    case "knowledge":
+      knowledge(pos[0], pos[1], flags);
+      break;
+    case "artifacts":
+      artifacts(pos[0]);
+      break;
+    case "doctor":
+      doctor(pos[0], flags);
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      version();
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      help();
+      break;
+    default:
+      log.err(`Unknown command: ${cmd}`);
+      help();
+      process.exitCode = 1;
+  }
+} catch (err) {
+  log.err(err.message);
+  if (process.env.DEBUG) console.error(err);
+  process.exitCode = 1;
+}

package/src/commands/add.mjs

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { PAYLOAD_SKILLS, TARGET } from "../lib/paths.mjs";
+import { copyFileSafe, exists } from "../lib/fs.mjs";
+import { loadSkills, mirrorFiles } from "../lib/skills.mjs";
+import fs from "node:fs";
+import { log, cyan } from "../lib/log.mjs";
+
+/**
+ * Add a single optional skill (e.g. after a `--minimal` install, or to pull in
+ * `add-data-layer`). Copies the SKILL.md and regenerates that skill's mirrors.
+ */
+export function add(skillName, targetDir) {
+  const root = path.resolve(targetDir || ".");
+  if (!skillName) {
+    log.err("Usage: groundwork add <skill-name>   (see `groundwork list`)");
+    process.exitCode = 1;
+    return;
+  }
+  const src = path.join(PAYLOAD_SKILLS, skillName, "SKILL.md");
+  if (!exists(src)) {
+    log.err(`Unknown skill "${skillName}". Run \`groundwork list\`.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  copyFileSafe(src, path.join(root, TARGET.skills, skillName, "SKILL.md"), {
+    force: true,
+  });
+  const [skill] = loadSkills([skillName]);
+  for (const f of mirrorFiles([skill], {
+    cursorDir: path.join(root, TARGET.cursor),
+    vscodeDir: path.join(root, TARGET.vscode),
+  })) {
+    fs.mkdirSync(path.dirname(f.rel), { recursive: true });
+    fs.writeFileSync(f.rel, f.content);
+  }
+
+  log.ok(`Added skill ${cyan("/" + skillName)} (+ Cursor/VS Code mirrors).`);
+}

package/src/commands/artifacts.mjs

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { TARGET } from "../lib/paths.mjs";
+import { writeText, exists } from "../lib/fs.mjs";
+import { renderArtifactsDoc } from "../lib/artifacts.mjs";
+import { log, cyan } from "../lib/log.mjs";
+
+/**
+ * Regenerate docs/ARTIFACTS.md in a target project from the single-source manifest.
+ * (init/update call writeArtifacts directly; this is the manual on-demand entry point.)
+ */
+export function artifacts(targetDir) {
+  const root = path.resolve(targetDir || ".");
+  if (!exists(path.join(root, TARGET.docs))) {
+    log.warn("No docs/ here. Run `groundwork init` first.");
+    return;
+  }
+  writeArtifacts(root);
+  log.ok(`Regenerated ${cyan("docs/ARTIFACTS.md")} from the manifest.`);
+}
+
+/** Write docs/ARTIFACTS.md from the manifest. Shared by init/update. */
+export function writeArtifacts(root) {
+  writeText(path.join(root, TARGET.docs, "ARTIFACTS.md"), renderArtifactsDoc());
+}