Primer

Primer helps you build real software with AI agents one verified milestone at a time.

The main work happens inside your AI coding agent. The primer CLI sets up the workspace, verifies prerequisites, and powers the milestone workflow under the hood.

Instead of handing an agent a huge vague task, Primer gives you a milestone contract, a verification step, and a clear next action.

Primer is a good fit if you want to:

• start from a real workspace instead of a blank prompt
• keep the agent focused on the current step
• verify progress before moving on
• learn the system as you build it

Current recipes:

• cli-tool: build a practical task tracker CLI in Python
• interpreter-mini: build a small expression language in Python
• operating-system: build an x86 operating system from bootloader to shell

• Start Here
• Guides
• 5 Minute Demo
• How Primer Works
• Why Primer
• Is Primer Beginner-Friendly?
• Who It's For
• Installation
  • Recommended quick install (macOS/Linux)
  • Homebrew (macOS/Linux)
  • npm / npx
  • Cargo
  • Native binaries
  • Build from source
  • Install from local source
  • Sanity check after install
  • Shell completions
• AI Tool Integration
• Available Recipe
• Tracks
• Agent Workflow Actions
• CLI Setup Commands
• JSON Examples
• Workspace Model
• Troubleshooting
• Contributing
• License

If you want the fastest path from zero to building inside your AI coding agent:

primer list
primer init cli-tool --tool codex --track learner --path ~/projects/task-cli-demo
cd ~/projects/task-cli-demo
primer doctor cli-tool --milestone 01-bootstrap

Use the terminal for setup:

1. primer list shows the catalog.
2. primer init creates a separate project workspace and generates AI-tool instructions for it.
3. primer doctor checks whether your local toolchain is ready for the first milestone.

Then open the generated workspace in your AI coding agent and use the Primer workflow actions there:

• primer-build: implement only the current milestone scope
• primer-verify: run milestone verification and mark it verified on success
• primer-next-milestone: unlock the next milestone only after verification passes
• primer-explain: show the deeper explanation for the current milestone
• primer-status: show current milestone, verification state, retries, and progress

Primer is designed so that:

• In a regular shell, you mainly use primer for setup, diagnostics, and utilities such as init, doctor, and completions.
• Inside a generated workspace in a supported AI tool, you do the actual milestone work through generated actions such as primer-build and primer-status.

If you are new to Primer, start with --track learner.

If you want one short walkthrough instead of the general setup story, use the 5 minute demo.

Primer's public docs now have three main entry paths:

• Learn With Primer: the beginner-friendly path focused on cli-tool, learner track, and understanding the loop
• Build Safely With Primer: the execution-focused path for milestone-by-milestone delivery and JSON wrappers
• Use Primer In An Existing Repository: the brownfield path built around workstreams, boundary analysis, and repo-local state

If you only want one short walkthrough, jump straight to the 5 minute demo.

The best quick demo path today is the beginner-friendly cli-tool recipe.

What this path demonstrates:

1. initialize a workspace
2. inspect the current milestone
3. watch verification fail before the code exists
4. implement one milestone
5. verify it successfully
6. advance safely

The full walkthrough lives in docs/5-minute-primer.md.

Quick start:

primer init cli-tool --tool codex --track learner --path ~/projects/task-cli-demo
cd ~/projects/task-cli-demo
primer doctor cli-tool --milestone 01-bootstrap

Then open the workspace in your AI tool and use:

• primer-status
• primer-build
• primer-verify
• primer-next-milestone

Primer has two layers:

1. The setup layer: the primer CLI creates the workspace, checks your environment, and manages workflow state.
2. The working layer: your AI coding agent uses the generated Primer actions inside that workspace while you build milestone by milestone.

In practice, that means:

• you touch the terminal first to initialize the workspace
• you spend most of your time inside the AI coding agent
• Primer verification decides when a milestone is actually complete

The CLI is important infrastructure, but it is not meant to be the primary day-to-day interface.

Most AI coding workflows fail in predictable ways:

• the task is too broad
• the agent implements future steps too early
• there is no reliable check for "done"
• progress is hard to see

Primer turns that into a repeatable loop:

1. Initialize a separate project workspace from a recipe.
2. Load the current milestone contract.
3. Build only that scope.
4. Run verification.
5. Advance only after it passes.

The result feels closer to a guided lab than an open-ended prompt.

The workflow is beginner-friendly. The current recipe catalog is not broadly beginner-oriented yet.

That distinction matters:

• Primer itself is designed to be approachable for students, entry-level developers, and people learning with AI assistance.
• The current flagship recipe, operating-system, is still an advanced systems project with a real toolchain and low-level concepts.

If you are a beginner or novice, the recommended path is:

• use --track learner
• start with the cli-tool recipe
• run primer doctor early so tooling issues are obvious
• use primer explain and primer verify as part of every milestone
• expect to learn incrementally instead of understanding the entire system up front

If you are completely new to programming, cli-tool is the best place to start. The more ambitious operating-system recipe is better treated as an advanced guided lab.

Primer is for people who want structure while building with AI tools:

• learners who want explanations, checkpoints, and visible progress
• builders who want tighter scope control and safer iteration
• educators and recipe authors who want reusable milestone-based learning paths

If you want to try ambitious projects without handing the whole problem to the agent at once, Primer is the point.

Primer is also meant to grow into a community library of guided labs. If you want to help create new recipes or improve the educational experience around existing ones, see CONTRIBUTING.md and docs/community-recipes.md.

Pick one installation path. You install the primer CLI because it bootstraps and supports the agent workflow.

curl -sSf https://raw.githubusercontent.com/armgabrielyan/primer/main/install.sh | sh

brew install armgabrielyan/tap/primer

npm install -g @armengabrielyan/primer

For one-off usage:

npx @armengabrielyan/primer list

The @armengabrielyan/primer package downloads the matching prebuilt primer binary for your platform during install.

cargo install primer

Download prebuilt archives from the GitHub Releases page.

git clone https://github.com/armgabrielyan/primer
cd primer
cargo build --release

The binary will be available at:

./target/release/primer

cargo install --path .

primer --help
primer list

Primer can generate shell completions for bash, zsh, and fish:

primer completions zsh
primer completions bash
primer completions fish

Primer has native workspace adapters for:

• Claude Code
• Codex
• OpenCode
• Gemini CLI
• Cursor

Primer is designed to be used inside your AI coding agent. primer init generates tool-specific files into the workspace so the workflow is available where the project work actually happens.

Use the same primer init shape for every supported tool:

primer init <recipe-id> --tool <claude|codex|opencode|gemini|cursor> --path ~/projects/my-workspace

Generated files by tool:

Those generated actions are the primary user experience. The CLI provides the underlying stateful operations, verification, and setup support that those actions rely on.

If your preferred AI tool can follow workspace instructions and run the local primer CLI, Primer can usually fit that workflow as well.

Current catalog:

For more detail on the current recipe, see recipes/operating-system/README.md.

Primer supports two interaction styles:

Examples:

primer init operating-system --tool codex --track learner --path ~/projects/my-os

primer init operating-system --tool codex --track builder --path ~/projects/my-os

If you do not pass --track, Primer uses learner.

You can switch later without re-initializing:

primer track builder
primer track learner

Once the workspace is initialized, this is the primary way to use Primer:

Primer also exposes matching CLI commands such as primer build, primer track, primer status, primer explain, primer verify, and primer next-milestone, but the default experience is to use the generated actions inside your AI coding agent.

Use primer status --json when you need the current workflow state in a machine-readable form. Use primer verify --json when you need the latest verification result as a machine-readable event. Use primer next-milestone --json when you need the milestone advancement result as a machine-readable transition. Use primer build --json when you need the current milestone contract, track guidance, and optional workstream intent context in a machine-readable form.

Use the CLI directly for setup, diagnostics, and terminal utilities:

Useful safety flags:

• primer init --dry-run shows what would happen without writing files.
• primer init --force allows initialization into a non-empty directory.

For an existing repository, bootstrap a repo-local workstream from the repository root:

primer workstream list
primer workstream analyze --goal "Reduce auth pipeline complexity"
primer workstream init auth-refactor --goal "Reduce auth pipeline complexity" --tool codex --track learner
primer workstream switch auth-refactor

primer workstream init also scaffolds .primer/workstreams/<workstream-id>/workstream-intent.md so you can keep goal, non-goals, constraints, and done-when short but durable while you rewrite the placeholder first milestone.

Use primer workstream list --json when you need the same repository-local workstream state in a machine-readable form. Use primer workstream analyze --json when you need brownfield candidate suggestions in a machine-readable form. Use primer recipe lint --json when you need recipe lint findings in a machine-readable form. Use primer milestone lint --json when you need one milestone's lint findings in a machine-readable form.

Primer's JSON output is meant for small wrappers and automation, not just tests.

The repo now includes example integrations in examples/json/README.md:

• status-summary.sh reads primer status --json and prints a compact milestone summary
• verify-summary.sh runs primer verify --json, prints a compact result summary, and exits with the same status as the verification run
• workstream-dashboard.sh reads primer workstream list --json and prints a compact repository dashboard

They use shell plus python3, so you can try them without adding jq:

bash examples/json/status-summary.sh /path/to/workspace
bash examples/json/verify-summary.sh /path/to/workspace
bash examples/json/workstream-dashboard.sh /path/to/repository

Primer uses two separate locations:

• the primer repo: recipes, adapter generation, the CLI engine, and shared workflow logic
• your generated project workspace: the code and Primer state for the project you are building
• your AI coding agent: the main place where you read, build, verify, and advance milestones

Do not build inside the primer repo itself. primer init is designed to create or prepare a separate workspace for that work.

After primer init, your generated workspace contains:

• the project files your agent will actually build
• the current Primer state
• tool-specific instructions and workflow actions

For most users, the generated workspace opened inside the AI coding agent is the primary interface. The CLI exists to support that workflow.

For brownfield work inside an existing repository, Primer can also run in repo-local workstream mode. In that case it stores authored workstream files under .primer/workstreams/<workstream-id>/ and runtime state under .primer/runtime/workstreams/<workstream-id>/, while keeping one active workstream in the root adapter context at a time via primer workstream switch.

• Run primer doctor after primer init if you are unsure whether your local toolchain is ready for the current milestone.
• If your AI tool does not see the generated Primer workflow actions, make sure you opened the generated workspace, not the primer repository.
• If your AI tool cannot run primer, install or build the CLI first and make sure it is on your PATH.
• primer init is safe by default. Use --force only when you deliberately want to initialize into a non-empty directory.

Primer is not only for people using recipes. It is also for people who want to author them.

See CONTRIBUTING.md for contributor workflow, quality bar, and community direction.

If you want to propose a new community learning path, start with docs/community-recipes.md.

Primer is available under the MIT License.