learnship

Agentic engineering done right.
📚 Full Docs · Get Started · How it works · Phase Loop · All Workflows · Configuration · Contributing · Changelog

What is learnship?

learnship is an agent harness for anyone who wants to build, learn, and ship real products using AI agents. It's the scaffolding that makes your AI coding agent actually reliable across real projects.

Every serious AI coding tool (Claude Code, Cursor, Manus, Devin) converges on the same architecture: a simple execution loop wraps the model, and the harness decides what information reaches the model, when, and how. The model is interchangeable. The harness is the product.

learnship gives you that harness as a portable, open-source layer that runs inside Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, or Codex CLI and adds three things your agent doesn't have by default:

• 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.
• Built-in learning. Neuroscience-backed checkpoints at every phase transition so you understand what you shipped, not just that you shipped it.

What problem does it solve?

If you've used AI coding assistants for more than a few sessions, you've hit this wall:

The agent forgets everything. Each session starts from scratch. Decisions get repeated. Code quality drifts. You ship fast but understand less. The more you rely on the AI, the less you own the outcome.

This is a harness problem, not a model problem. Research shows the same model on the same benchmark scores 42% with one scaffold and 78% with another. Cursor's lazy context loading cuts token usage by 47%. Vercel deleted 80% of their agent's tools and watched it go from failing tasks to completing them. Same model. The only variable is the harness.

learnship solves this with progressive disclosure, the pattern that separates working agents from impressive demos. Context is revealed incrementally, not dumped upfront. The right files, decisions, and phase context reach the agent exactly when needed, nothing more.

Who is it for?

learnship is built for anyone who wants to build and ship real products with AI agents, not just developers. If you're a founder, designer, researcher, or maker who uses AI tools to build things, this is for you.

It's the right tool if:

• You're building a real project (not just experimenting) and want the AI to stay aligned across sessions
• You're learning while building and want to actually understand what gets shipped
• You care about code quality and UI quality beyond "it works"
• You want parallel agent execution on Claude Code, OpenCode, or Gemini CLI to ship phases faster
• You've felt the frustration of context loss: repeating yourself every session while the agent forgets past decisions

It's probably overkill if you just need one-off scripts or quick fixes. Use /quick for that.

⚡ Get Started in 30 Seconds

1. Install

Requirements: Node.js ≥ 18, Git. Details →

Via npm (all platforms — recommended):

npx learnship

The installer auto-detects your platform. Choose global (all projects) or local (current project only):

npx learnship --global   # all projects
npx learnship --local    # this project only

Via platform marketplace (no terminal required):

# Claude Code — community marketplace
/plugin marketplace add FavioVazquez/learnship-marketplace
/plugin install learnship@learnship-marketplace

# Cursor — after marketplace approval
/add-plugin learnship

# Gemini CLI — native extension
gemini extensions install https://github.com/FavioVazquez/learnship

Or specify your platform explicitly. See Platform Support below.

Why npx learnship?

learnship is published to npm — npx learnship pulls the latest release directly. No github: prefix, no clone needed, no version pinning. The same bin/install.js runs regardless of whether you install via npm, marketplace, or native extension.

2. Start your AI agent and type

/ls

(or the platform equivalent; see the table below). /ls detects whether you have a project, walks you through starting one if not, or tells you exactly where you are and what to do next.

📚 Documentation

The full documentation site is at faviovazquez.github.io/learnship, built with MkDocs Material and deployed automatically on every release.

What's covered:

• Getting Started: install commands, first project walkthrough, the 5 commands you need to know
• Platform Guide: dedicated pages for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex CLI
• Core Concepts: phase loop, context engineering, planning artifacts, agentic vs vibe coding
• Skills: all 11 @agentic-learning actions and all 21 impeccable design commands
• Workflow Reference: all 49 workflows documented with when and why to use each
• Configuration: full .planning/config.json schema, speed presets, parallelization

🌐 Platform Support

learnship works on 6 platforms. Pick your tool:

# All platforms at once
npx learnship --all --global

🤖 Platform capabilities

Each platform gets the best experience it supports:

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).

🗺️ The 5 Commands You Actually Need

learnship has 49 workflows. You don't need to know them all. Start with these five and everything else surfaces naturally from /ls.

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.

🔄 The Phase Loop

Once you have a project, every feature ships through the phase loop. The core is four steps, and v2.0 extends it with three optional quality steps:

flowchart LR
    DP["/discuss-phase N<br/>Capture decisions"]
    PP["/plan-phase N<br/>Research + plans"]
    EP["/execute-phase N<br/>Build + commit"]
    VW["/verify-work N<br/>UAT + diagnose"]
    RV["/review<br/>Multi-persona review"]
    SH["/ship<br/>Test → PR"]
    CP["/compound<br/>Capture knowledge"]

    DP --> PP --> EP --> VW
    VW --> RV --> SH --> CP
    CP -->|"next phase"| DP
    VW -->|"all done"| DONE["✓ /complete-milestone"]

Just starting? /ls or /next will route you into the right step automatically.

🏗️ How It Works

Three integrated layers that reinforce each other:

graph LR
    WE["Workflow Engine<br/>Spec-driven phases<br/>Context-engineered plans<br/>Atomic execution"] --> LP["Learning Partner<br/>Neuroscience-backed<br/>Woven into workflows<br/>Builds real understanding"]
    WE --> DS["Design System<br/>Production-grade UI<br/>Impeccable aesthetics<br/>Anti-AI-slop standards"]
    LP --> DS
    DS --> LP

🆚 Agentic Engineering vs Vibe Coding

🧠 Context Engineering

Every agent invocation in learnship is loaded with structured context. Nothing is guessed:

flowchart LR
    subgraph CONTEXT["Loaded into every agent call"]
        A["AGENTS.md<br/>Project soul + current phase"]
        B["REQUIREMENTS.md<br/>What we're building"]
        C["DECISIONS.md<br/>Every architectural choice"]
        D["Phase CONTEXT.md<br/>Implementation preferences"]
    end
    CONTEXT --> AGENT["AI Agent"]
    AGENT --> P["Executable PLAN.md"]
    AGENT --> S["Commits + SUMMARY.md"]

🗂️ AGENTS.md: Persistent Project Memory

/new-project generates an AGENTS.md at your project root. On Windsurf, Claude Code, and Cursor it is loaded automatically every session as a project rule. On OpenCode, Gemini CLI, and Codex CLI the learnship workflows reference it explicitly. Either way, the agent always knows the project, current phase, tech stack, and past decisions without you repeating yourself.

AGENTS.md                   ← your AI agent reads this every conversation
├── Soul & Principles        # Pair-programmer framing, 10 working principles
├── Platform Context         # Points to .planning/, explains the phase loop
├── Current Phase            # Updated automatically by workflows
├── Project Structure        # Filled during new-project from your answers
├── Tech Stack               # Filled from research results
└── Regressions              # Updated by /debug when bugs are fixed

📖 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.

Core Workflow

Navigation

Phase Management

Brownfield, Discovery & Debugging

Decision Intelligence

Milestone Intelligence

Compounding & Quality (v2.0)

Maintenance

⚙️ Configuration

Project settings live in .planning/config.json. Set during /new-project or edit with /settings.

Full Schema

{
  "mode": "yolo",
  "granularity": "standard",
  "model_profile": "balanced",
  "learning_mode": "auto",
  "parallelization": false,
  "test_first": false,
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "validation": true,
    "review": true,
    "solutions_search": true
  },
  "review": {
    "auto_after_verify": false
  },
  "ship": {
    "auto_test": true,
    "conventional_commits": true,
    "pr_template": true
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "phase-{phase}-{slug}",
    "milestone_branch_template": "{milestone}-{slug}"
  }
}

Core Settings

Workflow Toggles

v2.0 Settings

Git Branching

Model Profiles

Platform note: Tiers map to the best available model on your platform: large = Claude Opus 4.6 / Gemini 3.1 Pro / GPT-5.4, medium = Claude Sonnet 4.6 / Gemini 3.1 Flash / GPT-5.4-mini, small = Claude Haiku 4.5 / Gemini 3.1 Flash-Lite / GPT-5.4-nano. Windsurf, Cursor, and OpenCode use the platform default model — tiers signal intended task complexity.

Speed vs. Quality Presets

🧩 Learning Partner

The learning partner is woven into the platform, not bolted on. It fires at natural workflow transitions to build genuine understanding, not just fluent answers.

How it fires

learning_mode: "auto"    → offered automatically at checkpoints (default)
learning_mode: "manual"  → only when you explicitly invoke @agentic-learning

All 11 actions

Core principle: Fluent answers from an AI are not the same as learning. Every action makes you do the cognitive work, with support rather than shortcuts.

Skills across platforms

🎨 Design System

The impeccable skill suite is always active as project context for any UI work. It provides design direction, anti-patterns, and 21 steering commands that prevent generic AI aesthetics. Based on @pbakaus/impeccable.

Commands

The AI Slop Test: If you showed the interface to someone and said "AI made this", would they believe you immediately? If yes, that's the problem. Use /critique to find out.

learnship integration

Automatic UI standards during execute-phase: When a phase involves UI work, learnship detects it automatically and activates @impeccable frontend-design principles before any code is written. You'll see a banner announcing it. The agent then applies typography, color, layout, and component standards across every task in the phase — not as a post-hoc review but as an active constraint during execution.

Post-action milestone recommendation: After any impeccable action produces recommendations, the agent suggests running /new-milestone to create a dedicated "UI Polish" milestone. This turns impeccable findings into versioned, traceable phases with plans and commits — so improvements don't disappear into chat history. Applying directly is always an option too.

Skills across platforms

💡 Usage Examples

New greenfield project

/new-project              # Answer questions, configure, approve roadmap
/discuss-phase 1          # Lock in your implementation preferences
/plan-phase 1             # Research + plan + verify
/execute-phase 1          # Wave-ordered execution
/verify-work 1            # Manual UAT
/review                   # v2.0: multi-persona code review
/ship                     # v2.0: test → commit → push → PR
/compound                 # v2.0: capture what you learned
                          # Repeat for each phase
/sync-docs                # v2.0: detect stale documentation
/audit-milestone          # Check everything shipped
/complete-milestone       # Archive, tag, done

Existing codebase (brownfield)

/map-codebase             # Structured codebase analysis
/new-project              # Questions focus on what you're ADDING
# Normal phase workflow from here

Quick bug fix

/quick "Fix login button not responding on mobile Safari"

Quick with discussion + verification

/quick --discuss --full "Add dark mode toggle"

Resuming after a break

/ls                       # See where you left off (offers to run next step)
# or
/next                     # Just pick up and go: auto-pilot
# or
/resume-work              # Full context restoration

Scope change mid-milestone

/add-phase                # Append new phase to roadmap
/insert-phase 3           # Insert urgent work between phases 3 and 4
/remove-phase 7           # Descope phase 7 and renumber

Preparing for release

/audit-milestone          # Check requirement coverage, detect stubs
/plan-milestone-gaps      # If audit found gaps, create phases to close them
/complete-milestone       # Archive, tag, done

Debugging something broken

/debug "Login flow fails after password reset"

🧭 Decision Intelligence

Every project accumulates decisions: architecture choices, library picks, scope trade-offs. The platform tracks them in a structured register so future sessions understand why the project is built the way it is.

.planning/DECISIONS.md is the decision register:

## DEC-001: Use Zustand over Redux
Date: 2026-03-01 | Phase: 2 | Type: library
Context: Needed client-side state for dashboard filters
Options: Zustand (simple, no boilerplate), Redux (complex, overkill for scope)
Choice: Zustand
Rationale: 3x less boilerplate, sufficient for current data flow complexity
Consequences: Locks React as UI framework; migration would require state rewrite
Status: active

Populated automatically by:

• discuss-phase surfaces prior decisions before each phase discussion
• plan-phase reads decisions before creating plans (never contradicts active ones)
• debug puts architectural lessons from bugs into the register
• decision-log manually captures any decision from any conversation

Queried by:

• audit-milestone checks decisions were honored in implementation
• knowledge-base aggregates all decisions into a searchable KNOWLEDGE.md

📁 Planning Artifacts

Every project creates a structured .planning/ directory:

.planning/
├── config.json               # Workflow settings
├── PROJECT.md                # Vision, requirements, key decisions
├── REQUIREMENTS.md           # v1 requirements with REQ-IDs
├── ROADMAP.md                # Phase breakdown with status tracking
├── STATE.md                  # Current position, decisions, blockers
├── DECISIONS.md              # Cross-phase decision register
├── KNOWLEDGE.md              # Aggregated lessons (from knowledge-base)
├── research/                 # Domain research from new-project
│   ├── STACK.md
│   ├── FEATURES.md
│   ├── ARCHITECTURE.md
│   ├── PITFALLS.md
│   └── SUMMARY.md
├── codebase/                 # Brownfield mapping (from map-codebase)
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   └── CONCERNS.md
├── todos/
│   ├── pending/              # Captured ideas awaiting work
│   └── done/                 # Completed todos
├── solutions/               # Knowledge compounding (from /compound) (v2.0)
│   ├── auth/                # Solutions by category
│   ├── performance/
│   └── ...
├── debug/                    # Active debug sessions
│   └── resolved/             # Archived debug sessions
├── quick/
│   └── 001-slug/             # Quick task artifacts
│       ├── 001-PLAN.md
│       ├── 001-SUMMARY.md
│       └── 001-VERIFICATION.md (if --full)
└── phases/
    └── 01-phase-name/
        ├── 01-CONTEXT.md     # Your implementation preferences
        ├── 01-DISCOVERY.md   # Unfamiliar area mapping (from discovery-phase)
        ├── 01-RESEARCH.md    # Ecosystem research findings
        ├── 01-VALIDATION.md  # Test coverage contract (from /validate-phase)
        ├── 01-01-PLAN.md     # Executable plan (wave 1)
        ├── 01-02-PLAN.md     # Executable plan (wave 1, independent)
        ├── 01-01-SUMMARY.md  # Execution outcomes
        ├── 01-UAT.md         # User acceptance test results
        └── 01-VERIFICATION.md # Post-execution verification

🔧 Troubleshooting

"Project already initialized"

/new-project found .planning/PROJECT.md already exists. If you want to start over, delete .planning/ first. To continue, use /progress or /resume-work.

Context degradation during long sessions

Start each major workflow with a fresh context. The platform is designed around fresh context windows; every agent gets a clean slate. Use /resume-work or /progress to restore state after clearing.

Plans seem wrong or misaligned

Run /discuss-phase [N] before planning. Most plan quality issues come from unresolved gray areas. Run /list-phase-assumptions [N] to see the intended approach before committing to a plan.

Execution produces stubs or incomplete code

Plans with more than 3 tasks are too large for reliable single-context execution. Re-plan with smaller scope: /plan-phase [N] with finer granularity.

Lost track of where you are

Run /ls. It reads all state files, shows your progress, and offers to run the next step.

Need to change something after execution

Use /quick for targeted fixes, or /verify-work to systematically identify and fix issues through UAT. Do not re-run /execute-phase on a phase that already has summaries.

Costs running too high

Switch to budget profile via /settings. Disable research and plan-check for familiar domains. Use granularity: "coarse" for fewer, broader phases.

Working on a private/sensitive project

Set commit_docs: false during /new-project or via /settings. Add .planning/ to .gitignore. Planning artifacts stay local.

Something broke and I don't know why

Run /debug "description of what's broken". It runs triage → root cause diagnosis → fix planning with a persistent debug session.

Phase passed UAT but has known gaps

Run /audit-milestone to surface all gaps, then /plan-milestone-gaps to create fix phases before release.

🚑 Recovery Quick Reference

📂 Repository Structure

learnship/
├── .windsurf/
│   ├── workflows/          # 49 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
│           ├── frontend-design/ #   Base skill + 7 reference files (typography, color, motion…)
│           ├── audit/           #   /audit
│           ├── critique/        #   /critique
│           ├── 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
│   └── learnship/          # /learnship:ls, /learnship:new-project, etc.
├── learnship/              # Payload installed into the target platform config dir
│   ├── workflows/          # 49 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)
├── assets/                 # Brand images (banner, explainers, diagrams)
├── bin/
│   └── install.js          # Multi-platform installer (Claude Code, OpenCode, Gemini CLI, Codex CLI, Windsurf)
├── tests/
│   └── validate_multiplatform.sh  # 94-check test suite
├── SKILL.md                # Meta-skill: platform context loaded by Cascade / AI agents
├── install.sh              # Shell installer wrapper
├── package.json            # npm package (npx learnship)
├── CHANGELOG.md            # Version history
└── CONTRIBUTING.md         # How to extend the platform

🙏 Inspiration & Credits

learnship was built on top of ideas and work from three open-source projects:

• get-shit-done: the spec-driven, context-engineered workflow system that inspired the phase lifecycle, planning artifacts, and agent coordination patterns
• agentic-learning: the learning partner skill whose neuroscience-backed techniques (retrieval, spacing, generation, reflection) power the Learning Partner layer
• impeccable: the frontend design skill that raised the bar on UI quality standards and powers the Design System layer

learnship adapts, combines, and extends these into a unified, multi-platform system. All three are used as inspiration and learnship is original work built on their shoulders.

License

MIT © Favio Vazquez