learnship 1.9.0

package/learnship/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/learnship/templates/state.md

@@ -0,0 +1,176 @@
+# State Template
+
+Template for `.planning/STATE.md` — the project's living memory.
+
+---
+
+## File Template
+
+```markdown
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated [date])
+
+**Core value:** [One-liner from PROJECT.md Core Value section]
+**Current focus:** [Current phase name]
+
+## Current Position
+
+Phase: [X] of [Y] ([Phase name])
+Plan: [A] of [B] in current phase
+Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+Last activity: [YYYY-MM-DD] — [What happened]
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: [N]
+- Average duration: [X] min
+- Total execution time: [X.X] hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: [durations]
+- Trend: [Improving / Stable / Degrading]
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- [Phase X]: [Decision summary]
+- [Phase Y]: [Decision summary]
+
+### Pending Todos
+
+[From .planning/todos/pending/ — ideas captured during sessions]
+
+None yet.
+
+### Blockers/Concerns
+
+[Issues that affect future work]
+
+None yet.
+
+## Session Continuity
+
+Last session: [YYYY-MM-DD HH:MM]
+Stopped at: [Description of last completed action]
+Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
+```
+
+<purpose>
+
+STATE.md is the project's short-term memory spanning all phases and sessions.
+
+**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
+
+**Solution:** A single, small file that's:
+- Read first in every workflow
+- Updated after every significant action
+- Contains digest of accumulated context
+- Enables instant session restoration
+
+</purpose>
+
+<lifecycle>
+
+**Creation:** After ROADMAP.md is created (during init)
+- Reference PROJECT.md (read it for current context)
+- Initialize empty accumulated context sections
+- Set position to "Phase 1 ready to plan"
+
+**Reading:** First step of every workflow
+- progress: Present status to user
+- plan: Inform planning decisions
+- execute: Know current position
+- transition: Know what's complete
+
+**Writing:** After every significant action
+- execute: After SUMMARY.md created
+  - Update position (phase, plan, status)
+  - Note new decisions (detail in PROJECT.md)
+  - Add blockers/concerns
+- transition: After phase marked complete
+  - Update progress bar
+  - Clear resolved blockers
+  - Refresh Project Reference date
+
+</lifecycle>
+
+<sections>
+
+### Project Reference
+Points to PROJECT.md for full context. Includes:
+- Core value (the ONE thing that matters)
+- Current focus (which phase)
+- Last update date (triggers re-read if stale)
+
+Claude reads PROJECT.md directly for requirements, constraints, and decisions.
+
+### Current Position
+Where we are right now:
+- Phase X of Y — which phase
+- Plan A of B — which plan within phase
+- Status — current state
+- Last activity — what happened most recently
+- Progress bar — visual indicator of overall completion
+
+Progress calculation: (completed plans) / (total plans across all phases) × 100%
+
+### Performance Metrics
+Track velocity to understand execution patterns:
+- Total plans completed
+- Average duration per plan
+- Per-phase breakdown
+- Recent trend (improving/stable/degrading)
+
+Updated after each plan completion.
+
+### Accumulated Context
+
+**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
+
+**Pending Todos:** Ideas captured via /add-todo
+- Count of pending todos
+- Reference to .planning/todos/pending/
+- Brief list if few, count if many (e.g., "5 pending todos — see /check-todos")
+
+**Blockers/Concerns:** From "Next Phase Readiness" sections
+- Issues that affect future work
+- Prefix with originating phase
+- Cleared when addressed
+
+### Session Continuity
+Enables instant resumption:
+- When was last session
+- What was last completed
+- Is there a .continue-here file to resume from
+
+</sections>
+
+<size_constraint>
+
+Keep STATE.md under 100 lines.
+
+It's a DIGEST, not an archive. If accumulated context grows too large:
+- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
+- Keep only active blockers, remove resolved ones
+
+The goal is "read once, know where we are" — if it's too long, that fails.
+
+</size_constraint>

package/learnship/templates/uat.md

@@ -0,0 +1,80 @@
+---
+phase: [N]
+status: pending
+created: [YYYY-MM-DD]
+---
+
+# Phase [N] UAT: [Phase Name]
+
+User acceptance test session for Phase [N]. Each scenario is walked through manually, issues logged with severity, and fix plans created for any blockers or majors.
+
+---
+
+## Test Scenarios
+
+### Scenario 1: [Scenario Name]
+
+**Expected behavior:**
+[What should happen when the user does X]
+
+**Steps:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**Result:** [ ] Pass  [ ] Skip  [ ] Issue
+
+**Notes:** _
+
+---
+
+### Scenario 2: [Scenario Name]
+
+**Expected behavior:**
+[What should happen]
+
+**Steps:**
+1. [Step 1]
+2. [Step 2]
+
+**Result:** [ ] Pass  [ ] Skip  [ ] Issue
+
+**Notes:** _
+
+---
+
+## Issues Found
+
+### Issue 1: [Short description]
+
+**Severity:** blocker | major | minor | polish
+
+**Scenario:** [Which scenario]
+
+**What happened:** [Actual behavior observed]
+
+**Expected:** [What should have happened]
+
+**Root cause:**
+```yaml
+root_cause: "[description]"
+affected_files:
+  - "[file path]"
+fix_approach: "[description of fix]"
+confidence: high | medium | low
+```
+
+**Status:** open | fixed | deferred
+
+---
+
+## Summary
+
+**Scenarios tested:** [N]
+**Passed:** [N]
+**Skipped:** [N]
+**Issues:** [N] ([X] blockers, [Y] majors, [Z] minors)
+
+**Overall verdict:** passed | issues_found | blocked
+
+**Fix phases needed:** [yes/no — list if yes]

package/learnship/workflows/add-phase.md

@@ -0,0 +1,84 @@
+---
+description: Append a new phase to the current milestone roadmap when scope grows after initial planning
+---
+
+# Add Phase
+
+Append a new integer phase to the end of the current milestone. Use when scope grows after initial planning — a new feature, an unplanned integration, or a discovered dependency.
+
+**Usage:** `add-phase [description]`
+
+## Step 1: Validate
+
+Check that a roadmap exists:
+```bash
+test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+```
+
+If missing: stop — run `new-project` first.
+
+If no description was provided as an argument, ask: "What does this new phase deliver?"
+
+## Step 2: Find Next Phase Number
+
+Read `.planning/ROADMAP.md` and find the highest existing integer phase number:
+```bash
+grep -E "^## Phase [0-9]+" .planning/ROADMAP.md | tail -1
+```
+
+Also scan the phases directory for any directories that may not be in the roadmap:
+```bash
+ls .planning/phases/ 2>/dev/null | grep -E "^[0-9]+" | sort -n | tail -3
+```
+
+Set `NEXT_NUM` = highest found + 1. Pad to 2 digits (01, 02, ..., 10, 11, ...).
+
+Generate a slug from the description (lowercase, hyphens, max 40 chars).
+
+## Step 3: Create Phase Directory
+
+```bash
+mkdir -p ".planning/phases/${NEXT_NUM}-${SLUG}"
+```
+
+## Step 4: Update ROADMAP.md
+
+Append the new phase entry to ROADMAP.md:
+
+```markdown
+## Phase [N]: [Description]
+
+**Goal:** [One sentence — what user can do after this phase]
+**Status:** [ ] Not started
+**Depends on:** Phase [N-1]
+
+### Plans
+*Not yet planned — run `plan-phase [N]`*
+```
+
+## Step 5: Update STATE.md
+
+Add to the "Roadmap Evolution" section under Accumulated Context (create if missing):
+```markdown
+### Roadmap Evolution
+- Phase [N] added: [description]
+```
+
+## Step 6: Commit
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md
+git commit -m "chore(roadmap): add phase [N] — [description]"
+```
+
+## Step 7: Confirm
+
+```
+Phase [N] added: [description]
+
+Directory: .planning/phases/[NN]-[slug]/
+Status: Not planned yet
+Roadmap: .planning/ROADMAP.md updated
+
+▶ Next: plan-phase [N]
+```