learnship 1.9.0

package/learnship/workflows/map-codebase.md

@@ -0,0 +1,142 @@
+---
+description: Analyze an existing codebase and produce structured reference docs before starting a new project on top of it
+---
+
+# Map Codebase
+
+Analyze an existing codebase through structured focused exploration. Produces 7 structured documents in `.planning/codebase/` that feed into `new-project` when adding features to existing code.
+
+**Use before:** `/new-project` on a brownfield (existing) codebase.
+
+**Philosophy:** Each agent gets fresh context, explores a specific domain, and writes documents directly. The orchestrator only confirms what was created — it never receives document contents.
+
+## Step 1: Check Existing Maps
+
+```bash
+ls .planning/codebase/ 2>/dev/null
+```
+
+If `.planning/codebase/` already exists with documents:
+
+```
+.planning/codebase/ already exists:
+- [list files found]
+
+Options:
+1. Refresh — delete and remap from scratch
+2. Update — only re-run specific agents
+3. Skip — use existing map as-is
+```
+
+Wait for response before continuing.
+
+## Step 2: Create Output Directory
+
+```bash
+mkdir -p .planning/codebase
+```
+
+Expected output files:
+- `STACK.md` — technologies and dependencies
+- `INTEGRATIONS.md` — external APIs, databases, auth
+- `ARCHITECTURE.md` — patterns, layers, data flow
+- `STRUCTURE.md` — directory layout, naming conventions
+- `CONVENTIONS.md` — code style, patterns, error handling
+- `TESTING.md` — test framework, structure, coverage
+- `CONCERNS.md` — tech debt, security, fragile areas
+
+## Step 3: Run Structured Mapping
+
+For each dimension below, adopt the relevant `@./agents/researcher.md` persona, explore the codebase thoroughly, and write the document directly.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► MAPPING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Running structured analysis...
+```
+
+**Agent 1 — Tech Stack:**
+Explore: languages, runtime, frameworks, package.json/requirements.txt, build config, env vars.
+Write: `STACK.md` (stack overview, versions, key libraries) + `INTEGRATIONS.md` (external APIs, databases, auth providers, webhooks, message queues).
+
+**Agent 2 — Architecture:**
+Explore: entry points, module structure, data flow, abstractions, dependency injection patterns, shared utilities.
+Write: `ARCHITECTURE.md` (overall pattern — monolith/microservices/serverless, layers, data flow, key abstractions) + `STRUCTURE.md` (directory map with purpose of each directory, file naming conventions, where to find things).
+
+**Agent 3 — Conventions & Quality:**
+Explore: code style, linting config, existing patterns for common operations (error handling, logging, validation), test files.
+Write: `CONVENTIONS.md` (coding style enforced, naming patterns, common idioms, what NOT to do based on existing code) + `TESTING.md` (test framework, structure, mocking approach, coverage state, how to run tests).
+
+**Agent 4 — Concerns:**
+Explore: TODO/FIXME/HACK comments, large files, circular dependencies, outdated packages, security patterns (secrets, auth, input validation).
+Write: `CONCERNS.md` (tech debt items, known bugs, security concerns, performance bottlenecks, fragile areas the planner should avoid or tread carefully around).
+
+## Step 4: Security Check
+
+Before committing, scan for accidentally captured secrets:
+
+```bash
+grep -rE '(sk-[a-zA-Z0-9]{20,}|sk_live_|sk_test_|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|-----BEGIN.*PRIVATE KEY)' .planning/codebase/*.md 2>/dev/null && echo "SECRETS_FOUND" || echo "CLEAN"
+```
+
+**If secrets found:**
+```
+⚠️  SECURITY ALERT: Potential secrets detected in codebase documents.
+
+[Show what was found]
+
+Review and remove sensitive values before committing.
+Reply "safe" once clean, or I'll skip the commit.
+```
+
+Wait for confirmation.
+
+## Step 5: Verify Output
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md 2>/dev/null
+```
+
+Report any missing or suspiciously short documents (< 20 lines = likely empty).
+
+## Step 6: Commit
+
+```bash
+git add .planning/codebase/
+git commit -m "docs: map existing codebase"
+```
+
+## Step 7: Present Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► CODEBASE MAPPED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Created .planning/codebase/:
+- STACK.md ([N] lines) — Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) — System design and patterns
+- STRUCTURE.md ([N] lines) — Directory layout and organization
+- CONVENTIONS.md ([N] lines) — Code style and patterns
+- TESTING.md ([N] lines) — Test structure and practices
+- INTEGRATIONS.md ([N] lines) — External services and APIs
+- CONCERNS.md ([N] lines) — Technical debt and issues
+
+▶ Next: new-project (questions will focus on what you're ADDING)
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** Codebase mapped. Test your understanding before building on top of it:
+>
+> `@agentic-learning explain [codebase/module name]` — Explain the architecture back in your own words. Gaps in the explanation reveal gaps in the mental model — before they become bugs.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning explain [codebase]` to verify your understanding of the architecture."*

package/learnship/workflows/milestone-retrospective.md

@@ -0,0 +1,178 @@
+---
+description: Structured learning retrospective at end of milestone — 5 questions, produces RETROSPECTIVE.md, triggers spaced review
+---
+
+# Milestone Retrospective
+
+A structured learning retrospective after a milestone ships. Five focused questions surface what was learned, what worked, what didn't, and what to carry forward. Produces a `RETROSPECTIVE.md` and schedules key concepts for spaced review.
+
+**Usage:** `milestone-retrospective`
+
+**Run after:** `complete-milestone`
+
+## Step 1: Load Context
+
+Read the milestone that just shipped:
+```bash
+ls .planning/milestones/ | sort -V | tail -3
+cat .planning/milestones/[VERSION]-ROADMAP.md 2>/dev/null | head -60
+```
+
+Read all phase SUMMARY.md files from this milestone:
+```bash
+ls .planning/milestones/[VERSION]-phases/*/*-SUMMARY.md 2>/dev/null || \
+ls .planning/phases/*/*-SUMMARY.md 2>/dev/null
+```
+
+Read the debug sessions log for this milestone:
+```bash
+ls .planning/debug/resolved/ 2>/dev/null
+```
+
+Read DECISIONS.md entries from this milestone period:
+```bash
+cat .planning/DECISIONS.md 2>/dev/null | grep -A 8 "Phase [1-[N]]"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► MILESTONE RETROSPECTIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone: [VERSION] — [Name]
+Phases completed: [N]
+Bugs fixed: [M] (from debug sessions)
+Decisions made: [K]
+```
+
+## Step 2: Five Retrospective Questions
+
+Ask each question and wait for a real answer before moving to the next. These are not checkboxes — they're reflection prompts.
+
+**Question 1: What did you actually build?**
+"Describe [VERSION] in your own words — not the requirements, but what you actually created. What can a user do now that they couldn't before?"
+
+**Question 2: What was harder than expected?**
+"Which phase or task took longer or required more rework than you anticipated? What made it hard?"
+
+**Question 3: What worked surprisingly well?**
+"Any decision, approach, or tool that paid off more than expected? Anything you'd do the same way next time?"
+
+**Question 4: What would you do differently?**
+"If you were starting this milestone over with what you know now — what's the one thing you'd change?"
+
+**Question 5: What should carry forward?**
+"Any patterns, decisions, or lessons from this milestone that should explicitly inform the next one? What goes into the decision register?"
+
+## Step 3: Synthesize Themes
+
+After all five answers, synthesize the key themes:
+
+```
+Retrospective themes:
+
+What we learned:
+- [theme 1]
+- [theme 2]
+
+What to repeat:
+- [approach/decision to carry forward]
+
+What to avoid:
+- [approach/anti-pattern to explicitly skip next time]
+
+Decisions to add to register:
+- [decision to capture in DECISIONS.md]
+```
+
+Ask: "Does this capture it? Anything to add or change?"
+
+## Step 4: Write RETROSPECTIVE.md
+
+Write `.planning/milestones/[VERSION]-RETROSPECTIVE.md`:
+
+```markdown
+---
+milestone: [VERSION]
+created: [date]
+---
+
+# Milestone Retrospective: [VERSION] — [Name]
+
+## What Was Built
+
+[Answer to Q1 — user's own words]
+
+## What Was Hard
+
+[Answer to Q2]
+
+## What Worked Well
+
+[Answer to Q3]
+
+## What to Do Differently
+
+[Answer to Q4]
+
+## Carry Forward
+
+[Answer to Q5]
+
+---
+
+## Key Learnings (for next milestone)
+
+[Synthesized themes — the 3-5 most actionable takeaways]
+
+## Decisions to Register
+
+[Any decisions surfaced that should be added to DECISIONS.md]
+```
+
+## Step 5: Update DECISIONS.md
+
+For each decision surfaced in the retrospective, append to `.planning/DECISIONS.md`:
+
+```markdown
+## DEC-[XXX]: [title — from retrospective]
+**Date:** [date] | **Phase:** retrospective | **Type:** lesson
+**Context:** [what situation surfaced this]
+**Choice:** [what we learned / what to do]
+**Rationale:** [from the retrospective answer]
+**Consequences:** [what this means for the next milestone]
+**Status:** active
+```
+
+## Step 6: Commit
+
+```bash
+git add .planning/milestones/[VERSION]-RETROSPECTIVE.md .planning/DECISIONS.md
+git commit -m "docs: add [VERSION] retrospective and carry-forward decisions"
+```
+
+## Step 7: Schedule for Spaced Review
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RETROSPECTIVE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Saved: .planning/milestones/[VERSION]-RETROSPECTIVE.md
+Decisions added: [N]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer (always, not conditional — retrospective IS the learning moment):
+
+> 💡 **Now schedule what you just reflected on:**
+>
+> `@agentic-learning space` — Identifies the key concepts and patterns from this milestone and schedules them for spaced review. Writes to `docs/revisit.md`. The next milestone starts smarter because of this.
+
+**If `manual`:** Offer: *"Tip: `@agentic-learning space` to schedule the key patterns from this milestone for review before the next one starts."*

package/learnship/workflows/new-milestone.md

@@ -0,0 +1,200 @@
+---
+description: Start a new milestone cycle on an existing project after a prior milestone is complete
+---
+
+# New Milestone
+
+Start the next version cycle for an existing project. Loads what shipped previously, gathers new goals, optionally researches new feature domains, defines scoped requirements, and creates a new phased roadmap.
+
+**Use after:** `/complete-milestone` has archived the previous milestone.
+
+## Step 1: Load Context
+
+Read all prior project context:
+```bash
+cat .planning/PROJECT.md
+cat .planning/STATE.md
+cat .planning/milestones/
+ls .planning/milestones/ 2>/dev/null
+```
+
+Display what shipped in the last milestone:
+```
+## Last milestone: [VERSION]
+[2-3 sentences from the milestone archive summarizing what was built]
+
+Pending todos carried forward:
+- [Any todos from STATE.md]
+```
+
+## Step 2: Gather Milestone Goals
+
+Ask openly: **"What do you want to build in this milestone?"**
+
+If a milestone scope was already discussed (look for `.planning/MILESTONE-CONTEXT.md`), load it and confirm:
+```
+I found a milestone context file from a prior discussion:
+[summary of scope]
+
+Use this as the starting point?
+```
+- **Yes** → proceed with it
+- **No / Start fresh** → ask from scratch
+
+Follow the thread. When you have enough to write clear goals, ask for confirmation before continuing.
+
+## Step 3: Determine Version
+
+Read the last version from `.planning/milestones/`:
+```bash
+ls .planning/milestones/ | grep -E "^v[0-9]" | sort -V | tail -3
+```
+
+Propose the next version (e.g., `v1.0 → v1.1`, or `v2.0` for a major scope change). Confirm with user or let them specify.
+
+## Step 4: Update PROJECT.md
+
+Add or update the current milestone section:
+```markdown
+## Current Milestone: [VERSION] [Name]
+
+**Goal:** [One sentence describing this milestone's focus]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+```
+
+Update the Active requirements section and "Last updated" footer.
+
+## Step 5: Update STATE.md
+
+Reset current position:
+```markdown
+## Current Position
+
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: [today] — Milestone [VERSION] started
+```
+
+Keep the Accumulated Context section (decisions, blockers from prior milestones carry forward).
+
+## Step 6: Commit Initial State
+
+```bash
+git add .planning/PROJECT.md .planning/STATE.md
+git commit -m "docs: start milestone [VERSION] [Name]"
+```
+
+If a MILESTONE-CONTEXT.md was consumed, delete it:
+```bash
+git rm .planning/MILESTONE-CONTEXT.md 2>/dev/null || true
+```
+
+## Step 7: Research Decision
+
+Read `workflow.research` from `.planning/config.json`.
+
+Ask: "Research the domain for the new features before defining requirements?"
+- **Research first** (recommended) — investigate new capabilities' ecosystem
+- **Skip research** — domain is familiar
+
+Update config accordingly:
+```bash
+# Edit .planning/config.json: set workflow.research to true or false
+```
+
+**If Research first:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCHING NEW MILESTONE FEATURES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/researcher.md` in project research mode, investigate the new feature domain:
+- Focus ONLY on the new capabilities — not the existing codebase
+- Write STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md to `.planning/research/`
+- Synthesize into `.planning/research/SUMMARY.md`
+
+## Step 8: Define Requirements
+
+Read PROJECT.md, existing REQUIREMENTS traceability (in milestones archive), and research (if run).
+
+Present feature categories for this milestone. For each, have the user select what's in scope (multi-select). Apply REQ-IDs continuing from the last milestone's numbering (or restarting per-domain).
+
+Create `.planning/REQUIREMENTS.md` fresh for this milestone:
+- v1 requirements with REQ-IDs
+- v2 requirements (next milestone candidates)
+- Out-of-scope items with reasoning
+
+Present for confirmation. Iterate if needed.
+
+```bash
+git add .planning/REQUIREMENTS.md
+git commit -m "docs: define [VERSION] requirements"
+```
+
+## Step 9: Create Roadmap
+
+Using `@./agents/planner.md` as planning persona, read PROJECT.md, REQUIREMENTS.md, research (if exists).
+
+Create a new `.planning/ROADMAP.md` with phases for this milestone only. Map every v1 requirement to exactly one phase.
+
+Present the proposed roadmap for approval. Iterate if needed.
+
+Update STATE.md to reflect the new phase count and first phase.
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md
+git commit -m "docs: create [VERSION] roadmap ([N] phases)"
+```
+
+## Step 10: Update AGENTS.md
+
+If `AGENTS.md` exists at the project root, update:
+
+1. **Current Phase block** — reset for new milestone:
+```markdown
+## Current Phase
+
+**Milestone:** [VERSION] — [Milestone Name]
+**Phase:** 1 — [Phase 1 Name from new ROADMAP.md]
+**Status:** planning
+**Last updated:** [today's date]
+```
+
+2. **Tech Stack** — update if the new milestone introduces new libraries or frameworks.
+
+```bash
+git add AGENTS.md
+git commit -m "docs: update AGENTS.md — milestone [VERSION] started"
+```
+
+## Step 11: Done
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► MILESTONE [VERSION] INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[VERSION] — [Name]** — [N] phases, [X] requirements
+
+▶ Next: discuss-phase 1 → plan-phase 1 → execute-phase 1
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** New milestone, new mental model. Before writing a line of code:
+>
+> `@agentic-learning brainstorm [milestone topic]` — Talk through the new features before committing to an approach. Surfaces blind spots before planning starts.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning brainstorm [milestone topic]` before planning starts to surface approach alternatives."*