v2.4.0 — Quick Setup, two-pass review, OWASP, health score, Playwright MCP

[v2.4.0] — 2026-05-25

Changed

• Parallel subagents are now on by default on Claude Code, OpenCode, and Codex CLI. Previously the /new-project setup wizard defaulted to sequential (parallelization.enabled: false) on all platforms and required the user to opt in. Now, on the three platforms with real parallel subagent APIs, Quick Setup and the Customize-mode default both set parallelization.enabled: true. The round-4 question in Customize mode still appears — it now recommends Yes instead of No. Users who prefer sequential execution can choose No during setup or set "parallelization": { "enabled": false } in .planning/config.json at any time. Windsurf, Cursor, and Gemini CLI are unchanged (sequential-only or experimental).

Added

• Quick Setup mode in /new-project — /new-project Step 2 now opens with a single setup-mode question: pick Quick — use recommended defaults to write .planning/config.json immediately, or pick Customize to walk through the 4-round, ~15-question wizard. Saves users ~14 questions on the happy path while leaving full customization one click away. Implemented as Steps 2a (setup mode) → 2b (custom rounds, skipped in quick mode) → 2c (write config, runs in both modes). Verified preserved through install transforms on all 5 installable platforms.
• Design-quality gate in /review and /ship — both workflows now surface @impeccable critique / polish / audit / harden when staged or changed files include UI extensions. Catches design regressions that code review and tests miss.
• All 11 agentic-learning actions now surfaced in SKILL.md checkpoint list — previously only 7 were referenced. Added contextual triggers for quiz (after research / review), explain-first (studying unfamiliar code), explain (after map-codebase / discovery-phase), and interleave (stuck across multiple domains in one session). All 11 actions are now discoverable through automatic checkpoints, not only through manual invocation.
• All 17 agents now in the model-profiles.md tier table — previously only 10 were listed. Researcher, project-researcher, research-synthesizer, roadmapper, doc-writer, doc-verifier, and security-auditor each now have a row across quality / balanced / budget plus a Notes column explaining why that tier is appropriate.
• Explicit "Boundaries — what this persona does NOT do" sections on 7 agents that lacked them: challenger, executor, ideation-agent, research-synthesizer, roadmapper, security-auditor, solution-writer. Synced to both source (learnship/agents/*.md) and wrappers (agents/learnship-*.md).
• .env.example — reference documenting every environment variable that affects the installer or hooks (CLAUDE_CONFIG_DIR, GEMINI_CONFIG_DIR, OPENCODE_CONFIG_DIR, XDG_CONFIG_HOME, CODEX_HOME, GEMINI_API_KEY, LEARNSHIP_TEST_MODE). learnship does not load .env itself — the file is a reference for contributors and users.
• Two-stage /review — /review now runs two sequential passes before producing its report. Pass 1 (Spec Compliance): reads PLAN.md must-haves or commit messages and checks whether each planned deliverable is present in the diff (COVERED / PARTIAL / MISSING). If gaps found, asks whether to proceed or stop. Pass 2 (Quality): the existing 6-persona review (correctness, testing, security, performance, maintainability, adversarial). New --quality-only flag skips Pass 1. Spec compliance result appears in the report header. Verified on all 6 platforms.
• OWASP Top 10 (2021) in /secure-phase — the security-auditor agent and secure-phase workflow now include an explicit OWASP Top 10 checklist (A01–A10) cross-mapped to STRIDE categories. Every SECURITY.md output must include an OWASP coverage table (Relevant / N/A / Found per category) proving exhaustive audit coverage. Closes the main gap vs. gstack and enterprise security checklists. Deployed to all 6 platforms via bin/install.js transforms.
• Numeric health score (0–100) in /health — /health now computes a deterministic score alongside the qualitative status. Scoring: starts at 100, deducts per issue (E002 −25, E003 −20, E004 −10, E005 −15, W003 −10, W004 −2/field, W006 −4/phase, W007 −2/dir, I001 −1/plan, uncommitted changes −5). Status bands: HEALTHY (90–100), DEGRADED (70–89), BROKEN (0–69). The repair footer now shows the point gain from running health --repair. Deployed to all 6 platforms.
• Playwright MCP guidance in /verify-work and /ship — both workflows now include an optional live UI smoke-test section that activates when @playwright/mcp is configured. In verify-work: walks the golden path for UI deliverables using mcp__playwright__* tools and logs any browser console errors as UAT issues. In ship: runs a quick smoke test on the primary changed flow before creating the PR. Supported on any MCP-enabled platform (Claude Code, OpenCode, Cursor, Windsurf, Codex CLI, Gemini CLI). Includes platform-specific setup instructions and a server-alive check. When MCP is not configured, the sections are silent — no disruption to existing workflows.

Security

• --target path-boundary enforcement — bin/install.js now rejects --target paths that resolve to /, common system dirs (/etc, /usr, /var, /bin, /sbin, /lib, /lib64, /boot, /dev, /proc, /sys, /root), or bare $HOME. Valid --target paths must resolve inside $HOME, /tmp, or the current working directory. Prevents a typo or hostile argument from triggering fs.rmSync on something important. Covered by 5 new tests in validate_security.sh.
• Manifest path-traversal protection — saveLocalPatches (which backs up locally-modified files before reinstall) now rejects manifest entries with ../ segments, absolute paths, or null bytes — so a corrupted or malicious learnship-file-manifest.json cannot exfiltrate files outside the install root. Covered by a new test in validate_security.sh.
• Strict session-ID validation in hooks — learnship-context-monitor.js and learnship-statusline.js now require the host-provided session ID to be ≤128 chars and match ^[A-Za-z0-9._-]+$. Replaces the prior allow-list-by-blocklist approach that allowed null bytes and high-bit characters through.

Fixed

• verifier agent was missing the Write tool — its spec required it to produce VERIFICATION.md, but its declared tools (Read, Bash, Glob, Grep) made that impossible on platforms that enforce the tool list. Now declares Read, Write, Bash, Glob, Grep in both source and wrapper.
• learnship-researcher was missing from CODEX_AGENT_SANDBOX — silently fell back to whatever Codex's default was. All 17 agents are now explicitly listed in the sandbox map.
• Double-learnship/ path in security-auditor wrapper — agents/learnship-security-auditor.md referenced ~/.claude/learnship/templates/security.md. After install.js rewrote ~/.claude/ → <targetDir>/learnship/, the path became <targetDir>/learnship/learnship/templates/security.md — pointing to a non-existent file. Fixed by changing the source to ~/.claude/templates/security.md. Added a regression test in validate_cross_platform.sh that scans every installed wrapper for double-learnship/ paths across Claude / OpenCode / Gemini.
• Root SKILL.md listed only 17 of 21 impeccable commands — missing arrange, typeset, overdrive, frontend-design. Now lists all 21, grouped by purpose (review/critique, refine/elevate, specific concerns, engineering attributes, foundations).
• marketplace/README.md claimed "49 structured workflows" — stale. Now correctly says 57.
• Silent color drop in OpenCode conversion — convertToOpencode previously dropped frontmatter lines like color: pink entirely if the color name wasn't in the hex map. Now logs a warning and falls back to #808080 (gray).
• Claude Opus version in model-profiles.md — was Claude Opus 4.6; Opus 4.7 has been current since April 16, 2026. Other model names (Gemini 3.1 Pro/Flash/Flash-Lite, GPT-5.4/mini/nano) were already correct and left unchanged.
• Misleading parallel-execution doc for Gemini CLI — docs/platform-guide/gemini-cli.md previously claimed parallel was on by default; this contradicted bin/install.js and learnship/workflows/execute-phase.md. Doc now accurately states Gemini CLI supports parallel subagents since April 2026 (experimental), with learnship defaulting to sequential for stability and opt-in via parallelization: true.

Documentation

• docs/getting-started/first-project.md Step 2 rewritten to introduce Quick vs. Customize and link to the full configuration reference.

---