learnship 1.9.17 → 1.9.19

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 42 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": "1.9.17",
+  "version": "1.9.19",
   "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 — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "1.9.17",
+  "version": "1.9.19",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/bin/install.js

@@ -501,6 +501,7 @@ function copyDir(srcDir, destDir, pathPrefix, platform) {
       let c = fs.readFileSync(src, 'utf8');
       c = replacePaths(c, pathPrefix, platform);
       if (entry.name === 'new-project.md') c = rewriteNewProject(c, platform);
+      if (entry.name === 'agents.md') c = rewriteAgentsMd(c, platform, pathPrefix);
       if (platform === 'opencode') c = convertToOpencode(c);
       // gemini agents converted separately; body ${VAR} escaping done there
       fs.writeFileSync(dest, c);
@@ -529,6 +530,62 @@ function replacePaths(content, pathPrefix, platform) {
   return c;
 }
 
+/**
+ * Rewrite AGENTS.md markers with platform-specific skill invocation instructions.
+ * On Windsurf, @agentic-learning and @impeccable are native @skill invocations.
+ * On all other platforms there is no @mention dispatch — the AI must be told
+ * explicitly where the skill files live and what to do when the user types @skill-name.
+ */
+function rewriteAgentsMd(content, platform, pathPrefix) {
+  if (!content.includes('<!-- LEARNSHIP_SKILLS_BLOCK -->')) return content;
+
+  let block;
+  if (platform === 'windsurf') {
+    block = `### Learning Partner — \`@agentic-learning\`
+
+Windsurf loads \`@agentic-learning\` natively as a skill. When the user (or a workflow) invokes \`@agentic-learning <action>\`, Windsurf automatically routes it to the installed skill.
+
+Available actions: \`learn\`, \`quiz\`, \`reflect\`, \`space\`, \`brainstorm\`, \`explain-first\`, \`struggle\`, \`either-or\`, \`interleave\`, \`cognitive-load\`
+
+### Design System — \`@impeccable\`
+
+Windsurf loads \`@impeccable\` natively as a skill. When the user (or a workflow) invokes \`@impeccable <action>\`, Windsurf automatically routes it to the installed skill.
+
+Available actions: \`adapt\`, \`animate\`, \`arrange\`, \`audit\`, \`bolder\`, \`clarify\`, \`colorize\`, \`critique\`, \`delight\`, \`distill\`, \`extract\`, \`frontend-design\`, \`harden\`, \`normalize\`, \`onboard\`, \`optimize\`, \`overdrive\`, \`polish\`, \`quieter\`, \`teach-impeccable\`, \`typeset\``;
+  } else {
+    // For all non-Windsurf platforms: @mention is not a native dispatch mechanism.
+    // The AI must read the skill file directly and execute the instructions inside it.
+    // pathPrefix ends with learnship/ — skills are at learnship/skills/
+    const skillsPath = pathPrefix + 'skills';
+
+    block = `### Learning Partner — \`@agentic-learning\`
+
+**There is no native @mention skill dispatch on this platform.** When a workflow checkpoint or the user mentions \`@agentic-learning <action>\`, you must:
+
+1. Read \`${skillsPath}/agentic-learning/SKILL.md\`
+2. Find the section for the requested action (e.g. \`either-or\`, \`brainstorm\`, \`reflect\`, \`quiz\`, etc.)
+3. Execute those instructions directly in this conversation
+
+Available actions: \`learn\`, \`quiz\`, \`reflect\`, \`space\`, \`brainstorm\`, \`explain-first\`, \`struggle\`, \`either-or\`, \`interleave\`, \`cognitive-load\`
+
+**Do NOT say "@agentic-learning isn't installed" — it is installed. Read the SKILL.md and run the action.**
+
+### Design System — \`@impeccable\`
+
+**There is no native @mention skill dispatch on this platform.** When a workflow checkpoint or the user mentions \`@impeccable <action>\`, you must:
+
+1. Read \`${skillsPath}/impeccable/SKILL.md\`
+2. Find the section for the requested action (e.g. \`audit\`, \`critique\`, \`polish\`, etc.)
+3. Execute those instructions directly in this conversation
+
+Available actions: \`adapt\`, \`animate\`, \`arrange\`, \`audit\`, \`bolder\`, \`clarify\`, \`colorize\`, \`critique\`, \`delight\`, \`distill\`, \`extract\`, \`frontend-design\`, \`harden\`, \`normalize\`, \`onboard\`, \`optimize\`, \`overdrive\`, \`polish\`, \`quieter\`, \`teach-impeccable\`, \`typeset\`
+
+**Do NOT say "@impeccable isn't installed" — it is installed. Read the SKILL.md and run the action.**`;
+  }
+
+  return content.replace('<!-- LEARNSHIP_SKILLS_BLOCK -->', block);
+}
+
 /** Rewrite new-project.md markers with exact platform-specific content at install time */
 function rewriteNewProject(content, platform) {
   const dirName = getDirName(platform);
@@ -1339,6 +1396,7 @@ if (process.env.LEARNSHIP_TEST_MODE) {
     parseJsonc,
     replacePaths,
     rewriteNewProject,
+    rewriteAgentsMd,
     installClaudePlugins,
     toHomePrefix,
     LEARNSHIP_CODEX_MARKER,

package/cursor-rules/learnship.mdc

@@ -44,6 +44,32 @@ Always read `STATE.md` and `ROADMAP.md` before any planning or execution operati
 - **Goal-backward verification**: Check that `must_haves` are met, not just that tasks ran.
 - **Deferred ideas**: Note things outside current phase scope in the roadmap backlog.
 
+## Skills — @agentic-learning and @impeccable
+
+**There is no native @mention skill dispatch in Cursor.** When a workflow checkpoint or the user mentions `@agentic-learning <action>` or `@impeccable <action>`, you must read the skill file and execute its instructions directly.
+
+### Learning Partner — `@agentic-learning`
+
+When `@agentic-learning <action>` is mentioned:
+1. Read `node_modules/learnship/skills/agentic-learning/SKILL.md` (or `learnship/skills/agentic-learning/SKILL.md` if installed locally)
+2. Find the section for the requested action
+3. Execute those instructions in this conversation
+
+Available actions: `learn`, `quiz`, `reflect`, `space`, `brainstorm`, `explain-first`, `struggle`, `either-or`, `interleave`, `cognitive-load`
+
+**Do NOT say "@agentic-learning isn't installed" — it is installed. Read the SKILL.md and run the action.**
+
+### Design System — `@impeccable`
+
+When `@impeccable <action>` is mentioned:
+1. Read `node_modules/learnship/skills/impeccable/SKILL.md` (or `learnship/skills/impeccable/SKILL.md` if installed locally)
+2. Find the section for the requested action
+3. Execute those instructions in this conversation
+
+Available actions: `adapt`, `animate`, `arrange`, `audit`, `bolder`, `clarify`, `colorize`, `critique`, `delight`, `distill`, `extract`, `frontend-design`, `harden`, `normalize`, `onboard`, `optimize`, `overdrive`, `polish`, `quieter`, `teach-impeccable`, `typeset`
+
+**Do NOT say "@impeccable isn't installed" — it is installed. Read the SKILL.md and run the action.**
+
 ## Parallel Execution
 
 Cursor supports real parallel subagents. During `/new-project` setup (Group D), ask:

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "1.9.17",
+  "version": "1.9.19",
   "description": "Agentic engineering done right — 42 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

@@ -100,6 +100,10 @@ When a user sends a message — whether it's a vague idea, a specific bug report
 
 ### Decision tree — apply in order:
 
+**0. Is `/new-project` currently in progress?**
+
+If `.planning/PROJECT.md` does NOT exist but you are currently running `/new-project` (i.e., you have asked "What do you want to build?" and are waiting for answers, or you are in any step of the new-project ceremony): **the user's message is an answer to your workflow question, not a task to route.** Do NOT apply the routing protocol. Continue the `/new-project` ceremony from where you left off.
+
 **1. Is there a `.planning/PROJECT.md`?**
 - **No** → Stop. Tell the user: "No project found. Run `/new-project` to initialize." Do nothing else.
 - **Yes** → Continue to step 2.
@@ -127,6 +131,7 @@ Always tell the user which workflow you're about to invoke and why, then wait fo
 - User says "the login button is broken" → ❌ Don't fix it directly → ✅ Route to `/quick`
 - User says "I want to add dark mode" → ❌ Don't start implementing → ✅ Route to `discuss-phase`
 - User pastes a detailed spec → ❌ Don't treat it as a command to execute → ✅ Classify size, propose workflow, wait for yes
+- `/new-project` asked "What do you want to build?" and user replies with a detailed description → ❌ Don't treat as a task to route → ✅ It is ANSWER_1. Record it and ask Exchange 2.
 
 ---
 
@@ -181,6 +186,8 @@ This project uses **learnship**. Key facts:
 
 ## Skills — Operational Knowledge
 
+<!-- LEARNSHIP_SKILLS_BLOCK -->
+
 ### CHANGELOG Discipline
 
 Every significant change gets a dated entry in `CHANGELOG.md` with:

package/learnship/workflows/new-project.md

@@ -10,6 +10,8 @@ Initialize a new project with full context gathering, optional research, require
 
 <!-- LEARNSHIP_PLATFORM_LABEL -->
 
+> **Routing protocol suspended.** While this workflow is running, every user message is an answer to a workflow question — not a task to route. Do NOT apply the request routing protocol until `/new-project` is fully complete and `.planning/PROJECT.md` exists.
+
 Check if `.planning/PROJECT.md` already exists:
 
 ```bash
@@ -18,6 +20,19 @@ python3 -c "import os; print('EXISTS' if os.path.exists('.planning/PROJECT.md')
 
 **If EXISTS:** Stop. Project already initialized. Use the `progress` workflow to see where you are.
 
+**Check for an existing codebase:**
+
+```bash
+python3 -c "
+import os, pathlib
+files = [p for p in pathlib.Path('.').rglob('*') if p.is_file() and not any(x in p.parts for x in ['.git', 'node_modules', '.planning', '__pycache__', '.venv'])]
+print('HAS_CODE' if len(files) > 2 else 'BLANK')
+print(f'{len(files)} files')
+"
+```
+
+**If HAS_CODE:** Note this internally as `EXISTING_CODEBASE = true`. You will scan the codebase briefly in Step 1b before questioning. Do NOT use existing code as an excuse to skip or shorten the questioning ceremony — the ceremony exists precisely because you need the user's intent, not just their code.
+
 Check if git is initialized:
 
 ```bash
@@ -39,6 +54,16 @@ Create the planning directory:
 mkdir -p .planning/research
 ```
 
+## Step 1b: Existing Codebase Scan (only if EXISTING_CODEBASE = true)
+
+If `EXISTING_CODEBASE = true`, do a quick structural scan before questioning so your follow-up questions are grounded in reality:
+
+```bash
+find . -maxdepth 3 -not -path './.git/*' -not -path './node_modules/*' -not -path './.planning/*' -not -path './__pycache__/*' -not -path './.venv/*' | sort | head -40
+```
+
+Note the tech stack, key directories, and any README content internally. Use this ONLY to ask sharper follow-up questions — never to infer the user's intent or skip ceremony steps.
+
 ## Step 2: Configuration
 
 Ask the user the following questions to configure the project. Ask them in a conversational way — not all at once, but grouped naturally.
@@ -128,6 +153,8 @@ This step is **strictly sequential**. You must complete each numbered exchange f
 Ask: **"What do you want to build?"**
 
 > 🛑 STOP. Wait for the user's answer. Do not continue until you have received it. Record their answer internally as `ANSWER_1`.
+>
+> ⚠️ **A detailed answer to Exchange 1 does NOT satisfy Exchanges 2–4.** No matter how thorough ANSWER_1 is — a full paragraph, a spec dump, a wall of requirements — it is raw material for the follow-up questions, not a replacement for them. You still MUST ask Exchanges 2, 3, and 4 before proceeding to Step 4. The purpose of follow-ups is not to extract information the user forgot to mention — it is to pressure-test, sharpen, and surface blind spots in what they already said.
 
 **Exchange 2 — First follow-up:**
 

package/package.json

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