learnship

You are working inside a project that uses learnship — a multi-platform agentic engineering system for building real products with spec-driven workflows, integrated learning, and impeccable design.

Platform Overview

This platform provides three integrated layers:

Workflow Engine — Structured project development through spec-driven phases
Agentic Learning — A learning partner that helps the user build genuine understanding while building software
Frontend Design — Impeccable UI quality for any user-facing work

Active Workflows

The following workflows are available as platform slash commands (Windsurf) or commands (Claude Code, OpenCode, Gemini CLI, Codex). Suggest the appropriate one when relevant:

| Workflow | When to suggest | |----------|----------------| | /new-project | User wants to start a new project from scratch | | /discuss-phase [N] | Before planning a phase — capture user's implementation vision | | /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 — time for user acceptance testing | | /ls | User asks "where are we?", "what's next?", or starts a new session — primary entry point | | /next | User wants to just keep moving without deciding what to do | | /quick [task] | Small ad-hoc task that doesn't need full phase ceremony | | /progress | Same as /ls — status overview and routing | | /pause-work | User is stopping mid-phase | | /resume-work | User is returning to an in-progress project | | /complete-milestone | All phases in the current milestone are done | | /compound | Just solved a problem or learned a pattern — capture it while fresh | | /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 | | /guard | Working on sensitive files — enable safety mode | | /sync-docs | After code changes — detect stale documentation |

Planning Artifacts

All project state lives in .planning/. Key files:

.planning/config.json — Settings including learning_mode ("auto" or "manual")
.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)

Always read STATE.md and ROADMAP.md before any planning or execution operation to understand current project position.

Agent Personas

Reference these files when adopting a specific role:

@./agents/planner.md — Creating PLAN.md files
@./agents/researcher.md — Researching domain or phase
@./agents/executor.md — Implementing plans (atomic commits, no scope creep)
@./agents/verifier.md — Verifying plans or phase goal achievement
@./agents/debugger.md — Diagnosing root causes (read-only, never fix)
@./agents/solution-writer.md — Writing solution documents for .planning/solutions/
@./agents/code-reviewer.md — Multi-persona code review through specific lenses
@./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

Learning Mode

Read learning_mode from .planning/config.json (default: "auto"):

auto — Proactively offer learning actions at natural workflow checkpoints (after planning, execution, verification)
manual — Only activate @agentic-learning when the user explicitly asks

Learning checkpoints:

After requirements approved → @agentic-learning brainstorm
After discuss-phase → @agentic-learning either-or
After plan-phase → @agentic-learning cognitive-load
After execute-phase → @agentic-learning reflect
After verify-work passes → @agentic-learning space
After /review → @agentic-learning learn (review findings as learning material)
After /challenge → @agentic-learning either-or (which lens was most valuable?)
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

Design Skill

The impeccable skill suite is always available for any UI work. Use its steering commands (/audit, /critique, /polish, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /normalize, /teach-impeccable) when reviewing or building user-facing interfaces.

Mandatory Gate — No Project, No Work

Before responding to any user message, check:

Does .planning/PROJECT.md exist?

No → The project has not been initialized. Do NOT implement anything. Tell the user:

"This project hasn't been set up with learnship yet. Run /new-project to initialize it — that takes about 10 minutes and sets up the spec, roadmap, and phase structure before any code gets written.

This is not optional: working without a spec means building the wrong thing. /new-project first."

Then stop. Do not offer to help with the task. Do not say "but I can also just fix it directly." Wait for the user to run /new-project.
Yes → Continue normally. Apply the workflow routing logic from AGENTS.md.

This gate applies to ALL messages — bug reports, feature requests, "quick fixes", detailed specs, anything. The only exception: if the user is currently mid-ceremony in /new-project (i.e., they are answering your questions), their messages are workflow answers, not tasks to route.

`/new-project` Ceremony Enforcement

When running /new-project, these are non-negotiable hard gates. Violating any of them produces a broken project:

Research decision = always ask the user. After PROJECT.md is confirmed, you MUST ask: "Do you want me to research the domain ecosystem first?" and WAIT for a reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
Research = 5 separate files. If the user chooses research, you MUST create exactly 5 files in .planning/research/: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md. Do NOT write a single monolithic research file. After writing all 5, run the node -e verification command from the workflow. If it fails, fix the files before proceeding.
AGENTS.md = copy from template. Read @./templates/agents.md BEFORE writing AGENTS.md. Sections marked "copy VERBATIM" must be copied word-for-word — do not rewrite, summarize, or rephrase them. After writing, run the node -e verification command. If it fails, fix AGENTS.md before proceeding.
Done = STOP. After displaying the Step 9 done banner, STOP completely. Do NOT automatically start /discuss-phase 1. Do NOT say "Let me start Phase 1" or "Now starting Phase 1." Wait for the user to type their next command.

Key Behaviors

Context efficiency: Reference file paths rather than inlining file contents. Load context fresh when needed rather than carrying it forward.
Atomic commits: Every task gets its own commit. Never batch unrelated changes.
No scope creep: Execute exactly what plans say. Document deviations in SUMMARY.md.
Goal-backward verification: Check that must_haves are met in the codebase, not just that tasks ran.
Deferred ideas: When users suggest things outside the current phase scope, note them for the roadmap backlog — don't act on them immediately.

Reference Files

@./references/questioning.md — Questioning techniques for new-project and discuss-phase
@./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/

learnship

Platform Overview

This platform provides three integrated layers:

Workflow Engine — Structured project development through spec-driven phases
Agentic Learning — A learning partner that helps the user build genuine understanding while building software
Frontend Design — Impeccable UI quality for any user-facing work

Active Workflows

The following workflows are available as platform slash commands (Windsurf) or commands (Claude Code, OpenCode, Gemini CLI, Codex). Suggest the appropriate one when relevant:

Planning Artifacts

All project state lives in .planning/. Key files:

.planning/config.json — Settings including learning_mode ("auto" or "manual")
.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)

Always read STATE.md and ROADMAP.md before any planning or execution operation to understand current project position.

Agent Personas

Reference these files when adopting a specific role:

@./agents/planner.md — Creating PLAN.md files
@./agents/researcher.md — Researching domain or phase
@./agents/executor.md — Implementing plans (atomic commits, no scope creep)
@./agents/verifier.md — Verifying plans or phase goal achievement
@./agents/debugger.md — Diagnosing root causes (read-only, never fix)
@./agents/solution-writer.md — Writing solution documents for .planning/solutions/
@./agents/code-reviewer.md — Multi-persona code review through specific lenses
@./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

Learning Mode

Read learning_mode from .planning/config.json (default: "auto"):

auto — Proactively offer learning actions at natural workflow checkpoints (after planning, execution, verification)
manual — Only activate @agentic-learning when the user explicitly asks

Learning checkpoints:

After requirements approved → @agentic-learning brainstorm
After discuss-phase → @agentic-learning either-or
After plan-phase → @agentic-learning cognitive-load
After execute-phase → @agentic-learning reflect
After verify-work passes → @agentic-learning space
After /review → @agentic-learning learn (review findings as learning material)
After /challenge → @agentic-learning either-or (which lens was most valuable?)
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

Design Skill

Mandatory Gate — No Project, No Work

Before responding to any user message, check:

Does .planning/PROJECT.md exist?

No → The project has not been initialized. Do NOT implement anything. Tell the user:

"This project hasn't been set up with learnship yet. Run /new-project to initialize it — that takes about 10 minutes and sets up the spec, roadmap, and phase structure before any code gets written.

This is not optional: working without a spec means building the wrong thing. /new-project first."

Then stop. Do not offer to help with the task. Do not say "but I can also just fix it directly." Wait for the user to run /new-project.
Yes → Continue normally. Apply the workflow routing logic from AGENTS.md.

`/new-project` Ceremony Enforcement

When running /new-project, these are non-negotiable hard gates. Violating any of them produces a broken project:

Research decision = always ask the user. After PROJECT.md is confirmed, you MUST ask: "Do you want me to research the domain ecosystem first?" and WAIT for a reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
Research = 5 separate files. If the user chooses research, you MUST create exactly 5 files in .planning/research/: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md. Do NOT write a single monolithic research file. After writing all 5, run the node -e verification command from the workflow. If it fails, fix the files before proceeding.
AGENTS.md = copy from template. Read @./templates/agents.md BEFORE writing AGENTS.md. Sections marked "copy VERBATIM" must be copied word-for-word — do not rewrite, summarize, or rephrase them. After writing, run the node -e verification command. If it fails, fix AGENTS.md before proceeding.
Done = STOP. After displaying the Step 9 done banner, STOP completely. Do NOT automatically start /discuss-phase 1. Do NOT say "Let me start Phase 1" or "Now starting Phase 1." Wait for the user to type their next command.

Key Behaviors

Context efficiency: Reference file paths rather than inlining file contents. Load context fresh when needed rather than carrying it forward.
Atomic commits: Every task gets its own commit. Never batch unrelated changes.
No scope creep: Execute exactly what plans say. Document deviations in SUMMARY.md.
Goal-backward verification: Check that must_haves are met in the codebase, not just that tasks ran.
Deferred ideas: When users suggest things outside the current phase scope, note them for the roadmap backlog — don't act on them immediately.

Reference Files

@./references/questioning.md — Questioning techniques for new-project and discuss-phase
@./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/

Adoption

faviovazquez/learnship

$ install --global

Security Scan Results

SKILL.md

learnship

Platform Overview

Active Workflows

Planning Artifacts

Agent Personas

Learning Mode

Design Skill

Mandatory Gate — No Project, No Work

/new-project Ceremony Enforcement

Key Behaviors

Reference Files

Related Skills

faviovazquez/typeset

faviovazquez/teach-impeccable

faviovazquez/quieter

faviovazquez/polish

faviovazquez/learnship

$ install --global

Security Scan Results

SKILL.md

learnship

Platform Overview

Active Workflows

Planning Artifacts

Agent Personas

Learning Mode

Design Skill

Mandatory Gate — No Project, No Work

/new-project Ceremony Enforcement

Key Behaviors

Reference Files

Related Skills

faviovazquez/typeset

faviovazquez/teach-impeccable

faviovazquez/quieter

faviovazquez/polish

`/new-project` Ceremony Enforcement

`/new-project` Ceremony Enforcement