learnship 2.0.8 → 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.8",
+  "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.8",
+  "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.8",
+  "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/workflows/new-project.md

@@ -298,46 +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/` with **mandatory sections** as specified below. Do not write freeform prose — each file must contain the required `##` headers.
+**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.
 
-1. **STACK.md** — Standard tech stack for this domain
-   - Required sections: `## Recommended Stack`, `## Alternatives Considered`, `## What NOT to Use` (with reasons), `## Versions`
-2. **FEATURES.md** — What features exist in this domain
-   - Required sections: `## Table Stakes` (must-haves), `## Differentiators` (nice-to-haves), `## Anti-Features` (what to avoid)
-3. **ARCHITECTURE.md** — How systems in this domain are typically structured
-   - Required sections: `## Component Boundaries`, `## Data Flow`, `## Build Order` (suggested sequence), `## Integration Points`
-4. **PITFALLS.md** — Common mistakes and prevention strategies
-   - Required sections: `## Common Mistakes`, `## Warning Signs`, `## Prevention Strategies`
+Create the research directory first:
 
-After all four complete, synthesize into `.planning/research/SUMMARY.md`:
-   - Required sections: `## Recommended Stack`, `## Table Stakes Features`, `## Key Architecture Decisions`, `## Top Pitfalls`
+```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.
+
+**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`
 
-**Post-research verification (cross-platform):**
+> 🔴 **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');
-"
+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');"
 ```
 
-> 🛑 If verification fails, fix the missing files or sections before proceeding. Do not skip research verification.
+> 🛑 **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:
 ```
@@ -435,63 +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.
-
-**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
-```
-
-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
-- [ ] `## Request Routing Protocol` exists with decision tree
-- [ ] `## 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
-
-**Automated verification (cross-platform — run this, do not skip):**
+**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.**
 
 ```bash
-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);}console.log('AGENTS.md VERIFIED OK — all '+required.length+' mandatory sections present');"
+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');"
 ```
 
-> 🛑 If verification fails, fix the missing sections before committing. Do NOT proceed to Step 9 with an incomplete AGENTS.md. Re-read `@./templates/agents.md` and add the missing sections.
+> 🛑 **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
@@ -502,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 ✓
@@ -534,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.0.8",
+  "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",