learnship 2.0.10 → 2.1.0

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",
+  "description": "Agentic engineering done right — 57 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.1.0",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

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

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://github.com/FavioVazquez/learnship/stargazers"><img src="https://img.shields.io/github/stars/FavioVazquez/learnship?style=flat&color=f59e0b" alt="Stars"></a>
   <a href="https://www.npmjs.com/package/learnship"><img src="https://img.shields.io/npm/v/learnship?color=cb3837&label=npm" alt="npm"></a>
   <img src="https://img.shields.io/badge/platforms-6-0ea5e9" alt="6 platforms">
-  <img src="https://img.shields.io/badge/workflows-49-3b82f6" alt="49 workflows">
+  <img src="https://img.shields.io/badge/workflows-57-3b82f6" alt="57 workflows">
 </p>
 
 <p align="center">
@@ -38,6 +38,7 @@ learnship gives you that harness as a portable, open-source layer that runs insi
 - **Persistent memory.** `/new-project` generates an `AGENTS.md` at your project root. Windsurf, Claude Code, and Cursor load it automatically every session; on other platforms the workflows reference it explicitly. No more repeating yourself.
 - **Structured process.** A repeatable phase loop (Discuss → Plan → Execute → Verify → Review → Ship → Compound) with spec-driven plans, wave-ordered execution, and UAT-driven verification. The harness controls what context reaches the agent at each step.
 - **Knowledge compounding (v2.0).** `/compound` captures solved problems as searchable documentation. `/review` runs multi-persona code review. `/challenge` stress-tests scope. `/ship` runs the full delivery pipeline. `/ideate` generates codebase-grounded ideas. `/guard` adds safety mode. `/sync-docs` detects stale documentation.
+- **Security, recovery, and session intelligence (v2.1).** `/secure-phase` runs per-phase STRIDE threat verification. `/forensics` investigates failed workflows. `/undo` safely reverts commits. `/note` captures ideas with zero friction. `/session-report` generates stakeholder summaries. `/docs-update` generates and verifies project documentation. `/extract-learnings` captures meta-knowledge from completed phases.
 - **Built-in learning.** Neuroscience-backed checkpoints at every phase transition so you understand what you shipped, not just that you shipped it.
 
 ---
@@ -140,7 +141,7 @@ What's covered:
 - **[Platform Guide](https://faviovazquez.github.io/learnship/platform-guide/windsurf/)**: dedicated pages for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex CLI
 - **[Core Concepts](https://faviovazquez.github.io/learnship/core-concepts/phase-loop/)**: phase loop, context engineering, planning artifacts, agentic vs vibe coding
 - **[Skills](https://faviovazquez.github.io/learnship/skills/agentic-learning/)**: all 11 `@agentic-learning` actions and all 21 `impeccable` design commands
-- **[Workflow Reference](https://faviovazquez.github.io/learnship/workflow-reference/core/)**: all 49 workflows documented with when and why to use each
+- **[Workflow Reference](https://faviovazquez.github.io/learnship/workflow-reference/core/)**: all 57 workflows documented with when and why to use each
 - **[Configuration](https://faviovazquez.github.io/learnship/configuration/)**: full `.planning/config.json` schema, speed presets, parallelization
 
 ---
@@ -176,7 +177,7 @@ Each platform gets the best experience it supports:
 | Skills (native `@invoke`) | ✓ | — | — | — | — |
 | Skills (context files) | ✓ | ✓ | ✓ | ✓ | ✓ |
 
-**What "parallel subagents" means:** On Claude Code, OpenCode, and Codex, `execute-phase` can spawn a dedicated executor agent per plan within a wave, each with its own full 200k context budget. Plans in the same wave run in parallel. Enable with `"parallelization": true` in `.planning/config.json`. All platforms default to sequential (always safe).
+**What "parallel subagents" means:** On Claude Code, OpenCode, and Codex, `execute-phase` can spawn a dedicated executor agent per plan within a wave, each with its own full 200k context budget. Plans in the same wave run in parallel. Enable with `"parallelization": { "enabled": true }` in `.planning/config.json` (legacy flat `"parallelization": true` also honored). Up to 5 concurrent agents per wave by default — configurable via `max_concurrent_agents`. All platforms default to sequential (always safe).
 
 ---
 
@@ -184,7 +185,7 @@ Each platform gets the best experience it supports:
 
 ![5 commands diagram](assets/quick-start-flow.png)
 
-learnship has 49 workflows. You don't need to know them all. Start with these five and everything else surfaces naturally from `/ls`.
+learnship has 57 workflows. You don't need to know them all. Start with these five and everything else surfaces naturally from `/ls`.
 
 | Command | What it does | When to use |
 |---------|-------------|-------------|
@@ -192,7 +193,7 @@ learnship has 49 workflows. You don't need to know them all. Start with these fi
 | `/next` | Read state and immediately run the right next workflow | When you just want to keep moving |
 | `/new-project` | Full init: questions → research → requirements → roadmap | Starting a new project |
 | `/quick "..."` | One-off task with atomic commits, no planning ceremony | Small fixes, experiments |
-| `/help` | All 49 workflows organized by category | Discovering capabilities |
+| `/help` | All 57 workflows organized by category | Discovering capabilities |
 
 > **Tip:** `/ls` works for both new and returning users. New user with no project? It explains learnship and offers to run `/new-project`. Returning user? It shows your progress and suggests exactly what to do next.
 
@@ -232,6 +233,25 @@ flowchart LR
 
 **Just starting?** `/ls` or `/next` will route you into the right step automatically.
 
+**Optional per-phase:** `/secure-phase N` (STRIDE security verification), `/extract-learnings N` (capture meta-knowledge).
+**Recovery:** `/forensics` (post-mortem), `/undo` (safe revert).
+
+### What's new in v2.1
+
+![v2.1 overview](assets/v21-overview.png)
+
+v2.1 adds 8 new workflows, 5 new references, 3 new templates, and 2 new agents — all with learning checkpoints and full 6-platform support:
+
+| Category | New workflows |
+|----------|--------------|
+| **Security** | `/secure-phase` — per-phase STRIDE threat verification |
+| **Documentation** | `/docs-update` — generate and verify project docs against codebase |
+| **Recovery** | `/forensics` — post-mortem investigation · `/undo` — safe git revert |
+| **Session** | `/note` — zero-friction capture · `/session-report` — stakeholder summaries |
+| **Learning** | `/extract-learnings` — decisions, lessons, patterns, surprises · `/milestone-summary` — team onboarding |
+
+Enhanced: `/discuss-phase` (scope guardrails + domain probes), `/execute-phase` (`--wave` flag + context scaling), `/quick` (`--research --validate --full` composable flags), `/ideate` (`--explore` Socratic mode).
+
 ---
 
 ## 🏗️ How It Works
@@ -310,7 +330,7 @@ AGENTS.md                   ← your AI agent reads this every conversation
 
 ## 📖 Workflow Reference: Advanced
 
-> These are all 49 workflows. Most users discover them naturally from `/ls`. Scan this when you want to know if a specific capability exists.
+> These are all 57 workflows. Most users discover them naturally from `/ls`. Scan this when you want to know if a specific capability exists.
 
 ### Core Workflow
 
@@ -411,11 +431,10 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 
 ```json
 {
-  "mode": "yolo",
+  "mode": "interactive",
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
-  "parallelization": false,
   "test_first": false,
   "planning": {
     "commit_docs": true,
@@ -428,7 +447,30 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
     "verifier": true,
     "validation": true,
     "review": true,
-    "solutions_search": true
+    "solutions_search": true,
+    "security_enforcement": true,
+    "discuss_mode": "discuss",
+    "tdd_mode": false
+  },
+  "parallelization": {
+    "enabled": false,
+    "plan_level": true,
+    "task_level": false,
+    "max_concurrent_agents": 5,
+    "min_plans_for_parallel": 2
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_phases": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "execute_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
   },
   "review": {
     "auto_after_verify": false
@@ -438,6 +480,9 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
     "conventional_commits": true,
     "pr_template": true
   },
+  "hooks": {
+    "context_warnings": true
+  },
   "git": {
     "branching_strategy": "none",
     "phase_branch_template": "phase-{phase}-{slug}",
@@ -454,7 +499,7 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 | `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase size: 3-5 / 5-8 / 8-12 phases |
 | `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Agent model tier (see table below) |
 | `learning_mode` | `auto`, `manual` | `auto` | `auto` offers learning at checkpoints; `manual` requires explicit invocation |
-| `parallelization` | `true`, `false` | `false` | Parallel subagents per plan on supported platforms |
+| `parallelization.enabled` | `true`, `false` | `false` | Parallel subagents per plan on supported platforms |
 | `test_first` | `true`, `false` | `false` | TDD mode: write failing test first, verify red, implement, verify green |
 | `planning.commit_mode` | `auto`, `manual` | `auto` | `auto` commits after each workflow step; `manual` skips all git commits |
 
@@ -802,7 +847,7 @@ Run `/audit-milestone` to surface all gaps, then `/plan-milestone-gaps` to creat
 ```
 learnship/
 ├── .windsurf/
-│   ├── workflows/          # 49 workflows as slash commands
+│   ├── workflows/          # 57 workflows as slash commands
 │   └── skills/
 │       ├── agentic-learning/   # Learning partner (SKILL.md + references), native on Windsurf + Claude Code
 │       └── impeccable/         # Design suite: 21 skills, native on Windsurf + Claude Code
@@ -812,13 +857,13 @@ learnship/
 │           ├── polish/          #   /polish
 │           └── …14 more/        #   /colorize /animate /bolder /quieter /distill /clarify…
 │                               # → on OpenCode/Gemini/Codex: both skills copied to learnship/skills/ as context files
-├── commands/               # 49 Claude Code-style slash command wrappers
+├── commands/               # 57 Claude Code-style slash command wrappers
 │   └── learnship/          # /learnship:ls, /learnship:new-project, etc.
 ├── learnship/              # Payload installed into the target platform config dir
-│   ├── workflows/          # 49 workflow markdown files (the actual instructions)
+│   ├── workflows/          # 57 workflow markdown files (the actual instructions)
 │   ├── references/         # Reference docs (questioning, verification, git, design, learning)
 │   └── templates/          # Document templates for .planning/ + AGENTS.md template
-├── agents/                 # 10 agent personas (planner, researcher, executor, verifier, debugger, plan-checker, solution-writer, code-reviewer, challenger, ideation-agent)
+├── agents/                 # 12 agent personas (planner, researcher, executor, verifier, debugger, plan-checker, solution-writer, code-reviewer, challenger, ideation-agent, security-auditor, doc-writer)
 ├── assets/                 # Brand images (banner, explainers, diagrams)
 ├── bin/
 │   └── install.js          # Multi-platform installer (Claude Code, OpenCode, Gemini CLI, Codex CLI, Windsurf)

package/SKILL.md

@@ -32,9 +32,17 @@ The following workflows are available as platform slash commands (Windsurf) or c
 | `/review` | Code ready for review — multi-persona quality check |
 | `/challenge` | About to commit to a milestone or big feature — stress-test the scope |
 | `/ship` | Tests pass, code reviewed — ship it (test → lint → commit → push → PR) |
-| `/ideate` | Looking for what to build next — codebase-grounded idea generation |
+| `/ideate` | Looking for what to build next — codebase-grounded idea generation (add `--explore` for Socratic mode) |
 | `/guard` | Working on sensitive files — enable safety mode |
 | `/sync-docs` | After code changes — detect stale documentation |
+| `/forensics` | Something went wrong — post-mortem investigation (read-only) |
+| `/undo` | Need to revert commits safely — preserves git history |
+| `/note [text]` | Quick idea capture — zero friction, no questions |
+| `/session-report` | End of session — generate summary for stakeholders |
+| `/secure-phase [N]` | After execution — per-phase STRIDE security verification |
+| `/docs-update` | Generate or update project documentation |
+| `/extract-learnings [N]` | After phase completion — structured learning extraction |
+| `/milestone-summary` | Generate comprehensive milestone summary for team onboarding |
 
 ## Planning Artifacts
 
@@ -44,7 +52,9 @@ All project state lives in `.planning/`. Key files:
 - `.planning/PROJECT.md` — Vision, requirements, key decisions
 - `.planning/ROADMAP.md` — Phase-by-phase delivery plan
 - `.planning/STATE.md` — Current position, decisions, blockers
-- `.planning/phases/[N]-[slug]/` — Per-phase artifacts (CONTEXT, RESEARCH, PLANs, SUMMARYs, UAT, VERIFICATION)
+- `.planning/phases/[N]-[slug]/` — Per-phase artifacts (CONTEXT, RESEARCH, PLANs, SUMMARYs, UAT, VERIFICATION, SECURITY, LEARNINGS)
+- `.planning/notes/` — Quick notes captured via `/note`
+- `.planning/reports/` — Session reports and forensic reports
 
 Always read STATE.md and ROADMAP.md before any planning or execution operation to understand current project position.
 
@@ -62,6 +72,8 @@ Reference these files when adopting a specific role:
 - `@./agents/challenger.md` — Stress-testing proposals through product and engineering lenses
 - `@./agents/ideation-agent.md` — Generating codebase-grounded improvement ideas
 - `@./agents/plan-checker.md` — Verifying PLAN.md completeness, goal coverage, wave correctness
+- `@./agents/security-auditor.md` — Per-phase STRIDE threat verification (read-only)
+- `@./agents/doc-writer.md` — Writing and updating project documentation
 
 ## Learning Mode
 
@@ -81,6 +93,10 @@ Learning checkpoints:
 - After `/ship` → `@agentic-learning reflect` (what went well in this cycle?)
 - After `/ideate` → `@agentic-learning brainstorm` (explore top idea collaboratively)
 - During complex quick tasks → `@agentic-learning struggle`
+- After `/forensics` → `@agentic-learning reflect` (what caused the failure?)
+- After `/extract-learnings` → `@agentic-learning space` (schedule learnings for review)
+- After `/secure-phase` → `@agentic-learning learn` (security patterns)
+- After `/session-report` → `@agentic-learning reflect` (session-level reflection)
 
 ## Design Skill
 
@@ -129,7 +145,13 @@ When running `/new-project`, these are non-negotiable hard gates. Violating any
 ## Reference Files
 
 - `@./references/questioning.md` — Questioning techniques for new-project and discuss-phase
+- `@./references/domain-probes.md` — Domain-aware probing patterns (auth, real-time, dashboard, API, DB, search, AI/ML)
 - `@./references/verification-patterns.md` — How to verify implementation quality
 - `@./references/git-integration.md` — Git commit conventions and branching strategy
 - `@./references/planning-config.md` — Config.json schema and options
 - `@./references/solution-schema.md` — YAML frontmatter schema for `.planning/solutions/`
+- `@./references/thinking-models.md` — Structured reasoning models for planning (Pre-Mortem, MECE, Constraint, etc.)
+- `@./references/universal-anti-patterns.md` — Rules that apply to all workflows and agents
+- `@./references/context-budget.md` — Context window management and degradation tiers
+- `@./references/gates.md` — Gate taxonomy (pre-flight, revision, escalation, abort)
+- `@./references/common-bug-patterns.md` — Stub detection, wiring gaps, state drift patterns

package/agents/learnship-doc-writer.md

@@ -0,0 +1,63 @@
+---
+name: learnship-doc-writer
+description: Writes and updates project documentation files — grounded in the live codebase, verifies factual claims. Spawned by docs-update workflow.
+tools: Read, Write, Edit, Bash, Glob, Grep
+color: cyan
+---
+
+<role>
+You are a learnship doc-writer. You write and update project documentation files that are grounded in the actual codebase — every claim must be verifiable.
+
+Spawned by `docs-update` when parallelization is enabled.
+
+Your job: Write a single documentation file (README, ARCHITECTURE, etc.) that accurately describes the current state of the project.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+Before writing, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
+2. Read `.planning/STATE.md` for current phase and decisions
+3. Read `.planning/PROJECT.md` for project vision and scope
+</project_context>
+
+<writing_principles>
+
+## Core Rules
+
+1. **Ground every claim in the codebase.** Don't write "the API supports pagination" unless you can verify pagination code exists. Read the source before documenting it.
+2. **Verify file paths.** Every file path mentioned in the doc must exist on disk. Run `ls` to check.
+3. **Verify commands.** Every command shown in a doc should work. If you can't run it, mark it with a note.
+4. **Preserve existing voice.** When updating an existing doc, match the author's writing style. Don't rewrite sections that are still accurate.
+5. **Be specific, not generic.** "Run `npm start` to start the dev server on port 3000" beats "Start the development server."
+
+## Doc Types
+
+| Type | Purpose | Key Sections |
+|------|---------|-------------|
+| README | First thing a new person reads | What, why, quickstart, structure |
+| ARCHITECTURE | System design overview | Components, data flow, key decisions |
+| GETTING-STARTED | Setup from zero to running | Prerequisites, install, first run |
+| DEVELOPMENT | Day-to-day dev workflow | Commands, conventions, debugging |
+| TESTING | How to write and run tests | Framework, patterns, running |
+| CONFIGURATION | All config options | Schema, defaults, examples |
+| API | Endpoint reference | Routes, params, responses |
+| CONTRIBUTING | How to contribute | Process, standards, PR template |
+| DEPLOYMENT | How to deploy | Environments, commands, CI/CD |
+
+## Verification
+
+After writing each doc, verify:
+```bash
+# Check all file references exist
+grep -oE '`[a-zA-Z0-9_./-]+\.[a-z]+`' [doc] | tr -d '`' | while read f; do
+  [ -f "$f" ] || echo "MISSING: $f"
+done
+```
+
+If any file reference is broken, fix the doc before committing.
+
+</writing_principles>

package/agents/learnship-security-auditor.md

@@ -0,0 +1,67 @@
+---
+name: learnship-security-auditor
+description: Verifies threat mitigation coverage for a phase — reads PLAN.md threat data, analyzes codebase for security concerns, classifies threats. Read-only — does not modify source code.
+tools: Read, Bash, Glob, Grep
+color: red
+---
+
+<role>
+You are a learnship security auditor. You verify that security threats identified during planning have been properly mitigated in the implementation.
+
+Spawned by `secure-phase` when parallelization is enabled.
+
+Your job: Analyze the codebase for security concerns, classify threats using STRIDE, and produce a SECURITY.md report.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+
+**You are READ-ONLY.** Do not modify source code. Only write the SECURITY.md report file.
+</role>
+
+<project_context>
+Before auditing, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
+2. Read `.planning/STATE.md` for current phase and decisions
+3. Read `.planning/config.json` for security enforcement settings
+</project_context>
+
+<audit_methodology>
+
+## STRIDE Categories
+
+| Category | Question | Examples |
+|----------|----------|----------|
+| **S**poofing | Can someone pretend to be someone else? | Auth bypass, session hijacking |
+| **T**ampering | Can someone modify data they shouldn't? | SQL injection, CSRF, file manipulation |
+| **R**epudiation | Can actions be denied after the fact? | Missing audit logs, unsigned transactions |
+| **I**nfo Disclosure | Can sensitive data leak? | Exposed secrets, verbose errors, PII in logs |
+| **D**enial of Service | Can the system be made unavailable? | Unbounded queries, resource exhaustion |
+| **E**levation of Privilege | Can someone gain unauthorized access? | Missing authz checks, insecure defaults |
+
+## What to Check
+
+For each file modified in this phase:
+
+1. **Input validation** — Are user inputs validated before processing?
+2. **Authentication** — Are auth checks present on protected routes?
+3. **Authorization** — Are permission checks granular enough?
+4. **Data handling** — Are secrets, PII, and tokens handled safely?
+5. **Error handling** — Do errors leak implementation details?
+6. **Dependencies** — Are there known vulnerabilities in new dependencies?
+
+## Threat Classification
+
+For each identified concern:
+- **CLOSED** — mitigation found in code, OR accepted risk documented, OR transferred to third-party
+- **OPEN** — none of the above
+
+## Output Format
+
+Write the SECURITY.md file using the template at `~/.claude/learnship/templates/security.md`. Fill in:
+- Trust boundaries from the analysis
+- Complete threat register with STRIDE categories
+- Status for each threat (open/closed)
+- Evidence for closed threats
+
+</audit_methodology>

package/bin/install.js

@@ -42,6 +42,8 @@ const CODEX_AGENT_SANDBOX = {
   'learnship-code-reviewer':     'read-only',
   'learnship-challenger':        'read-only',
   'learnship-ideation-agent':    'read-only',
+  'learnship-security-auditor':  'read-only',
+  'learnship-doc-writer':        'workspace-write',
 };
 
 // ─── Colors ────────────────────────────────────────────────────────────────
@@ -658,10 +660,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/commands/learnship/discuss-phase.md

@@ -6,7 +6,7 @@ allowed-tools:
   - Read
   - Bash
   - Write
-  - AskUserQuestion
+  - Task
 ---
 
 <execution_context>

package/commands/learnship/docs-update.md

@@ -0,0 +1,22 @@
+---
+name: learnship:docs-update
+description: Generate, update, and verify project documentation — detects project type, builds doc queue, verifies against live codebase
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/docs-update.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship docs-update workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/execute-phase.md

@@ -1,16 +1,12 @@
 ---
 name: learnship:execute-phase
-description: Execute all plans in a phase with wave-based ordered execution, spawning subagents per plan where supported
-argument-hint: "<phase-number>"
+description: Execute all plans in a phase using wave-based ordered execution — spawns subagents per plan where the platform supports it
+argument-hint: "[N]"
 allowed-tools:
   - Read
   - Bash
   - Write
-  - Edit
-  - Glob
-  - Grep
   - Task
-  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/extract-learnings.md

@@ -0,0 +1,22 @@
+---
+name: learnship:extract-learnings
+description: Extract structured learnings from completed phase artifacts — decisions, lessons, patterns, surprises
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/extract-learnings.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship extract-learnings workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/forensics.md

@@ -0,0 +1,21 @@
+---
+name: learnship:forensics
+description: Post-mortem investigation for failed or stuck workflows — read-only diagnostic report
+argument-hint: "[problem description]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<execution_context>
+@~/.claude/workflows/forensics.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship forensics workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/help.md

@@ -1,8 +1,9 @@
 ---
 name: learnship:help
-description: Show all available learnship workflows with descriptions and when to use them
+description: Show all available workflows with descriptions and when to use them
 allowed-tools:
   - Read
+  - Bash
 ---
 
 <execution_context>

package/commands/learnship/ideate.md

@@ -1,7 +1,7 @@
 ---
 name: learnship:ideate
 description: Codebase-grounded divergent thinking — discover what is worth working on
-argument-hint: "[focus]"
+argument-hint: "[focus] | --explore [topic]"
 allowed-tools:
   - Read
   - Bash

package/commands/learnship/milestone-summary.md

@@ -0,0 +1,22 @@
+---
+name: learnship:milestone-summary
+description: Generate a comprehensive milestone summary for team onboarding — a new contributor reads it and understands the project
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/milestone-summary.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship milestone-summary workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/note.md

@@ -0,0 +1,22 @@
+---
+name: learnship:note
+description: Zero-friction idea capture — one write, one confirmation line, no questions
+argument-hint: "[text] | list | promote N"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/note.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship note workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/plan-phase.md

@@ -7,7 +7,6 @@ allowed-tools:
   - Bash
   - Write
   - Task
-  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/quick.md

@@ -1,16 +1,12 @@
 ---
 name: learnship:quick
 description: Execute an ad-hoc task with full agentic guarantees — atomic commits, state tracking, no full planning ceremony
-argument-hint: ""<task description>""
+argument-hint: "[description]"
 allowed-tools:
   - Read
   - Bash
   - Write
-  - Edit
-  - Glob
-  - Grep
   - Task
-  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/secure-phase.md

@@ -0,0 +1,23 @@
+---
+name: learnship:secure-phase
+description: Per-phase security verification — STRIDE threat register, mitigation check, SECURITY.md generation
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/secure-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship secure-phase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>