learnship 2.3.6 → 2.4.0

package/cursor-rules/learnship.mdc

@@ -69,8 +69,8 @@ Suggest the appropriate workflow slash command when relevant:
 | `/discuss-milestone` | Capture milestone-level goals before `/new-milestone` |
 | `/plan-phase [N]` | After discussing a phase — create executable plans |
 | `/execute-phase [N]` | Plans exist and are ready to run |
-| `/verify-work [N]` | Phase execution complete — user acceptance testing |
-| `/review` | Code ready for review — multi-persona quality check |
+| `/verify-work [N]` | Phase execution complete — user acceptance testing (+ live UI smoke test on any MCP-enabled platform when @playwright/mcp is configured) |
+| `/review` | Code ready for review — spec compliance pass then 6-persona quality review |
 | `/ship` | Tests pass, code reviewed — ship it (test → lint → commit → push → PR) |
 | `/complete-milestone` | All phases in the current milestone are done |
 | `/ls` | User asks "where are we?", "what's next?", or starts a new session |
@@ -82,14 +82,14 @@ Suggest the appropriate workflow slash command when relevant:
 | `/ideate` | Codebase-grounded idea generation (`--explore` for Socratic mode) |
 | `/challenge` | Stress-test a proposal with product + engineering forcing questions |
 | `/settings` | Change project configuration after setup |
-| `/health` | Project health check — stale files, uncommitted changes, config drift |
+| `/health` | Project health check — stale files, uncommitted changes, config drift, numeric score 0–100 |
 | `/compound` | Just solved a problem or learned a pattern — capture it while fresh |
 | `/pause-work` | User is stopping mid-phase |
 | `/resume-work` | User is returning to an in-progress project |
 | `/guard` | Working on sensitive files — enable safety mode |
 | `/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 |
+| `/secure-phase [N]` | After execution — per-phase STRIDE + OWASP Top 10 security verification |
 | `/validate-phase [N]` | Retroactive test coverage audit for a completed phase |
 | `/diagnose-issues` | Batch-diagnose multiple UAT issues after `/verify-work` |
 | `/docs-update` | Generate or update project documentation |
@@ -101,6 +101,34 @@ Suggest the appropriate workflow slash command when relevant:
 | `/knowledge-base` | Aggregate learnings across sessions into searchable KNOWLEDGE.md |
 | `/transition` | Hand off project context to a new session or collaborator |
 
+## Secondary Workflows
+
+The 20 less-frequently-used workflows below are also available on Cursor. Suggest them in the matching situation; the user can also discover them via `/help`.
+
+| Workflow | When to suggest |
+|----------|----------------|
+| `/help` | User asks "what commands exist?" or wants the full reference |
+| `/add-phase [description]` | Append a new phase to the end of the roadmap |
+| `/insert-phase [N] [description]` | Insert urgent work between existing phases |
+| `/remove-phase [N]` | Remove a future phase and renumber |
+| `/research-phase [N]` | Deep phase research only — no plans yet |
+| `/list-phase-assumptions [N]` | Preview intended approach before planning the phase |
+| `/discovery-phase [N]` | Map an unfamiliar code area — files, deps, risks — before planning |
+| `/audit-milestone` | Pre-release audit — requirement coverage + stub detection |
+| `/plan-milestone-gaps` | Create fix phases from audit findings |
+| `/milestone-retrospective` | 5-question retrospective after `/complete-milestone` |
+| `/decision-log [description]` | Capture a decision with context, alternatives, rationale |
+| `/execute-plan [N] [id]` | Re-run a single PLAN.md in isolation (e.g., after a failure) |
+| `/validate-phase [N]` | (Listed in Core — also reachable here) retroactive coverage audit |
+| `/add-todo [description]` | Capture an idea without interrupting flow |
+| `/check-todos` | Review and act on captured todos |
+| `/add-tests [N]` | Generate unit + E2E tests for a completed phase |
+| `/cleanup` | Archive completed milestone phase directories |
+| `/set-profile [quality\|balanced\|budget]` | One-step model-profile switch |
+| `/update` | Update the learnship platform itself to the latest version |
+| `/reapply-patches` | Restore local edits after an `/update` |
+| `/release` | Cut a release after `/complete-milestone` (tagging, npm publish, etc.) |
+
 ## Planning Artifacts
 
 All project state lives in `.planning/`. Key files:

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.3.6",
+  "version": "2.4.0",
   "description": "Agentic engineering done right — 57 structured workflows, 17 specialist agent personas, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",

package/hooks/learnship-context-monitor.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// learnship-hook-version: 2.2.0
+// learnship-hook-version: 2.4.0
 // Context Monitor — PostToolUse hook
 // Reads context metrics from the statusline bridge file and injects
 // warnings when context usage is high. Makes the AGENT aware of
@@ -28,8 +28,11 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input);
     const sessionId = data.session_id;
 
-    if (!sessionId) process.exit(0);
-    if (/[/\\]|\.\./.test(sessionId)) process.exit(0);
+    if (!sessionId || typeof sessionId !== 'string') process.exit(0);
+    // Session IDs from the host platform should be opaque tokens.
+    // Reject anything that could escape the temp-file naming scheme.
+    if (sessionId.length > 128) process.exit(0);
+    if (!/^[A-Za-z0-9._-]+$/.test(sessionId)) process.exit(0);
 
     // Check if context warnings are disabled via config
     const cwd = data.cwd || process.cwd();

package/hooks/learnship-prompt-guard.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// learnship-hook-version: 2.2.0
+// learnship-hook-version: 2.4.0
 // Prompt Injection Guard — PreToolUse hook
 // Scans file content being written to .planning/ for prompt injection patterns.
 // Defense-in-depth: catches injected instructions before they enter agent context.

package/hooks/learnship-session-state.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// learnship-hook-version: 2.2.0
+// learnship-hook-version: 2.4.0
 // Session State — SessionStart hook
 // Injects project state reminder on every session start for orientation.
 // Also checks for learnship updates in the background.

package/hooks/learnship-statusline.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// learnship-hook-version: 2.2.0
+// learnship-hook-version: 2.4.0
 // learnship Statusline — shows model, project state, directory, and context usage
 // Installed by learnship for Claude Code and Gemini CLI.
 
@@ -101,8 +101,13 @@ function runStatusline() {
         const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
         const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
 
-        // Write bridge file for context-monitor hook
-        const sessionSafe = session && !/[/\\]|\.\./.test(session);
+        // Write bridge file for context-monitor hook.
+        // Session IDs from the host platform should be opaque tokens — refuse
+        // anything that could escape the temp-file naming scheme.
+        const sessionSafe = typeof session === 'string'
+          && session.length > 0
+          && session.length <= 128
+          && /^[A-Za-z0-9._-]+$/.test(session);
         if (sessionSafe) {
           try {
             const bridgePath = path.join(os.tmpdir(), `learnship-ctx-${session}.json`);

package/learnship/agents/challenger.md

@@ -14,6 +14,13 @@ You are not here to block progress — you are here to make sure the team builds
 
 **Evidence over intuition** — ground challenges in DECISIONS.md, KNOWLEDGE.md, solutions/, and codebase docs when available.
 
+## Boundaries — what this persona does NOT do
+
+- **Do NOT make the decision.** Your output is a verdict (proceed / rethink / reduce-scope) plus rationale. The user owns the choice.
+- **Do NOT veto.** A challenger that says "no, don't build this" without offering a sharpened alternative is just an obstacle.
+- **Do NOT modify code, plans, or docs.** You analyze and recommend. Other personas write.
+- **Do NOT pad with general advice.** Each forcing question must be answerable with a concrete fact about *this* proposal — generic questions get dropped.
+
 ## Product Lens
 
 Ask 3-5 of these forcing questions:

package/learnship/agents/executor.md

@@ -19,6 +19,13 @@ You implement exactly what the plan specifies. You do not improve, extend, or re
 
 **Verify before committing** — use the `<verify>` field of each task to confirm it worked before the commit.
 
+## Boundaries — what this persona does NOT do
+
+- **Do NOT improve the plan.** If the plan is wrong, surface the obstacle in SUMMARY.md and propose a deviation — do not silently "fix" the plan as you go.
+- **Do NOT batch commits.** Every task gets its own commit, even if two tasks touch the same file.
+- **Do NOT refactor adjacent code.** If you see a smell, note it for the next planning cycle. Touching unrelated code makes the diff impossible to review.
+- **Do NOT skip the verify step.** A task without verification is a task that might not be done. If `<verify>` is absent in the plan, write a minimal verification (a node -e, a grep, a test command) before committing.
+
 ## Before Executing
 
 Load project context:

package/learnship/agents/ideation-agent.md

@@ -14,6 +14,13 @@ You generate ideas, not plans. Your output feeds into ranking and filtering —
 
 **Cross-frame is good** — if an idea spans multiple thinking frames, that's a signal of strength, not a problem.
 
+## Boundaries — what this persona does NOT do
+
+- **Do NOT write plans.** Ideas go to the adversarial filter; plans come from the planner. If an idea wins the filter, the user runs `/plan-phase` — not you.
+- **Do NOT execute or modify code.** Ideation is read-only research. You may grep, glob, and read files. You do not edit them.
+- **Do NOT critique or rank.** That's the filtering step's job. Generate broadly; let the filter cut.
+- **Do NOT skip the codebase grounding.** An idea with no file/pattern citation is not an idea — it is product advice. Cite specifics or drop it.
+
 ## Thinking Frames
 
 You'll be assigned ONE of these as your starting bias (not a constraint — follow promising threads):

package/learnship/agents/research-synthesizer.md

@@ -26,6 +26,13 @@ Your SUMMARY.md is consumed by the roadmapper (or the planning step) which uses
 
 **Be opinionated.** The roadmapper needs clear recommendations, not wishy-washy summaries.
 
+## Boundaries — what this persona does NOT do
+
+- **Do NOT run new research.** Your job is to synthesize what's already in `.planning/research/`. If a gap exists, flag it for follow-up — don't try to fill it yourself with web searches.
+- **Do NOT modify the 4 source research files.** They are inputs. Edit only SUMMARY.md.
+- **Do NOT make roadmap decisions.** Surface implications and gaps for the roadmapper; let the roadmapper structure phases.
+- **Do NOT concatenate.** If SUMMARY.md reads like a TOC of the 4 input files, you haven't synthesized — you've copied. Find the cross-cutting threads.
+
 ## Execution Flow
 
 ### Step 1: Read Research Files

package/learnship/agents/roadmapper.md

@@ -22,6 +22,13 @@ You are invoked by `/new-project` (after research + requirements) or `/new-miles
 
 **Right-sized phases:** Too small = overhead. Too large = risk. Aim for phases that take 1-3 planning sessions to complete.
 
+## Boundaries — what this persona does NOT do
+
+- **Do NOT write PLAN.md files.** The roadmap is a map of phases, not their implementation. PLAN.md is the planner's job, one phase at a time, on demand.
+- **Do NOT invent requirements.** If a requirement isn't in REQUIREMENTS.md or PROJECT.md, flag it for the user — don't silently extend scope.
+- **Do NOT modify research or requirements.** They are inputs. Write ROADMAP.md only.
+- **Do NOT skip success criteria.** Every phase needs observable, testable success criteria. If you can't name them, the phase is the wrong shape.
+
 ## Phase Structure
 
 Each phase in the roadmap must include:

package/learnship/agents/security-auditor.md

@@ -26,6 +26,15 @@ Before auditing, load project context:
 3. Read `.planning/config.json` for security enforcement settings
 </project_context>
 
+<boundaries>
+## Boundaries — what this persona does NOT do
+
+- **Do NOT modify source code.** You are read-only on the codebase. The only file you write is `SECURITY.md` (or an equivalent report).
+- **Do NOT fix vulnerabilities you find.** Document them with severity, mitigation suggestions, and verification steps — let the executor or debugger fix.
+- **Do NOT skip threats listed in PLAN.md.** If the plan declared a threat (S/T/R/I/D/E), you must explicitly classify whether it is mitigated, partially mitigated, or unaddressed.
+- **Do NOT block on uncertainty.** When a mitigation is ambiguous, mark it `needs-human-review` rather than refusing to produce SECURITY.md.
+</boundaries>
+
 <audit_methodology>
 
 ## STRIDE Categories
@@ -50,6 +59,25 @@ For each file modified in this phase:
 5. **Error handling** — Do errors leak implementation details?
 6. **Dependencies** — Are there known vulnerabilities in new dependencies?
 
+## OWASP Top 10 (2021) Cross-Reference
+
+For every audit, cross-map STRIDE findings against the OWASP Top 10. For each category, mark as **Relevant** (check it), **N/A** (not applicable to this phase's changes), or **Found** (issue exists).
+
+| # | OWASP Category | STRIDE | What to look for |
+|---|---------------|--------|-----------------|
+| A01 | Broken Access Control | E | Missing authz checks, IDOR, path traversal, CORS misconfiguration |
+| A02 | Cryptographic Failures | I | Plaintext secrets, weak ciphers, no TLS, sensitive data in logs/URLs |
+| A03 | Injection | T | SQL, command, LDAP, XPath, template injection; unsanitized user input |
+| A04 | Insecure Design | S/T/E | No rate limiting, unsafe business logic, missing threat model |
+| A05 | Security Misconfiguration | S/I/E | Debug mode on, default credentials, verbose errors, open cloud storage |
+| A06 | Vulnerable Components | T/I/E | Outdated dependencies, known CVEs, unmaintained packages |
+| A07 | Auth Failures | S | Weak/missing passwords, broken session management, no account lockout |
+| A08 | Software/Data Integrity | T | Unsigned updates, unsafe deserialization, CI without integrity checks |
+| A09 | Logging/Monitoring Failures | R | No audit trail, sensitive data in logs, missing alerting on auth failures |
+| A10 | SSRF | T/I | User-controlled URLs fetched server-side, internal service enumeration |
+
+Include an OWASP coverage table in SECURITY.md. For irrelevant categories, a single "N/A — [reason]" is sufficient. Never skip a category entirely — the coverage table proves exhaustiveness.
+
 ## Threat Classification
 
 For each identified concern:

package/learnship/agents/solution-writer.md

@@ -21,6 +21,13 @@ Load context:
 2. Read conversation history for the problem and solution
 3. Search `.planning/solutions/` for existing related docs
 
+## Boundaries — what this persona does NOT do
+
+- **Do NOT modify source code.** Solutions are documentation of what already happened. The fix lives in git history; the solution file lives in `.planning/solutions/`.
+- **Do NOT invent details.** Every field (problem, root cause, solution, prevention) must come from the conversation or repo evidence — never fabricated for completeness.
+- **Do NOT duplicate.** Search `.planning/solutions/` first. If a near-duplicate exists, append/update it rather than creating a parallel doc.
+- **Do NOT skip frontmatter.** YAML frontmatter is what makes solutions searchable by future planning. A solution without it is invisible.
+
 ## Classification
 
 Determine the **track** from the problem_type:

package/learnship/agents/verifier.md

@@ -1,7 +1,7 @@
 ---
 name: learnship-verifier
 description: Verifies that a phase goal was actually achieved after execution — checks must_haves, requirement coverage, and integration links. Spawned by execute-phase on platforms with subagent support.
-tools: Read, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep
 color: purple
 ---
 

package/learnship/references/model-profiles.md

@@ -4,18 +4,25 @@ Model profiles control which AI model tier each learnship agent uses. Profiles a
 
 ## Profile Definitions
 
-| Agent | `quality` | `balanced` | `budget` |
-|-------|-----------|------------|----------|
-| planner | large | large | medium |
-| executor | large | medium | medium |
-| phase-researcher | large | medium | small |
-| debugger | large | medium | medium |
-| verifier | medium | medium | small |
-| plan-checker | medium | medium | small |
-| solution-writer | medium | medium | small |
-| code-reviewer | large | medium | medium |
-| challenger | large | medium | medium |
-| ideation-agent | large | medium | small |
+| Agent | `quality` | `balanced` | `budget` | Notes |
+|-------|-----------|------------|----------|-------|
+| planner | large | large | medium | Always large — planning is where architecture decisions happen. |
+| executor | large | medium | medium | Follows explicit PLAN.md; reasoning is in the plan, not the agent. |
+| phase-researcher | large | medium | small | Codebase-only research; no web search needed. |
+| project-researcher | large | medium | small | Greenfield research; uses web search to discover ecosystem. |
+| research-synthesizer | medium | medium | small | Reads research files and produces SUMMARY.md. |
+| researcher | large | medium | small | General-purpose research used across many workflows. |
+| roadmapper | large | medium | small | Maps requirements to phases; needs strong scope reasoning. |
+| debugger | large | medium | medium | Root-cause investigation needs broad reasoning. |
+| verifier | medium | medium | small | Goal-backward checking, mostly structural. |
+| plan-checker | medium | medium | small | Plan completeness checks (vertical-slice, wave correctness). |
+| solution-writer | medium | medium | small | Captures solved problems while context is fresh. |
+| code-reviewer | large | medium | medium | Multi-persona review; needs to reason about correctness + security + perf. |
+| challenger | large | medium | medium | Stress-tests proposals; needs strong adversarial reasoning. |
+| ideation-agent | large | medium | small | Generates ideas across creative frames. |
+| security-auditor | large | medium | medium | STRIDE threat modeling; rigorous reasoning required. |
+| doc-writer | medium | medium | small | Writes/updates docs from live code; structural task. |
+| doc-verifier | medium | medium | small | Checks docs match code; pattern matching. |
 
 ## Platform Model Resolution
 
@@ -23,7 +30,7 @@ Each tier resolves to the best available model on your platform:
 
 | Tier | Anthropic (Claude Code) | Google (Gemini CLI) | OpenAI (Codex CLI) | Windsurf / Cursor / OpenCode |
 |------|------------------------|--------------------|--------------------|-----------------------------|
-| `large` | Claude Opus 4.6 | Gemini 3.1 Pro | GPT-5.4 | Uses platform default (best available) |
+| `large` | Claude Opus 4.7 | Gemini 3.1 Pro | GPT-5.4 | Uses platform default (best available) |
 | `medium` | Claude Sonnet 4.6 | Gemini 3.1 Flash | GPT-5.4-mini | Uses platform default |
 | `small` | Claude Haiku 4.5 | Gemini 3.1 Flash-Lite | GPT-5.4-nano | Uses platform default |
 

package/learnship/workflows/execute-phase.md

@@ -10,13 +10,14 @@ Execute all plans in a phase. Plans run in waves — ordered by dependencies. On
 
 **Core principle:** Orchestrate, don't implement directly. Describe each plan's objective clearly, execute each plan in sequence (or in parallel via subagents), collect results.
 
-> **Platform note:** This workflow detects whether subagent spawning is available by reading `parallelization.enabled` from `.planning/config.json`. Set `"parallelization": { "enabled": true }` to enable parallel agent spawning on supported platforms. Defaults to `false` (sequential — always safe). The legacy flat `"parallelization": true` is also honored for backward compatibility.
+> **Platform note:** This workflow detects whether subagent spawning is available by reading `parallelization.enabled` from `.planning/config.json`. On Claude Code, OpenCode, and Codex, `/new-project` sets this to `true` by default. To disable: `"parallelization": { "enabled": false }`. The legacy flat `"parallelization": true` is also honored for backward compatibility.
 
 <runtime_compatibility>
 **Subagent spawning is runtime-specific:**
 - **Claude Code:** Uses `Task(subagent_type=..., ...)` — blocks until complete, returns result
 - **OpenCode / Codex:** Subagent spawning supported with platform-native dispatch
-- **Windsurf / Cursor:** No subagent spawning — always use sequential inline execution
+- **Windsurf:** No subagent spawning — always use sequential inline execution
+- **Cursor:** Cursor 2.4+ has native parallel agents, but learnship dispatches sequentially via the `.mdc` rule context (no `Task()` API available in that execution model)
 - **Gemini CLI:** Subagents exist but parallel execution limited — default to sequential
 
 **Fallback rule:** If a spawned agent completes its work (commits visible, SUMMARY.md exists) but the orchestrator never receives the completion signal, treat it as successful based on spot-checks and continue to the next wave/plan. Never block indefinitely.
@@ -194,7 +195,7 @@ Task(
 
 Spawn all plans in the wave before waiting. Wait for all agents to complete, then proceed to spot-checks.
 
-**If parallelization is disabled (sequential mode — Windsurf, Cursor, Gemini CLI, or user preference):**
+**If parallelization is disabled (sequential mode — Windsurf, Cursor, Gemini CLI, or user preference on any platform):**
 
 <persona_context>
 You are now the **learnship executor**. Implement code from plans, one task at a time.

package/learnship/workflows/health.md

@@ -109,14 +109,42 @@ try{
 "
 ```
 
-## Step 4: Format Output
+## Step 4: Compute Health Score
+
+Based on all findings from Step 3, compute a numeric score (0–100):
+
+**Start at 100. Apply deductions:**
+
+| Code | Issue | Deduction |
+|------|-------|-----------|
+| E002 | PROJECT.md missing | −25 |
+| E003 | ROADMAP.md missing | −20 |
+| E004 | STATE.md missing | −10 |
+| E005 | config.json parse error | −15 |
+| W003 | config.json missing | −10 |
+| W002 | state/roadmap phase mismatch | −5 |
+| W004 | missing config fields | −2 per missing field, max −10 |
+| W006 | phase in roadmap but no directory | −4 per phase, max −12 |
+| W007 | orphaned phase directory | −2 per dir, max −6 |
+| I001 | PLAN.md without SUMMARY.md | −1 per plan, max −5 |
+| (uncommitted) | .planning/ has unstaged changes | −5 |
+
+`Score = max(0, 100 − total_deductions)`
+
+**Status bands:**
+- 90–100 → **HEALTHY** ✓
+- 70–89 → **DEGRADED** ⚠
+- 0–69 → **BROKEN** ✗
+
+## Step 5: Format Output
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  learnship ► HEALTH CHECK
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Status: HEALTHY | DEGRADED | BROKEN
+Score:  [N]/100
+Status: HEALTHY ✓ | DEGRADED ⚠ | BROKEN ✗
 Errors: [N]   Warnings: [N]   Info: [N]
 ```
 
@@ -155,10 +183,10 @@ Consider: git add .planning/ && git commit -m "docs: update planning artifacts"
 
 **Footer if repairable issues and --repair not used:**
 ```
-[N] issue(s) can be auto-repaired. Run: health --repair
+[N] issue(s) can be auto-repaired (+[N] points). Run: health --repair
 ```
 
-## Step 5: Repair (if --repair flag)
+## Step 6: Repair (if --repair flag)
 
 Run repairs for each repairable issue found:
 

package/learnship/workflows/new-project.md

@@ -121,8 +121,34 @@ Note the tech stack, key directories, and any README content internally. Use thi
 
 ## Step 2: Configuration
 
-> **🔴 MANDATORY INTERACTIVE QUESTIONS — You MUST present each round as a blocking question using `AskUserQuestion` (or your platform's equivalent: `ask_user_question` on Windsurf, `ask_user` on Gemini, `request_user_input` on Codex). Each round is a SEPARATE blocking call. Do NOT combine all rounds into one. Do NOT render questions as plain text or markdown lists — you MUST use the interactive question tool so the user clicks options. Wait for the user's reply after EACH round before showing the next round.**
->
+> **🔴 MANDATORY INTERACTIVE QUESTIONS — You MUST present each question as a blocking call using `AskUserQuestion` (or your platform's equivalent: `ask_user_question` on Windsurf, `ask_user` on Gemini, `request_user_input` on Codex). Do NOT render questions as plain text or markdown lists — you MUST use the interactive question tool so the user clicks options. Wait for the user's reply before continuing.**
+
+### Step 2a — Setup Mode (1 question)
+
+> Ask this single blocking question first. Many users just want sensible defaults — this question lets them skip the 15-question customization wizard entirely.
+
+```
+AskUserQuestion([
+  {
+    header: "Setup Mode",
+    question: "How do you want to configure this project?",
+    multiSelect: false,
+    options: [
+      { label: "Quick — use recommended defaults (Recommended)", description: "Skip the 15 customization questions. Uses: auto mode, coarse phases, balanced models, all workflow agents on, ship pipeline + conventional commits + PR template, auto-commit planning docs, parallelization off (you can flip it later in .planning/config.json). Best for: most projects." },
+      { label: "Customize — walk through every setting", description: "Answer ~15 questions across 4 rounds to tune working style, granularity, model profile, workflow agents, pipeline, git, and (on supported platforms) parallel subagents. Best for: teams with specific conventions or unusual project shapes." }
+    ]
+  }
+])
+```
+
+> 🛑 STOP. Wait for the user's reply. Record as `SETUP_MODE = quick | custom`.
+
+**If `SETUP_MODE = quick`:** Skip Step 2b entirely. Jump directly to **Step 2c — Write Config** below, using the recommended defaults documented there. Do NOT ask any of the Round 1–4 questions.
+
+**If `SETUP_MODE = custom`:** Proceed through Step 2b (Rounds 1–4 below). All questions must be answered before writing config.
+
+### Step 2b — Customize Configuration (only if `SETUP_MODE = custom`)
+
 > **🛑 FORBIDDEN:** Do NOT present all questions at once as a text wall. Do NOT skip any question. Do NOT invent answers. Do NOT proceed to the config.json write step until ALL 4 rounds have been answered by the user.
 
 **Round 1 — Core settings (6 questions):**
@@ -299,9 +325,15 @@ AskUserQuestion([
 
 <!-- LEARNSHIP_PARALLEL_BLOCK -->
 
-> 🛑 STOP. Wait for the user's Round 4 reply (parallelization) before continuing.
+> 🛑 STOP. **Only if the parallel block above actually asks a question:** wait for the user's Round 4 reply before continuing. If the parallel block is informational (parallelization auto-set to `false` for the platform), no answer is needed — proceed directly to Step 2c.
+
+### Step 2c — Write Config
+
+> This step runs in **both modes**:
+> - If `SETUP_MODE = quick`: use the **recommended defaults** for every field (the values labeled "(Recommended)" in the Step 2b questions, and `parallelization.enabled = false`).
+> - If `SETUP_MODE = custom`: use the user's answers from Rounds 1–4.
 
-**Now create `.planning/config.json`** — use EXACTLY this schema. Map the user's answers to these keys. Do NOT invent keys. Do NOT use flat keys like `working_style`, `model_tier`, `platform`, `milestone`, or `phases` — those are WRONG.
+**Now create `.planning/config.json`** — use EXACTLY this schema. Map the user's answers (or recommended defaults) to these keys. Do NOT invent keys. Do NOT use flat keys like `working_style`, `model_tier`, `platform`, `milestone`, or `phases` — those are WRONG.
 
 **Key mapping from questions to config:**
 - Working Style → `"mode"`: `"auto"` or `"interactive"`