@microsoft/agentrc 2.0.1-1 → 2.0.1-100
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +73 -216
- package/dist/index.js +2591 -1273
- package/dist/index.js.map +1 -1
- package/dist/skills/area-instructions/SKILL.md +37 -0
- package/dist/skills/nested-detail/SKILL.md +22 -0
- package/dist/skills/nested-hub/SKILL.md +65 -0
- package/dist/skills/root-instructions/SKILL.md +29 -0
- package/package.json +14 -6
package/README.md
CHANGED
|
@@ -1,274 +1,131 @@
|
|
|
1
1
|
# AgentRC
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Context engineering for AI coding agents.**
|
|
4
4
|
|
|
5
5
|
[](https://github.com/microsoft/agentrc/actions/workflows/ci.yml)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
8
|
> [!WARNING]
|
|
9
|
-
> **Experimental** —
|
|
9
|
+
> **Experimental** — Under active development. Expect breaking changes. [Open an issue](https://github.com/microsoft/agentrc/issues) with feedback.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
---
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
**Generate** — Produce tailored instructions, evals, and dev configs using the Copilot SDK.
|
|
15
|
-
**Maintain** — Run evaluations in CI to catch instruction drift as code evolves.
|
|
13
|
+
AI coding agents work best when they know how to build, test, and lint your code — plus your architecture, conventions, and the external services your team relies on. Most repos ship none of that.
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## Quick Start
|
|
15
|
+
AgentRC reads your codebase and generates the files that close that gap — then evaluates whether they actually help, so the context doesn't go stale as your code evolves.
|
|
20
16
|
|
|
21
17
|
```bash
|
|
22
|
-
|
|
23
|
-
npx github:microsoft/agentrc readiness
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
`npx github:<owner>/agentrc ...` installs from the Git repository and runs the package `prepare` script, which builds the CLI before first use.
|
|
27
|
-
|
|
28
|
-
Or install locally:
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
git clone https://github.com/microsoft/agentrc.git
|
|
32
|
-
cd agentrc && npm install && npm run build && npm link
|
|
33
|
-
|
|
34
|
-
# 1. Inspect the repo shape
|
|
35
|
-
agentrc analyze
|
|
36
|
-
|
|
37
|
-
# 2. Check how AI-ready your repo is
|
|
38
|
-
agentrc readiness
|
|
39
|
-
|
|
40
|
-
# 3. Generate AI instructions
|
|
41
|
-
agentrc instructions
|
|
42
|
-
|
|
43
|
-
# 4. Generate MCP and VS Code configs
|
|
44
|
-
agentrc generate mcp
|
|
45
|
-
agentrc generate vscode
|
|
46
|
-
|
|
47
|
-
# Or do the guided flow interactively
|
|
48
|
-
agentrc init
|
|
18
|
+
npx github:microsoft/agentrc
|
|
49
19
|
```
|
|
50
20
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
| Requirement | Notes |
|
|
54
|
-
| --------------------------------- | ---------------------------------------------------------------- |
|
|
55
|
-
| **Node.js 20+** | Runtime |
|
|
56
|
-
| **GitHub Copilot CLI** | Bundled with the VS Code Copilot Chat extension |
|
|
57
|
-
| **Copilot authentication** | Run `copilot` → `/login` |
|
|
58
|
-
| **GitHub CLI** _(optional)_ | For batch processing and PRs: `brew install gh && gh auth login` |
|
|
59
|
-
| **Azure DevOps PAT** _(optional)_ | Set `AZURE_DEVOPS_PAT` for Azure DevOps workflows |
|
|
60
|
-
|
|
61
|
-
## Commands
|
|
62
|
-
|
|
63
|
-
### `agentrc analyze` — Inspect Repository Structure
|
|
64
|
-
|
|
65
|
-
Detects languages, frameworks, monorepo/workspace structure, and area mappings:
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
agentrc analyze # terminal summary
|
|
69
|
-
agentrc analyze --json # machine-readable analysis
|
|
70
|
-
agentrc analyze --output analysis.json # save JSON report
|
|
71
|
-
agentrc analyze --output analysis.md # save Markdown report
|
|
72
|
-
agentrc analyze --output analysis.json --force # overwrite existing report
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
### `agentrc readiness` — Assess AI Readiness
|
|
76
|
-
|
|
77
|
-
Score a repo across 9 pillars grouped into **Repo Health** and **AI Setup**:
|
|
78
|
-
|
|
79
|
-
```bash
|
|
80
|
-
agentrc readiness # terminal summary
|
|
81
|
-
agentrc readiness --visual # GitHub-themed HTML report
|
|
82
|
-
agentrc readiness --per-area # include per-area breakdown
|
|
83
|
-
agentrc readiness --output readiness.json # save JSON report
|
|
84
|
-
agentrc readiness --output readiness.md # save Markdown report
|
|
85
|
-
agentrc readiness --output readiness.html # save HTML report
|
|
86
|
-
agentrc readiness --policy ./examples/policies/strict.json # apply a custom policy
|
|
87
|
-
agentrc readiness --json # machine-readable JSON
|
|
88
|
-
agentrc readiness --fail-level 3 # CI gate: exit 1 if below level 3
|
|
89
|
-
```
|
|
21
|
+
Works as a CLI, as a [VS Code extension](docs/extension.md), and in your [CI/CD pipeline](docs/ci-integration.md) to monitor drift. No config needed — runs on any repo with Node.js 22+.
|
|
90
22
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
| Level | Name | What it means |
|
|
94
|
-
| ----- | ---------- | -------------------------------------------------- |
|
|
95
|
-
| 1 | Functional | Builds, tests, basic tooling in place |
|
|
96
|
-
| 2 | Documented | README, CONTRIBUTING, custom AI instructions exist |
|
|
97
|
-
|
|
98
|
-
At Level 2, AgentRC 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.
|
|
23
|
+

|
|
99
24
|
|
|
100
|
-
|
|
101
|
-
| 4 | Optimized | MCP servers, custom agents, AI skills configured |
|
|
102
|
-
| 5 | Autonomous | Full AI-native development with minimal oversight |
|
|
25
|
+
## What it does
|
|
103
26
|
|
|
104
|
-
###
|
|
27
|
+
### Measure
|
|
105
28
|
|
|
106
|
-
|
|
29
|
+
Score your repo’s AI-readiness across 9 pillars and a 5-level maturity model. Find out what context is missing — from basic linting to MCP server configs.
|
|
107
30
|
|
|
108
31
|
```bash
|
|
109
|
-
agentrc
|
|
110
|
-
agentrc instructions --format agents-md # AGENTS.md
|
|
111
|
-
agentrc instructions --per-app # per-app in monorepos
|
|
112
|
-
agentrc instructions --areas # root + all detected areas
|
|
113
|
-
agentrc instructions --area frontend # single area
|
|
114
|
-
agentrc instructions --model claude-sonnet-4.5
|
|
32
|
+
npx github:microsoft/agentrc readiness
|
|
115
33
|
```
|
|
116
34
|
|
|
117
|
-
###
|
|
118
|
-
|
|
119
|
-
Measure how instructions improve AI responses with a judge model:
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
agentrc eval --init # scaffold eval config from codebase
|
|
123
|
-
agentrc eval agentrc.eval.json # run evaluation
|
|
124
|
-
agentrc eval --model gpt-4.1 --judge-model claude-sonnet-4.5
|
|
125
|
-
agentrc eval --fail-level 80 # CI gate: exit 1 if pass rate < 80%
|
|
126
|
-
```
|
|
35
|
+
### Generate
|
|
127
36
|
|
|
128
|
-
|
|
37
|
+
Produce tailored instruction files, evals, and dev configs via the Copilot SDK. No templates — AgentRC reads your actual code and generates context specific to your stack.
|
|
129
38
|
|
|
130
39
|
```bash
|
|
131
|
-
agentrc
|
|
132
|
-
agentrc generate vscode --force # .vscode/settings.json (overwrite)
|
|
40
|
+
npx github:microsoft/agentrc instructions
|
|
133
41
|
```
|
|
134
42
|
|
|
135
|
-
###
|
|
136
|
-
|
|
137
|
-
```bash
|
|
138
|
-
agentrc batch # interactive TUI (GitHub)
|
|
139
|
-
agentrc batch --provider azure # Azure DevOps
|
|
140
|
-
agentrc batch owner/repo1 owner/repo2 --json
|
|
141
|
-
agentrc batch-readiness --output team.html
|
|
142
|
-
agentrc pr owner/repo-name # clone → generate → open PR
|
|
143
|
-
```
|
|
43
|
+
### Maintain
|
|
144
44
|
|
|
145
|
-
|
|
45
|
+
Context goes stale as your codebase evolves. Evaluate whether your instructions still improve agent responses, and run the check in CI so drift doesn't slip through.
|
|
146
46
|
|
|
147
47
|
```bash
|
|
148
|
-
agentrc
|
|
48
|
+
npx github:microsoft/agentrc eval
|
|
149
49
|
```
|
|
150
50
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
Interactive or headless repo onboarding — detects your stack and walks through readiness, instructions, and config generation. For monorepos, auto-detects workspaces and bootstraps `agentrc.config.json` with workspace and area definitions.
|
|
51
|
+
## AgentRC maintains itself with GitHub Agentic Workflows
|
|
154
52
|
|
|
155
|
-
|
|
53
|
+
This repository dogfoods [GitHub Agentic Workflows](https://github.github.com/gh-aw/) for recurring maintenance and demos:
|
|
156
54
|
|
|
157
|
-
|
|
55
|
+
| Workflow | Purpose | Output |
|
|
56
|
+
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------ |
|
|
57
|
+
| [AgentRC Readiness Report](.github/workflows/agentrc-readiness-report.md) | Runs AgentRC against this repository and explains the highest-impact gaps | One short-lived issue |
|
|
58
|
+
| [AgentRC Readiness Upgrade](.github/workflows/agentrc-readiness-upgrade.md) | Improves one evidence-backed instruction and verifies the result | One draft PR |
|
|
59
|
+
| [Issue Triage](.github/workflows/issue-triage.md) | Classifies new issues and asks for missing information | Bounded labels and one comment |
|
|
60
|
+
| [CI Failure Doctor](.github/workflows/ci-doctor.md) | Diagnoses failed CI from logs and repository changes | One issue or one comment |
|
|
158
61
|
|
|
159
|
-
|
|
160
|
-
{ "ok": true, "status": "success", "data": { ... } }
|
|
161
|
-
```
|
|
62
|
+
The source workflows are Markdown. `gh aw compile` generates the reviewable `.lock.yml` workflows that GitHub Actions executes. CI fails when those generated files drift.
|
|
162
63
|
|
|
163
|
-
|
|
64
|
+
See [Agentic Workflows](docs/agentic-workflows.md) for the architecture and maintenance commands. Use the [golden demo runbook](docs/agentic-workflows-demo.md) for the lone-maintainer narrative, exact stage flow, and fallback plan.
|
|
164
65
|
|
|
165
|
-
|
|
66
|
+
## Works at every scale
|
|
166
67
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
68
|
+
| Workflow | Command |
|
|
69
|
+
| ------------------------- | ----------------------------------------- |
|
|
70
|
+
| Interactive hub | `agentrc` |
|
|
71
|
+
| One-time setup | `agentrc init` |
|
|
72
|
+
| CI quality gate | `agentrc readiness --fail-level 3 --json` |
|
|
73
|
+
| Batch across an org | `agentrc batch` |
|
|
74
|
+
| Automated PR for any repo | `agentrc pr owner/repo` |
|
|
171
75
|
|
|
172
|
-
|
|
173
|
-
{
|
|
174
|
-
"name": "my-org-policy",
|
|
175
|
-
"criteria": {
|
|
176
|
-
"disable": ["lint-config"],
|
|
177
|
-
"override": { "readme": { "impact": "high", "level": 2 } }
|
|
178
|
-
},
|
|
179
|
-
"extras": { "disable": ["pre-commit"] },
|
|
180
|
-
"thresholds": { "passRate": 0.9 }
|
|
181
|
-
}
|
|
182
|
-
```
|
|
76
|
+
Works with **GitHub** and **Azure DevOps**. Supports monorepos, multi-root VS Code workspaces, and custom [policies](docs/policies.md).
|
|
183
77
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
### Configuration File
|
|
187
|
-
|
|
188
|
-
`agentrc.config.json` (repo root or `.github/`) configures areas, workspaces, and policies:
|
|
189
|
-
|
|
190
|
-
```json
|
|
191
|
-
{
|
|
192
|
-
"areas": [{ "name": "docs", "applyTo": "docs/**" }],
|
|
193
|
-
"workspaces": [
|
|
194
|
-
{
|
|
195
|
-
"name": "frontend",
|
|
196
|
-
"path": "packages/frontend",
|
|
197
|
-
"areas": [
|
|
198
|
-
{ "name": "app", "applyTo": "app/**" },
|
|
199
|
-
{ "name": "shared", "applyTo": ["shared/**", "common/**"] }
|
|
200
|
-
]
|
|
201
|
-
}
|
|
202
|
-
],
|
|
203
|
-
"policies": ["./policies/strict.json"]
|
|
204
|
-
}
|
|
205
|
-
```
|
|
78
|
+
## What gets generated
|
|
206
79
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
80
|
+
| File | Purpose |
|
|
81
|
+
| --------------------------------- | ------------------------------------------ |
|
|
82
|
+
| `.github/copilot-instructions.md` | Teaches AI agents your repo's conventions |
|
|
83
|
+
| `.vscode/mcp.json` | Connects AI to your stack's tools and data |
|
|
84
|
+
| `.vscode/settings.json` | Tunes VS Code for AI-assisted development |
|
|
85
|
+
| `agentrc.eval.json` | Test cases to measure instruction quality |
|
|
210
86
|
|
|
211
|
-
>
|
|
87
|
+
> For multi-agent support (Copilot + Claude + others), generate `AGENTS.md` with `--output AGENTS.md`. See [Custom instructions in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-instructions).
|
|
212
88
|
|
|
213
|
-
|
|
89
|
+
## Works with APM
|
|
214
90
|
|
|
215
|
-
|
|
91
|
+
[APM](https://github.com/microsoft/apm) (Agent Package Manager) distributes agent instructions, skills, and prompts across repos — like npm for AI agent configs.
|
|
216
92
|
|
|
217
|
-
|
|
218
|
-
npm run typecheck # type check
|
|
219
|
-
npm run lint # ESLint (flat config + Prettier)
|
|
220
|
-
npm run test # Vitest tests
|
|
221
|
-
npm run test:coverage # with coverage
|
|
222
|
-
npm run build # production build via tsup
|
|
223
|
-
npx tsx src/index.ts --help # run from source
|
|
224
|
-
```
|
|
93
|
+
AgentRC generates the content. APM distributes it:
|
|
225
94
|
|
|
226
|
-
|
|
95
|
+
- **In your project** — run `agentrc init` to generate instructions, then `apm install org/standards` to pull in shared agent packages from your team
|
|
96
|
+
- **For your team** — create a dedicated APM package with your best instructions and skills, then teammates install it with `apm install`
|
|
97
|
+
- **At scale** — `apm audit` scans for security issues; `apm-policy.yml` enforces org standards across all repos
|
|
227
98
|
|
|
228
|
-
|
|
229
|
-
cd vscode-extension
|
|
230
|
-
npm install && npm run build
|
|
231
|
-
# Press F5 to launch Extension Development Host
|
|
232
|
-
```
|
|
99
|
+
The `.instructions.md` format is shared by both tools — no conversion needed when moving instructions into APM packages.
|
|
233
100
|
|
|
234
|
-
|
|
101
|
+
## Documentation
|
|
235
102
|
|
|
236
|
-
|
|
103
|
+
| | |
|
|
104
|
+
| -------------------------------------------------- | ------------------------------------------------------- |
|
|
105
|
+
| **[Getting Started](docs/getting-started.md)** | Prerequisites and first run |
|
|
106
|
+
| **[Concepts](docs/concepts.md)** | Maturity model, readiness pillars, how generation works |
|
|
107
|
+
| **[Commands](docs/commands.md)** | Full CLI reference |
|
|
108
|
+
| **[Configuration](docs/configuration.md)** | Areas, workspaces, monorepos |
|
|
109
|
+
| **[Policies](docs/policies.md)** | Custom readiness scoring |
|
|
110
|
+
| **[At Scale](docs/at-scale.md)** | Batch processing across orgs |
|
|
111
|
+
| **[CI Integration](docs/ci-integration.md)** | GitHub Actions & Azure Pipelines |
|
|
112
|
+
| **[VS Code Extension](docs/extension.md)** | Sidebar views, commands, settings |
|
|
113
|
+
| **[Agent Plugin](plugin/README.md)** | Install as a Copilot agent plugin with built-in skills |
|
|
114
|
+
| **[Agentic Workflows](docs/agentic-workflows.md)** | Dogfooding, maintenance, and live demo guide |
|
|
115
|
+
| **[Golden Demo](docs/agentic-workflows-demo.md)** | Lone-maintainer story and stage-ready runbook |
|
|
116
|
+
| **[Examples](examples/)** | Configs, evals, and policies |
|
|
237
117
|
|
|
238
|
-
|
|
239
|
-
packages/core/
|
|
240
|
-
└── src/
|
|
241
|
-
├── index.ts # Shared public API surface
|
|
242
|
-
├── services/ # Core product logic reused by CLI and extension
|
|
243
|
-
│ ├── readiness.ts # 9-pillar scoring engine with pillar groups
|
|
244
|
-
│ ├── visualReport.ts # HTML report generator
|
|
245
|
-
│ ├── instructions.ts # Copilot SDK integration
|
|
246
|
-
│ ├── analyzer.ts # Repo scanning (languages, frameworks, monorepos)
|
|
247
|
-
│ ├── evaluator.ts # Eval runner + trajectory viewer
|
|
248
|
-
│ ├── generator.ts # MCP/VS Code config generation
|
|
249
|
-
│ ├── policy.ts # Readiness policy loading and chain resolution
|
|
250
|
-
│ ├── policy/ # Plugin engine (types, compiler, loader, adapter, shadow)
|
|
251
|
-
│ ├── git.ts # Git operations (clone, branch, push)
|
|
252
|
-
│ ├── github.ts # GitHub API (Octokit)
|
|
253
|
-
│ └── azureDevops.ts # Azure DevOps API
|
|
254
|
-
└── utils/ # Shared utilities (fs, logger, output)
|
|
255
|
-
|
|
256
|
-
src/
|
|
257
|
-
├── cli.ts # Commander CLI wiring
|
|
258
|
-
├── commands/ # CLI subcommands (thin orchestrators)
|
|
259
|
-
├── index.ts # CLI entrypoint
|
|
260
|
-
└── ui/ # Ink/React terminal UI
|
|
261
|
-
|
|
262
|
-
vscode-extension/ # VS Code extension shell over packages/core
|
|
263
|
-
```
|
|
118
|
+
[Customize AI in VS Code](https://code.visualstudio.com/docs/copilot/customization/overview) · [Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) · [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
264
119
|
|
|
265
120
|
## Troubleshooting
|
|
266
121
|
|
|
267
|
-
**"Copilot CLI not found"** — Install the GitHub Copilot Chat extension in VS Code. The CLI is bundled with it.
|
|
122
|
+
**"Copilot CLI not found"** — Install the [GitHub Copilot Chat extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) in VS Code. The CLI is bundled with it.
|
|
123
|
+
|
|
124
|
+
**"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login`.
|
|
268
125
|
|
|
269
|
-
**"
|
|
126
|
+
**"GitHub auth required"** — `brew install gh && gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`).
|
|
270
127
|
|
|
271
|
-
**"
|
|
128
|
+
**"Azure DevOps auth required"** — Set `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
|
|
272
129
|
|
|
273
130
|
## License
|
|
274
131
|
|