@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/templates/project.md

@@ -0,0 +1,184 @@
+# PROJECT.md Template
+
+Template for `.planning/PROJECT.md` — the living project context document.
+
+<template>
+
+```markdown
+# [Project Name]
+
+## What This Is
+
+[Current accurate description — 2-3 sentences. What does this product do and who is it for?
+Use the user's language and framing. Update whenever reality drifts from this description.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.
+One sentence that drives prioritization when tradeoffs arise.]
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. -->
+
+(None yet — ship to validate)
+
+### Active
+
+<!-- Current scope. Building toward these. -->
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
+
+- [Exclusion 1] — [why]
+- [Exclusion 2] — [why]
+
+## Context
+
+[Background information that informs implementation:
+- Technical environment or ecosystem
+- Relevant prior work or experience
+- User research or feedback themes
+- Known issues to address]
+
+## Constraints
+
+- **[Type]**: [What] — [Why]
+- **[Type]**: [What] — [Why]
+
+Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+
+---
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**What This Is:**
+- Current accurate description of the product
+- 2-3 sentences capturing what it does and who it's for
+- Use the user's words and framing
+- Update when the product evolves beyond this description
+
+**Core Value:**
+- The single most important thing
+- Everything else can fail; this cannot
+- Drives prioritization when tradeoffs arise
+- Rarely changes; if it does, it's a significant pivot
+
+**Requirements — Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- ✓ [Requirement] — [version/phase]`
+- These are locked — changing them requires explicit discussion
+
+**Requirements — Active:**
+- Current scope being built toward
+- These are hypotheses until shipped and validated
+- Move to Validated when shipped, Out of Scope if invalidated
+
+**Requirements — Out of Scope:**
+- Explicit boundaries on what we're not building
+- Always include reasoning (prevents re-adding later)
+- Includes: considered and rejected, deferred to future, explicitly excluded
+
+**Context:**
+- Background that informs implementation decisions
+- Technical environment, prior work, user feedback
+- Known issues or technical debt to address
+- Update as new context emerges
+
+**Constraints:**
+- Hard limits on implementation choices
+- Tech stack, timeline, budget, compatibility, dependencies
+- Include the "why" — constraints without rationale get questioned
+
+**Key Decisions:**
+- Significant choices that affect future work
+- Add decisions as they're made throughout the project
+- Track outcome when known:
+  - ✓ Good — decision proved correct
+  - ⚠️ Revisit — decision may need reconsideration
+  - — Pending — too early to evaluate
+
+**Last Updated:**
+- Always note when and why the document was updated
+- Format: `after Phase 2` or `after v1.0 milestone`
+- Triggers review of whether content is still accurate
+
+</guidelines>
+
+<evolution>
+
+PROJECT.md evolves throughout the project lifecycle.
+
+**After each phase transition:**
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone:**
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state (users, feedback, metrics)
+
+</evolution>
+
+<brownfield>
+
+For existing codebases:
+
+1. **Map codebase first** via `/pbr:map-codebase`
+
+2. **Infer Validated requirements** from existing code:
+   - What does the codebase actually do?
+   - What patterns are established?
+   - What's clearly working and relied upon?
+
+3. **Gather Active requirements** from user:
+   - Present inferred current state
+   - Ask what they want to build next
+
+4. **Initialize:**
+   - Validated = inferred from existing code
+   - Active = user's goals for this work
+   - Out of Scope = boundaries user specifies
+   - Context = includes current codebase state
+
+</brownfield>
+
+<state_reference>
+
+STATE.md references PROJECT.md:
+
+```markdown
+## Project Reference
+
+See: .planning/PROJECT.md (updated [date])
+
+**Core value:** [One-liner from Core Value section]
+**Current focus:** [Current phase name]
+```
+
+This ensures Claude reads current PROJECT.md context.
+
+</state_reference>

package/plan-build-run/templates/requirements.md

@@ -0,0 +1,231 @@
+# Requirements Template
+
+Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done."
+
+<template>
+
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### [Category 2]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+- [ ] **[CAT]-03**: [Requirement description]
+
+### [Category 3]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### [Category]
+
+- **[CAT]-01**: [Requirement description]
+- **[CAT]-02**: [Requirement description]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| [REQ-ID] | Phase [N] | Pending |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Mapped to phases: [Y]
+- Unmapped: [Z] ⚠️
+
+---
+*Requirements defined: [date]*
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**Requirement Format:**
+- ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
+- Description: User-centric, testable, atomic
+- Checkbox: Only for v1 requirements (v2 are not yet actionable)
+
+**Categories:**
+- Derive from research FEATURES.md categories
+- Keep consistent with domain conventions
+- Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
+
+**v1 vs v2:**
+- v1: Committed scope, will be in roadmap phases
+- v2: Acknowledged but deferred, not in current roadmap
+- Moving v2 → v1 requires roadmap update
+
+**Out of Scope:**
+- Explicit exclusions with reasoning
+- Prevents "why didn't you include X?" later
+- Anti-features from research belong here with warnings
+
+**Traceability:**
+- Empty initially, populated during roadmap creation
+- Each requirement maps to exactly one phase
+- Unmapped requirements = roadmap gap
+
+**Status Values:**
+- Pending: Not started
+- In Progress: Phase is active
+- Complete: Requirement verified
+- Blocked: Waiting on external factor
+
+</guidelines>
+
+<evolution>
+
+**After each phase completes:**
+1. Mark covered requirements as Complete
+2. Update traceability status
+3. Note any requirements that changed scope
+
+**After roadmap updates:**
+1. Verify all v1 requirements still mapped
+2. Add new requirements if scope expanded
+3. Move requirements to v2/out of scope if descoped
+
+**Requirement completion criteria:**
+- Requirement is "Complete" when:
+  - Feature is implemented
+  - Feature is verified (tests pass, manual check done)
+  - Feature is committed
+
+</evolution>
+
+<example>
+
+```markdown
+# Requirements: CommunityApp
+
+**Defined:** 2025-01-14
+**Core Value:** Users can share and discuss content with people who share their interests
+
+## v1 Requirements
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### Profiles
+
+- [ ] **PROF-01**: User can create profile with display name
+- [ ] **PROF-02**: User can upload avatar image
+- [ ] **PROF-03**: User can write bio (max 500 chars)
+- [ ] **PROF-04**: User can view other users' profiles
+
+### Content
+
+- [ ] **CONT-01**: User can create text post
+- [ ] **CONT-02**: User can upload image with post
+- [ ] **CONT-03**: User can edit own posts
+- [ ] **CONT-04**: User can delete own posts
+- [ ] **CONT-05**: User can view feed of posts
+
+### Social
+
+- [ ] **SOCL-01**: User can follow other users
+- [ ] **SOCL-02**: User can unfollow users
+- [ ] **SOCL-03**: User can like posts
+- [ ] **SOCL-04**: User can comment on posts
+- [ ] **SOCL-05**: User can view activity feed (followed users' posts)
+
+## v2 Requirements
+
+### Notifications
+
+- **NOTF-01**: User receives in-app notifications
+- **NOTF-02**: User receives email for new followers
+- **NOTF-03**: User receives email for comments on own posts
+- **NOTF-04**: User can configure notification preferences
+
+### Moderation
+
+- **MODR-01**: User can report content
+- **MODR-02**: User can block other users
+- **MODR-03**: Admin can view reported content
+- **MODR-04**: Admin can remove content
+- **MODR-05**: Admin can ban users
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Real-time chat | High complexity, not core to community value |
+| Video posts | Storage/bandwidth costs, defer to v2+ |
+| OAuth login | Email/password sufficient for v1 |
+| Mobile app | Web-first, mobile later |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| PROF-01 | Phase 2 | Pending |
+| PROF-02 | Phase 2 | Pending |
+| PROF-03 | Phase 2 | Pending |
+| PROF-04 | Phase 2 | Pending |
+| CONT-01 | Phase 3 | Pending |
+| CONT-02 | Phase 3 | Pending |
+| CONT-03 | Phase 3 | Pending |
+| CONT-04 | Phase 3 | Pending |
+| CONT-05 | Phase 3 | Pending |
+| SOCL-01 | Phase 4 | Pending |
+| SOCL-02 | Phase 4 | Pending |
+| SOCL-03 | Phase 4 | Pending |
+| SOCL-04 | Phase 4 | Pending |
+| SOCL-05 | Phase 4 | Pending |
+
+**Coverage:**
+- v1 requirements: 18 total
+- Mapped to phases: 18
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2025-01-14*
+*Last updated: 2025-01-14 after initial definition*
+```
+
+</example>

package/plan-build-run/templates/research-outputs/ARCHITECTURE.md.tmpl

@@ -0,0 +1,86 @@
+<!-- Source: begin/SKILL.md | Purpose: Template for researcher ARCHITECTURE.md output -->
+
+# Architecture Analysis
+
+**Project:** {project_name}
+**Description:** {project_description}
+**Domain:** {domain}
+**Researched:** {date}
+**Confidence:** HIGH/MEDIUM/LOW
+
+## Recommended Architecture Pattern
+
+**Pattern:** {pattern_name}
+**Rationale:** {why_this_pattern}
+
+### System Overview
+
+```
+{ascii_architecture_diagram}
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| {name} | {what it owns} | {how it is usually built} |
+
+## Codebase Organization
+
+```
+src/
+  {folder}/           # {purpose}
+    {subfolder}/      # {purpose}
+    {file}.ts         # {purpose}
+  {folder}/           # {purpose}
+  {folder}/           # {purpose}
+```
+
+### Structure Rationale
+
+- **{folder}/:** {why organized this way}
+
+## Data Flow and State Management
+
+### Request Flow
+
+```
+{user_action}
+    -> {component} -> {handler} -> {service} -> {data_store}
+    <- {response}  <- {transform} <- {query}  <- {database}
+```
+
+### State Management
+
+**Approach:** {state_management_approach}
+**Library:** {state_library}
+**Pattern:** {state_pattern}
+
+### Key Data Flows
+
+1. **{flow_name}:** {description of how data moves}
+2. **{flow_name}:** {description of how data moves}
+
+## Component Communication Patterns
+
+| From | To | Pattern | Notes |
+|------|----|---------|-------|
+| {component_a} | {component_b} | {props/events/store/api} | {considerations} |
+
+## Scaling Considerations
+
+| Scale | Architecture Adjustments |
+|-------|--------------------------|
+| 0-1k users | {approach} |
+| 1k-100k users | {approach} |
+| 100k+ users | {approach} |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | What People Do | Why It Is Wrong | Do This Instead |
+|-------------|----------------|-----------------|-----------------|
+| {name} | {the mistake} | {the problem} | {correct approach} |
+
+---
+*Architecture research for: {project_name}*
+*Researched: {date}*

package/plan-build-run/templates/research-outputs/FEATURES.md.tmpl

@@ -0,0 +1,77 @@
+<!-- Source: begin/SKILL.md | Purpose: Template for researcher FEATURES.md output -->
+
+# Feature Implementation Analysis
+
+**Project:** {project_name}
+**Description:** {project_description}
+**Domain:** {domain}
+**Researched:** {date}
+**Confidence:** HIGH/MEDIUM/LOW
+
+## Feature-to-Library Mapping
+
+| Feature Area | Recommended Library | Version | Why |
+|-------------|---------------------|---------|-----|
+| {feature_area} | {library} | {version} | {rationale} |
+
+## Standard Patterns per Feature Area
+
+### {feature_area_1}
+
+**Pattern:** {pattern_name}
+**Implementation:** {brief_description}
+**Complexity:** LOW/MEDIUM/HIGH
+
+### {feature_area_2}
+
+**Pattern:** {pattern_name}
+**Implementation:** {brief_description}
+**Complexity:** LOW/MEDIUM/HIGH
+
+## Third-Party Integrations
+
+| Integration | Purpose | Library/SDK | Complexity | Notes |
+|-------------|---------|-------------|------------|-------|
+| {service} | {purpose} | {library} | LOW/MEDIUM/HIGH | {gotchas} |
+
+## Implementation Complexity Estimates
+
+| Feature | Complexity | Effort (days) | Dependencies | Risk |
+|---------|------------|---------------|--------------|------|
+| {feature} | LOW/MEDIUM/HIGH | {estimate} | {deps} | {risk_notes} |
+
+## Feature Dependencies
+
+```
+{feature_a}
+    requires --> {feature_b}
+                     requires --> {feature_c}
+
+{feature_d} --enhances--> {feature_a}
+
+{feature_e} --conflicts--> {feature_f}
+```
+
+## MVP Definition
+
+### Launch With (v1)
+
+- [ ] {feature} -- {why essential}
+
+### Add After Validation (v1.x)
+
+- [ ] {feature} -- {trigger for adding}
+
+### Future Consideration (v2+)
+
+- [ ] {feature} -- {why defer}
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| {feature} | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+
+---
+*Feature research for: {project_name}*
+*Researched: {date}*

package/plan-build-run/templates/research-outputs/PITFALLS.md.tmpl

@@ -0,0 +1,65 @@
+<!-- Source: begin/SKILL.md | Purpose: Template for researcher PITFALLS.md output -->
+
+# Common Pitfalls Analysis
+
+**Project:** {project_name}
+**Description:** {project_description}
+**Domain:** {domain}
+**Researched:** {date}
+**Confidence:** HIGH/MEDIUM/LOW
+
+## Common Mistakes
+
+| Pitfall | Impact | Prevention | Phase to Address |
+|---------|--------|------------|------------------|
+| {pitfall} | {impact_description} | {prevention_strategy} | Phase {N} |
+
+## Critical Pitfalls (Detail)
+
+### {pitfall_name}
+
+**What goes wrong:** {failure_mode}
+**Why it happens:** {root_cause}
+**How to avoid:** {prevention}
+**Warning signs:** {early_detection}
+**Phase to address:** Phase {N}
+
+---
+
+## Performance Concerns
+
+| Trap | Symptoms | Prevention | Breaks At |
+|------|----------|------------|-----------|
+| {trap} | {how you notice} | {how to avoid} | {scale threshold} |
+
+## Security Considerations
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| {mistake} | {what could happen} | {how to avoid} |
+
+## Scalability Risks
+
+| Risk | Current Impact | Future Impact | Mitigation |
+|------|---------------|---------------|------------|
+| {risk} | {now} | {at scale} | {strategy} |
+
+## Technical Debt Patterns
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| {shortcut} | {benefit} | {cost} | {conditions or never} |
+
+## "Looks Done But Isn't" Checklist
+
+- [ ] **{feature}:** Often missing {thing} -- verify {check}
+
+## Pitfall-to-Phase Mapping
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| {pitfall} | Phase {N} | {how to verify prevention worked} |
+
+---
+*Pitfalls research for: {project_name}*
+*Researched: {date}*