@davidbalzan/groundwork 0.3.1

package/payload/doc-templates/templates/PRD_TEMPLATE.md

@@ -0,0 +1,348 @@
+---
+title: "PRD Template"
+tags: [groundwork/template]
+aliases: []
+---
+
+# Product Requirements Document: [Product Name]
+
+**Version**: 1.0
+**Status**: Draft | Review | Approved
+**Created**: [Date]
+**Last Updated**: [Date]
+**Author**: [Name]
+
+---
+
+## 1. Executive Summary
+
+> A brief 2-3 sentence overview of what we're building and why it matters.
+
+[Summarize the product, its core value proposition, and the primary problem it solves.]
+
+---
+
+## 2. Problem Statement
+
+### The Problem
+
+[Describe the specific problem users face. Be concrete and measurable.]
+
+### Current State
+
+[How do users currently solve this problem? What are the pain points?]
+
+### Impact
+
+- **Who is affected**: [User segments]
+- **How often**: [Frequency of the problem]
+- **Severity**: [Low/Medium/High/Critical]
+- **Business impact**: [Revenue, churn, efficiency loss, etc.]
+
+---
+
+## 3. Vision & Goals
+
+### Product Vision
+
+> [One sentence describing the ideal future state]
+
+### Goals
+
+| Goal     | Metric         | Target         | Timeline |
+| -------- | -------------- | -------------- | -------- |
+| [Goal 1] | [How measured] | [Target value] | [When]   |
+| [Goal 2] | [How measured] | [Target value] | [When]   |
+| [Goal 3] | [How measured] | [Target value] | [When]   |
+
+### Non-Goals (Out of Scope)
+
+- [What we are explicitly NOT building]
+- [Features deferred to future versions]
+- [Adjacent problems we won't address]
+
+---
+
+## 4. User Personas & Stories
+
+### Primary Persona: [Name]
+
+- **Role**: [Job title/role]
+- **Goal**: [What they want to achieve]
+- **Pain Points**: [Current frustrations]
+- **Tech Savviness**: [Low/Medium/High]
+
+### Secondary Persona: [Name]
+
+- **Role**: [Job title/role]
+- **Goal**: [What they want to achieve]
+- **Pain Points**: [Current frustrations]
+
+### User Stories
+
+#### Epic: [Epic Name]
+
+| ID     | As a...   | I want to... | So that... | Priority    |
+| ------ | --------- | ------------ | ---------- | ----------- |
+| US-001 | [persona] | [action]     | [benefit]  | Must Have   |
+| US-002 | [persona] | [action]     | [benefit]  | Should Have |
+| US-003 | [persona] | [action]     | [benefit]  | Could Have  |
+
+---
+
+## 5. Functional Requirements
+
+### 5.1 Core Features
+
+#### Feature 1: [Feature Name]
+
+**Priority**: Must Have | Should Have | Could Have | Won't Have
+
+**Description**: [What it does]
+
+**Acceptance Criteria**:
+
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+**User Flow**:
+
+```
+1. User [action]
+2. System [response]
+3. User [action]
+4. System [response]
+```
+
+#### Feature 2: [Feature Name]
+
+**Priority**: [Priority]
+
+**Description**: [What it does]
+
+**Acceptance Criteria**:
+
+- [ ] [Criterion]
+- [ ] [Criterion]
+
+### 5.2 Feature Priority Matrix
+
+| Feature     | Priority    | Complexity | Dependencies | Phase |
+| ----------- | ----------- | ---------- | ------------ | ----- |
+| [Feature 1] | Must Have   | Medium     | None         | 1     |
+| [Feature 2] | Should Have | High       | Feature 1    | 2     |
+| [Feature 3] | Could Have  | Low        | None         | 2     |
+
+---
+
+## 6. Non-Functional Requirements
+
+### 6.1 Performance
+
+| Metric            | Requirement | Measurement  |
+| ----------------- | ----------- | ------------ |
+| Page Load Time    | < 2 seconds | p95 latency  |
+| API Response Time | < 200ms     | p95 latency  |
+| Concurrent Users  | 10,000      | Load testing |
+| Uptime            | 99.9%       | Monthly SLA  |
+
+### 6.2 Security
+
+- [ ] Authentication: [Method - JWT, OAuth, etc.]
+- [ ] Authorization: [RBAC, ABAC, etc.]
+- [ ] Data Encryption: [At rest, in transit]
+- [ ] Compliance: [GDPR, SOC2, HIPAA, etc.]
+- [ ] Audit Logging: [What events to log]
+
+### 6.3 Scalability
+
+- **Initial Scale**: [Expected users/data at launch]
+- **Growth Target**: [Expected scale in 12 months]
+- **Scaling Strategy**: [Horizontal/vertical, cloud provider]
+
+### 6.4 Accessibility
+
+- [ ] WCAG 2.1 Level AA compliance
+- [ ] Screen reader support
+- [ ] Keyboard navigation
+- [ ] Color contrast requirements
+
+### 6.5 Internationalization
+
+- [ ] Languages supported: [List]
+- [ ] RTL support: [Yes/No]
+- [ ] Currency/date localization: [Yes/No]
+
+---
+
+## 7. Technical Constraints
+
+### Technology Stack
+
+| Layer          | Technology         | Version      | Rationale    |
+| -------------- | ------------------ | ------------ | ------------ |
+| Frontend       | [e.g., React]      | [e.g., 19.x] | [Why chosen] |
+| Backend        | [e.g., Node.js]    | [e.g., 22.x] | [Why chosen] |
+| Database       | [e.g., PostgreSQL] | [e.g., 17]   | [Why chosen] |
+| Infrastructure | [e.g., AWS]        | -            | [Why chosen] |
+
+### Integration Requirements
+
+| System     | Type    | Purpose   | Priority |
+| ---------- | ------- | --------- | -------- |
+| [System 1] | API     | [Purpose] | Required |
+| [System 2] | Webhook | [Purpose] | Optional |
+
+### Constraints & Limitations
+
+- **Budget**: [If applicable]
+- **Timeline**: [Hard deadlines]
+- **Team Size**: [Available resources]
+- **Legacy Systems**: [What must be maintained]
+- **Regulatory**: [Compliance requirements]
+
+---
+
+## 8. Data Requirements
+
+### Data Model Overview
+
+```
+[High-level ERD or description of key entities]
+
+Entity: User
+- id, email, name, created_at, updated_at
+
+Entity: [Other entities]
+```
+
+### Data Migration
+
+- [ ] Migration from existing system required: [Yes/No]
+- [ ] Data volume: [Estimated records]
+- [ ] Migration strategy: [Big bang, phased, parallel run]
+
+### Data Retention & Privacy
+
+- **Retention Period**: [How long data is kept]
+- **PII Handling**: [How personal data is managed]
+- **Data Deletion**: [User data deletion process]
+
+---
+
+## 9. Success Metrics & KPIs
+
+### Primary Metrics
+
+| Metric     | Current    | Target | Measurement Method |
+| ---------- | ---------- | ------ | ------------------ |
+| [Metric 1] | [Baseline] | [Goal] | [How measured]     |
+| [Metric 2] | [Baseline] | [Goal] | [How measured]     |
+
+### Secondary Metrics
+
+| Metric   | Target | Purpose          |
+| -------- | ------ | ---------------- |
+| [Metric] | [Goal] | [Why it matters] |
+
+### Success Criteria
+
+**MVP is successful if**:
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+---
+
+## 10. Risks & Mitigations
+
+| Risk     | Probability  | Impact       | Mitigation       | Owner |
+| -------- | ------------ | ------------ | ---------------- | ----- |
+| [Risk 1] | High/Med/Low | High/Med/Low | [How to address] | [Who] |
+| [Risk 2] | High/Med/Low | High/Med/Low | [How to address] | [Who] |
+| [Risk 3] | High/Med/Low | High/Med/Low | [How to address] | [Who] |
+
+### Assumptions
+
+- [Assumption 1]
+- [Assumption 2]
+- [Assumption 3]
+
+### Dependencies
+
+- [External dependency 1]
+- [External dependency 2]
+
+---
+
+## 11. Timeline & Phases
+
+### High-Level Roadmap
+
+```
+Phase 1: Foundation (Weeks 1-4)
+├── [Deliverable 1]
+├── [Deliverable 2]
+└── [Deliverable 3]
+
+Phase 2: Core Features (Weeks 5-8)
+├── [Deliverable 1]
+├── [Deliverable 2]
+└── [Deliverable 3]
+
+Phase 3: Polish & Launch (Weeks 9-12)
+├── [Deliverable 1]
+├── [Deliverable 2]
+└── [Deliverable 3]
+```
+
+### Milestones
+
+| Milestone    | Target Date | Deliverables      |
+| ------------ | ----------- | ----------------- |
+| MVP Complete | [Date]      | [What's included] |
+| Beta Launch  | [Date]      | [What's included] |
+| GA Launch    | [Date]      | [What's included] |
+
+---
+
+## 12. Open Questions
+
+| #   | Question   | Owner | Due Date | Resolution             |
+| --- | ---------- | ----- | -------- | ---------------------- |
+| 1   | [Question] | [Who] | [When]   | [Answer when resolved] |
+| 2   | [Question] | [Who] | [When]   | [Answer when resolved] |
+
+---
+
+## 13. Appendix
+
+### A. Glossary
+
+| Term   | Definition   |
+| ------ | ------------ |
+| [Term] | [Definition] |
+
+### B. References
+
+- [Link to related documents]
+- [Link to research]
+- [Link to competitive analysis]
+
+### C. Revision History
+
+| Version | Date   | Author | Changes       |
+| ------- | ------ | ------ | ------------- |
+| 1.0     | [Date] | [Name] | Initial draft |
+
+---
+
+## Approval
+
+| Role          | Name | Date | Signature |
+| ------------- | ---- | ---- | --------- |
+| Product Owner |      |      |           |
+| Tech Lead     |      |      |           |
+| Stakeholder   |      |      |           |

package/payload/doc-templates/templates/PRODUCTION_ROADMAP_TEMPLATE.md

@@ -0,0 +1,168 @@
+---
+title: "Production Roadmap Template"
+tags: [groundwork/template]
+aliases: ["Roadmap Template"]
+---
+
+# [Project Name] - Production Roadmap
+
+> Single source of truth for the project's journey from current state to production readiness. Updated as phases progress and priorities shift.
+
+---
+
+## 🎯 Current Status
+
+> For the live state of all in-flight work streams, see `[[WORKSTREAMS]]`. This section is the high-level phase pointer; `[[WORKSTREAMS]]` is the per-stream detail.
+
+**Phase**: Phase [N] - [Phase Name — the active development phase]
+**Task**: [Current task name — the specific work item being executed right now]
+**Status**: [🚧 In Progress / ⏸️ Blocked / ✅ Complete — current execution status]
+**Branch**: `[branch-name — the git branch where active work is happening]`
+**Blocking Issues**: [List any blockers preventing progress, or "None" if unblocked]
+
+---
+
+## 📊 Current State Assessment
+
+### ✅ What We Have
+
+- [Feature/capability that is built and working — describe functional state, e.g., "Authentication with JWT tokens, tested against PostgreSQL"]
+- [Feature/capability that is built and working — include quality indicators like test coverage or performance metrics]
+- [Feature/capability that is built and working — note any limitations or known issues]
+- [Infrastructure that is set up — e.g., "CI/CD pipeline with GitHub Actions, deploys to staging on merge"]
+
+### 🚨 What's Missing for Production
+
+- [Critical gap — describe what's missing, why it matters, and the risk of shipping without it, e.g., "Rate limiting: API is vulnerable to abuse without request throttling"]
+- [Critical gap — describe impact on users/business, e.g., "Error monitoring: No visibility into production failures, mean time to detect is unknown"]
+- [Critical gap — describe technical debt or quality concern, e.g., "Test coverage at 45%: Key user flows untested, refactoring is risky"]
+- [Critical gap — describe operational concern, e.g., "No database backup strategy: Single point of failure for all user data"]
+
+### 📈 Production Readiness Score
+
+- **Functional Completeness**: [X]% — [Brief explanation of what's included in this assessment]
+- **Test Coverage**: [X]% — [Current coverage and target, e.g., "45% current → 80% target"]
+- **Security Posture**: [Low/Medium/High] — [Brief assessment, e.g., "Auth works but no rate limiting, CORS too permissive"]
+- **Operational Readiness**: [Low/Medium/High] — [Brief assessment, e.g., "No monitoring, no alerting, manual deploys"]
+
+---
+
+## 🗺️ Phase Overview
+
+### Phase 1: [Phase Name — e.g., "Foundation & Core Infrastructure"]
+
+**Goal**: [One-liner that describes the measurable outcome of this phase, e.g., "Users can sign up, log in, and access the main dashboard with data persisted in PostgreSQL"]
+**Duration**: [X] weeks — [Brief justification for estimate, e.g., "Based on 3 major features with 2-3 day estimates each"]
+**Status**: [🟢 Complete / 🟡 In Progress / ⚪ Not Started]
+
+**Key Deliverables**:
+
+- [ ] [Deliverable with acceptance criteria — e.g., "User authentication: signup, login, logout, password reset flows all functional with email verification"]
+- [ ] [Deliverable with acceptance criteria — e.g., "Database schema: Core tables created with migrations, seeding script for dev data"]
+- [ ] [Deliverable with acceptance criteria — e.g., "API health monitoring: /health endpoint returns status, uptime, and version"]
+
+**Dependencies**: [What must exist before this phase starts — e.g., "None — this is the foundation phase"]
+**Risks**: [Primary risk and mitigation — e.g., "Schema design may need revision; mitigate by starting with minimal viable schema"]
+
+---
+
+### Phase 2: [Phase Name — e.g., "Core Features & Business Logic"]
+
+**Goal**: [One-liner measurable outcome, e.g., "All primary user workflows are functional, tested, and performant under expected load"]
+**Duration**: [X] weeks — [Brief justification]
+**Status**: [🟢 Complete / 🟡 In Progress / ⚪ Not Started]
+
+**Key Deliverables**:
+
+- [ ] [Deliverable with acceptance criteria — describe what "done" looks like for this feature]
+- [ ] [Deliverable with acceptance criteria — include measurable targets where possible]
+- [ ] [Deliverable with acceptance criteria — note integration points with other phases]
+
+**Dependencies**: [What must be complete — e.g., "Phase 1 complete: auth, database, and core API operational"]
+**Risks**: [Primary risk — e.g., "Third-party API integration may have rate limits; mitigate with caching layer"]
+
+---
+
+### Phase 3: [Phase Name — e.g., "Polish, Security & Production Hardening"]
+
+**Goal**: [One-liner measurable outcome, e.g., "Application is secure, performant, monitored, and ready for public launch"]
+**Duration**: [X] weeks — [Brief justification]
+**Status**: [🟢 Complete / 🟡 In Progress / ⚪ Not Started]
+
+**Key Deliverables**:
+
+- [ ] [Deliverable with acceptance criteria — e.g., "Rate limiting: 100 req/min per IP on public endpoints, 1000 req/min for authenticated"]
+- [ ] [Deliverable with acceptance criteria — e.g., "Error monitoring: Sentry integrated, alerts configured for error rate > 1%"]
+
+**Dependencies**: [What must be complete — e.g., "Phase 2 complete: all core features functional and tested"]
+**Risks**: [Primary risk — e.g., "Performance optimization may reveal architectural issues; budget extra time for refactoring"]
+
+---
+
+## 📊 Implementation Priority Matrix
+
+| Phase           | Priority                            | Blocks Other Phases?           | Complexity                              | Duration  | Key Risk                |
+| --------------- | ----------------------------------- | ------------------------------ | --------------------------------------- | --------- | ----------------------- |
+| Phase 1: [Name] | [🔴 Critical / 🟡 High / 🟢 Medium] | [Yes → blocks Phase 2, 3 / No] | [Low/Medium/High — brief justification] | [X weeks] | [One-line risk summary] |
+| Phase 2: [Name] | [Priority]                          | [What it blocks]               | [Complexity]                            | [X weeks] | [Risk summary]          |
+| Phase 3: [Name] | [Priority]                          | [What it blocks]               | [Complexity]                            | [X weeks] | [Risk summary]          |
+
+**Critical Path**: [Describe the sequence of dependent phases that determines the minimum project duration, e.g., "Phase 1 → Phase 2 → Phase 3 (sequential, ~12 weeks total)"]
+
+---
+
+## ⚡ Quick Wins (Can Start Immediately)
+
+> Tasks that provide immediate value with minimal risk and effort. Execute these in parallel with phase work.
+
+1. **[Quick win name]** ([estimated duration, e.g., "2 hours"])
+   - [What to do — be specific enough that a developer can start immediately]
+   - [Expected impact — e.g., "Reduces page load by ~200ms" or "Fixes confusing error message"]
+   - [How to validate — e.g., "Run lighthouse audit, confirm score > 90"]
+
+2. **[Quick win name]** ([estimated duration])
+   - [What to do]
+   - [Expected impact]
+
+3. **[Quick win name]** ([estimated duration])
+   - [What to do]
+   - [Expected impact]
+
+---
+
+## 📈 Success Metrics
+
+### Technical Metrics
+
+- [ ] [Metric with specific target — e.g., "API response time: p95 < 200ms for all endpoints"]
+- [ ] [Metric with specific target — e.g., "Test coverage: > 80% line coverage across all packages"]
+- [ ] [Metric with specific target — e.g., "Build time: < 60 seconds for full production build"]
+- [ ] [Metric with specific target — e.g., "Zero critical/high severity security vulnerabilities"]
+
+### Business Metrics
+
+- [ ] [Metric with specific target — e.g., "User onboarding: < 2 minutes from signup to first value"]
+- [ ] [Metric with specific target — e.g., "Uptime: 99.9% availability during business hours"]
+
+### Operational Metrics
+
+- [ ] [Metric with specific target — e.g., "Mean time to detect failures: < 5 minutes"]
+- [ ] [Metric with specific target — e.g., "Deployment frequency: ability to deploy multiple times per day"]
+
+---
+
+## 🔄 Revision History
+
+| Date                       | Change                  | Reason                                     |
+| -------------------------- | ----------------------- | ------------------------------------------ |
+| [Date of initial creation] | Initial roadmap created | [Project kickoff / sprint planning / etc.] |
+
+---
+
+## 🔗 Related Documents
+
+- **[[TECH_STACK|Tech Stack]]** - Technology choices and versions
+- **[[ARCHITECTURE_GUIDE|Architecture Guide]]** - System design and patterns
+- **[[DECISIONS|Decisions Log]]** - Architectural Decision Records
+- **[Phase Details](./phases/)** - Detailed phase task breakdowns with checklists
+- **[[WORKSTREAMS|Workstreams]]** - Live state of parallel work streams

package/payload/doc-templates/templates/QUEUE_TEMPLATE.md

@@ -0,0 +1,17 @@
+# QUEUE — <project>
+
+The inbound task queue. Phases are planned via `/plan-phase` and appear here as single items
+referencing the full task breakdown. Ad-hoc tasks (bug fixes, improvements) are added directly by
+the human. This file is intake only: live in-flight state lives in [[WORKSTREAMS]], completions
+are recorded in `docs/DONE.md`.
+
+**Write rule (single writer per file):** the human (or their planning proxy) writes here — add /
+reorder / remove / edit items, set priority (`P1`/`P2`/`P3`; top-to-bottom breaks ties), add
+constraints, acceptance criteria, or refs inline. Whoever executes work never edits this file — it
+reads the top unblocked item fresh and appends the completion to `docs/DONE.md` instead. Pruning
+satisfied items is the writer's job. No compare-and-swap ceremony needed: the filesystem enforces
+the boundary.
+
+## Queue
+
+- [ ] (P1) Phase 1: [Phase Name] — see [[phases/phase1/PHASE1_TASKS]] · acceptance: all Phase 1 success criteria met