@microsoft/agentrc 2.0.1-3 → 2.0.1-30
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 +61 -230
- package/dist/index.js +1544 -856
- 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 +44 -0
- package/dist/skills/root-instructions/SKILL.md +29 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,283 +1,114 @@
|
|
|
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:
|
|
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 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
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
## Prerequisites
|
|
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:
|
|
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.
|
|
66
16
|
|
|
67
17
|
```bash
|
|
68
|
-
agentrc
|
|
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
|
|
18
|
+
npx github:microsoft/agentrc
|
|
73
19
|
```
|
|
74
20
|
|
|
75
|
-
|
|
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.
|
|
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+.
|
|
102
22
|
|
|
103
|
-
|
|
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:**
|
|
23
|
+

|
|
119
24
|
|
|
120
|
-
|
|
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)
|
|
25
|
+
## What it does
|
|
123
26
|
|
|
124
|
-
###
|
|
27
|
+
### Measure
|
|
125
28
|
|
|
126
|
-
|
|
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.
|
|
127
30
|
|
|
128
31
|
```bash
|
|
129
|
-
agentrc
|
|
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%
|
|
32
|
+
npx github:microsoft/agentrc readiness
|
|
133
33
|
```
|
|
134
34
|
|
|
135
|
-
###
|
|
35
|
+
### Generate
|
|
136
36
|
|
|
137
|
-
|
|
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.
|
|
138
38
|
|
|
139
39
|
```bash
|
|
140
|
-
agentrc
|
|
141
|
-
agentrc generate vscode --force # .vscode/settings.json (overwrite)
|
|
40
|
+
npx github:microsoft/agentrc instructions
|
|
142
41
|
```
|
|
143
42
|
|
|
144
|
-
###
|
|
43
|
+
### Maintain
|
|
145
44
|
|
|
146
|
-
|
|
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
|
-
```
|
|
153
|
-
|
|
154
|
-
### `agentrc tui` — Interactive Mode
|
|
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.
|
|
155
46
|
|
|
156
47
|
```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": { ... } }
|
|
48
|
+
npx github:microsoft/agentrc eval
|
|
170
49
|
```
|
|
171
50
|
|
|
172
|
-
|
|
51
|
+
## Works at every scale
|
|
173
52
|
|
|
174
|
-
|
|
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` |
|
|
175
60
|
|
|
176
|
-
|
|
177
|
-
agentrc readiness --policy ./examples/policies/strict.json
|
|
178
|
-
agentrc readiness --policy ./examples/policies/strict.json,./my-overrides.json # chain multiple
|
|
179
|
-
```
|
|
61
|
+
Works with **GitHub** and **Azure DevOps**. Supports monorepos, multi-root VS Code workspaces, and custom [policies](docs/policies.md).
|
|
180
62
|
|
|
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
|
-
```
|
|
192
|
-
|
|
193
|
-
Policies can also be set in `agentrc.config.json` (`{ "policies": ["./my-policy.json"] }`).
|
|
194
|
-
|
|
195
|
-
### Configuration File
|
|
196
|
-
|
|
197
|
-
`agentrc.config.json` (repo root or `.github/`) configures areas, workspaces, and policies:
|
|
198
|
-
|
|
199
|
-
```json
|
|
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
|
-
```
|
|
63
|
+
## What gets generated
|
|
215
64
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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 |
|
|
219
71
|
|
|
220
|
-
>
|
|
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).
|
|
221
73
|
|
|
222
|
-
|
|
74
|
+
## Works with APM
|
|
223
75
|
|
|
224
|
-
|
|
76
|
+
[APM](https://github.com/microsoft/apm) (Agent Package Manager) distributes agent instructions, skills, and prompts across repos — like npm for AI agent configs.
|
|
225
77
|
|
|
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
|
-
```
|
|
78
|
+
AgentRC generates the content. APM distributes it:
|
|
234
79
|
|
|
235
|
-
|
|
80
|
+
- **In your project** — run `agentrc init` to generate instructions, then `apm install org/standards` to pull in shared agent packages from your team
|
|
81
|
+
- **For your team** — create a dedicated APM package with your best instructions and skills, then teammates install it with `apm install`
|
|
82
|
+
- **At scale** — `apm audit` scans for security issues; `apm-policy.yml` enforces org standards across all repos
|
|
236
83
|
|
|
237
|
-
|
|
238
|
-
cd vscode-extension
|
|
239
|
-
npm install && npm run build
|
|
240
|
-
# Press F5 to launch Extension Development Host
|
|
241
|
-
```
|
|
84
|
+
The `.instructions.md` format is shared by both tools — no conversion needed when moving instructions into APM packages.
|
|
242
85
|
|
|
243
|
-
|
|
86
|
+
## Documentation
|
|
244
87
|
|
|
245
|
-
|
|
88
|
+
| | |
|
|
89
|
+
| ---------------------------------------------- | ------------------------------------------------------- |
|
|
90
|
+
| **[Getting Started](docs/getting-started.md)** | Prerequisites and first run |
|
|
91
|
+
| **[Concepts](docs/concepts.md)** | Maturity model, readiness pillars, how generation works |
|
|
92
|
+
| **[Commands](docs/commands.md)** | Full CLI reference |
|
|
93
|
+
| **[Configuration](docs/configuration.md)** | Areas, workspaces, monorepos |
|
|
94
|
+
| **[Policies](docs/policies.md)** | Custom readiness scoring |
|
|
95
|
+
| **[At Scale](docs/at-scale.md)** | Batch processing across orgs |
|
|
96
|
+
| **[CI Integration](docs/ci-integration.md)** | GitHub Actions & Azure Pipelines |
|
|
97
|
+
| **[VS Code Extension](docs/extension.md)** | Sidebar views, commands, settings |
|
|
98
|
+
| **[Agent Plugin](plugin/README.md)** | Install as a Copilot agent plugin with built-in skills |
|
|
99
|
+
| **[Examples](examples/)** | Configs, evals, and policies |
|
|
246
100
|
|
|
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
|
-
```
|
|
101
|
+
[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
102
|
|
|
274
103
|
## Troubleshooting
|
|
275
104
|
|
|
276
|
-
**"Copilot CLI not found"** — Install the GitHub Copilot Chat extension in VS Code. The CLI is bundled with it.
|
|
105
|
+
**"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.
|
|
106
|
+
|
|
107
|
+
**"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login`.
|
|
277
108
|
|
|
278
|
-
**"
|
|
109
|
+
**"GitHub auth required"** — `brew install gh && gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`).
|
|
279
110
|
|
|
280
|
-
**"
|
|
111
|
+
**"Azure DevOps auth required"** — Set `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
|
|
281
112
|
|
|
282
113
|
## License
|
|
283
114
|
|