learnship 2.0.7 → 2.0.9

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 49 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "learnship",
   "displayName": "learnship",
   "description": "Agentic engineering done right — 49 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/SKILL.md

@@ -106,6 +106,16 @@ Does .planning/PROJECT.md exist?
 
 **This gate applies to ALL messages** — bug reports, feature requests, "quick fixes", detailed specs, anything. The only exception: if the user is currently mid-ceremony in `/new-project` (i.e., they are answering your questions), their messages are workflow answers, not tasks to route.
 
+## `/new-project` Ceremony Enforcement
+
+When running `/new-project`, these are non-negotiable hard gates. Violating any of them produces a broken project:
+
+1. **Research = 5 separate files.** If the user chooses research, you MUST create exactly 5 files in `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Do NOT write a single monolithic research file. After writing all 5, run the `node -e` verification command from the workflow. If it fails, fix the files before proceeding.
+
+2. **AGENTS.md = copy from template.** Read `@./templates/agents.md` BEFORE writing AGENTS.md. Sections marked "copy VERBATIM" must be copied word-for-word — do not rewrite, summarize, or rephrase them. After writing, run the `node -e` verification command. If it fails, fix AGENTS.md before proceeding.
+
+3. **Done = STOP.** After displaying the Step 9 done banner, **STOP completely**. Do NOT automatically start `/discuss-phase 1`. Do NOT say "Let me start Phase 1" or "Now starting Phase 1." Wait for the user to type their next command.
+
 ## Key Behaviors
 
 - **Context efficiency**: Reference file paths rather than inlining file contents. Load context fresh when needed rather than carrying it forward.

package/cursor-rules/learnship.mdc

@@ -47,9 +47,13 @@ When the user runs `/new-project`, execute these **9 mandatory steps in order**.
 
 2. **After Step 4 (PROJECT.md confirmed):** Do NOT write REQUIREMENTS.md or ROADMAP.md. First ask: "Before I write the requirements — do you want me to research the domain ecosystem first?" Wait for reply.
 
-3. **After Step 7 (roadmap approved):** Do NOT display the done banner or suggest next steps. Generate AGENTS.md (Step 8) first.
+3. **Research = 5 separate files.** If the user chooses research, create exactly 5 files in `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Do NOT write a single monolithic research file. Run the `node -e` verification command from the workflow — it must print `RESEARCH VERIFIED OK` before proceeding.
 
-4. **Step 9 next step is `/discuss-phase 1` — not `/plan-phase`.** The phase loop is: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work`. `discuss-phase` is mandatory first — it writes the CONTEXT.md that planning depends on.
+4. **After Step 7 (roadmap approved):** Do NOT display the done banner or suggest next steps. Generate AGENTS.md (Step 8) first.
+
+5. **AGENTS.md = copy from template.** Read `@./templates/agents.md` BEFORE writing. Sections marked "copy VERBATIM" (Soul, Principles, Request Routing Protocol, Platform Context, Skills, Regressions) must be copied word-for-word. Run the `node -e` verification — it must print `AGENTS.md VERIFIED OK` before proceeding.
+
+6. **Step 9 = STOP.** After displaying the done banner, **STOP completely**. Do NOT automatically start `/discuss-phase 1`. Do NOT say "Let me start Phase 1." Wait for the user's next message. The next step is `/discuss-phase 1` — **start here, not `/plan-phase`**. The phase loop is: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work`.
 
 **Routing protocol suspended during `/new-project`.** Every user message while the ceremony is in progress is an answer to a workflow question, not a task to route.
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "Agentic engineering done right — 49 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",

package/learnship/templates/agents.md

@@ -204,7 +204,16 @@ When a new decision is made during a session, capture it with `/decision-log`.
 
 ### Solutions Store
 
-Compounded solutions live in `.planning/solutions/` — organized by category (build-errors, runtime-errors, best-practices, etc.) with YAML frontmatter for searchability. After fixing a bug or completing a notable feature, run `/compound` to capture the solution while context is fresh. The `/plan-phase` workflow automatically searches these before planning.
+Compounded solutions live in `.planning/solutions/` — organized by category (build-errors, runtime-errors, best-practices, etc.) with YAML frontmatter for searchability. The `/plan-phase` workflow automatically searches these before planning.
+
+**Run `/compound` after any of these events — do not skip:**
+- Fixing a bug (especially root-cause discoveries)
+- Completing a phase (`execute-phase` → `verify-work` → `/compound`)
+- Shipping a feature (`/ship` → `/compound`)
+- Any aha moment or pattern discovery during development
+- Resolving a debugging session (`/debug` → `/compound`)
+
+Context fades fast. If a solution was worth finding, it's worth capturing.
 
 ---
 

package/learnship/workflows/audit-milestone.md

@@ -154,6 +154,8 @@ Status: [PASSED ✓ | GAPS FOUND ⚠️]
 Milestone [VERSION] is ready to ship.
 
 ▶ Next: complete-milestone
+
+💡 Run `/sync-docs` first to check for stale documentation before release.
 ```
 
 **If GAPS FOUND:**
@@ -164,6 +166,8 @@ Milestone [VERSION] is ready to ship.
 
 ▶ Next: plan-milestone-gaps — create fix phases for all gaps
     OR: complete-milestone — ship anyway (mark gaps as known issues)
+
+💡 Run `/sync-docs` to check for stale documentation alongside the gap fixes.
 ```
 
 ---

package/learnship/workflows/discuss-phase.md

@@ -224,6 +224,9 @@ Created: .planning/phases/[padded_phase]-[slug]/[padded_phase]-CONTEXT.md
 ---
 
 ▶ Next Up: plan-phase [X]
+
+💡 Ambitious scope? `/challenge` — stress-test the approach before planning
+💡 Made important decisions? `/compound` — capture them while context is fresh
 ```
 
 ---

package/learnship/workflows/execute-phase.md

@@ -329,6 +329,14 @@ If `AGENTS.md` exists at the project root, update the `## Current Phase` block t
 
 Also append any newly created key files or modules to the `## Project Structure` tree if significant new directories were created during this phase.
 
+**Post-update verification (cross-platform):**
+
+```bash
+node -e "const fs=require('fs');if(!fs.existsSync('AGENTS.md')){process.exit(0);}const f=fs.readFileSync('AGENTS.md','utf8');const required=['Soul','Principles','Request Routing Protocol','Platform Context','Current Phase','Project Structure','Tech Stack','Skills','Regressions'];const missing=required.filter(s=>!f.includes('## '+s));if(missing.length){console.log('AGENTS.md sections lost during update:\\n'+missing.map(s=>'  ## '+s).join('\\n'));process.exit(1);}console.log('AGENTS.md sections intact');"
+```
+
+> If verification fails, restore the missing sections from `@./templates/agents.md` before committing.
+
 ```bash
 git add AGENTS.md
 git commit -m "docs: update AGENTS.md — phase [X] complete"

package/learnship/workflows/ls.md

@@ -30,6 +30,8 @@ spec-driven phases, context-engineered plans, atomic execution,
 and a learning partner woven into every phase transition.
 
 ▶ To start: /new-project
+▶ Not sure what to build? `@agentic-learning brainstorm [idea]` — think through it first
+▶ Have an existing codebase? /ideate — scan for improvement opportunities
 ▶ For a quick one-off task: /quick "description"
 ▶ To see all commands: /help
 ```

package/learnship/workflows/new-project.md

@@ -243,6 +243,13 @@ Based on all previous answers, ask a third follow-up that clarifies scope, edge
 
 **Gate check — before proceeding to Step 4:**
 
+> 🛑 **HARD GATE — count your messages.** Before continuing, verify:
+> 1. You sent exactly **4 separate question messages** (Exchanges 1–4)
+> 2. You received exactly **4 separate user answers** (`ANSWER_1` through `ANSWER_4`)
+> 3. Each answer came from a **different user message** (not extracted from one long reply)
+>
+> If any count is wrong, go back and complete the missing exchanges. Do NOT proceed with fewer than 4 exchanges under any circumstances — even if the user's first answer was extremely detailed.
+
 Verify internally: do you have `ANSWER_1`, `ANSWER_2`, `ANSWER_3`, and `ANSWER_4` recorded? If any is missing, go back and ask it. Only after all four answers are in hand may you ask:
 
 "I think I have a solid picture of what you're building. Ready for me to write PROJECT.md, or is there more you want to cover first?"
@@ -291,14 +298,56 @@ Ask: **"Before I write the requirements — do you want me to research the domai
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Run 4 research passes sequentially. Each writes a file to `.planning/research/`:
+**You MUST create exactly 5 separate markdown files.** Do NOT write a single monolithic research file. Do NOT combine multiple files into one. Each file is a separate write operation.
+
+Create the research directory first:
+
+```bash
+node -e "require('fs').mkdirSync('.planning/research',{recursive:true})"
+```
+
+Now create each file one at a time. After writing each file, move to the next.
 
-1. **STACK.md** — Standard tech stack for this domain (specific libraries, versions, what NOT to use and why)
-2. **FEATURES.md** — What features exist in this domain: table stakes vs. differentiators vs. anti-features
-3. **ARCHITECTURE.md** — How systems in this domain are typically structured, component boundaries, data flow, suggested build order
-4. **PITFALLS.md** — Common mistakes, warning signs, prevention strategies
+**File 1 of 5 — Write `.planning/research/STACK.md` now:**
+Research the standard tech stack for this domain. The file MUST contain these exact `##` headers:
+- `## Recommended Stack`
+- `## Alternatives Considered`
+- `## What NOT to Use` (with reasons)
+- `## Versions`
+
+**File 2 of 5 — Write `.planning/research/FEATURES.md` now:**
+Research what features exist in this domain. The file MUST contain these exact `##` headers:
+- `## Table Stakes` (must-haves)
+- `## Differentiators` (nice-to-haves)
+- `## Anti-Features` (what to avoid)
+
+**File 3 of 5 — Write `.planning/research/ARCHITECTURE.md` now:**
+Research how systems in this domain are typically structured. The file MUST contain these exact `##` headers:
+- `## Component Boundaries`
+- `## Data Flow`
+- `## Build Order` (suggested sequence)
+- `## Integration Points`
+
+**File 4 of 5 — Write `.planning/research/PITFALLS.md` now:**
+Research common mistakes and prevention strategies. The file MUST contain these exact `##` headers:
+- `## Common Mistakes`
+- `## Warning Signs`
+- `## Prevention Strategies`
+
+**File 5 of 5 — Write `.planning/research/SUMMARY.md` now:**
+Synthesize the 4 files above into a summary. The file MUST contain these exact `##` headers:
+- `## Recommended Stack`
+- `## Table Stakes Features`
+- `## Key Architecture Decisions`
+- `## Top Pitfalls`
+
+> 🔴 **HARD GATE — Run this verification command now. Do not skip it. Do not proceed without running it.**
+
+```bash
+node -e "const fs=require('fs'),path=require('path');const dir='.planning/research/';const checks={'STACK.md':['Recommended Stack','What NOT to Use'],'FEATURES.md':['Table Stakes','Differentiators'],'ARCHITECTURE.md':['Component Boundaries','Data Flow'],'PITFALLS.md':['Common Mistakes','Prevention Strategies'],'SUMMARY.md':['Recommended Stack','Top Pitfalls']};const missing=[];for(const[file,sections]of Object.entries(checks)){const fp=path.join(dir,file);if(!fs.existsSync(fp)){missing.push(file+' MISSING');continue;}const c=fs.readFileSync(fp,'utf8');for(const s of sections){if(!c.includes('## '+s))missing.push(file+': missing ## '+s);}}if(missing.length){console.log('RESEARCH INCOMPLETE:\\n'+missing.join('\\n'));process.exit(1);}console.log('RESEARCH VERIFIED OK — all 5 files present with required sections');"
+```
 
-After all four complete, synthesize into `.planning/research/SUMMARY.md` covering: recommended stack, table stakes features, key architecture decisions, top pitfalls to avoid.
+> 🛑 **If the command prints `RESEARCH INCOMPLETE` or exits with code 1:** Go back and create or fix the missing files. Then run the verification again. You MUST see `RESEARCH VERIFIED OK` before continuing. Do NOT proceed to Step 6 without a passing verification.
 
 Display key findings:
 ```
@@ -396,54 +445,49 @@ git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md && git
 
 > **🔴 MANDATORY — This step must always be completed. Do not skip it, do not defer it, do not move to Step 9 without writing AGENTS.md to the project root. AGENTS.md is the persistent memory file that every future session depends on.**
 
-Start by reading `@./templates/agents.md` in full. This is the **canonical template**. The generated AGENTS.md must follow its exact structure.
+**Substep 8a — Read the template.** Read `@./templates/agents.md` in full RIGHT NOW before writing anything. This is the canonical template. You need its exact content.
+
+> 🛑 **HARD GATE:** Did you just read `@./templates/agents.md`? If not, go back and read it now. The next substep requires copying sections verbatim from the template. You cannot do that without reading it first.
+
+**Substep 8b — Write AGENTS.md.** Create the file `AGENTS.md` at the project root. The file structure MUST follow the template exactly. Here is the required section order:
+
+1. `# AGENTS.md — [Project Name]` — replace `[PROJECT NAME]` with the actual project name
+2. `## Soul — Who We Are Together` — **copy VERBATIM from the template** including all of Voice & Character and Relationship Model. Do not rewrite, summarize, or rephrase any of it.
+3. `## Principles — How We Operate` — **copy VERBATIM from the template**. All 10 numbered principles, word for word.
+4. `## Request Routing Protocol` — **copy VERBATIM from the template**. The entire decision tree and examples.
+5. `## Platform Context` — **copy VERBATIM from the template**. The learnship key facts block.
+6. `## Current Phase` — **FILL IN** with project-specific data:
+   ```
+   **Milestone:** v1.0 — [Milestone Name from PROJECT.md]
+   **Phase:** 1 — [Phase 1 name from ROADMAP.md]
+   **Status:** planning
+   **Last updated:** [today's date]
+   ```
+7. `## Project Structure` — **FILL IN** by scanning existing directories:
+   ```bash
+   node -e "const{readdirSync,statSync}=require('fs'),{join}=require('path');const walk=(d,dep=0)=>{if(dep>2)return;try{readdirSync(d).filter(f=>!f.startsWith('.')&&f!=='node_modules').forEach(f=>{const p=join(d,f);if(statSync(p).isDirectory()){console.log(' '.repeat(dep*2)+'├── '+f+'/');walk(p,dep+1);}});}catch{}};walk('.');"
+   ```
+   Populate the tree with real directories and one-line descriptions.
+8. `## Tech Stack` — **FILL IN** using research output (if available) or user's stated stack:
+   - Language + version
+   - Framework
+   - Key libraries (the 3-5 most important)
+   - How to run the dev server
+   - How to run tests
+9. `## Skills — Operational Knowledge` — **copy VERBATIM from the template**. CHANGELOG Discipline, Decisions Register, and Solutions Store sections.
+10. `## Regressions — What Broke and What We Learned` — **copy VERBATIM from the template**. The empty starter block.
+
+**You may ADD project-specific sections** (e.g., Conventions, Content Sources, Definition of Done) **after** Tech Stack and **before** Skills. But you must NEVER remove, rename, or replace the 10 sections listed above.
+
+**Substep 8c — Verify AGENTS.md.** Run this command now. Do not skip it.
+
+> 🔴 **HARD GATE — Run this verification command now. Do not skip it. Do not proceed without running it.**
 
-**Sections to copy VERBATIM (do not rewrite, do not summarize, do not rephrase):**
-- `## Soul — Who We Are Together` (entire section including Voice & Character and Relationship Model)
-- `## Principles — How We Operate` (all 10 principles, verbatim)
-- `## Platform Context` (the learnship key facts block, verbatim)
-- `## Skills — Operational Knowledge` (CHANGELOG Discipline and Decisions Register, verbatim)
-- `## Regressions — What Broke and What We Learned` (the empty starter block, verbatim)
-
-**Sections to FILL IN with project-specific information:**
-
-**Title** — Replace `[PROJECT NAME]` with the actual project name.
-
-**Current Phase** block:
-```
-Milestone: v1.0 — [Milestone Name from PROJECT.md]
-Phase: 1 — [Phase 1 name from ROADMAP.md]
-Status: planning
-Last updated: [today's date]
-```
-
-**Project Structure** — derive from the project description and any existing directories:
 ```bash
-find . -maxdepth 2 -not -path './.git/*' -not -path './node_modules/*' -not -path './.planning/*' -type d | sort | head -20
-# PowerShell: Get-ChildItem -Directory -Recurse -Depth 2 | Where-Object { $_.FullName -notmatch '\.git|node_modules|\.planning' } | Select-Object -First 20
+node -e "const fs=require('fs');if(!fs.existsSync('AGENTS.md')){console.log('AGENTS.md NOT FOUND');process.exit(1);}const f=fs.readFileSync('AGENTS.md','utf8');const required=['Soul','Principles','Request Routing Protocol','Platform Context','Current Phase','Project Structure','Tech Stack','Skills','Regressions'];const missing=required.filter(s=>!f.includes('## '+s));if(missing.length){console.log('AGENTS.md INCOMPLETE — missing sections:\\n'+missing.map(s=>'  ## '+s).join('\\n'));process.exit(1);}const verbatim=['pair programmer','Direct, no fluff','Have opinions','Friction Is Signal','Minimal Upstream Fix','decision tree'];const missingV=verbatim.filter(s=>!f.includes(s));if(missingV.length){console.log('AGENTS.md TEMPLATE VIOLATION — these verbatim phrases are missing (did you rewrite instead of copy?):\\n'+missingV.join('\\n'));process.exit(1);}console.log('AGENTS.md VERIFIED OK — all '+required.length+' sections present, verbatim content intact');"
 ```
 
-Populate the `## Project Structure` tree with real directories and one-line descriptions.
-
-**Tech Stack** — use the research output (if research was run) or the user's stated stack:
-- Language + version
-- Framework
-- Key libraries (the 3-5 most important)
-- How to run the dev server
-- How to run tests
-
-**You may ADD project-specific sections** (e.g., Conventions, Content Sources, Definition of Done) **after** the Tech Stack section and **before** Skills. But you must NEVER remove, rename, or replace the template sections listed above.
-
-**Verification checklist (run before committing):**
-- [ ] File starts with `# AGENTS.md — [Project Name]`
-- [ ] `## Soul — Who We Are Together` exists with Voice & Character and Relationship Model
-- [ ] `## Principles — How We Operate` exists with all 10 numbered principles
-- [ ] `## Platform Context` exists with the 7-step phase loop
-- [ ] `## Current Phase` exists with milestone, phase, status, and date
-- [ ] `## Project Structure` exists with a directory tree
-- [ ] `## Tech Stack` exists with language, framework, libraries, dev server, tests
-- [ ] `## Skills — Operational Knowledge` exists with CHANGELOG Discipline and Decisions Register
-- [ ] `## Regressions — What Broke and What We Learned` exists at the end
+> 🛑 **If the command prints `INCOMPLETE` or `TEMPLATE VIOLATION` or exits with code 1:** The AGENTS.md is broken. Re-read `@./templates/agents.md` and fix the missing sections or restore the verbatim content. Run the verification again. You MUST see `AGENTS.md VERIFIED OK` before continuing to Step 9.
 
 **If `commit_mode` is `auto`:**
 ```bash
@@ -454,6 +498,8 @@ git add AGENTS.md && git commit -m "docs: add AGENTS.md with project context"
 
 ## Step 9: Done
 
+Display this banner and then **STOP. Do not continue. Do not run any other workflow. Do not start Phase 1.**
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  learnship ► PROJECT INITIALIZED ✓
@@ -486,16 +532,26 @@ After verify-work passes: `/review` for multi-persona code review, `/ship` to te
 > **Platform detected:** `[PLATFORM]` — parallelization is `[true/false]`
 ```
 
+> 🔴 **HARD STOP — `/new-project` is now complete. This workflow is FINISHED.**
+>
+> **Do NOT automatically start `/discuss-phase 1`.** Do NOT run any phase workflow. Do NOT begin implementing Phase 1. Do NOT say "Let me start Phase 1" or "Now starting Phase 1" or anything similar.
+>
+> The user must explicitly type `/discuss-phase 1` (or another command) in a **new message** to continue. Your only job now is to display the banner above and wait.
+>
+> If the user's next message is a new task or question, apply the Request Routing Protocol from AGENTS.md — the routing suspension from Step 1 is now lifted.
+
 ---
 
 ## Learning Checkpoint
 
 Read `learning_mode` from `.planning/config.json`.
 
-**If `auto`:** Offer this now:
+**If `auto`:** Offer this after the done banner (still within this message, but AFTER the banner):
 
 > 💡 **Learning moment:** You've just defined what you're building. Want to validate your mental model before coding starts?
 > 
 > `@agentic-learning brainstorm [your project topic]` — Talk through the design and surface any blind spots before the first line of code.
 
 **If `manual`:** Add a quiet note: *"Tip: `@agentic-learning brainstorm [topic]` is available whenever you want to think through the design."*
+
+**After displaying the learning checkpoint, STOP. Wait for the user's next message.**

package/learnship/workflows/next.md

@@ -19,10 +19,14 @@ node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/PROJECT.md
 **If MISSING:**
 
 ```
-No project found. Starting /new-project...
+No project found.
+
+▶ Starting: /new-project — initialize a new project
+▶ Not sure what to build? `@agentic-learning brainstorm [idea]` — think through it first
+▶ Have an existing codebase? /ideate — scan for improvement opportunities
 ```
 
-Immediately run the `new-project` workflow. Stop here.
+Ask the user which option they'd like. If they choose `/new-project` or don't specify, run the `new-project` workflow. Stop here.
 
 ---
 

package/learnship/workflows/quick.md

@@ -238,6 +238,9 @@ Summary: .planning/quick/[NEXT_NUM]-[SLUG]/[NEXT_NUM]-SUMMARY.md
 [If --full: Verification: [status]]
 Commit: [hash]
 
+💡 Solved something notable? `/compound` — capture the solution while context is fresh
+💡 Ready to push? `/ship` — test → commit → push → PR
+
 Ready for next task: quick
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: spec-driven workflows, integrated learning, and production-grade design.",
   "keywords": [
     "agentic",