learnship 1.9.0

package/learnship/workflows/cleanup.md

@@ -0,0 +1,107 @@
+---
+description: Archive completed milestone phase directories to keep .planning/phases/ clean
+---
+
+# Cleanup
+
+Archive phase directories from completed milestones into `.planning/milestones/[version]-phases/`. Keeps `.planning/phases/` focused on the current milestone only.
+
+**Usage:** `cleanup`
+
+## Step 1: Find Completed Milestones
+
+```bash
+cat .planning/milestones/MILESTONES.md 2>/dev/null || ls .planning/milestones/ 2>/dev/null
+```
+
+Read `.planning/MILESTONES.md` (or list `.planning/milestones/`) to identify completed milestones and their versions.
+
+Extract each milestone version (e.g., `v1.0`, `v1.1`, `v2.0`).
+
+Check which milestone archive directories already exist:
+```bash
+ls -d .planning/milestones/v*-phases 2>/dev/null
+```
+
+Filter to milestones that do NOT already have a `-phases` archive directory. These are the ones needing cleanup.
+
+If all milestones already have phase archives:
+```
+All completed milestones already have phase directories archived.
+Nothing to clean up.
+```
+Stop.
+
+## Step 2: Determine Phase Membership
+
+For each completed milestone without a `-phases` archive, find which phases belong to it.
+
+Read the archived ROADMAP snapshot for that milestone:
+```bash
+cat ".planning/milestones/[version]-ROADMAP.md" 2>/dev/null
+```
+
+Extract phase numbers and names from the archived roadmap.
+
+Check which of those phase directories still exist in `.planning/phases/`:
+```bash
+ls -d .planning/phases/*/ 2>/dev/null
+```
+
+Match phase directories to milestone membership. Only include directories that still exist.
+
+## Step 3: Show Dry-Run Summary
+
+```
+Cleanup Summary
+
+v[X.Y] — [Milestone Name]
+Phase directories to archive:
+- 01-foundation/
+- 02-auth/
+- 03-core-features/
+Destination: .planning/milestones/v[X.Y]-phases/
+
+v[X.Z] — [Milestone Name]
+Phase directories to archive:
+- 04-security/
+- 05-hardening/
+Destination: .planning/milestones/v[X.Z]-phases/
+
+---
+
+Proceed with archiving? (yes/no)
+```
+
+Wait for confirmation. If "no": stop.
+
+## Step 4: Archive Phase Directories
+
+For each milestone and its phase directories:
+
+```bash
+mkdir -p ".planning/milestones/v[X.Y]-phases"
+mv ".planning/phases/[phase-dir]/" ".planning/milestones/v[X.Y]-phases/"
+```
+
+Repeat for all milestones in the cleanup set.
+
+## Step 5: Commit
+
+```bash
+git add .planning/milestones/ .planning/phases/
+git commit -m "chore: archive phase dirs from completed milestones"
+```
+
+## Step 6: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► CLEANUP COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Archived:
+- v[X.Y]: [N] phase directories → .planning/milestones/v[X.Y]-phases/
+
+.planning/phases/ now contains only current milestone phases.
+```

package/learnship/workflows/complete-milestone.md

@@ -0,0 +1,191 @@
+---
+description: Archive a completed milestone, tag the release, and prepare for the next version
+---
+
+# Complete Milestone
+
+Mark the current milestone as shipped. Archives plans and requirements, updates the roadmap, tags the git release, and sets up for the next milestone.
+
+**Use when:** all phases in the current milestone are complete and verified.
+
+## Step 1: Verify Readiness
+
+Read `.planning/ROADMAP.md` and `.planning/REQUIREMENTS.md`.
+
+Check every phase in the milestone:
+```bash
+for phase_dir in .planning/phases/*/; do
+  plans=$(ls "${phase_dir}"*-PLAN.md 2>/dev/null | wc -l)
+  summaries=$(ls "${phase_dir}"*-SUMMARY.md 2>/dev/null | wc -l)
+  echo "${phase_dir}: ${plans} plans, ${summaries} summaries"
+done
+```
+
+Present readiness report:
+```
+Milestone: [Name]
+
+| Phase | Plans | Summaries | Status |
+|-------|-------|-----------|--------|
+| 1: [Name] | [N] | [N] | ✓ Complete |
+| 2: [Name] | [N] | [N] | ✓ Complete |
+...
+
+Requirements: [X] of [Y] v1 requirements checked off
+```
+
+**If any phase incomplete** (plans > summaries): stop and show which phases need execution.
+
+**If requirements incomplete**: list unchecked requirements and ask to proceed anyway or address them first.
+
+Ask for confirmation:
+- **Archive and tag release** → proceed
+- **Not ready — I need to finish something** → stop
+
+## Step 2: Determine Version
+
+Read `.planning/STATE.md` and check for existing version tags:
+```bash
+git tag --list "v*" | sort -V | tail -5
+```
+
+Propose the next version (e.g., `v1.0`, `v1.1`, `v2.0`). Ask for confirmation or let user specify.
+
+## Step 3: Archive Milestone Artifacts
+
+Create the milestones archive directory:
+```bash
+mkdir -p .planning/milestones
+```
+
+Archive the roadmap for this milestone:
+```bash
+cp .planning/ROADMAP.md ".planning/milestones/${VERSION}-ROADMAP.md"
+```
+
+Archive the requirements:
+```bash
+cp .planning/REQUIREMENTS.md ".planning/milestones/${VERSION}-REQUIREMENTS.md"
+```
+
+## Step 4: Update ROADMAP.md
+
+Replace the current milestone's detailed phases with a one-line summary per milestone section:
+
+```markdown
+## Completed Milestones
+
+### [VERSION] — [Milestone Name]
+Completed [date]. [N] phases, [M] requirements delivered. See `.planning/milestones/[VERSION]-ROADMAP.md` for full details.
+
+---
+```
+
+Delete `.planning/REQUIREMENTS.md` (a fresh one will be created for the next milestone):
+```bash
+git rm .planning/REQUIREMENTS.md
+```
+
+## Step 5: Update PROJECT.md
+
+Read `.planning/PROJECT.md` and update:
+- Bump version reference
+- Move "Active" requirements that were completed to "Validated"
+- Update the "Key Decisions" table with final outcomes
+- Update the "Last updated" footer
+
+## Step 6: Create Milestone Summary in STATE.md
+
+Add a milestone completion entry to STATE.md:
+
+```markdown
+## Milestone History
+
+### [VERSION] — [Milestone Name]
+Completed: [date]
+Phases: [N]
+Requirements delivered: [list of REQ-IDs]
+Key achievements: [2-3 sentence summary]
+```
+
+## Step 7: Git Tag the Release
+
+Commit all updated artifacts:
+```bash
+git add .planning/
+git commit -m "docs: archive milestone [VERSION]"
+```
+
+Tag the release:
+```bash
+git tag -a "[VERSION]" -m "Milestone [VERSION]: [Milestone Name]
+
+[2-3 sentence summary of what was built]
+
+Phases: [N]
+Requirements: [M] delivered"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MILESTONE [VERSION] COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[Milestone Name]**
+[N] phases complete | [M] requirements delivered
+Tagged: [VERSION]
+
+Archives:
+- .planning/milestones/[VERSION]-ROADMAP.md
+- .planning/milestones/[VERSION]-REQUIREMENTS.md
+```
+
+## Step 7b: Update AGENTS.md
+
+If `AGENTS.md` exists at the project root, update:
+
+1. **Current Phase block** — mark milestone complete:
+```markdown
+## Current Phase
+
+**Milestone:** [VERSION] — [Milestone Name] ✓ shipped
+**Phase:** —
+**Status:** milestone complete — ready for next milestone
+**Last updated:** [today's date]
+```
+
+2. **Project Structure** — update if the milestone added significant new modules.
+
+```bash
+git add AGENTS.md
+git commit -m "docs: update AGENTS.md — milestone [VERSION] complete"
+```
+
+## Step 8: Offer Next Milestone
+
+Ask: "Ready to start the next milestone?"
+
+- **Yes, start planning next milestone** → Run `new-project` logic adapted for a new milestone on an existing codebase:
+  - Skip git init (already exists)
+  - Ask what to build next
+  - Research the new feature domain
+  - Define new requirements
+  - Create new ROADMAP.md
+- **Not yet** → stop here
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** Milestone [VERSION] is shipped. This is the right time for a deep reflection.
+>
+> `@agentic-learning reflect` — What did you learn building this? What was your goal? What gaps remain for the next milestone?
+>
+> `@agentic-learning space` — Schedule the key concepts from this milestone for spaced review before the next one starts.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` for a milestone retrospective."*

package/learnship/workflows/debug.md

@@ -0,0 +1,245 @@
+---
+description: Systematic debugging with persistent state — triage, diagnose root cause, plan fix, execute
+---
+
+# Debug
+
+Systematic debugging workflow: triage → root cause diagnosis → fix planning → execution. Creates a persistent debug session file so context survives across context resets.
+
+**Usage:** `debug [description]`
+
+## Step 1: Create Debug Session
+
+```bash
+mkdir -p .planning/debug
+DATE=$(date +%Y%m%d-%H%M)
+```
+
+Generate a slug from the description (lowercase, hyphens). Create session file:
+```
+.planning/debug/[DATE]-[SLUG].md
+```
+
+Write initial session header:
+```markdown
+---
+status: open
+opened: [datetime]
+description: [description]
+---
+
+# Debug: [description]
+
+## Session Log
+```
+
+## Step 2: Triage
+
+Ask: **"What is the exact symptom?"**
+
+If description was provided as an argument, use it as starting context. Then ask follow-up questions one at a time:
+
+1. "When does this happen? Always, sometimes, or only under specific conditions?"
+2. "What did you expect to happen?"
+3. "When did it start? Was it working before? What changed?"
+4. "What have you already tried?"
+
+After gathering answers, write a triage summary to the session file:
+```markdown
+## Triage
+
+**Symptom:** [exact description]
+**Expected:** [what should happen]
+**Frequency:** [always/intermittent/condition-specific]
+**Regression:** [when it started, what changed]
+**Already tried:** [list]
+```
+
+## Step 3: Form Hypotheses
+
+Based on the symptom and triage, generate 2-4 candidate root causes ranked by likelihood:
+
+```
+Hypotheses (ranked by likelihood):
+
+1. [Most likely]: [explanation of why this would cause the symptom]
+2. [Second]: [explanation]
+3. [Third]: [explanation]
+```
+
+Ask: "Does any of these match what you're seeing? Or should I investigate a different direction?"
+
+## Step 4: Investigate
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+Spawn a dedicated debugger agent with a fresh context budget for deep investigation:
+```
+Task(
+  subagent_type="learnship-debugger",
+  prompt="
+    <objective>
+    Investigate the bug described in [session_file].
+    Trace from the user-facing symptom inward to find the root cause.
+    Find the specific file and line where behavior diverges from expected.
+    Confirm: 'If this were fixed, would the symptom go away?'
+    Write investigation findings back to [session_file].
+    </objective>
+
+    <files_to_read>
+    - [session_file] (debug session with triage + hypotheses)
+    - ./AGENTS.md or ./CLAUDE.md or ./GEMINI.md (project context, whichever exists)
+    </files_to_read>
+  "
+)
+```
+
+Wait for agent to complete, then read the updated session file.
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/debugger.md` as your investigation persona:
+
+For the most likely hypothesis, investigate the codebase (read-only):
+- Trace from the user-facing symptom inward toward the root cause
+- Find the specific file and line where behavior diverges from expected
+- Confirm: "If this were fixed, would the symptom go away?"
+
+Update session file with investigation notes:
+```markdown
+## Investigation
+
+### Hypothesis [N]: [description]
+**Files checked:** [list]
+**Finding:** [what was found]
+**Root cause:** [specific file:line and why it causes the symptom]
+**Confidence:** high | medium | low
+```
+
+If hypothesis disproved: move to next hypothesis. If all hypotheses disproved: surface new ones based on what was found.
+
+## Step 5: Diagnose
+
+Present root cause diagnosis:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DEBUG ► ROOT CAUSE FOUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Root cause: [specific description]
+Location: [file:line]
+Why: [how this causes the symptom]
+Confidence: high | medium | low
+```
+
+Write to session file:
+```markdown
+## Root Cause
+
+**Location:** [file:line]
+**Cause:** [description]
+**Why it produces the symptom:** [explanation]
+**Confidence:** high | medium | low
+```
+
+If confidence is low: explain what additional information would help confirm.
+
+## Step 6: Plan the Fix
+
+Propose a minimal fix:
+
+```
+Fix approach: [1-3 sentences describing the change]
+Files to modify:
+- [file]: [what to change]
+
+Risk: [any side effects or things to watch out for]
+```
+
+Ask: "Does this approach look right? Should I implement it, or do you want to adjust?"
+
+## Step 7: Implement Fix
+
+Once confirmed, implement the fix using the executor approach from `@./agents/executor.md`:
+- Make only the changes needed to fix the root cause
+- No scope creep — don't fix other things while you're in there
+- Commit atomically:
+
+```bash
+git add [files changed]
+git commit -m "fix([scope]): [description of what was fixed]"
+```
+
+## Step 8: Verify Fix
+
+Test the fix against the original symptom:
+```bash
+[run the verify command from the relevant plan, or run tests]
+```
+
+Ask: "Does this fix the problem?"
+
+## Step 9: Close Session
+
+Update session file:
+```markdown
+## Resolution
+
+**Fix applied:** [description]
+**Commit:** [hash]
+**Verified:** [yes/no — how verified]
+**Status:** resolved | partial | unresolved
+```
+
+Move to resolved:
+```bash
+mkdir -p .planning/debug/resolved
+mv ".planning/debug/[session-file]" ".planning/debug/resolved/"
+```
+
+## Step 9b: Update AGENTS.md Regressions
+
+If `AGENTS.md` exists at the project root, append a regression entry to the `## Regressions` section:
+
+```markdown
+### [YYYY-MM-DD]: [short description — e.g., "Auth token not passed to API calls"]
+
+**Root cause:** [one sentence — the actual code location and why]
+**Fix:** [what was changed]
+**Lesson:** [the principle extracted — what to watch for next time]
+```
+
+Remove the `> No regressions logged yet.` placeholder line if it's still there.
+
+```bash
+git add AGENTS.md .planning/debug/resolved/[session-file]
+git commit -m "docs(debug): close session — [description]"
+```
+
+```
+Debug session closed.
+Session: .planning/debug/resolved/[session-file]
+
+▶ If more issues remain: debug [new description]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After resolving, offer based on what happened:
+
+> 💡 **Learning moment:** Root cause found and fixed. Bugs are the highest-signal learning moments — don’t let this one fade:
+>
+> `@agentic-learning learn [bug domain]` — Active retrieval on the concept that broke. You explain the root cause first, gaps get filled. This is how "I've seen this bug" becomes real pattern recognition.
+>
+> `@agentic-learning struggle [the problem]` — Reproduce a similar problem from scratch with a hint ladder. The re-investigation builds deeper intuition than reading the fix.
+>
+> `@agentic-learning either-or` — Which debugging strategy worked (hypothesis testing, bisect, tracing)? Log it for future sessions.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [bug domain]` · `@agentic-learning struggle [problem]` to turn this bug into a lasting pattern."*

package/learnship/workflows/decision-log.md

@@ -0,0 +1,131 @@
+---
+description: Capture an architectural or scope decision with its context, alternatives, and rationale into .planning/DECISIONS.md
+---
+
+# Decision Log
+
+Capture a decision — architectural choice, library pick, scope trade-off, pattern selection — into `.planning/DECISIONS.md`. The decision register is the project's institutional memory: it tells future Cascade (and future you) *why* the project is built the way it is.
+
+**Usage:** `decision-log [description]` or just `decision-log` to capture from recent conversation.
+
+## Step 1: Extract Decision Content
+
+**With description argument:** Use it as the decision title/focus.
+
+**Without argument:** Analyze recent conversation to extract the decision being made:
+- What choice was just discussed or made?
+- What were the alternatives?
+- What was the rationale?
+- What does this lock in or foreclose?
+
+Formulate:
+- `title` — 3-8 words (e.g., "Use Zustand over Redux for state", "Single-table DynamoDB design")
+- `type` — `architecture` | `library` | `scope` | `pattern` | `lesson`
+- `context` — why this decision was needed (1-2 sentences)
+- `options` — alternatives that were considered (list)
+- `choice` — what was decided
+- `rationale` — why this choice over the alternatives
+- `consequences` — what this locks in or makes harder
+
+## Step 2: Read Existing DECISIONS.md
+
+```bash
+cat .planning/DECISIONS.md 2>/dev/null || echo "File does not exist yet."
+```
+
+If it doesn't exist, it will be created. Note the highest existing DEC-XXX number to assign the next ID.
+
+## Step 3: Check for Conflicts
+
+Scan existing decisions for any that might conflict with or be superseded by the new one:
+
+```bash
+grep -i "[key words from title]" .planning/DECISIONS.md 2>/dev/null
+```
+
+If a related decision exists, show it and ask: "This may relate to DEC-[XXX]: [title]. Is this a new decision, or does it update/supersede the existing one?"
+
+- **New decision** → create DEC-[next]
+- **Updates existing** → add a note to existing entry, create new entry with `supersedes: DEC-[XXX]`
+
+## Step 4: Read Phase Context
+
+```bash
+cat .planning/STATE.md | grep "Phase:"
+```
+
+Note the current phase number for the decision record.
+
+## Step 5: Write to DECISIONS.md
+
+If DECISIONS.md doesn't exist, create it with header:
+
+```markdown
+# Decisions Register
+
+A living record of architectural, scope, and pattern decisions made during this project.
+Each entry captures context, alternatives considered, and rationale — so future sessions
+understand *why* the project is built the way it is.
+
+Read this before proposing approaches that may conflict with prior decisions.
+
+---
+```
+
+Append the new entry:
+
+```markdown
+## DEC-[XXX]: [title]
+
+**Date:** [YYYY-MM-DD] | **Phase:** [N] | **Type:** [type]
+
+**Context:** [why this decision was needed]
+
+**Options considered:**
+- [option A]: [brief description and trade-off]
+- [option B]: [brief description and trade-off]
+
+**Choice:** [what was decided]
+
+**Rationale:** [why this over the alternatives]
+
+**Consequences:** [what this locks in, what it makes harder, what it enables]
+
+**Status:** active
+
+---
+```
+
+## Step 6: Commit
+
+```bash
+git add .planning/DECISIONS.md
+git commit -m "docs: log decision — [title]"
+```
+
+## Step 7: Confirm
+
+```
+Decision logged: DEC-[XXX]
+
+  [title]
+  Type: [type] | Phase: [N]
+
+Decisions register: .planning/DECISIONS.md ([N] total decisions)
+
+Continue with current work, or capture another with decision-log.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After logging a significant architectural decision:
+
+> 💡 **Decision logged.** Want to explore it deeper?
+>
+> `@agentic-learning either-or` — Walk through the decision more systematically: what did each option optimize for? What would have to be true for the other option to have been better? This builds the decision-making intuition, not just the record.
+
+**If `manual`:** No note (keep it fast — this workflow is meant to be a quick capture).