@microsoft/agentrc 2.0.1-3 → 2.0.1-5
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 +53 -235
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,283 +1,101 @@
|
|
|
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
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
# Run directly (no install needed)
|
|
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:
|
|
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.
|
|
29
16
|
|
|
30
17
|
```bash
|
|
31
|
-
|
|
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 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
|
|
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 20+.
|
|
64
22
|
|
|
65
|
-
|
|
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` — Run Readiness Report
|
|
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
|
-
```
|
|
90
|
-
|
|
91
|
-
**Maturity levels:**
|
|
92
|
-
|
|
93
|
-
| Level | Name | What it means |
|
|
94
|
-
| ----- | ------------ | --------------------------------------------------- |
|
|
95
|
-
| 1 | Functional | Builds, tests, basic tooling in place |
|
|
96
|
-
| 2 | Documented | README, CONTRIBUTING, custom instructions exist |
|
|
97
|
-
| 3 | Standardized | CI/CD, security policies, CODEOWNERS, observability |
|
|
98
|
-
| 4 | Optimized | MCP servers, custom agents, AI skills configured |
|
|
99
|
-
| 5 | Autonomous | Full AI-native development with minimal oversight |
|
|
100
|
-
|
|
101
|
-
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.
|
|
102
|
-
|
|
103
|
-
### `agentrc instructions` — Generate Instructions
|
|
104
|
-
|
|
105
|
-
Generate instructions using the Copilot SDK:
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
agentrc instructions # copilot-instructions.md (default)
|
|
109
|
-
agentrc instructions --output AGENTS.md # custom output path
|
|
110
|
-
agentrc instructions --strategy nested # nested hub + detail files in .agents/
|
|
111
|
-
agentrc instructions --areas # root + all detected areas
|
|
112
|
-
agentrc instructions --area frontend # single area
|
|
113
|
-
agentrc instructions --areas-only # areas only (skip root)
|
|
114
|
-
agentrc instructions --dry-run # preview without writing
|
|
115
|
-
agentrc instructions --model claude-sonnet-4.6
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
**Concepts:**
|
|
119
|
-
|
|
120
|
-
- **Format**: Output file — `copilot-instructions.md` (default) or `AGENTS.md` (via `--output`)
|
|
121
|
-
- **Strategy**: `flat` (single file, default) or `nested` (hub + per-topic detail files)
|
|
122
|
-
- **Scope**: `root only` (default), `--areas` (root + areas), `--area <name>` (single area)
|
|
123
|
-
|
|
124
|
-
### `agentrc eval` — Evaluate Instructions
|
|
125
|
-
|
|
126
|
-
Measure how instructions improve AI responses with a judge model:
|
|
23
|
+
|
|
127
24
|
|
|
128
|
-
|
|
129
|
-
agentrc eval --init # scaffold eval config from codebase
|
|
130
|
-
agentrc eval agentrc.eval.json # run evaluation
|
|
131
|
-
agentrc eval --model gpt-4.1 --judge-model claude-sonnet-4.6
|
|
132
|
-
agentrc eval --fail-level 80 # CI gate: exit 1 if pass rate < 80%
|
|
133
|
-
```
|
|
25
|
+
## What it does
|
|
134
26
|
|
|
135
|
-
###
|
|
27
|
+
### Measure
|
|
136
28
|
|
|
137
|
-
|
|
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.
|
|
138
30
|
|
|
139
31
|
```bash
|
|
140
|
-
agentrc
|
|
141
|
-
agentrc generate vscode --force # .vscode/settings.json (overwrite)
|
|
32
|
+
npx github:microsoft/agentrc readiness
|
|
142
33
|
```
|
|
143
34
|
|
|
144
|
-
###
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
agentrc batch # interactive TUI (GitHub)
|
|
148
|
-
agentrc batch --provider azure # Azure DevOps
|
|
149
|
-
agentrc batch owner/repo1 owner/repo2 --json
|
|
150
|
-
agentrc batch-readiness --output team.html
|
|
151
|
-
agentrc pr owner/repo-name # clone → generate → open PR
|
|
152
|
-
```
|
|
35
|
+
### Generate
|
|
153
36
|
|
|
154
|
-
|
|
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.
|
|
155
38
|
|
|
156
39
|
```bash
|
|
157
|
-
agentrc
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
### `agentrc init` — Init Repository
|
|
161
|
-
|
|
162
|
-
Interactive or headless repo onboarding — analyzes your stack and generates instructions. For monorepos, auto-detects workspaces and bootstraps `agentrc.config.json` with workspace and area definitions.
|
|
163
|
-
|
|
164
|
-
### Global Options
|
|
165
|
-
|
|
166
|
-
All commands support `--json` (structured JSON to stdout) and `--quiet` (suppress stderr). JSON output uses a `CommandResult<T>` envelope:
|
|
167
|
-
|
|
168
|
-
```json
|
|
169
|
-
{ "ok": true, "status": "success", "data": { ... } }
|
|
40
|
+
npx github:microsoft/agentrc instructions
|
|
170
41
|
```
|
|
171
42
|
|
|
172
|
-
###
|
|
43
|
+
### Maintain
|
|
173
44
|
|
|
174
|
-
|
|
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.
|
|
175
46
|
|
|
176
47
|
```bash
|
|
177
|
-
agentrc
|
|
178
|
-
agentrc readiness --policy ./examples/policies/strict.json,./my-overrides.json # chain multiple
|
|
48
|
+
npx github:microsoft/agentrc eval
|
|
179
49
|
```
|
|
180
50
|
|
|
181
|
-
|
|
182
|
-
{
|
|
183
|
-
"name": "my-org-policy",
|
|
184
|
-
"criteria": {
|
|
185
|
-
"disable": ["lint-config"],
|
|
186
|
-
"override": { "readme": { "impact": "high", "level": 2 } }
|
|
187
|
-
},
|
|
188
|
-
"extras": { "disable": ["pre-commit"] },
|
|
189
|
-
"thresholds": { "passRate": 0.9 }
|
|
190
|
-
}
|
|
191
|
-
```
|
|
51
|
+
## Works at every scale
|
|
192
52
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
{
|
|
201
|
-
"areas": [{ "name": "docs", "applyTo": "docs/**" }],
|
|
202
|
-
"workspaces": [
|
|
203
|
-
{
|
|
204
|
-
"name": "frontend",
|
|
205
|
-
"path": "packages/frontend",
|
|
206
|
-
"areas": [
|
|
207
|
-
{ "name": "app", "applyTo": "app/**" },
|
|
208
|
-
{ "name": "shared", "applyTo": ["shared/**", "common/**"] }
|
|
209
|
-
]
|
|
210
|
-
}
|
|
211
|
-
],
|
|
212
|
-
"policies": ["./policies/strict.json"]
|
|
213
|
-
}
|
|
214
|
-
```
|
|
53
|
+
| Workflow | Command |
|
|
54
|
+
| ------------------------- | ----------------------------------------- |
|
|
55
|
+
| Interactive hub | `agentrc` |
|
|
56
|
+
| One-time setup | `agentrc init` |
|
|
57
|
+
| CI quality gate | `agentrc readiness --fail-level 3 --json` |
|
|
58
|
+
| Batch across an org | `agentrc batch` |
|
|
59
|
+
| Automated PR for any repo | `agentrc pr owner/repo` |
|
|
215
60
|
|
|
216
|
-
|
|
217
|
-
- **`workspaces`** — monorepo sub-projects; each workspace groups areas scoped to a subdirectory. Area `applyTo` patterns are relative to the workspace path. Workspace areas get namespaced names (`frontend/app`) and a `workingDirectory` for scoped eval sessions.
|
|
218
|
-
- `agentrc init` auto-detects workspaces (via `.vscode` folders and sibling-area grouping) and bootstraps this file.
|
|
61
|
+
Works with **GitHub** and **Azure DevOps**. Supports monorepos, multi-root VS Code workspaces, and custom [policies](docs/policies.md).
|
|
219
62
|
|
|
220
|
-
|
|
63
|
+
## What gets generated
|
|
221
64
|
|
|
222
|
-
|
|
65
|
+
| File | Purpose |
|
|
66
|
+
| --------------------------------- | ------------------------------------------ |
|
|
67
|
+
| `.github/copilot-instructions.md` | Teaches AI agents your repo's conventions |
|
|
68
|
+
| `.vscode/mcp.json` | Connects AI to your stack's tools and data |
|
|
69
|
+
| `.vscode/settings.json` | Tunes VS Code for AI-assisted development |
|
|
70
|
+
| `agentrc.eval.json` | Test cases to measure instruction quality |
|
|
223
71
|
|
|
224
|
-
|
|
72
|
+
> 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).
|
|
225
73
|
|
|
226
|
-
|
|
227
|
-
npm run typecheck # type check
|
|
228
|
-
npm run lint # ESLint (flat config + Prettier)
|
|
229
|
-
npm run test # Vitest tests
|
|
230
|
-
npm run test:coverage # with coverage
|
|
231
|
-
npm run build # production build via tsup
|
|
232
|
-
npx tsx src/index.ts --help # run from source
|
|
233
|
-
```
|
|
74
|
+
## Documentation
|
|
234
75
|
|
|
235
|
-
|
|
76
|
+
| | |
|
|
77
|
+
| ---------------------------------------------- | ------------------------------------------------------- |
|
|
78
|
+
| **[Getting Started](docs/getting-started.md)** | Prerequisites and first run |
|
|
79
|
+
| **[Concepts](docs/concepts.md)** | Maturity model, readiness pillars, how generation works |
|
|
80
|
+
| **[Commands](docs/commands.md)** | Full CLI reference |
|
|
81
|
+
| **[Configuration](docs/configuration.md)** | Areas, workspaces, monorepos |
|
|
82
|
+
| **[Policies](docs/policies.md)** | Custom readiness scoring |
|
|
83
|
+
| **[At Scale](docs/at-scale.md)** | Batch processing across orgs |
|
|
84
|
+
| **[CI Integration](docs/ci-integration.md)** | GitHub Actions & Azure Pipelines |
|
|
85
|
+
| **[VS Code Extension](docs/extension.md)** | Sidebar views, commands, settings |
|
|
86
|
+
| **[Examples](examples/)** | Configs, evals, and policies |
|
|
236
87
|
|
|
237
|
-
|
|
238
|
-
cd vscode-extension
|
|
239
|
-
npm install && npm run build
|
|
240
|
-
# Press F5 to launch Extension Development Host
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and code style guidelines.
|
|
244
|
-
|
|
245
|
-
## Project Structure
|
|
246
|
-
|
|
247
|
-
```
|
|
248
|
-
packages/core/
|
|
249
|
-
└── src/
|
|
250
|
-
├── index.ts # Shared public API surface
|
|
251
|
-
├── services/ # Core product logic reused by CLI and extension
|
|
252
|
-
│ ├── readiness.ts # 9-pillar scoring engine with pillar groups
|
|
253
|
-
│ ├── visualReport.ts # HTML report generator
|
|
254
|
-
│ ├── instructions.ts # Copilot SDK integration
|
|
255
|
-
│ ├── analyzer.ts # Repo scanning (languages, frameworks, monorepos)
|
|
256
|
-
│ ├── evaluator.ts # Eval runner + trajectory viewer
|
|
257
|
-
│ ├── generator.ts # MCP/VS Code config generation
|
|
258
|
-
│ ├── policy.ts # Readiness policy loading and chain resolution
|
|
259
|
-
│ ├── policy/ # Plugin engine (types, compiler, loader, adapter, shadow)
|
|
260
|
-
│ ├── git.ts # Git operations (clone, branch, push)
|
|
261
|
-
│ ├── github.ts # GitHub API (Octokit)
|
|
262
|
-
│ └── azureDevops.ts # Azure DevOps API
|
|
263
|
-
└── utils/ # Shared utilities (fs, logger, output)
|
|
264
|
-
|
|
265
|
-
src/
|
|
266
|
-
├── cli.ts # Commander CLI wiring
|
|
267
|
-
├── commands/ # CLI subcommands (thin orchestrators)
|
|
268
|
-
├── index.ts # CLI entrypoint
|
|
269
|
-
└── ui/ # Ink/React terminal UI
|
|
270
|
-
|
|
271
|
-
vscode-extension/ # VS Code extension shell over packages/core
|
|
272
|
-
```
|
|
88
|
+
[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)
|
|
273
89
|
|
|
274
90
|
## Troubleshooting
|
|
275
91
|
|
|
276
|
-
**"Copilot CLI not found"** — Install the GitHub Copilot Chat extension in VS Code. The CLI is bundled with it.
|
|
92
|
+
**"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.
|
|
93
|
+
|
|
94
|
+
**"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login`.
|
|
277
95
|
|
|
278
|
-
**"
|
|
96
|
+
**"GitHub auth required"** — `brew install gh && gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`).
|
|
279
97
|
|
|
280
|
-
**"
|
|
98
|
+
**"Azure DevOps auth required"** — Set `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
|
|
281
99
|
|
|
282
100
|
## License
|
|
283
101
|
|