@davidbalzan/groundwork 0.3.1

package/payload/doc-templates/COMMANDS.md

@@ -0,0 +1,419 @@
+---
+title: "AI Commands Guide"
+tags: [groundwork/reference]
+aliases: ["Commands"]
+---
+
+# AI Assistant Commands Guide
+
+This guide explains how to use the Groundwork workflow commands across different IDEs.
+
+---
+
+## Quick Reference
+
+| Command         | Purpose                       | When to Use                        |
+| --------------- | ----------------------------- | ---------------------------------- |
+| `create-prd`    | Define the product (PRD)      | **First** — right after install    |
+| `kickstart`     | Scaffold project docs FROM the PRD | After the PRD exists          |
+| `domain-model`  | Build the ubiquitous-language glossary + context map | During system design |
+| `check-versions` | Audit deps vs latest stable  | Right after kickstart + periodically |
+| `plan-phase`    | Create phase task breakdown   | Starting a new development phase   |
+| `start-session` | Load project context          | Start of each coding session       |
+| `next`          | Recommend the next step       | Whenever unsure where you are      |
+| `check-task`    | Mark tasks complete           | After completing a task            |
+| `update-workstreams` | Update live parallel-stream state | End of session or on stream change |
+| `log-decision`  | Record architectural decision | After making tech choices          |
+| `add-data-layer` | Add optional Drizzle + DB layer | When a feature needs persistence |
+| `remember`      | Capture a cross-project lesson | After discovering a useful pattern |
+
+(Phase progress is read-only — just ask, or run `groundwork status`.)
+
+---
+
+## Workflow Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     PROJECT LIFECYCLE                                │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌────────────┐    ┌──────────┐    ┌────────────┐    ┌────────────┐ │
+│  │ create-prd │ ──▶│kickstart │ ──▶│ plan-phase │ ──▶│start-session│ │
+│  └────────────┘    └──────────┘    └────────────┘    └────────────┘ │
+│       │                                                     │        │
+│       ▼                                                     ▼        │
+│  Defines the          Scaffolds docs/     Creates tasks     │        │
+│  product (PRD)        FROM the PRD         for Phase 1       │        │
+│                                                             │        │
+│                         DEVELOPMENT LOOP                    │        │
+│                    ┌────────────────────────┐               │        │
+│                    │                        │               │        │
+│                    ▼                        │               │        │
+│              ┌──────────┐             ┌─────┴──────┐        │        │
+│              │check-task│ ◀────────── │   Code!    │ ◀──────┘        │
+│              └──────────┘             └────────────┘                 │
+│                    │                        ▲                        │
+│                    ▼                        │                        │
+│              ┌────────────┐           ┌─────┴──────┐                 │
+│              │workstreams │ ────────▶ │log-decision│                 │
+│              └────────────┘           └────────────┘                 │
+│                                                                      │
+│         (phase progress: `groundwork status` — read-only, on demand) │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## IDE-Specific Usage
+
+### Claude Code (Terminal)
+
+Use slash commands directly:
+
+```bash
+# Initialize a new project
+/kickstart MyProject
+
+# Create product requirements
+/create-prd "E-commerce platform"
+
+# Start a coding session
+/start-session
+
+# Plan a phase
+/plan-phase 1 "Foundation"
+
+# Log a decision
+/log-decision "Use PostgreSQL for database"
+
+# Update workstreams
+/update-workstreams "Phase 2 auth stream: middleware done, RBAC next"
+
+# Mark a task complete
+/check-task 2.3
+
+# Capture a cross-project learning
+/remember "typescript: Always use Zod for runtime validation"
+```
+
+### Cursor
+
+Type `/` in Agent chat (Cmd+L) to see available commands:
+
+```
+/create-prd
+/kickstart
+/check-versions
+/plan-phase
+/start-session
+/next
+/check-task
+/update-workstreams
+/log-decision
+/domain-model
+/add-data-layer
+/remember
+```
+
+Alternative: Use `@` file references:
+
+```
+@kickstart.md - initialize my new project
+@create-prd.md - create PRD for authentication system
+```
+
+### VS Code Copilot
+
+1. Open Copilot Chat (Cmd+Shift+I)
+2. Click the paperclip icon or type `/`
+3. Select "Prompt..." from the menu
+4. Choose the prompt you want
+
+Available prompts:
+
+- `create-prd.prompt.md`
+- `kickstart.prompt.md`
+- `check-versions.prompt.md`
+- `plan-phase.prompt.md`
+- `start-session.prompt.md`
+- `next.prompt.md`
+- `check-task.prompt.md`
+- `update-workstreams.prompt.md`
+- `log-decision.prompt.md`
+- `domain-model.prompt.md`
+- `add-data-layer.prompt.md`
+- `remember.prompt.md`
+
+---
+
+## Command Details
+
+### `/kickstart`
+
+**Purpose**: Scaffold a project's documentation **from an existing PRD**. Run after `/create-prd`.
+
+**What it does**:
+
+0. Reads [[PRD]] and derives project name, scope, and phases from it (no re-interview)
+1. Creates folder structure (`docs/`, `apps/web/`, `apps/api/`, `packages/shared/`)
+2. Guides through tech stack selection → [[TECH_STACK]]
+3. Records architecture decisions → [[ARCHITECTURE_GUIDE]], [[DECISIONS]]
+4. Sets up phase structure (from the PRD) → [[PRODUCTION_ROADMAP]], `phases/`
+5. Initializes workstreams tracking → [[WORKSTREAMS]]
+6. Optionally creates design system → [[DESIGN_SYSTEM]]
+
+**When to use**: After the PRD exists, to turn it into the project scaffold. (If you ran
+`/create-prd` first — as you should — kickstart won't re-ask what the PRD already covers.)
+
+**Example**:
+
+```
+/kickstart "TaskFlow - A project management app"
+```
+
+---
+
+### `/create-prd`
+
+**Purpose**: Generate a comprehensive Product Requirements Document.
+
+**What it does**:
+
+1. Guides through problem discovery
+2. Captures vision and measurable goals
+3. Defines user personas and stories
+4. Documents functional requirements with acceptance criteria
+5. Captures non-functional requirements (performance, security)
+6. Identifies risks and creates timeline
+
+**When to use**: Before starting development, to define what you're building.
+
+**Example**:
+
+```
+/create-prd "User authentication system with OAuth support"
+```
+
+**Output**: [[PRD]] or `docs/PRD_[ProductName].md`
+
+---
+
+### `/start-session`
+
+**Purpose**: Load project context at the beginning of a coding session.
+
+**What it does**:
+
+1. Reads [[WORKSTREAMS]] for live stream state
+2. Reviews phase progress from roadmap
+3. Checks recent decisions that affect current work
+4. Summarizes blockers and next steps
+
+**When to use**: Every time you start working on the project.
+
+**Example**:
+
+```
+/start-session
+```
+
+**Output**: Session summary with current task, recent progress, and suggested next steps.
+
+---
+
+### `/plan-phase`
+
+**Purpose**: Create detailed task breakdown for a development phase.
+
+**What it does**:
+
+1. Analyzes phase goals from roadmap
+2. Explores codebase for relevant patterns
+3. Assesses risks and dependencies
+4. Creates 4-6 major tasks with sub-steps
+5. Defines success criteria
+
+**When to use**: Starting a new phase of development.
+
+**Example**:
+
+```
+/plan-phase 2 "Authentication & Authorization"
+```
+
+**Output**:
+
+- `docs/phases/phase2/README.md`
+- `docs/phases/phase2/PHASE2_TASKS.md`
+
+---
+
+### `/log-decision`
+
+**Purpose**: Create an Architectural Decision Record (ADR).
+
+**What it does**:
+
+1. Captures the decision context
+2. Documents what was decided
+3. Records consequences (positive, negative, risks)
+4. Lists alternatives considered
+5. Updates the ADR index
+
+**When to use**: After making significant technical decisions.
+
+**Example**:
+
+```
+/log-decision "Use Redis for session caching"
+```
+
+**Output**: New ADR entry in [[DECISIONS]]
+
+---
+
+### `/update-workstreams`
+
+**Purpose**: Update `docs/WORKSTREAMS.md` with the live state of parallel work streams. The swarm-native replacement for a single "current focus", and the live counterpart to `[[QUEUE]]`.
+
+**What it does**:
+
+1. Adds, updates, or closes a stream row (one row per live stream)
+2. Records owner/agent, branch · worktree, status, and blocker
+3. Moves finished streams to `Recently Closed` with an outcome
+4. Sets the "Last Updated" timestamp
+
+**When to use**:
+
+- End of coding session
+- When a stream changes status (started / in review / blocked / done)
+- When a coordinator opens or closes a stream from the backlog
+
+**Example**:
+
+```
+/update-workstreams "Phase 2 auth stream: middleware done, RBAC next"
+```
+
+---
+
+### `/check-task`
+
+**Purpose**: Mark tasks as complete and update progress.
+
+**What it does**:
+
+1. Updates checkbox in task file (`- [ ]` → `- [x]`)
+2. Updates progress statistics
+3. Adds completion notes if significant
+4. Optionally updates related files
+
+**When to use**: After completing a task or sub-task.
+
+**Example**:
+
+```
+/check-task 2.3
+```
+
+---
+
+### Phase progress (no skill)
+
+Phase progress is read-only — just ask ("what's the status of phase 2?") or run
+`groundwork status` (or `node docs/.groundwork/scripts/phase-status.mjs [N]`) for a
+deterministic, computed count. There's no dedicated skill.
+
+---
+
+## File Locations
+
+| IDE         | Location                 | File Pattern       |
+| ----------- | ------------------------ | ------------------ |
+| Claude Code | `.claude/skills/[name]/` | `SKILL.md`         |
+| Cursor      | `.cursor/commands/`      | `[name].md`        |
+| VS Code     | `.vscode/prompts/`       | `[name].prompt.md` |
+
+---
+
+## Tips for Effective Use
+
+### Start Every Session Right
+
+```
+/start-session
+```
+
+This loads context and reminds you where you left off.
+
+### Capture Decisions Immediately
+
+When you make a technology choice, log it:
+
+```
+/log-decision "Chose Zustand over Redux for state management"
+```
+
+Future you will thank you.
+
+### Keep Workstreams Updated
+
+At the end of each session, or whenever a stream changes status:
+
+```
+/update-workstreams "Completed X, next up is Y"
+```
+
+### Check Phase Progress for Planning
+
+Before starting new work, run `groundwork status` to see what's left and what's blocked.
+
+### Don't Skip the PRD
+
+Even for small features:
+
+```
+/create-prd "Dark mode toggle"
+```
+
+It forces you to think through requirements before coding.
+
+---
+
+## Troubleshooting
+
+### Commands not appearing in Cursor
+
+- Ensure files are in `.cursor/commands/` (not `.cursor/prompts/`)
+- Restart Cursor after adding new commands
+- Check that files have `.md` extension
+
+### Commands not appearing in VS Code
+
+- Ensure files are in `.vscode/prompts/`
+- Files must have `.prompt.md` extension
+- Check the `mode` in frontmatter (`ask` or `edit`)
+
+### Claude Code skills not working
+
+- Skills must be in `.claude/skills/[name]/SKILL.md`
+- Check the frontmatter format (`name`, `description` are required)
+- **Do NOT set `disable-model-invocation`.** Groundwork skills are meant to be
+  **auto-executable** — the agent invokes them on its own when the `description`
+  matches the situation. Setting `disable-model-invocation: true` makes a skill
+  user-only (you'd have to type `/name`), which defeats the flow.
+- A clear, action-oriented `description` is what lets the agent pick the right skill.
+
+---
+
+## Contributing
+
+To add a new command:
+
+1. Create the Claude Code skill in `.claude/skills/[name]/SKILL.md`
+2. Create the Cursor command in `.cursor/commands/[name].md`
+3. Create the VS Code prompt in `.vscode/prompts/[name].prompt.md`
+4. Update this guide with the new command
+5. Update the IDE-specific READMEs

package/payload/doc-templates/DECISIONS.md

@@ -0,0 +1,168 @@
+---
+title: "Architectural Decisions"
+tags: [groundwork/reference]
+aliases: ["DECISIONS", "ADR", "Decision Log"]
+---
+
+# Architectural Decision Records (ADRs)
+
+> **Document the "why" behind significant technical decisions.**
+
+ADRs capture context that's easy to forget: why we chose X over Y, what constraints existed, and what trade-offs we accepted. Future team members (and AI assistants) will thank you.
+
+---
+
+## Decision Log
+
+| ID      | Decision                                                        | Status   | Date       |
+| ------- | --------------------------------------------------------------- | -------- | ---------- |
+| ADR-001 | [Monorepo with Turborepo](#adr-001-monorepo-with-turborepo)     | Accepted | 2026-02-20 |
+| ADR-002 | [React + Vite for Frontend](#adr-002-react--vite-for-frontend)  | Accepted | 2026-02-20 |
+| ADR-003 | [Node.js + Hono for Backend](#adr-003-nodejs--hono-for-backend) | Accepted | 2026-02-20 |
+
+---
+
+## ADR-001: Monorepo with Turborepo
+
+**Status**: Accepted
+**Date**: 2026-02-20
+
+### Context
+
+We need to manage frontend, backend, and shared packages in a cohesive way across the project.
+
+### Decision
+
+Use Turborepo with pnpm workspaces for monorepo management.
+
+### Consequences
+
+**Positive:**
+
+- Shared TypeScript types between frontend and backend
+- Parallel builds and caching speed up CI
+- Single repository simplifies dependency management
+- pnpm provides efficient disk usage with symlinks
+
+**Negative:**
+
+- Need to configure Turborepo pipeline
+- All team members work in same repo
+- Shared packages require careful versioning
+
+### Alternatives Considered
+
+| Alternative    | Pros                               | Cons                            | Why Not                    |
+| -------------- | ---------------------------------- | ------------------------------- | -------------------------- |
+| Nx             | More features, powerful generators | Steeper learning curve, heavier | Overkill for most projects |
+| Lerna          | Familiar, established              | Legacy, less active development | Outdated patterns          |
+| Separate repos | Independent deployments            | Friction for shared code        | Coordination overhead      |
+
+---
+
+## ADR-002: React + Vite for Frontend
+
+**Status**: Accepted
+**Date**: 2026-02-20
+
+### Context
+
+Need a frontend framework with fast iteration and a mature ecosystem.
+
+### Decision
+
+Use React 19 with Vite as the build tool and Tailwind CSS 4 for styling.
+
+### Consequences
+
+**Positive:**
+
+- React's component model and ecosystem maturity
+- Vite provides fast HMR essential for UI development
+- Tailwind 4 with CSS-first config and design tokens
+- Wide library support and team familiarity
+
+**Negative:**
+
+- Bundle size consideration for production
+- Tailwind 4 is relatively new (CSS-based config)
+
+### Alternatives Considered
+
+| Alternative | Pros                      | Cons                                   | Why Not                            |
+| ----------- | ------------------------- | -------------------------------------- | ---------------------------------- |
+| Next.js     | Full-stack, SSR           | SSR not always needed, adds complexity | Over-engineered for many use cases |
+| Vue + Vite  | Great DX, smaller bundle  | Smaller ecosystem                      | Fewer libraries available          |
+| Svelte      | Compiled, minimal runtime | Less mature ecosystem                  | Library ecosystem not ready        |
+
+---
+
+## ADR-003: Node.js + Hono for Backend
+
+**Status**: Accepted
+**Date**: 2026-02-20
+
+### Context
+
+Need a fast, lightweight backend framework with excellent TypeScript support.
+
+### Decision
+
+Use Node.js runtime with Hono web framework.
+
+### Consequences
+
+**Positive:**
+
+- Hono is lightweight, Web Standards-based (~14kb)
+- TypeScript-first with excellent types
+- Built-in middleware (CORS, logger, Zod validation)
+- Portable across runtimes (Node, Bun, Deno, Cloudflare Workers)
+
+**Negative:**
+
+- Smaller ecosystem than Express
+- Team needs to learn Hono patterns
+
+### Alternatives Considered
+
+| Alternative | Pros                     | Cons                                  | Why Not                            |
+| ----------- | ------------------------ | ------------------------------------- | ---------------------------------- |
+| Express     | Huge ecosystem, familiar | Legacy patterns, no native TypeScript | Dated patterns                     |
+| Fastify     | Fast, good TS support    | More complex plugin system            | Heavier than needed                |
+| Bun + Hono  | Better performance       | Bun still evolving, edge cases        | Node.js more stable for production |
+
+---
+
+## ADR Template
+
+```markdown
+## ADR-XXX: [Title]
+
+**Status**: Proposed | Accepted | Rejected | Superseded by ADR-XXX
+**Date**: YYYY-MM-DD
+
+### Context
+
+What is the issue that we're seeing that is motivating this decision?
+
+### Decision
+
+What is the change that we're proposing and/or doing?
+
+### Consequences
+
+**Positive:**
+
+- Benefit 1
+
+**Negative:**
+
+- Trade-off 1
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Why Not |
+| ----------- | ---- | ---- | ------- |
+| Option A    | ...  | ...  | ...     |
+```

package/payload/doc-templates/FACTS.md

@@ -0,0 +1,43 @@
+---
+title: "Facts"
+tags: [groundwork/core]
+aliases: ["Facts", "Fact Store", "Verified Facts"]
+---
+
+# Facts
+
+> **Verified project facts — the shared world-model.** One entry per settled question about
+> this project's reality ("does X exist?", "is Y enabled?"). A claim belongs here only once
+> it has been *verified*; everything else is a hypothesis that stays in conversation.
+
+This is the seam file next to `[[QUEUE]]` (inbound), `[[WORKSTREAMS]]` (live), and
+`[[DONE]]` (completion log): **FACTS.md** is the *settled* state — answers that were
+verified once so they don't get re-derived, re-asserted, and drift. Useful solo,
+essential with multiple agents.
+
+**Write rules:**
+
+- **One writer per fact:** whoever verified it writes it. A conflicting read replaces the
+  entry (don't append a duplicate id).
+- Every entry carries **when**, **who**, and **how** it was verified. `groundwork doctor`
+  flags entries missing those, and entries older than 14 days.
+- Other docs and messages **cite fact ids** instead of restating the claim.
+- Re-verify on dispute or staleness — update the `verified:` line in place.
+
+**Entry format (pinned — required, not just an example):**
+
+```
+- `fact-id` — the claim, stated so it stays true or false
+  verified: YYYY-MM-DDTHH:MMZ · by: who-verified · method: how it was verified
+```
+
+One fact per entry: stable kebab-case id in backticks · **em-dash `—` (U+2014)** · claim on
+the first line; the indented second line uses **middot ` · ` (U+00B7)** separators — exact
+glyphs, not ASCII. Parsers (doctor, `set-fact.mjs`, UIs) split on those glyphs.
+
+## Facts
+
+<!-- add entries in the pinned format above, e.g.:
+     - `auto-disavow-flag` — does NOT exist anywhere in the codebase
+       verified: 2026-07-02T14:30Z · by: disavow-worker-1 · method: git grep + gh api origin/main
+-->