{"id":48430857,"url":"https://github.com/armgabrielyan/primer","last_synced_at":"2026-04-06T10:31:05.714Z","repository":{"id":346189966,"uuid":"1187937541","full_name":"armgabrielyan/primer","owner":"armgabrielyan","description":"Build real software step-by-step with Claude, Codex, OpenCode, Gemini, Cursor, and other agents","archived":false,"fork":false,"pushed_at":"2026-03-22T17:44:45.000Z","size":209,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T08:42:13.242Z","etag":null,"topics":["agent-skills","ai","ai-agents","ai-tools","claude-code","codex","cursor","gemini","learn-to-code","learning-by-doing","learning-project","opencode"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/armgabrielyan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T11:52:23.000Z","updated_at":"2026-03-23T01:51:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/armgabrielyan/primer","commit_stats":null,"previous_names":["armgabrielyan/primer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/armgabrielyan/primer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armgabrielyan%2Fprimer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armgabrielyan%2Fprimer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armgabrielyan%2Fprimer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armgabrielyan%2Fprimer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/armgabrielyan","download_url":"https://codeload.github.com/armgabrielyan/primer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armgabrielyan%2Fprimer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31469728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai","ai-agents","ai-tools","claude-code","codex","cursor","gemini","learn-to-code","learning-by-doing","learning-project","opencode"],"created_at":"2026-04-06T10:31:05.647Z","updated_at":"2026-04-06T10:31:05.703Z","avatar_url":"https://github.com/armgabrielyan.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Primer\n\nPrimer helps you build real software with AI agents one verified milestone at a time.\n\nThe 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.\n\nInstead of handing an agent a huge vague task, Primer gives you a milestone contract, a verification step, and a clear next action.\n\nPrimer is a good fit if you want to:\n\n- start from a real workspace instead of a blank prompt\n- keep the agent focused on the current step\n- verify progress before moving on\n- learn the system as you build it\n\nCurrent recipes:\n\n- `cli-tool`: build a practical task tracker CLI in Python\n- `interpreter-mini`: build a small expression language in Python\n- `operating-system`: build an x86 operating system from bootloader to shell\n\n## Table of Contents\n\n- [Start Here](#start-here)\n- [Guides](#guides)\n- [5 Minute Demo](#5-minute-demo)\n- [How Primer Works](#how-primer-works)\n- [Why Primer](#why-primer)\n- [Is Primer Beginner-Friendly?](#is-primer-beginner-friendly)\n- [Who It's For](#who-its-for)\n- [Installation](#installation)\n  - [Recommended quick install (macOS/Linux)](#recommended-quick-install-macoslinux)\n  - [Homebrew (macOS/Linux)](#homebrew-macoslinux)\n  - [npm / npx](#npm--npx)\n  - [Cargo](#cargo)\n  - [Native binaries](#native-binaries)\n  - [Build from source](#build-from-source)\n  - [Install from local source](#install-from-local-source)\n  - [Sanity check after install](#sanity-check-after-install)\n  - [Shell completions](#shell-completions)\n- [AI Tool Integration](#ai-tool-integration)\n- [Available Recipe](#available-recipe)\n- [Tracks](#tracks)\n- [Agent Workflow Actions](#agent-workflow-actions)\n- [CLI Setup Commands](#cli-setup-commands)\n- [JSON Examples](#json-examples)\n- [Workspace Model](#workspace-model)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Start Here\n\nIf you want the fastest path from zero to building inside your AI coding agent:\n\n```bash\nprimer list\nprimer init cli-tool --tool codex --track learner --path ~/projects/task-cli-demo\ncd ~/projects/task-cli-demo\nprimer doctor cli-tool --milestone 01-bootstrap\n```\n\nUse the terminal for setup:\n\n1. `primer list` shows the catalog.\n2. `primer init` creates a separate project workspace and generates AI-tool instructions for it.\n3. `primer doctor` checks whether your local toolchain is ready for the first milestone.\n\nThen open the generated workspace in your AI coding agent and use the Primer workflow actions there:\n\n- `primer-build`: implement only the current milestone scope\n- `primer-verify`: run milestone verification and mark it verified on success\n- `primer-next-milestone`: unlock the next milestone only after verification passes\n- `primer-explain`: show the deeper explanation for the current milestone\n- `primer-status`: show current milestone, verification state, retries, and progress\n\nPrimer is designed so that:\n\n- In a regular shell, you mainly use `primer` for setup, diagnostics, and utilities such as `init`, `doctor`, and `completions`.\n- 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`.\n\nIf you are new to Primer, start with `--track learner`.\n\nIf you want one short walkthrough instead of the general setup story, use the [5 minute demo](docs/5-minute-primer.md).\n\n## Guides\n\nPrimer's public docs now have three main entry paths:\n\n- [Learn With Primer](docs/learn-with-primer.md): the beginner-friendly path focused on `cli-tool`, learner track, and understanding the loop\n- [Build Safely With Primer](docs/build-safely-with-primer.md): the execution-focused path for milestone-by-milestone delivery and JSON wrappers\n- [Use Primer In An Existing Repository](docs/use-primer-in-existing-repo.md): the brownfield path built around workstreams, boundary analysis, and repo-local state\n\nIf you only want one short walkthrough, jump straight to the [5 minute demo](docs/5-minute-primer.md).\n\n## 5 Minute Demo\n\nThe best quick demo path today is the beginner-friendly `cli-tool` recipe.\n\nWhat this path demonstrates:\n\n1. initialize a workspace\n2. inspect the current milestone\n3. watch verification fail before the code exists\n4. implement one milestone\n5. verify it successfully\n6. advance safely\n\nThe full walkthrough lives in [docs/5-minute-primer.md](docs/5-minute-primer.md).\n\nQuick start:\n\n```bash\nprimer init cli-tool --tool codex --track learner --path ~/projects/task-cli-demo\ncd ~/projects/task-cli-demo\nprimer doctor cli-tool --milestone 01-bootstrap\n```\n\nThen open the workspace in your AI tool and use:\n\n- `primer-status`\n- `primer-build`\n- `primer-verify`\n- `primer-next-milestone`\n\n## How Primer Works\n\nPrimer has two layers:\n\n1. The setup layer: the `primer` CLI creates the workspace, checks your environment, and manages workflow state.\n2. The working layer: your AI coding agent uses the generated Primer actions inside that workspace while you build milestone by milestone.\n\nIn practice, that means:\n\n- you touch the terminal first to initialize the workspace\n- you spend most of your time inside the AI coding agent\n- Primer verification decides when a milestone is actually complete\n\nThe CLI is important infrastructure, but it is not meant to be the primary day-to-day interface.\n\n## Why Primer\n\nMost AI coding workflows fail in predictable ways:\n\n- the task is too broad\n- the agent implements future steps too early\n- there is no reliable check for \"done\"\n- progress is hard to see\n\nPrimer turns that into a repeatable loop:\n\n1. Initialize a separate project workspace from a recipe.\n2. Load the current milestone contract.\n3. Build only that scope.\n4. Run verification.\n5. Advance only after it passes.\n\nThe result feels closer to a guided lab than an open-ended prompt.\n\n## Is Primer Beginner-Friendly?\n\nThe workflow is beginner-friendly. The current recipe catalog is not broadly beginner-oriented yet.\n\nThat distinction matters:\n\n- Primer itself is designed to be approachable for students, entry-level developers, and people learning with AI assistance.\n- The current flagship recipe, `operating-system`, is still an advanced systems project with a real toolchain and low-level concepts.\n\nIf you are a beginner or novice, the recommended path is:\n\n- use `--track learner`\n- start with the `cli-tool` recipe\n- run `primer doctor` early so tooling issues are obvious\n- use `primer explain` and `primer verify` as part of every milestone\n- expect to learn incrementally instead of understanding the entire system up front\n\nIf 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.\n\n## Who It's For\n\nPrimer is for people who want structure while building with AI tools:\n\n- learners who want explanations, checkpoints, and visible progress\n- builders who want tighter scope control and safer iteration\n- educators and recipe authors who want reusable milestone-based learning paths\n\nIf you want to try ambitious projects without handing the whole problem to the agent at once, Primer is the point.\n\nPrimer 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](CONTRIBUTING.md) and [docs/community-recipes.md](docs/community-recipes.md).\n\n## Installation\n\nPick one installation path. You install the `primer` CLI because it bootstraps and supports the agent workflow.\n\n### Recommended quick install (macOS/Linux)\n\n```bash\ncurl -sSf https://raw.githubusercontent.com/armgabrielyan/primer/main/install.sh | sh\n```\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install armgabrielyan/tap/primer\n```\n\n### npm / npx\n\n```bash\nnpm install -g @armengabrielyan/primer\n```\n\nFor one-off usage:\n\n```bash\nnpx @armengabrielyan/primer list\n```\n\nThe `@armengabrielyan/primer` package downloads the matching prebuilt `primer` binary for your platform during install.\n\n### Cargo\n\n```bash\ncargo install primer\n```\n\n### Native binaries\n\nDownload prebuilt archives from the [GitHub Releases](https://github.com/armgabrielyan/primer/releases) page.\n\n| Platform | Architecture | Download |\n|---|---|---|\n| Linux | x86_64 (glibc) | `primer-VERSION-x86_64-unknown-linux-gnu.tar.gz` |\n| Linux | x86_64 (musl/static) | `primer-VERSION-x86_64-unknown-linux-musl.tar.gz` |\n| Linux | ARM64 | `primer-VERSION-aarch64-unknown-linux-gnu.tar.gz` |\n| macOS | Intel | `primer-VERSION-x86_64-apple-darwin.tar.gz` |\n| macOS | Apple Silicon | `primer-VERSION-aarch64-apple-darwin.tar.gz` |\n| Windows | x86_64 | `primer-VERSION-x86_64-pc-windows-msvc.zip` |\n\n### Build from source\n\n```bash\ngit clone https://github.com/armgabrielyan/primer\ncd primer\ncargo build --release\n```\n\nThe binary will be available at:\n\n```bash\n./target/release/primer\n```\n\n### Install from local source\n\n```bash\ncargo install --path .\n```\n\n### Sanity check after install\n\n```bash\nprimer --help\nprimer list\n```\n\n### Shell completions\n\nPrimer can generate shell completions for bash, zsh, and fish:\n\n```bash\nprimer completions zsh\nprimer completions bash\nprimer completions fish\n```\n\n## AI Tool Integration\n\nPrimer has native workspace adapters for:\n\n- Claude Code\n- Codex\n- OpenCode\n- Gemini CLI\n- Cursor\n\nPrimer 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.\n\nUse the same `primer init` shape for every supported tool:\n\n```bash\nprimer init \u003crecipe-id\u003e --tool \u003cclaude|codex|opencode|gemini|cursor\u003e --path ~/projects/my-workspace\n```\n\nGenerated files by tool:\n\n| Tool | Generated files |\n|---|---|\n| Claude Code | `CLAUDE.md`, `.claude/commands/` |\n| Codex | `AGENTS.md`, `.agents/skills/` |\n| OpenCode | `AGENTS.md`, `.opencode/skills/` |\n| Gemini CLI | `GEMINI.md`, `.gemini/skills/` |\n| Cursor | `AGENTS.md`, `.cursor/skills/` |\n\nThose generated actions are the primary user experience. The CLI provides the underlying stateful operations, verification, and setup support that those actions rely on.\n\nIf your preferred AI tool can follow workspace instructions and run the local `primer` CLI, Primer can usually fit that workflow as well.\n\n## Available Recipe\n\nCurrent catalog:\n\n| Recipe ID | Project | Difficulty | Best starting advice |\n|---|---|---|---|\n| `cli-tool` | Build a Task Tracker CLI | `beginner` | Start here if you are new to Primer, new to AI-assisted building, or want a fast first success |\n| `interpreter-mini` | Build a Mini Expression Interpreter | `intermediate` | Start here after `cli-tool` if you want a more conceptual project with parsing and evaluation |\n| `operating-system` | Build Your Own Operating System | `advanced` | Start with `--track learner` and treat it like a guided lab, not a quick tutorial |\n\nFor more detail on the current recipe, see [recipes/operating-system/README.md](recipes/operating-system/README.md).\n\n## Tracks\n\nPrimer supports two interaction styles:\n\n| Track | What it feels like | Best for |\n|---|---|---|\n| `learner` | The agent explains the step, teaches while building, and pauses at natural checkpoints | beginners, students, and first-time Primer users |\n| `builder` | The agent implements directly with minimal commentary | users who already understand the workflow and want less narration |\n\nExamples:\n\n```bash\nprimer init operating-system --tool codex --track learner --path ~/projects/my-os\n```\n\n```bash\nprimer init operating-system --tool codex --track builder --path ~/projects/my-os\n```\n\nIf you do not pass `--track`, Primer uses `learner`.\n\nYou can switch later without re-initializing:\n\n```bash\nprimer track builder\nprimer track learner\n```\n\n## Agent Workflow Actions\n\nOnce the workspace is initialized, this is the primary way to use Primer:\n\n| Action | What it does | When to use it |\n|---|---|---|\n| `primer-build` | Load the current milestone scope and implement only that step | when you are actively building |\n| `primer-track` | Switch the active learner or builder track for the workspace | when you want a different guidance style without re-initializing |\n| `primer-status` | Show current milestone, verification state, and progress | anytime you want orientation |\n| `primer-explain` | Show the deeper explanation for the current milestone | when you want more context or teaching |\n| `primer-verify` | Run milestone verification and mark it verified on success | when you think the milestone is done |\n| `primer-next-milestone` | Unlock the next milestone only after verification passes | when you are ready to advance |\n\nPrimer 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.\n\nUse `primer status --json` when you need the current workflow state in a machine-readable form.\nUse `primer verify --json` when you need the latest verification result as a machine-readable event.\nUse `primer next-milestone --json` when you need the milestone advancement result as a machine-readable transition.\nUse `primer build --json` when you need the current milestone contract, track guidance, and optional workstream intent context in a machine-readable form.\n\n## CLI Setup Commands\n\nUse the CLI directly for setup, diagnostics, and terminal utilities:\n\n| Command | What it does | When to use it |\n|---|---|---|\n| `primer list` | List available recipes | when you are exploring |\n| `primer recipe lint` | Lint local recipe structure and milestone quality guidance | when you are authoring or reviewing recipes |\n| `primer milestone lint` | Lint one milestone contract and sizing boundary from a workspace, recipe, or workstream | when you want feedback on the current or target milestone |\n| `primer init` | Create a workspace and generate adapter files | when you are starting a new project |\n| `primer doctor` | Check local prerequisites for a recipe milestone | before you begin or when setup is failing |\n| `primer workstream list` | List initialized brownfield workstreams in the current repository, including active state and saved progress | when you want to see what is available, active, and where each workstream will resume |\n| `primer workstream analyze` | Analyze repository boundaries and suggest safe first-milestone candidates | when you need help choosing the first brownfield milestone |\n| `primer workstream init` | Bootstrap Primer inside the current repository for one brownfield workstream | when you want a milestone path inside an existing repo |\n| `primer workstream switch` | Activate and resume another initialized brownfield workstream in the current repository | when you want to move between repo-local workstreams |\n| `primer track` | Switch the active learner or builder track in the current workspace | when you want to change interaction style mid-workflow |\n| `primer completions` | Generate shell completion scripts | when you want faster terminal use |\n\nUseful safety flags:\n\n- `primer init --dry-run` shows what would happen without writing files.\n- `primer init --force` allows initialization into a non-empty directory.\n\nFor an existing repository, bootstrap a repo-local workstream from the repository root:\n\n```bash\nprimer workstream list\nprimer workstream analyze --goal \"Reduce auth pipeline complexity\"\nprimer workstream init auth-refactor --goal \"Reduce auth pipeline complexity\" --tool codex --track learner\nprimer workstream switch auth-refactor\n```\n\n`primer workstream init` also scaffolds `.primer/workstreams/\u003cworkstream-id\u003e/workstream-intent.md` so you can keep goal, non-goals, constraints, and done-when short but durable while you rewrite the placeholder first milestone.\n\nUse `primer workstream list --json` when you need the same repository-local workstream state in a machine-readable form.\nUse `primer workstream analyze --json` when you need brownfield candidate suggestions in a machine-readable form.\nUse `primer recipe lint --json` when you need recipe lint findings in a machine-readable form.\nUse `primer milestone lint --json` when you need one milestone's lint findings in a machine-readable form.\n\n## JSON Examples\n\nPrimer's JSON output is meant for small wrappers and automation, not just tests.\n\nThe repo now includes example integrations in [examples/json/README.md](examples/json/README.md):\n\n- `status-summary.sh` reads `primer status --json` and prints a compact milestone summary\n- `verify-summary.sh` runs `primer verify --json`, prints a compact result summary, and exits with the same status as the verification run\n- `workstream-dashboard.sh` reads `primer workstream list --json` and prints a compact repository dashboard\n\nThey use shell plus `python3`, so you can try them without adding `jq`:\n\n```bash\nbash examples/json/status-summary.sh /path/to/workspace\nbash examples/json/verify-summary.sh /path/to/workspace\nbash examples/json/workstream-dashboard.sh /path/to/repository\n```\n\n## Workspace Model\n\nPrimer uses two separate locations:\n\n- the `primer` repo: recipes, adapter generation, the CLI engine, and shared workflow logic\n- your generated project workspace: the code and Primer state for the project you are building\n- your AI coding agent: the main place where you read, build, verify, and advance milestones\n\nDo not build inside the `primer` repo itself. `primer init` is designed to create or prepare a separate workspace for that work.\n\nAfter `primer init`, your generated workspace contains:\n\n- the project files your agent will actually build\n- the current Primer state\n- tool-specific instructions and workflow actions\n\nFor most users, the generated workspace opened inside the AI coding agent is the primary interface. The CLI exists to support that workflow.\n\nFor 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/\u003cworkstream-id\u003e/` and runtime state under `.primer/runtime/workstreams/\u003cworkstream-id\u003e/`, while keeping one active workstream in the root adapter context at a time via `primer workstream switch`.\n\n## Troubleshooting\n\n- Run `primer doctor` after `primer init` if you are unsure whether your local toolchain is ready for the current milestone.\n- If your AI tool does not see the generated Primer workflow actions, make sure you opened the generated workspace, not the `primer` repository.\n- If your AI tool cannot run `primer`, install or build the CLI first and make sure it is on your `PATH`.\n- `primer init` is safe by default. Use `--force` only when you deliberately want to initialize into a non-empty directory.\n\n## Contributing\n\nPrimer is not only for people using recipes. It is also for people who want to author them.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contributor workflow, quality bar, and community direction.\n\nIf you want to propose a new community learning path, start with [docs/community-recipes.md](docs/community-recipes.md).\n\n## License\n\nPrimer is available under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmgabrielyan%2Fprimer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmgabrielyan%2Fprimer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmgabrielyan%2Fprimer/lists"}