learnship 1.9.0

package/learnship/workflows/remove-phase.md

@@ -0,0 +1,128 @@
+---
+description: Remove a planned (not yet executed) phase and renumber subsequent phases
+---
+
+# Remove Phase
+
+Remove a future phase from the roadmap, delete its directory, and renumber subsequent phases to maintain a clean linear sequence.
+
+**Usage:** `remove-phase [N]`
+
+**Only future phases can be removed.** Completed phases (with SUMMARY.md files) require explicit confirmation. The git commit is the historical record of what was removed.
+
+## Step 1: Parse and Validate
+
+Extract the phase number from arguments. If missing:
+```
+Usage: remove-phase [N]
+Example: remove-phase 7
+
+[N] = phase number to remove (integer or decimal like 3.1)
+```
+
+Check roadmap exists:
+```bash
+test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+```
+
+## Step 2: Verify the Phase is Future
+
+Read `.planning/STATE.md` to find the current phase number.
+
+Read `.planning/ROADMAP.md` to confirm phase `[N]` exists.
+
+If target phase ≤ current phase:
+```
+Cannot remove Phase [N].
+
+Only future (unstarted) phases can be removed.
+Current phase: [current]
+Phase [N] is current or already completed.
+
+To undo completed work: use git revert on the phase commits.
+```
+
+Stop.
+
+## Step 3: Check for Executed Work
+
+```bash
+ls ".planning/phases/[NN]-[slug]/"*-SUMMARY.md 2>/dev/null
+```
+
+If SUMMARY.md files exist, the phase has partially executed content. Warn:
+```
+⚠️  Phase [N] has [M] executed plan(s) with SUMMARY.md files.
+Removing it will delete this work from the roadmap (git history preserves the commits).
+
+Are you sure?
+- Yes, remove it anyway
+- No, keep it
+```
+
+Wait for confirmation before proceeding.
+
+## Step 4: Confirm Removal
+
+Show what will happen:
+```
+Removing Phase [N]: [Name]
+
+This will:
+- Delete: .planning/phases/[NN]-[slug]/
+- Renumber: Phases [N+1] through [max] → [N] through [max-1]
+- Update: ROADMAP.md and STATE.md
+
+Proceed? (yes/no)
+```
+
+Wait for explicit confirmation.
+
+## Step 5: Execute Removal
+
+**Delete the phase directory:**
+```bash
+rm -rf ".planning/phases/[NN]-[slug]/"
+```
+
+**Renumber subsequent phases:**
+
+For each phase directory after `[N]` (in reverse order to avoid conflicts):
+```bash
+# Example: phase 08 → 07, 09 → 08, etc.
+for dir in $(ls .planning/phases/ | grep -E "^[0-9]" | sort -rV); do
+  # extract number, if > removed phase number, decrement and rename
+done
+```
+
+Also rename files inside each renamed directory (PLAN.md, SUMMARY.md, etc. that start with the old phase number).
+
+**Update ROADMAP.md:**
+- Remove the phase `[N]` section entirely
+- Update all subsequent phase numbers and any `Depends on` references
+
+**Update STATE.md:**
+- Decrement total phase count
+- Add to Roadmap Evolution: `- Phase [N] ([name]) removed`
+
+## Step 6: Commit
+
+```bash
+git add -A
+git commit -m "chore(roadmap): remove phase [N] ([original-name])"
+```
+
+The commit message preserves the historical record.
+
+## Step 7: Confirm
+
+```
+Phase [N] ([original-name]) removed.
+
+Changes made:
+- Deleted: .planning/phases/[NN]-[slug]/
+- Renumbered: [M] phases
+- Updated: ROADMAP.md, STATE.md
+
+▶ Next: progress (to see updated roadmap)
+```

package/learnship/workflows/research-phase.md

@@ -0,0 +1,137 @@
+---
+description: Deep-dive domain research for a phase without immediately creating plans
+---
+
+# Research Phase
+
+Run standalone domain research for a phase. Useful when the domain is unfamiliar, the phase is complex, or you want to explore options before committing to a planning approach.
+
+**Normally you don't need this** — `plan-phase` runs research automatically. Use `research-phase` when you want research results to review and discuss before planning starts.
+
+**Usage:** `research-phase [N]`
+
+## Step 1: Validate Phase
+
+```bash
+test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+```
+
+Find phase `[N]` in ROADMAP.md:
+```bash
+grep -E "Phase [N]:" .planning/ROADMAP.md
+```
+
+If not found: list available phases and stop.
+
+## Step 2: Check Existing Research
+
+```bash
+ls ".planning/phases/"*"/"*"-RESEARCH.md" 2>/dev/null | grep "^[N]-\|/[N][^0-9]"
+```
+
+If RESEARCH.md already exists for this phase:
+```
+Research already exists: .planning/phases/[phase-dir]/[N]-RESEARCH.md
+
+Options:
+1. View existing research
+2. Re-run and overwrite
+3. Skip — use existing
+```
+
+Wait for choice.
+
+## Step 3: Load Context
+
+Read all available phase context:
+```bash
+cat .planning/ROADMAP.md        # phase goal and requirements
+cat .planning/REQUIREMENTS.md   # requirement IDs and acceptance criteria
+cat .planning/STATE.md          # project history and past decisions
+```
+
+Check for CONTEXT.md (user decisions from discuss-phase):
+```bash
+ls ".planning/phases/[padded_phase]-[slug]/"*"-CONTEXT.md" 2>/dev/null
+```
+
+If CONTEXT.md exists, read it — user decisions shape what to research.
+
+## Step 4: Run Research
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCHING PHASE [N]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/researcher.md` as your research persona in **phase research mode**:
+
+Read all loaded context, then investigate how to implement this phase. Write `.planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md` with two sections:
+
+**Don't Hand-Roll** — problems that have battle-tested solutions:
+```
+- Problem: [what looks custom]
+  Solution: Use [library/approach]
+  Why: [specific reason — ESM compat, maintenance, type safety, etc.]
+```
+
+**Common Pitfalls** — what goes wrong in this type of phase:
+```
+- Pitfall: [what fails]
+  Warning sign: [what to look for]
+  Prevention: [how to avoid]
+  Phase impact: [when/where to address this]
+```
+
+## Step 5: Commit Research
+
+```bash
+git add ".planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md"
+git commit -m "docs([padded_phase]): phase research"
+```
+
+## Step 6: Present Results
+
+Display key findings:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCH COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase [N]: [Name]
+
+Don't hand-roll: [N items]
+Pitfalls: [N items]
+
+Key findings:
+- [Most important recommendation]
+- [Second most important]
+- [Third]
+
+File: .planning/phases/[phase-dir]/[N]-RESEARCH.md
+```
+
+Ask: "What would you like to do next?"
+- **Plan this phase** → `plan-phase [N]` (research is already done, will be skipped)
+- **Discuss first** → `discuss-phase [N]` → then plan
+- **Read full research** → show the research file
+- **Done for now** → stop
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer all three — new research is the best time to use all of them:
+
+> 💡 **Learning moment:** Research complete — new domain concepts are fresh. Lock them in before they fade:
+>
+> `@agentic-learning learn [phase topic]` — Active retrieval on the key concepts from this research. You explain first, gaps get filled. This is how domain knowledge becomes intuition, not just notes.
+>
+> `@agentic-learning explain-first [phase topic]` — Explain the domain back in your own words before planning starts. If you can’t explain it clearly, the plans won’t be clear either.
+>
+> `@agentic-learning quiz [phase topic]` — Test yourself on what the research surfaced. Retrieval practice now means fewer surprises during execution.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [topic]` · `@agentic-learning explain-first [topic]` to consolidate the research before planning."*

package/learnship/workflows/resume-work.md

@@ -0,0 +1,162 @@
+---
+description: Restore full project context and continue from where you left off — use when returning after a break, or when you say "continue", "where were we", "pick up where we left off", or "what were we doing"
+---
+
+# Resume Work
+
+Instantly restore full project context. Use when starting a new session, returning after time away, or when you said "continue" or "where were we."
+
+## Step 1: Check Planning Structure
+
+```bash
+test -f .planning/STATE.md && echo "HAS_STATE" || echo "NO_STATE"
+test -f .planning/PROJECT.md && echo "HAS_PROJECT" || echo "NO_PROJECT"
+test -f .planning/ROADMAP.md && echo "HAS_ROADMAP" || echo "NO_ROADMAP"
+```
+
+If nothing exists: stop — run `new-project` to start a project.
+
+If STATE.md missing but PROJECT.md + ROADMAP.md exist: reconstruct STATE.md (see Reconstruction section below).
+
+## Step 2: Load State
+
+```bash
+cat .planning/STATE.md
+cat .planning/PROJECT.md
+```
+
+Extract:
+- **What we're building:** core value and current focus from PROJECT.md
+- **Current position:** Phase X of Y, Plan A of B, status
+- **Recent decisions:** key decisions affecting current work
+- **Blockers/concerns:** issues carried forward
+- **Last activity:** when and what
+
+## Step 3: Check for Incomplete Work
+
+```bash
+# Check for continue-here handoff files
+find .planning/phases -name ".continue-here.md" -type f 2>/dev/null
+
+# Check for plans without matching summaries (incomplete execution)
+for plan in .planning/phases/*/*-PLAN.md; do
+  base="${plan%-PLAN.md}"
+  summary="${base}-SUMMARY.md"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null
+```
+
+## Step 4: Present Status
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PROJECT STATUS                                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Building: [one-liner from PROJECT.md]                        ║
+║                                                               ║
+║  Phase: [X] of [Y] — [Phase name]                            ║
+║  Plan:  [A] of [B] — [Status]                                 ║
+║  Progress: [████████░░] [N]%                                 ║
+║                                                               ║
+║  Last activity: [date] — [what happened]                     ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+If `.continue-here.md` found:
+```
+⚠️  Mid-plan handoff detected:
+    File: .planning/phases/[phase]/.continue-here.md
+    Task: [X] of [Y]
+    [brief description of where we left off]
+```
+
+If incomplete plan (PLAN without SUMMARY):
+```
+⚠️  Incomplete execution:
+    Plan: [plan file]
+    Execution started but no SUMMARY found.
+```
+
+If blockers exist:
+```
+⚠️  Carried concerns:
+    - [blocker]
+```
+
+## Step 5: Determine Next Action
+
+**Priority order:**
+
+1. **`.continue-here.md` exists** → read it fully, resume from `<next_action>`
+   - Display: "Resuming from: [next_action from file]"
+   - Delete the continue file after loading: `rm .planning/phases/[phase]/.continue-here.md`
+   - Commit the deletion: `git add -A && git commit -m "chore: consume resume handoff"`
+
+2. **Incomplete plan (PLAN without SUMMARY)** → offer to continue execution
+   - Primary: `execute-phase [X]`
+   - Secondary: Review the plan first
+
+3. **Current phase ready to execute (plans exist)** → `execute-phase [X]`
+
+4. **Current phase needs planning** → check for CONTEXT.md
+   - CONTEXT.md exists: `plan-phase [X]`
+   - No CONTEXT.md: `discuss-phase [X]` (recommended)
+
+5. **Current phase done, next phase up** → `discuss-phase [X+1]`
+
+6. **All phases done** → `complete-milestone`
+
+Present the primary recommended action clearly:
+```
+▶ Recommended next step: [workflow name] [phase number if applicable]
+
+Also available:
+- progress — full status overview
+- [other relevant options]
+```
+
+## Step 6: Update Session Continuity
+
+Update STATE.md session section:
+```markdown
+## Session Continuity
+
+Last session: [now]
+Stopped at: Session resumed
+```
+
+```bash
+git add .planning/STATE.md
+git commit -m "docs(state): session resumed"
+```
+
+---
+
+## Reconstruction (when STATE.md is missing)
+
+If STATE.md is missing but other artifacts exist:
+
+"STATE.md missing. Reconstructing from artifacts..."
+
+1. Read `PROJECT.md` → extract "What This Is" and Core Value
+2. Read `ROADMAP.md` → find all phases, identify current position (last phase with incomplete work)
+3. Scan `*-SUMMARY.md` files → extract decisions and concerns
+4. Check for `.continue-here.md` files → session continuity
+
+Write a reconstructed `.planning/STATE.md` and proceed normally.
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto` and time since last session is more than 1 day (check `Last session` in STATE.md):**
+
+> 💡 **Back after a break:** Before diving in, warm up the mental model:
+>
+> `@agentic-learning quiz [current phase topic]` — Quick active recall on what was being built. Surfaces what’s faded since the last session before it shows up as a bug.
+>
+> `@agentic-learning space` — If `docs/revisit.md` exists, review what was scheduled for today.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning quiz [topic]` to warm up before resuming."*

package/learnship/workflows/set-profile.md

@@ -0,0 +1,78 @@
+---
+description: Quick model profile switch without opening full settings
+---
+
+# Set Profile
+
+One-step model profile switch. Edits `.planning/config.json` without opening the full settings menu.
+
+**Usage:** `set-profile [quality|balanced|budget]`
+
+## Step 1: Parse Argument
+
+If no argument provided:
+```
+Usage: set-profile [profile]
+
+Profiles:
+  quality   — Opus for all agents (highest quality, highest cost)
+  balanced  — Opus for planning, Sonnet for execution (recommended)
+  budget    — Sonnet for writing, Haiku for research/verification (lowest cost)
+
+Current profile: [read from .planning/config.json]
+```
+Stop.
+
+## Step 2: Validate
+
+If argument is not one of `quality`, `balanced`, `budget`:
+```
+Unknown profile: [argument]
+Valid options: quality, balanced, budget
+```
+Stop.
+
+## Step 3: Read Current Config
+
+```bash
+cat .planning/config.json
+```
+
+Note the current `model_profile` value.
+
+If already set to the requested profile:
+```
+Profile is already set to [profile]. No change needed.
+```
+Stop.
+
+## Step 4: Update Config
+
+Update the `model_profile` field in `.planning/config.json`:
+
+```bash
+python3 -c "
+import json
+cfg = json.load(open('.planning/config.json'))
+cfg['model_profile'] = '[profile]'
+json.dump(cfg, open('.planning/config.json', 'w'), indent=2)
+print('Updated.')
+"
+```
+
+## Step 5: Confirm
+
+```bash
+git add .planning/config.json
+git commit -m "chore(config): set model profile to [profile]"
+```
+
+```
+Profile updated: [old] → [profile]
+
+[quality]  — Opus agents for all tasks. Use for production milestones.
+[balanced] — Opus for planning, Sonnet for execution. Best default.
+[budget]   — Sonnet/Haiku. Use for prototyping or exploration.
+
+Takes effect immediately on the next workflow run.
+```

package/learnship/workflows/settings.md

@@ -0,0 +1,204 @@
+---
+description: Interactive settings editor for .planning/config.json
+---
+
+# Settings
+
+Interactive configuration editor for the current project. Updates `.planning/config.json` with your preferences.
+
+**Usage:** `settings`
+
+## Step 1: Ensure Config Exists
+
+```bash
+test -f .planning/config.json && echo "exists" || echo "missing"
+```
+
+If missing, create from template:
+```bash
+cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/config.json << 'EOF'
+{
+  "mode": "yolo",
+  "granularity": "standard",
+  "model_profile": "balanced",
+  "learning_mode": "auto",
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true
+  },
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "phase-{phase}-{slug}",
+    "milestone_branch_template": "{milestone}-{slug}"
+  }
+}
+EOF
+```
+
+## Step 2: Read Current Config
+
+```bash
+cat .planning/config.json
+```
+
+Parse current values to use as defaults in the prompts.
+
+## Step 3: Present Settings Menu
+
+Display current settings and ask what to change:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► SETTINGS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Current configuration:
+
+[1] Mode:              [current] (yolo | interactive)
+[2] Granularity:       [current] (coarse | standard | fine)
+[3] Model profile:     [current] (quality | balanced | budget)
+[4] Learning mode:     [current] (auto | manual)
+[5] Research agent:    [on/off]
+[6] Plan check agent:  [on/off]
+[7] Verifier agent:    [on/off]
+[8] Nyquist validation:[on/off]
+[9] Git branching:     [current] (none | phase | milestone)
+[10] Commit docs:      [on/off]
+
+Enter a number to change a setting, or 'done' to save.
+```
+
+Wait for selection. Repeat until user types "done".
+
+## Step 4: Change Selected Setting
+
+For each selected setting, explain the options and ask for the new value:
+
+**[1] Mode:**
+```
+Mode controls how much Cascade auto-approves vs. asks you:
+- yolo: auto-approves decisions, fastest flow
+- interactive: confirms at each step, more control
+
+Current: [current]. New value?
+```
+
+**[2] Granularity:**
+```
+Granularity controls phase size:
+- coarse: 3-5 phases (broad strokes)
+- standard: 5-8 phases (default)
+- fine: 8-12 phases (more granular, better for complex projects)
+
+Current: [current]. New value?
+```
+
+**[3] Model profile:**
+```
+Model profile controls which model tier each agent uses:
+- quality: Opus for all decision-making agents (highest cost, best results)
+- balanced: Opus for planning, Sonnet for execution (default — good balance)
+- budget: Sonnet for writing code, Haiku for research/verification (lowest cost)
+
+Current: [current]. New value?
+```
+
+**[4] Learning mode:**
+```
+Learning mode controls when learning actions are offered:
+- auto: offered automatically at workflow checkpoints (default)
+- manual: only when you explicitly invoke @agentic-learning
+
+Current: [current]. New value?
+```
+
+**[5-7] Agent toggles (research / plan_check / verifier):**
+```
+[Research / Plan check / Verifier] agent:
+- on: agent runs (recommended for production work)
+- off: skip this agent (faster, for familiar domains or prototyping)
+
+Current: [current]. New value? (on/off)
+```
+
+**[8] Nyquist validation:**
+```
+Nyquist validation maps automated test coverage to requirements during plan-phase.
+- on: plans include automated verify commands per task (recommended)
+- off: skip validation research (good for rapid prototyping)
+
+Current: [current]. New value? (on/off)
+```
+
+**[9] Git branching:**
+```
+Branching strategy:
+- none: no automatic branches (good for solo work)
+- phase: create a branch at each execute-phase (good for code review per phase)
+- milestone: one branch for all phases in a milestone (good for release branches)
+
+Current: [current]. New value?
+```
+
+**[10] Commit docs:**
+```
+Whether .planning/ files are committed to git:
+- on: planning artifacts tracked in git (default)
+- off: keep .planning/ local only (add to .gitignore for privacy)
+
+Current: [current]. New value? (on/off)
+```
+
+## Step 5: Save Config
+
+After user types "done", write the updated config:
+
+```bash
+cat > .planning/config.json << EOF
+{
+  "mode": "[value]",
+  "granularity": "[value]",
+  "model_profile": "[value]",
+  "learning_mode": "[value]",
+  "planning": {
+    "commit_docs": [true/false],
+    "search_gitignored": false
+  },
+  "workflow": {
+    "research": [true/false],
+    "plan_check": [true/false],
+    "verifier": [true/false],
+    "nyquist_validation": [true/false]
+  },
+  "git": {
+    "branching_strategy": "[value]",
+    "phase_branch_template": "phase-{phase}-{slug}",
+    "milestone_branch_template": "{milestone}-{slug}"
+  }
+}
+EOF
+```
+
+## Step 6: Commit
+
+```bash
+git add .planning/config.json
+git commit -m "chore(config): update project settings"
+```
+
+## Step 7: Confirm
+
+```
+Settings saved to .planning/config.json
+
+Changes made:
+- [setting]: [old value] → [new value]
+
+These settings apply to all future workflow runs in this project.
+```