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

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/gemini-extension.json

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

@@ -479,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.
@@ -518,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.10",
+  "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",