learnship 2.0.9 → 2.0.11

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.9",
+  "version": "2.0.11",
   "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.9",
+  "version": "2.0.11",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/SKILL.md

@@ -110,11 +110,13 @@ Does .planning/PROJECT.md exist?
 
 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.
+1. **Research decision = always ask the user.** After PROJECT.md is confirmed, you MUST ask: "Do you want me to research the domain ecosystem first?" and WAIT for a reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
 
-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.
+2. **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.
 
-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.
+3. **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.
+
+4. **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
 

package/bin/install.js

@@ -658,10 +658,13 @@ function rewriteNewProject(content, platform) {
   content = content.replace('<!-- LEARNSHIP_PARALLEL_BLOCK -->', parallelBlock);
 
   // Platform-specific AGENTS.md note
-  // Gemini CLI reads GEMINI.md automatically but NOT AGENTS.md — copy it so sessions have context
-  const agentsMdNote = platform === 'gemini'
-    ? `> **Gemini CLI** reads \`GEMINI.md\` automatically at session start, not \`AGENTS.md\`. Copy it now so every future session has project context:\n> \`\`\`bash\n> cp AGENTS.md GEMINI.md\n> git add GEMINI.md && git commit -m "docs: add GEMINI.md for Gemini CLI auto-loading"\n> \`\`\``
-    : '';
+  // Claude Code reads CLAUDE.md as primary; Gemini CLI reads GEMINI.md — copy so sessions have context
+  let agentsMdNote = '';
+  if (platform === 'claude') {
+    agentsMdNote = `> **Claude Code** reads \`CLAUDE.md\` as its primary context file. Copy AGENTS.md now so every future session has project context:\n> \`\`\`bash\n> cp AGENTS.md CLAUDE.md\n> git add CLAUDE.md && git commit -m "docs: add CLAUDE.md for Claude Code auto-loading"\n> \`\`\`\n>\n> **Keep them in sync:** Whenever you update AGENTS.md (e.g. via \`execute-phase\`), also update CLAUDE.md: \`cp AGENTS.md CLAUDE.md\``;
+  } else if (platform === 'gemini') {
+    agentsMdNote = `> **Gemini CLI** reads \`GEMINI.md\` automatically at session start, not \`AGENTS.md\`. Copy it now so every future session has project context:\n> \`\`\`bash\n> cp AGENTS.md GEMINI.md\n> git add GEMINI.md && git commit -m "docs: add GEMINI.md for Gemini CLI auto-loading"\n> \`\`\`\n>\n> **Keep them in sync:** Whenever you update AGENTS.md (e.g. via \`execute-phase\`), also update GEMINI.md: \`cp AGENTS.md GEMINI.md\``;
+  }
   content = content.replace('<!-- LEARNSHIP_AGENTSMD_PLATFORM_NOTE -->', agentsMdNote);
 
   return content;

package/cursor-rules/learnship.mdc

@@ -45,7 +45,7 @@ When the user runs `/new-project`, execute these **9 mandatory steps in order**.
 
 1. **Exchange 1 answer does NOT skip Exchanges 2–4.** No matter how detailed the user's answer to "What do you want to build?" — it is raw material for follow-ups, not a replacement. You MUST still ask Exchanges 2, 3, and 4.
 
-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.
+2. **Research decision = always ask the user.** After PROJECT.md is confirmed, ask: "Do you want me to research the domain ecosystem first?" and WAIT for the user's reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
 
 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.
 

package/gemini-extension.json

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

@@ -21,6 +21,9 @@ collaborators with different strengths.
   The "why" matters more than the "what."
 - **Domain-aware, not domain-faking.** Know the domain of this project. When uncertain about
   domain concepts, say so rather than hallucinate. Getting it wrong here has real consequences.
+- **Stop when confused, not after.** If something is ambiguous, surface it immediately. Present
+  the interpretations. Ask which one. Don't pick silently and run with it — that's how wrong
+  assumptions become wrong code.
 - **Learnings are first-class.** Every significant fix gets a "why it broke" and "what we
   learned." This is non-negotiable.
 - **Swearing is allowed when it lands.** Don't force it. Don't avoid it.
@@ -46,9 +49,13 @@ Decision-making heuristics for navigating ambiguity.
 When something is hard to implement, that's information about the design — not just an
 obstacle to power through. Investigate the resistance before routing around it.
 
-### 2. Minimal Upstream Fix Over Downstream Workaround
+### 2. Minimal Fix, Surgical Change
 
-Fix the root cause. Don't patch symptoms. One fix, one place.
+Fix the root cause, not the symptoms. One fix, one place. Touch only what you must — don't
+"improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken.
+Match existing style, even if you'd do it differently. Every changed line should trace directly
+to the request. When your changes create orphans (unused imports, dead variables), clean those
+up — but don't remove pre-existing dead code unless asked.
 
 ### 3. Preserve Real-World Signal
 
@@ -70,15 +77,19 @@ future guardrails.
 
 When we disagree, the motivation is wanting the project to succeed — not being right.
 
-### 7. One Moving Part at a Time
+### 7. One Thing at a Time, Nothing Extra
 
 When debugging or adding features, change one thing, verify, then move to the next.
-Multi-variable changes obscure what actually fixed the problem.
+Multi-variable changes obscure what actually fixed the problem. Write the minimum code
+that solves the stated problem — no speculative features, no abstractions for single-use
+cases, no "flexibility" that wasn't requested. If 200 lines could be 50, rewrite.
 
-### 8. Code Reads > Code Writes
+### 8. Understand First, Then Change
 
 Read existing code thoroughly before editing. Understand the current design before proposing
-changes. Most bugs come from not understanding what's already there. Read first, always.
+changes. Most bugs come from not understanding what's already there. When something is
+ambiguous and multiple interpretations exist, present them and ask — don't silently pick one.
+If you're confused, stop. Name what's unclear. Ask.
 
 ### 9. Keep Copies in Sync
 

package/learnship/workflows/execute-phase.md

@@ -337,8 +337,14 @@ node -e "const fs=require('fs');if(!fs.existsSync('AGENTS.md')){process.exit(0);
 
 > If verification fails, restore the missing sections from `@./templates/agents.md` before committing.
 
+**Sync platform-native copies (if they exist):**
+
+```bash
+node -e "const fs=require('fs');const copies=[['CLAUDE.md','Claude Code'],['GEMINI.md','Gemini CLI']];if(!fs.existsSync('AGENTS.md'))process.exit(0);copies.forEach(([f,p])=>{if(fs.existsSync(f)){fs.copyFileSync('AGENTS.md',f);console.log('Synced AGENTS.md → '+f+' ('+p+')');}});"
+```
+
 ```bash
-git add AGENTS.md
+git add AGENTS.md CLAUDE.md GEMINI.md 2>/dev/null
 git commit -m "docs: update AGENTS.md — phase [X] complete"
 ```
 

package/learnship/workflows/new-project.md

@@ -282,13 +282,47 @@ git add .planning/PROJECT.md && git commit -m "docs: initialize project"
 
 ## Step 5: Research Decision
 
-> **🔴 MANDATORY USER CHOICE — You must ask this question and wait for a reply. You are NOT allowed to decide this yourself, even if the domain seems trivial, familiar, or well-understood. The user decides. Always.**
+> **🔴 MANDATORY USER CHOICE — You must ask this question and wait for a reply. You are NOT allowed to decide this yourself.**
 
-Ask: **"Before I write the requirements — do you want me to research the domain ecosystem first?"**
-- **Research first** (recommended) — Discover standard stacks, expected features, architecture patterns
-- **Skip research** — I know this domain well, go straight to requirements
+Display this question to the user exactly as written:
 
-> 🛑 STOP. Wait for the user's explicit choice. Do not default to either option. Do not reason about whether research is needed — that is the user's call. Do not write REQUIREMENTS.md yet. Do not proceed until the user replies.
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCH DECISION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Before I write the requirements — do you want me to
+research the domain ecosystem first?
+
+ 1. Research first (recommended)
+    → Discover standard stacks, expected features,
+      architecture patterns, common pitfalls
+
+ 2. Skip research
+    → Go straight to requirements
+
+Reply 1 or 2.
+```
+
+> � **HARD GATE — This is a user decision. You MUST wait for the user to reply.**
+>
+> **You are FORBIDDEN from deciding this yourself.** It does not matter if:
+> - The tech stack is already defined in PROJECT.md
+> - The domain seems trivial or well-understood
+> - You already know the ecosystem
+> - The user gave detailed answers in Deep Questioning
+> - The project seems simple
+>
+> **None of these are valid reasons to skip the question.** The user ALWAYS gets asked. The user ALWAYS decides.
+>
+> **Forbidden responses (do NOT say anything like these):**
+> - "The tech stack is already well-defined in PROJECT.md. No research needed."
+> - "Since you've already described the stack, I'll skip research."
+> - "Moving straight to requirements/roadmap."
+> - "Research isn't necessary for this project."
+> - Any sentence that contains "no research needed" or "skip research" that you wrote yourself (not the user).
+>
+> **The ONLY acceptable next action is: display the question above and wait.** Do not write REQUIREMENTS.md. Do not write ROADMAP.md. Do not proceed to Step 6. Wait for the user's reply.
 
 **If Research first:**
 
@@ -445,6 +479,43 @@ 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.**
 
+**Substep 8a-pre — Check for existing context files.** Run this command now:
+
+```bash
+node -e "const fs=require('fs');const files=['AGENTS.md','CLAUDE.md','GEMINI.md','.cursorrules'];const found=files.filter(f=>fs.existsSync(f));if(found.length){console.log('EXISTING: '+found.join(', '));}else{console.log('NONE FOUND');}"
+```
+
+**If the command prints `EXISTING:`** — Ask the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► EXISTING CONTEXT FILES DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I found existing context file(s): [list from command output]
+
+What would you like to do?
+
+ 1. Replace (recommended for new learnship projects)
+    → Overwrite with learnship's AGENTS.md
+
+ 2. Merge
+    → Keep your existing content, add learnship sections
+
+ 3. Keep separate
+    → Write AGENTS.md alongside your existing file(s)
+
+Reply 1, 2, or 3.
+```
+
+> 🔴 **HARD GATE — Wait for the user's reply. Do NOT auto-decide.**
+
+- **Replace (1):** Continue to substep 8a. The old files will be overwritten.
+- **Merge (2):** Read the existing file(s) first, then in substep 8b, append learnship sections that are missing (Soul, Principles, Request Routing Protocol, etc.) while preserving the user's existing content at the top.
+- **Keep separate (3):** Continue to substep 8a. Write `AGENTS.md` as a new file. Leave existing files untouched.
+
+**If the command prints `NONE FOUND`:** Continue directly to substep 8a.
+
 **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.
@@ -484,7 +555,7 @@ git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md && git
 > 🔴 **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);}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');"
+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','Surgical Change','Nothing Extra','Understand First','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 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.

package/package.json

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