@davidbalzan/groundwork 0.3.1

package/payload/doc-templates/STACK_MAP.md

@@ -0,0 +1,90 @@
+---
+title: "Stack Map"
+tags: [groundwork/core]
+aliases: ["Stack"]
+---
+
+# Stack Map
+
+> **Single source of truth for versions.** Every technology → the version the starter
+> pins, the latest stable at last audit, and the files you touch to swap it.
+> For the "why" behind each choice, see [[DECISIONS]].
+
+> **Rule:** no other doc restates version numbers — they link here. When you bump a
+> dependency, update the `Pinned` column here and nowhere else.
+
+> ⚠️ **Versions drift.** The "Latest stable" column is a snapshot from the date below.
+> Refresh it with `/check-versions` (or `node docs/.groundwork/scripts/check-versions.mjs`),
+> which queries the registry and flags anything a major behind. Update this column and
+> the audit date whenever you run it.
+> Last audited: **2026-06-29**.
+
+---
+
+## Core
+
+| Technology | Pinned (starter) | Latest stable | Files to Change                                                       |
+| ---------- | ---------------- | ------------- | --------------------------------------------------------------------- |
+| Node.js    | >=22             | 22 LTS / 24   | `package.json` (`engines`), `.github/workflows/ci.yml`, `Dockerfile`  |
+| TypeScript | 5.7.x            | **6.0.x** ⬆   | `tsconfig.base.json`, all `tsconfig.json`, `package.json` (dep)        |
+| pnpm       | 10.4.x           | 10.x          | `package.json` (`packageManager`), `pnpm-workspace.yaml`              |
+| Turborepo  | 2.4.x            | 2.10.x        | `turbo.json`, `package.json` (dep)                                    |
+
+## Frontend (`apps/web/`)
+
+| Technology   | Pinned (starter) | Latest stable | Files to Change                                                               |
+| ------------ | ---------------- | ------------- | ----------------------------------------------------------------------------- |
+| React        | 19.0.x           | 19.2.x        | `apps/web/package.json`, `apps/web/tsconfig.json` (`jsx`), `eslint.config.js` |
+| Vite         | 6.1.x            | **8.x** ⬆     | `apps/web/vite.config.ts`, `apps/web/package.json`                            |
+| Tailwind CSS | 4.0.x            | 4.3.x         | `apps/web/src/index.css`, `apps/web/package.json`                             |
+
+## Backend (`apps/api/`)
+
+| Technology | Pinned (starter) | Latest stable | Files to Change                                                          |
+| ---------- | ---------------- | ------------- | ------------------------------------------------------------------------ |
+| Hono       | 4.7.x            | 4.12.x        | `apps/api/package.json`, `apps/api/src/index.ts`, `apps/api/src/routes/` |
+| Zod        | 3.x              | 4.x           | `apps/api/package.json`, `apps/api/src/env.ts`                           |
+
+## Shared Packages
+
+| Package              | Path               | Files to Change                                        |
+| -------------------- | ------------------ | ------------------------------------------------------ |
+| `@<scope>/shared`    | `packages/shared/` | `packages/shared/package.json`, `packages/shared/src/` |
+| `@<scope>/ui`        | `packages/ui/`     | `packages/ui/package.json`, `packages/ui/src/`         |
+
+## Developer Tooling
+
+| Tool           | Purpose             | Files to Change                                              |
+| -------------- | ------------------- | ------------------------------------------------------------ |
+| ESLint         | Linting             | `eslint.config.js`, `package.json` (dep)                     |
+| Prettier       | Formatting          | `.prettierrc` (if exists), `package.json` (dep)              |
+| Vitest         | Testing             | `vitest.config.ts`, `package.json` (dep)                     |
+| Husky          | Git hooks           | `.husky/pre-commit`, `package.json` (dep + `prepare` script) |
+| lint-staged    | Staged file linting | `package.json` (`lint-staged` config)                        |
+| GitHub Actions | CI                  | `.github/workflows/ci.yml`                                   |
+
+---
+
+## Optional modules
+
+Not in the base starter — added on demand. The data layer is wired by the
+`/add-data-layer` skill, which pins these to latest stable at install time.
+
+| Technology  | Typical version | Added by              | Notes                                  |
+| ----------- | --------------- | --------------------- | -------------------------------------- |
+| Drizzle ORM | 0.45.x          | `/add-data-layer`     | Type-safe SQL; `drizzle-kit` for migrations |
+| PostgreSQL  | 17              | `/add-data-layer`     | Default engine (MySQL/SQLite also supported) |
+| Zustand     | 5.x             | manual                | Client state — add only if local state outgrows React |
+
+When you adopt one, move its row up into the active stack above with a pinned version.
+
+---
+
+## Pending upgrades
+
+Tracked gaps between `Pinned` and `Latest stable` (⬆ above):
+
+- **Vite 6 → 8** — two majors; review `vite.config.ts` + plugin compatibility before bumping.
+- **TypeScript 5.7 → 6.0** — one major; run a typecheck pass across all packages.
+
+Do bumps as a dedicated stream (own branch, build + test verify), not inline with feature work.

package/payload/doc-templates/WORKSTREAMS.md

@@ -0,0 +1,79 @@
+---
+title: "Workstreams"
+tags: [groundwork/core]
+aliases: ["Workstreams", "Active Work", "Streams"]
+---
+
+# Workstreams
+
+> **Live state of every parallel stream of work.** The swarm-native replacement for a
+> single "current focus" — one row per stream, scales from solo to a coordinated fleet.
+
+This is the live counterpart to `[[QUEUE]]`:
+
+- **`[[QUEUE]]`** = the *inbound* queue — what to pick up next (human + `/plan-phase` own it).
+- **`WORKSTREAMS.md`** = the *live* state — what is in flight right now (whoever is working writes it, including a multi-agent coordinator).
+- **`[[DONE]]`** = the *completion log* — append-only, written by whoever executes.
+
+Update with `/update-workstreams`.
+
+---
+
+## Active Streams
+
+| Stream | Owner / Agent | Branch · Worktree | Status | Blocker | Last note |
+| ------ | ------------- | ----------------- | ------ | ------- | --------- |
+| —      | —             | —                 | ⏳ Queued | —    | Run `/kickstart`, then `/plan-phase` to populate the backlog |
+
+Status: 🚧 In Progress · 🔍 In Review · ⏳ Queued · ⛔ Blocked · ✅ Done
+
+---
+
+## Recently Closed
+
+_Closed streams move here with an outcome and date (YYYY-MM-DD)._
+
+---
+
+## Last Updated
+
+**Date**: (set on first update)
+**Status**: Template ready
+
+<!-- ─────────────────────── coordinator extensions ───────────────────────
+Present ONLY when a multi-agent coordinator runs this project (a solo
+/update-workstreams user never adds these). Under a coordinator, WORKSTREAMS.md
+is the single board — these sections replace the retired LIVE_STATE board.
+
+`/update-workstreams` and `groundwork status` parse only the core above
+(## Active Streams + ## Recently Closed) and MUST preserve everything below this
+fence verbatim. Write-regions:
+  · Active Streams / Recently Closed — shared; one row per owner; read-before-write CAS
+  · all sections below — coordinator-only, single-writer
+  · Needs David — coordinator writes; David clears
+
+When adopted, the coordinator materialises these sections (drop the comment):
+
+## Open PRs
+| Repo | PR | Owner | Status | Merge Gate |
+| ---- | -- | ----- | ------ | ---------- |
+
+## Cutover Gates    (State distinguishes merged≠deployed, code-complete≠ops-ready)
+| Gate | Owner | State | Notes |
+| ---- | ----- | ----- | ----- |
+
+## Needs David
+| Decision | Context | Recommendation |
+| -------- | ------- | -------------- |
+
+## Risks
+| Risk | Impact | Mitigation |
+| ---- | ------ | ---------- |
+
+## Rooms
+| Room | Purpose | Owner | State |
+| ---- | ------- | ----- | ----- |
+
+## Decisions Recorded
+- <ADR / decision ref>
+──────────────────────────────────────────────────────────────────────── -->

package/payload/doc-templates/_INDEX.md

@@ -0,0 +1,54 @@
+---
+title: "Groundwork Vault"
+tags: [groundwork/core]
+aliases: ["MOC", "Map of Content", "Index"]
+---
+
+# Project Docs
+
+Map of Content for this project's documentation (scaffolded by Groundwork).
+
+## Core
+
+- [[GROUNDWORK_METHODOLOGY]] — Full methodology, philosophy, workflow
+- [[CONTEXT]] — Ubiquitous-language glossary / domain model (via `/domain-model`)
+- [[WORKSTREAMS]] — Live state of parallel work streams
+- [[FACTS]] — Verified project facts (settled world-model)
+- [[STACK_MAP]] — Single source of truth for versions
+
+## Reference
+
+- [[ARTIFACTS]] — Artifact map: where each doc lives, who writes/reads it (agent reference)
+- [[COMMANDS]] — AI skill commands across Claude Code, Cursor, VS Code
+- [[DECISIONS]] — Architectural Decision Records (ADRs)
+
+## Project Artifacts
+
+These are generated by `/kickstart` for each new project:
+
+- `[[TECH_STACK]]` — Technology choices (generated)
+- `[[ARCHITECTURE_GUIDE]]` — System design (generated)
+- `[[PRODUCTION_ROADMAP]]` — Phase roadmap (generated)
+- `[[DESIGN_SYSTEM]]` — Visual language (generated, optional)
+- `[[PRD]]` — Product requirements (generated by `/create-prd`)
+- `[[QUEUE]]` — Inbound task queue (generated by `/kickstart`, updated by `/plan-phase`)
+- `[[DONE]]` — Completion log (append-only, written by whoever executes)
+
+## Templates
+
+Used by `/kickstart` and `/plan-phase` to scaffold project docs:
+
+- [[TECH_STACK_TEMPLATE]]
+- [[ARCHITECTURE_GUIDE_TEMPLATE]]
+- [[PRODUCTION_ROADMAP_TEMPLATE]]
+- [[DESIGN_SYSTEM_TEMPLATE]]
+- [[PRD_TEMPLATE]]
+- [[QUEUE_TEMPLATE]]
+- [[DONE_TEMPLATE]]
+- [[PHASES_README_TEMPLATE]]
+- [[PHASE_README_TEMPLATE]]
+- [[TASK_TEMPLATE]]
+
+## Phases
+
+- [[phases/README|Phases Overview]]

package/payload/doc-templates/phases/README.md

@@ -0,0 +1,36 @@
+---
+title: "Phases Overview"
+tags: [groundwork/phase]
+aliases: ["Phases"]
+---
+
+# Development Phases
+
+## Phase Organization
+
+Each phase has its own folder with:
+
+- [[README]] — Phase overview and quick reference
+- `PHASEN_TASKS.md` — Detailed task breakdown with checklists
+
+Use `/plan-phase` to generate a new phase.
+
+## Templates
+
+See `templates/` for phase document templates.
+
+## Progress Tracking
+
+- **Completed Phases**: 0
+- **Current Phase**: None (run `/kickstart` then `/plan-phase`)
+- **Overall Progress**: 0%
+
+## Documentation Standards
+
+Each phase follows the same structure:
+
+- Clear overview with goals and deliverables
+- Detailed task breakdown with checkboxes
+- Code examples and implementation patterns
+- Testing requirements
+- Success criteria

package/payload/doc-templates/phases/templates/README.md

@@ -0,0 +1,63 @@
+---
+title: "Phase Templates"
+tags: [groundwork/template]
+aliases: ["Task Templates"]
+---
+
+# Planning Templates
+
+This directory contains reusable templates for planning documents, tasks, and specifications.
+
+## Available Templates
+
+### Task Template
+
+**File**: [[TASK_TEMPLATE]]  
+**Purpose**: Standard template for task planning and tracking
+
+Use this template when:
+
+- Breaking down a feature into tasks
+- Planning a new implementation
+- Creating a work breakdown structure
+
+Sections included:
+
+- Task overview and objectives
+- Scope and deliverables
+- Implementation steps
+- Rollback plans for risky tasks
+- Testing requirements
+- Definition of done
+
+### Task Template Prompt
+
+**File**: [[task_template_prompt]]  
+**Purpose**: AI assistant prompt for generating task documents
+
+Use this when:
+
+- Working with AI assistants to plan tasks
+- Generating consistent task documentation
+- Ensuring comprehensive task breakdowns
+
+## Usage
+
+1. Copy the appropriate template
+2. Fill in the sections with your specific details
+3. Adjust sections as needed for your use case
+4. Save in the appropriate planning directory
+
+## Creating New Templates
+
+When creating new templates:
+
+1. Use clear section headings
+2. Include placeholder text with examples
+3. Document the template's purpose
+4. Add it to this README
+
+## Navigation
+
+- [[README|Back to Phases]]
+- Task Examples - See completed tasks using these templates (create a `completed/` directory as needed)

package/payload/doc-templates/phases/templates/TASK_TEMPLATE.md

@@ -0,0 +1,302 @@
+---
+title: "Task Template"
+tags: [groundwork/template]
+aliases: []
+---
+
+# [PROJECT NAME] [TASK TYPE] Tasks
+
+## Overview
+
+[Brief description of the project/task. Explain what is being migrated/refactored/implemented and why it's necessary.]
+
+## 🔍 [TASK TYPE] Audit Summary
+
+**CRITICAL FINDINGS**: [Summary of key discoveries during initial analysis]
+
+### 📊 **Components [TO BE MIGRATED/IMPLEMENTED]**:
+
+- **[Category 1]**: [Number] [Component Type] ([specific examples])
+- **[Category 2]**: [Number] [Component Type] ([specific examples])
+- **[Category 3]**: [Number] [Component Type] ([specific examples])
+- **[Supporting Infrastructure]**: [Details about supporting files, configs, etc.]
+
+### ⚠️ **Impact Assessment**:
+
+- **[Risk Type 1]**: [Description of risk and potential impact]
+- **[Risk Type 2]**: [Description of risk and potential impact]
+- **[Risk Type 3]**: [Description of risk and potential impact]
+- **[Architecture Impact]**: [How this affects system architecture]
+
+### 📈 **Scale of [TASK TYPE]**:
+
+- **[X] Major Tasks** ([Task IDs]) → ✅ **[Y] COMPLETE**, **[Z] REMAINING**
+- **[X]+ Sub-Steps** → ✅ **[Y] COMPLETED**, **[Z]+ REMAINING**
+- **[X-Y] Days** estimated completion time → **~[Z] Days REMAINING**
+- **[X] [Task Type] Phases** from [priority level] to [priority level]
+
+### 🎉 **COMPLETED [TASKS]**:
+
+- ✅ **[Task ID]: [Task Name]** - [Brief description of what was accomplished] ([metrics, lines of code, endpoints, etc.])
+- ✅ **[Task ID]: [Task Name]** - [Brief description of what was accomplished] ([metrics])
+
+## 🚨 Components Not Yet [MIGRATED/IMPLEMENTED]
+
+### [Category 1] ([source location/])
+
+- **[Component Name]** - [Description and importance] ([line count/size if relevant])
+- **[Component Name]** - [Description and importance] ([line count/size if relevant])
+
+### [Category 2] ([source location/])
+
+- **[Component Name]** - [Description and purpose]
+- **[Component Name]** - [Description and purpose]
+
+### [Additional Categories as needed]
+
+[Continue pattern for all major categories of components]
+
+## 🎯 Target Architecture
+
+### [System] Structure
+
+```
+[target structure]/
+├── [package1]/           # [Purpose and contents]
+│   ├── [subdir]/        # [Purpose]
+│   └── [subdir]/        # [Purpose]
+├── [package2]/           # [Purpose and contents]
+├── [package3]/           # [Purpose and contents]
+└── [package4]/           # [Purpose and contents]
+```
+
+### [Integration] Pattern
+
+- **[Pattern 1]**: [Description of how components will work together]
+- **[Pattern 2]**: [Description of architectural decision]
+- **[Pattern 3]**: [Description of key principle]
+- **[Pattern 4]**: [Description of important constraint]
+
+### Architecture Principles
+
+1. **[Principle 1]**: [Description]
+2. **[Principle 2]**: [Description]
+3. **[Principle 3]**: [Description]
+4. **[Principle 4]**: [Description]
+5. **[Principle 5]**: [Description]
+
+## 📋 [Task Type] Tasks
+
+### Phase 1: [Phase Name - Priority Level]
+
+#### [x] Task [ID]: [Task Name]
+
+**Priority**: [CRITICAL/HIGH/MEDIUM/LOW] ✅ **[STATUS]**
+**Package**: `[target location]`
+**Dependencies**:
+
+- [Dependency 1 description]
+- [Dependency 2 description]
+- [Dependency 3 description]
+
+**Sub-Steps**:
+
+- [x] [Task ID].[Sub-ID]: [Detailed sub-task description]
+- [x] [Task ID].[Sub-ID]: [Detailed sub-task description]
+- [ ] [Task ID].[Sub-ID]: [Detailed sub-task description]
+- [ ] [Task ID].[Sub-ID]: [Detailed sub-task description]
+- [ ] [Task ID].[Sub-ID]: **[Special task category if needed]**
+- [ ] [Task ID].[Sub-ID]: **Add OpenAPI annotations for [task] endpoints**
+- [ ] [Task ID].[Sub-ID]: **Create OpenAPI schemas for [component] requests/responses**
+- [ ] [Task ID].[Sub-ID]: **Document [service endpoints] endpoints with OpenAPI**
+- [ ] [Task ID].[Sub-ID]: **Update main OpenAPI spec to include [service]**
+- [ ] [Task ID].[Sub-ID]: **Make sure everything builds**
+- [ ] [Task ID].[Sub-ID]: **Make sure everything is in running condition**
+
+**[✅ COMPLETION STATUS]**: [Detailed summary of what was accomplished, metrics, and current status]
+
+#### [ ] Task [ID]: [Task Name]
+
+**Priority**: [PRIORITY LEVEL]
+**Package**: `[target location]`
+**Dependencies**:
+
+- [Dependencies listed]
+
+**Sub-Steps**:
+
+- [ ] [Task ID].[Sub-ID]: [Sub-task description]
+- [ ] [Task ID].[Sub-ID]: [Sub-task description]
+
+**Expected Deliverables**:
+
+- **[Deliverable 1]**: [Description of what will be created]
+- **[Deliverable 2]**: [Description of what will be created]
+- **[Integration/API Component]**: [Description of interfaces/endpoints]
+- **[Documentation]**: [Description of docs to be created]
+
+**Interfaces / contracts** _(if the task introduces or changes any — signatures only, no bodies)_:
+
+```ts
+// types, function/method signatures, endpoint shapes, table columns
+```
+
+**🔄 Rollback Plan** _(for risky tasks)_:
+
+- **Revert trigger**: [Condition that triggers rollback - e.g., "Tests fail after migration"]
+- **Rollback steps**: [How to undo - e.g., "git revert to commit X, restore DB backup"]
+- **Data recovery**: [If applicable - backup locations, restore procedures]
+- **Notification**: [Who to inform if rollback occurs]
+
+### Phase 2: [Phase Name - Priority Level]
+
+[Continue pattern for remaining phases...]
+
+### Phase [N]: [Final Phase Name]
+
+#### [ ] Task [ID]: [Final Task Name]
+
+**Priority**: [PRIORITY]
+**Package**: [Location]
+**Dependencies**:
+
+- [All previous tasks must be complete]
+- [Any specific dependencies]
+
+**Sub-Steps**:
+
+- [ ] [Task ID].1: **[Audit/Review step]**
+- [ ] [Task ID].2: **[Validation step]**
+- [ ] [Task ID].3: **[Documentation step]**
+- [ ] [Task ID].[N]: **[Final verification step]**
+
+**🎯 SUCCESS CRITERIA**: [Detailed description of how to know this phase is complete]
+
+## 🎯 Success Criteria
+
+### Functional Requirements
+
+- [ ] [Functional requirement 1]
+- [ ] [Functional requirement 2]
+- [ ] [Functional requirement 3]
+- [ ] [Performance/metrics requirement]
+- [ ] [Quality requirement]
+
+### Quality Requirements
+
+- [ ] [Quality gate 1]
+- [ ] [Quality gate 2]
+- [ ] [Documentation requirement]
+- [ ] [Security requirement]
+- [ ] [Performance requirement]
+
+### Architecture Requirements
+
+- [ ] [Architecture validation 1]
+- [ ] [Architecture validation 2]
+- [ ] [Build/deployment requirement]
+- [ ] [Development workflow requirement]
+- [ ] [Production readiness requirement]
+
+## 🤔 Low-confidence decisions
+
+_The choices in this plan the author is least sure about — naming, boundaries, library picks,
+task ordering — and why. Review these first; they are cheap to change before code exists._
+
+- **[Decision]**: [Why uncertain] — [alternative considered]
+- **[Decision]**: [Why uncertain] — [alternative considered]
+
+## 📅 Estimated Timeline
+
+**Phase 1 ([Phase Name])**: [X-Y] days
+
+- [Brief description of what's included]
+- [Number]+ sub-steps across [X] major [components/services]
+
+**Phase 2 ([Phase Name])**: [X-Y] days
+
+- [Brief description of what's included]
+- [Number]+ sub-steps for [category description]
+
+**Phase [N] ([Final Phase])**: [X-Y] days
+
+- [Brief description of what's included]
+- [Number]+ sub-steps for [category description]
+
+**Total Estimated Time**: [X-Y] days → **~[Z] Days REMAINING** ✅ **[A] Days COMPLETED**
+**Total Sub-Steps**: [X]+ detailed checkboxes → ✅ **[Y] COMPLETED**, **[Z]+ REMAINING**
+**[Special Category] Tasks**: [X]+ dedicated sub-steps → ✅ **[Y] COMPLETED**, **[Z]+ REMAINING**
+
+## 🚀 [Task Type] Progress
+
+1. ✅ **Task [ID] ([Name])** - [STATUS] with [metrics/deliverables]
+2. ✅ **Task [ID] ([Name])** - [STATUS] with [metrics/deliverables]
+3. 🚧 **Task [ID] ([Name])** - [IN PROGRESS] with [current status]
+4. Continue with remaining tasks by priority
+5. Validate each phase before proceeding to the next
+
+## 🎯 **CURRENT STATUS**: [X]/[Y] Major Tasks [Status] ([Z]% Progress)
+
+**✅ PREVIOUS COMPLETION**: [Description of most recently completed major task with detailed summary]
+
+**🚧 CURRENT WORK**: [Description of current task in progress with detailed progress summary]
+
+**🎯 NEXT**: [Description of next steps and upcoming tasks]
+
+## 🔄 Rollback & Contingency Plans
+
+> _For phases with significant risk, document how to safely undo changes._
+
+### High-Risk Tasks Identified
+
+| Task     | Risk Level | Rollback Complexity | Backup Required      |
+| -------- | ---------- | ------------------- | -------------------- |
+| Task X.X | 🔴 High    | Medium              | ✅ Yes - DB snapshot |
+| Task Y.Y | 🟡 Medium  | Low                 | ❌ No - code only    |
+
+### Pre-Phase Checklist
+
+- [ ] Database backup created: `[backup location/timestamp]`
+- [ ] Current branch tagged: `git tag pre-phase-N-backup`
+- [ ] Dependent services notified of potential rollback window
+- [ ] Rollback runbook reviewed by team
+
+### Emergency Rollback Procedure
+
+**If critical failure occurs:**
+
+1. **Stop** - Don't make additional changes
+2. **Assess** - Identify what broke and impact scope
+3. **Communicate** - Notify stakeholders: [contact list]
+4. **Rollback** - Execute steps below:
+
+```bash
+# Code rollback
+git revert --no-commit HEAD~N  # N = number of commits to undo
+git commit -m "Rollback: [reason]"
+
+# Database rollback (if applicable)
+# [Database-specific restore commands]
+```
+
+5. **Verify** - Run smoke tests to confirm system stability
+6. **Document** - Add post-mortem notes to this section
+
+### Post-Mortem Notes
+
+_Add notes here if rollback was executed:_
+
+- **Date**:
+- **Trigger**:
+- **Resolution**:
+- **Prevention**:
+
+---
+
+## 📝 Notes
+
+- [Important note about testing/validation requirements]
+- [Note about documentation requirements]
+- [Note about compatibility requirements]
+- [Note about migration/change management]
+- [Note about automation/tooling considerations]