Prime your repositories for AI-assisted development.
Primer is a CLI and VS Code extension that helps teams prepare repositories for AI-assisted development. It generates custom instructions, assesses AI readiness across a maturity model, and supports batch processing across organizations.
# Run directly (no install needed)
npx github:microsoft/agent-init readinessnpx github:<owner>/primer ... installs from the Git repository and runs the package prepare script, which builds the CLI before first use.
Or install locally:
git clone https://github.com/microsoft/agent-init.git
cd primer && npm install && npm run build && npm link
# 1. Check how AI-ready your repo is
primer readiness
# 2. Generate AI instructions
primer instructions
# 3. Generate MCP and VS Code configs
primer generate mcp
primer generate vscode
# Or do everything interactively
primer init| Requirement | Notes |
|---|---|
| Node.js 20+ | Runtime |
| GitHub Copilot CLI | Bundled with the VS Code Copilot Chat extension |
| Copilot authentication | Run copilot → /login |
| GitHub CLI (optional) | For batch processing and PRs: brew install gh && gh auth login |
| Azure DevOps PAT (optional) | Set AZURE_DEVOPS_PAT for Azure DevOps workflows |
Detects languages, frameworks, monorepo/workspace structure, and area mappings:
primer analyze # terminal summary
primer analyze --json # machine-readable analysis
primer analyze --output analysis.json # save JSON report
primer analyze --output analysis.md # save Markdown report
primer analyze --output analysis.json --force # overwrite existing reportScore a repo across 9 pillars grouped into Repo Health and AI Setup:
primer readiness # terminal summary
primer readiness --visual # GitHub-themed HTML report
primer readiness --per-area # include per-area breakdown
primer readiness --output readiness.json # save JSON report
primer readiness --output readiness.md # save Markdown report
primer readiness --output readiness.html # save HTML report
primer readiness --policy ./examples/policies/strict.json # apply a custom policy
primer readiness --json # machine-readable JSON
primer readiness --fail-level 3 # CI gate: exit 1 if below level 3Maturity levels:
| Level | Name | What it means |
|---|---|---|
| 1 | Functional | Builds, tests, basic tooling in place |
| 2 | Documented | README, CONTRIBUTING, custom AI instructions exist |
At Level 2, Primer also checks instruction consistency — when a repo has multiple AI instruction files (e.g. copilot-instructions.md, CLAUDE.md, AGENTS.md), it detects whether they diverge. Symlinked or identical files pass; diverging files fail with a similarity score and a suggestion to consolidate.
| 3 | Standardized | CI/CD, security policies, CODEOWNERS, observability | | 4 | Optimized | MCP servers, custom agents, AI skills configured | | 5 | Autonomous | Full AI-native development with minimal oversight |
Generate copilot-instructions.md or AGENTS.md using the Copilot SDK:
primer instructions # copilot-instructions.md (default)
primer instructions --format agents-md # AGENTS.md
primer instructions --per-app # per-app in monorepos
primer instructions --areas # root + all detected areas
primer instructions --area frontend # single area
primer instructions --model claude-sonnet-4.5Measure how instructions improve AI responses with a judge model:
primer eval --init # scaffold eval config from codebase
primer eval primer.eval.json # run evaluation
primer eval --model gpt-4.1 --judge-model claude-sonnet-4.5
primer eval --fail-level 80 # CI gate: exit 1 if pass rate < 80%primer generate mcp # .vscode/mcp.json
primer generate vscode --force # .vscode/settings.json (overwrite)primer batch # interactive TUI (GitHub)
primer batch --provider azure # Azure DevOps
primer batch owner/repo1 owner/repo2 --json
primer batch-readiness --output team.html
primer pr owner/repo-name # clone → generate → open PRprimer tuiInteractive or headless repo onboarding — detects your stack and walks through readiness, instructions, and config generation.
All commands support --json (structured JSON to stdout) and --quiet (suppress stderr). JSON output uses a CommandResult<T> envelope:
{ "ok": true, "status": "success", "data": { ... } }Policies customize scoring criteria, override metadata, and tune thresholds:
primer readiness --policy ./examples/policies/strict.json
primer readiness --policy ./examples/policies/strict.json,./my-overrides.json # chain multiple{
"name": "my-org-policy",
"criteria": {
"disable": ["lint-config"],
"override": { "readme": { "impact": "high", "level": 2 } }
},
"extras": { "disable": ["pre-commit"] },
"thresholds": { "passRate": 0.9 }
}Policies can also be set in primer.config.json ({ "policies": ["./my-policy.json"] }).
Security: Config-sourced policies are restricted to JSON files only — JS/TS module policies must be passed via
--policy.
See docs/plugins.md for the full plugin authoring guide, including imperative TypeScript plugins, lifecycle hooks, and the trust model.
npm run typecheck # type check
npm run lint # ESLint (flat config + Prettier)
npm run test # Vitest tests
npm run test:coverage # with coverage
npm run build # production build via tsup
npx tsx src/index.ts --help # run from sourcecd vscode-extension
npm install && npm run build
# Press F5 to launch Extension Development HostSee CONTRIBUTING.md for workflow and code style guidelines.
src/
├── cli.ts # Commander CLI wiring
├── commands/ # CLI subcommands (thin orchestrators)
├── services/ # Core logic
│ ├── readiness.ts # 9-pillar scoring engine with pillar groups
│ ├── visualReport.ts # HTML report generator
│ ├── instructions.ts # Copilot SDK integration
│ ├── analyzer.ts # Repo scanning (languages, frameworks, monorepos)
│ ├── evaluator.ts # Eval runner + trajectory viewer
│ ├── generator.ts # MCP/VS Code config generation
│ ├── policy.ts # Readiness policy loading and chain resolution
│ ├── policy/ # Plugin engine (types, compiler, loader, adapter, shadow)
│ ├── git.ts # Git operations (clone, branch, push)
│ ├── github.ts # GitHub API (Octokit)
│ └── azureDevops.ts # Azure DevOps API
├── ui/ # Ink/React terminal UI
└── utils/ # Shared utilities (fs, logger, output)
vscode-extension/ # VS Code extension (commands, tree views, webview)
"Copilot CLI not found" — Install the GitHub Copilot Chat extension in VS Code. The CLI is bundled with it.
"Copilot CLI not logged in" — Run copilot in your terminal, then /login to authenticate.
"GitHub authentication required" — Install GitHub CLI (brew install gh && gh auth login) or set GITHUB_TOKEN / GH_TOKEN.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
