learnship 1.9.22 → 2.0.0

package/learnship/workflows/challenge.md

@@ -0,0 +1,189 @@
+---
+description: Product + engineering challenge gate — is this worth building?
+---
+
+# Challenge
+
+Product and engineering challenge gate. Asks forcing questions to determine whether a proposed feature, project, or milestone is worth building — before investing in planning and execution.
+
+Two lenses:
+- **Product lens:** "Is this worth building?" — demand, specificity, alternatives, user impact
+- **Engineering lens:** "Will it hold?" — complexity, maintainability, scalability, risk
+
+**Usage:** `challenge` — challenge the current milestone or phase
+**Usage:** `challenge [description]` — challenge a specific idea or proposal
+
+## Step 1: Gather Context
+
+Read available project context:
+
+```bash
+cat .planning/DECISIONS.md 2>/dev/null
+cat .planning/KNOWLEDGE.md 2>/dev/null
+ls .planning/solutions/ 2>/dev/null
+```
+
+**Brownfield enhancement:** If `.planning/codebase/` exists, also read:
+```bash
+cat .planning/codebase/ARCHITECTURE.md 2>/dev/null
+cat .planning/codebase/CONCERNS.md 2>/dev/null
+```
+
+If a description argument was provided, use it as the proposal to challenge.
+
+If no argument: read `.planning/ROADMAP.md` and `.planning/STATE.md` to identify the current or next milestone/phase as the proposal.
+
+## Step 2: Product Challenge
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode):**
+
+```
+Task(
+  subagent_type="learnship-challenger",
+  prompt="
+    <objective>
+    Run the PRODUCT lens challenge on this proposal:
+    [proposal description]
+
+    Ask 3-5 forcing questions from the product perspective:
+    1. Who specifically wants this? (not 'users' — name the persona and their pain)
+    2. What do they do today without it? (status quo is always the competitor)
+    3. How would you know it succeeded? (concrete metric, not 'engagement')
+    4. What's the narrowest version that still delivers value?
+    5. What are you saying NO to by building this?
+
+    Read DECISIONS.md and KNOWLEDGE.md for context on prior decisions.
+    If ARCHITECTURE.md and CONCERNS.md exist, validate against existing architecture.
+
+    Return: answers to each question + verdict (proceed/rethink/reduce-scope)
+    </objective>
+
+    <files_to_read>
+    - .planning/DECISIONS.md (if exists)
+    - .planning/KNOWLEDGE.md (if exists)
+    - .planning/codebase/ARCHITECTURE.md (if exists)
+    - .planning/codebase/CONCERNS.md (if exists)
+    </files_to_read>
+  "
+)
+```
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/challenger.md` as your challenge persona, ask the 3-5 product forcing questions and answer them based on available context.
+
+## Step 3: Engineering Challenge
+
+**If `parallelization` is `true`:**
+
+```
+Task(
+  subagent_type="learnship-challenger",
+  prompt="
+    <objective>
+    Run the ENGINEERING lens challenge on this proposal:
+    [proposal description]
+
+    Ask 3-5 forcing questions from the engineering perspective:
+    1. What's the complexity ceiling? (will this stay simple or inevitably grow complex?)
+    2. What existing patterns does this break? (check ARCHITECTURE.md)
+    3. What's the failure mode? (when this breaks, what happens to the user?)
+    4. What does this make harder later? (second-order effects on maintenance)
+    5. Is there a simpler approach that delivers 80% of the value?
+
+    Read DECISIONS.md and KNOWLEDGE.md for context on prior decisions.
+    Search .planning/solutions/ for related past issues.
+
+    Return: answers to each question + verdict (proceed/rethink/reduce-scope)
+    </objective>
+
+    <files_to_read>
+    - .planning/DECISIONS.md (if exists)
+    - .planning/KNOWLEDGE.md (if exists)
+    - .planning/codebase/ARCHITECTURE.md (if exists)
+    </files_to_read>
+  "
+)
+```
+
+**If `parallelization` is `false`:**
+
+Using `@./agents/challenger.md`, switch to the engineering lens and ask the 3-5 engineering forcing questions.
+
+## Step 4: Synthesize Verdict
+
+Combine both lenses into a verdict:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► CHALLENGE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proposal: [description]
+
+## Product Lens
+[summary of product challenge findings]
+
+## Engineering Lens
+[summary of engineering challenge findings]
+
+## Verdict: [PROCEED | RETHINK | REDUCE SCOPE]
+
+[1-3 sentence rationale]
+
+[If RETHINK: specific concerns that need addressing]
+[If REDUCE SCOPE: suggested narrower scope]
+[If PROCEED: key risks to monitor]
+```
+
+Present the verdict using the platform's blocking question tool:
+- **Proceed as planned** → continue to planning
+- **Adjust scope** → describe adjustments, then re-challenge or proceed
+- **Rethink** → go back to ideation or discussion
+
+## Step 5: Record Decision
+
+If the user makes a decision based on the challenge:
+
+```bash
+# Append to DECISIONS.md if it exists
+cat >> .planning/DECISIONS.md << 'EOF'
+
+### DEC-[NNN]: [Challenge verdict — proposal title]
+
+**Date:** [YYYY-MM-DD]
+**Type:** scope
+**Context:** Challenged via `/challenge` — product + engineering lens
+**Decision:** [proceed | reduced scope | rethought]
+**Rationale:** [key reasons from both lenses]
+EOF
+
+git add .planning/DECISIONS.md
+git commit -m "docs: challenge verdict — [proposal title]"
+```
+
+---
+
+## Integration Points
+
+- `/new-project` Step 7: optionally suggest `/challenge` before committing to scope
+- `/discuss-milestone`: suggest `/challenge` for ambitious milestones
+- `/quick --challenge`: flag for quick tasks that warrant a sanity check
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After the challenge, offer:
+
+> 💡 **Learning moment:** Challenge gates sharpen product thinking:
+>
+> `@agentic-learning either-or` — Which lens (product vs engineering) surfaced the most important concern? Log the reasoning pattern for future decisions.
+>
+> `@agentic-learning brainstorm [proposal topic]` — If the verdict was "rethink," use collaborative brainstorming to explore alternative approaches.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log which challenge lens was most valuable."*

package/learnship/workflows/complete-milestone.md

@@ -163,6 +163,15 @@ git add AGENTS.md
 git commit -m "docs: update AGENTS.md — milestone [VERSION] complete"
 ```
 
+## Step 7c: Sync Documentation
+
+Suggest running `/sync-docs` before the release tag to catch stale documentation:
+
+```
+💡 Before tagging the release, consider running `/sync-docs` to detect
+any documentation that drifted during this milestone.
+```
+
 ## Step 8: Offer Next Milestone
 
 Ask: "Ready to start the next milestone?"

package/learnship/workflows/compound.md

@@ -0,0 +1,305 @@
+---
+description: Capture a solution at the moment of solving — structured doc to .planning/solutions/
+---
+
+# Compound
+
+Capture a recently solved problem or learned pattern while context is fresh. Creates structured documentation in `.planning/solutions/` with YAML frontmatter for searchability. Each documented solution compounds your team's knowledge — the first time takes research, the next time takes minutes.
+
+**Usage:** `compound` — document the most recent fix or learning
+**Usage:** `compound [brief context]` — provide additional context hint
+
+## Step 1: Choose Mode
+
+Present the user with two options before proceeding. Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini, `ask_user_question` in Windsurf). If no question tool is available, present the options and wait for the user's reply.
+
+```
+1. Full (recommended) — the complete compound workflow. Researches,
+   cross-references, and reviews your solution to produce documentation
+   that compounds your project's knowledge.
+
+2. Lightweight — same documentation, single pass. Faster and uses
+   fewer tokens, but won't detect duplicates or cross-reference
+   existing docs. Best for simple fixes or long sessions nearing
+   context limits.
+```
+
+Do NOT pre-select a mode. Do NOT skip this prompt. Wait for the user's choice before proceeding.
+
+---
+
+## Full Mode
+
+### Phase 1: Parallel Research
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+Launch these tasks IN PARALLEL. Each returns text data to the orchestrator — subagents must NOT write any files.
+
+```
+Task(
+  subagent_type="learnship-solution-writer",
+  prompt="
+    <objective>
+    RESEARCH ONLY — do NOT write any files.
+    Analyze conversation history to extract:
+    1. Problem classification (bug vs knowledge track)
+    2. YAML frontmatter skeleton with fields: title, date, category, module,
+       problem_type, component, severity, tags
+    3. Category directory path mapped from problem_type
+    4. Suggested filename: [sanitized-problem-slug]-[YYYY-MM-DD].md
+
+    Bug track problem_types: build_error, test_failure, runtime_error,
+    performance_issue, database_issue, security_issue, ui_bug,
+    integration_issue, logic_error
+
+    Knowledge track problem_types: best_practice, documentation_gap,
+    workflow_issue, developer_experience
+
+    Category mapping:
+    - build_error → build-errors/
+    - test_failure → test-failures/
+    - runtime_error → runtime-errors/
+    - performance_issue → performance-issues/
+    - database_issue → database-issues/
+    - security_issue → security-issues/
+    - ui_bug → ui-bugs/
+    - integration_issue → integration-issues/
+    - logic_error → logic-errors/
+    - best_practice → best-practices/
+    - workflow_issue → workflow-issues/
+    - developer_experience → developer-experience/
+    - documentation_gap → documentation-gaps/
+
+    Return text data only.
+    </objective>
+
+    <files_to_read>
+    - $LEARNSHIP_DIR/references/solution-schema.md
+    </files_to_read>
+  "
+)
+```
+
+Simultaneously, search `.planning/solutions/` for related documentation:
+
+```bash
+# Search for related solutions
+find .planning/solutions/ -name "*.md" -type f 2>/dev/null | head -20
+```
+
+If solutions exist, grep for keyword matches from the current problem:
+```bash
+grep -ril "[keyword1]\|[keyword2]" .planning/solutions/ 2>/dev/null
+```
+
+For each candidate, read the frontmatter (first 30 lines) to assess overlap across five dimensions: problem statement, root cause, solution approach, referenced files, and prevention rules.
+
+Score overlap:
+- **High** (4-5 dimensions match): essentially the same problem solved again
+- **Moderate** (2-3 dimensions match): same area but different angle
+- **Low** (0-1 dimensions match): related but distinct
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/solution-writer.md` as your analysis persona, perform all research in sequence:
+
+1. Extract from conversation history: problem, symptoms, what was tried, what worked
+2. Classify: determine track (bug vs knowledge), problem_type, category, severity
+3. Search `.planning/solutions/` for related docs using grep-first filtering
+4. Assess overlap with existing docs
+5. Suggest filename: `[sanitized-slug]-[YYYY-MM-DD].md`
+
+### Phase 2: Assembly & Write
+
+**WAIT for all Phase 1 research to complete before proceeding.**
+
+Check the overlap assessment:
+
+| Overlap | Action |
+|---------|--------|
+| **High** — existing doc covers the same problem and solution | **Update the existing doc** with fresher context rather than creating a duplicate. Add `last_updated: YYYY-MM-DD` to frontmatter. |
+| **Moderate** — same area but different angle or solution | **Create a new doc**. Note the overlap for future consolidation. |
+| **Low or none** | **Create a new doc** normally. |
+
+Create directory if needed:
+```bash
+node -e "require('fs').mkdirSync('.planning/solutions/[category]/',{recursive:true})"
+```
+
+Write the solution document using the appropriate track template:
+
+**Bug track template:**
+```markdown
+---
+title: [Clear problem title]
+date: [YYYY-MM-DD]
+category: [category directory]
+module: [module or area]
+problem_type: [enum value]
+severity: [critical|high|medium|low]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear problem title]
+
+## Problem
+[1-2 sentence description of the issue and impact]
+
+## Symptoms
+- [Observable symptom or error]
+
+## What Didn't Work
+- [Attempted fix and why it failed]
+
+## Solution
+[The fix that worked, including code snippets]
+
+## Why This Works
+[Root cause explanation and why the fix addresses it]
+
+## Prevention
+- [Concrete practice, test, or guardrail]
+
+## Related
+- [Related docs or issues, if any]
+```
+
+**Knowledge track template:**
+```markdown
+---
+title: [Clear, descriptive title]
+date: [YYYY-MM-DD]
+category: [category directory]
+module: [module or area]
+problem_type: [enum value]
+severity: [critical|high|medium|low]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear, descriptive title]
+
+## Context
+[What situation, gap, or friction prompted this guidance]
+
+## Guidance
+[The practice, pattern, or recommendation with code examples]
+
+## Why This Matters
+[Rationale and impact of following or not following this guidance]
+
+## When to Apply
+- [Conditions or situations where this applies]
+
+## Examples
+[Concrete before/after or usage examples]
+
+## Related
+- [Related docs or issues, if any]
+```
+
+### Phase 3: Commit & Confirm
+
+```bash
+git add ".planning/solutions/[category]/[filename].md"
+git commit -m "docs(solutions): compound — [short title]"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► COMPOUND COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File created:
+- .planning/solutions/[category]/[filename].md
+
+What's next?
+1. Continue workflow (recommended)
+2. View documentation
+3. Link related documentation
+```
+
+Present the "What's next?" options using the platform's blocking question tool. Wait for the user's selection before proceeding.
+
+**Alternate output (when updating an existing doc due to high overlap):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► COMPOUND UPDATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overlap detected: .planning/solutions/[category]/[existing-file].md
+  Action: Updated existing doc with fresher context
+  Added: last_updated: [YYYY-MM-DD]
+
+File updated:
+- .planning/solutions/[category]/[existing-file].md
+```
+
+---
+
+## Lightweight Mode
+
+Single-pass alternative — same documentation, fewer tokens. No subagents, no cross-referencing, no duplicate detection.
+
+1. **Extract from conversation**: Identify the problem and solution from conversation history
+2. **Classify**: Determine track (bug vs knowledge), category, and filename using the schema from `$LEARNSHIP_DIR/references/solution-schema.md`
+3. **Write minimal doc**: Create `.planning/solutions/[category]/[filename].md` using the appropriate track template with:
+   - YAML frontmatter with track-appropriate fields
+   - Bug track: Problem, solution with key code snippets, one prevention tip
+   - Knowledge track: Context, guidance with key examples, one applicability note
+4. **Skip cross-referencing** to conserve context
+
+```bash
+node -e "require('fs').mkdirSync('.planning/solutions/[category]/',{recursive:true})"
+# Write the file
+git add ".planning/solutions/[category]/[filename].md"
+git commit -m "docs(solutions): compound — [short title] (lightweight)"
+```
+
+**Lightweight output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► COMPOUND COMPLETE ✓ (lightweight)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File created:
+- .planning/solutions/[category]/[filename].md
+
+Note: This was created in lightweight mode. For richer documentation
+(cross-references, overlap detection), re-run /compound in a fresh session.
+```
+
+**No subagents are launched. No parallel tasks. One file written.**
+
+---
+
+## The Compounding Philosophy
+
+Each documented solution compounds your project's knowledge:
+
+1. First time you solve a problem → Research (30 min)
+2. Document the solution → `.planning/solutions/` (5 min)
+3. Next time similar issue occurs → Quick lookup (2 min)
+4. Knowledge compounds → Team gets smarter
+
+**Each unit of engineering work should make subsequent units of work easier — not harder.**
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After documenting, offer based on what happened:
+
+> 💡 **Learning moment:** Solution captured. Compound the knowledge further:
+>
+> `@agentic-learning learn [solution domain]` — Active retrieval on the concept you just documented. You explain the root cause first, gaps get filled. This is how fixes become lasting pattern recognition.
+>
+> `@agentic-learning space` — Schedule this concept for spaced revisit. Writes to `docs/revisit.md`. Future sessions start with less decay.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [domain]` · `@agentic-learning space` to turn this solution into a lasting pattern."*

package/learnship/workflows/debug.md

@@ -200,6 +200,13 @@ node -e "require('fs').mkdirSync('.planning/debug/resolved',{recursive:true})"
 mv ".planning/debug/[session-file]" ".planning/debug/resolved/"
 ```
 
+Suggest compounding the solution:
+```
+💡 Compound this fix? Run `/compound` to capture the problem, root cause,
+and solution while context is fresh. Future plan-phase runs will search
+these solutions before planning.
+```
+
 ## Step 9b: Update AGENTS.md Regressions
 
 If `AGENTS.md` exists at the project root, append a regression entry to the `## Regressions` section:

package/learnship/workflows/discuss-milestone.md

@@ -120,6 +120,11 @@ Goals: [N] captured
 Anti-goals: [N] captured
 
 ▶ Next: new-milestone [VERSION]  (will read this context automatically)
+
+💡 For ambitious milestones, consider running `/challenge` first to stress-test
+the scope through product and engineering lenses before committing.
+
+💡 Not sure what to build? Run `/ideate` for codebase-grounded idea generation.
 ```
 
 ---

package/learnship/workflows/execute-phase.md

@@ -82,6 +82,27 @@ Check if `@impeccable teach-impeccable` has been run for this project (look for
 
 Carry these principles through every task in every wave of this phase.
 
+## Step 2c: TDD Mode Check
+
+Read `test_first` from `.planning/config.json` (defaults to `false`).
+
+If `test_first` is `true`:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► TDD MODE ACTIVE — red-green-refactor per task
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+In TDD mode, each executor uses the red-green-refactor cycle:
+1. **Red** — write the failing test first
+2. **Verify red** — confirm the test fails
+3. **Green** — write minimum code to pass
+4. **Verify green** — confirm the test passes
+5. **Refactor** — clean up without changing behavior
+6. **Commit** — atomic commit (test + implementation together)
+
+Both inline (`@./agents/executor.md`) and subagent (`learnship-executor`) executors honor this setting.
+
 ## Step 3: Execute Waves
 
 Read `parallelization` from `.planning/config.json` (defaults to `false`).
@@ -323,7 +344,10 @@ git commit -m "docs: update AGENTS.md — phase [X] complete"
 **Phase [X]: [Name]** — all plans complete, goals verified.
 
 ▶ Next: verify-work [X]  (manual UAT)
+   Then: /review → /ship → /compound
    Then: discuss-phase [X+1] → plan-phase [X+1]
+
+💡 Working on sensitive files? Run `/guard [scope]` to enable safety mode.
 ```
 
 ---