@microsoft/agentrc 2.0.1-2 → 2.0.1-21

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 CHANGED
@@ -1,274 +1,114 @@
1
1
  # AgentRC
2
2
 
3
- > Prime your repositories for AI-assisted development.
3
+ **Context engineering for AI coding agents.**
4
4
 
5
5
  [![CI](https://github.com/microsoft/agentrc/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/agentrc/actions/workflows/ci.yml)
6
6
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7
7
 
8
8
  > [!WARNING]
9
- > **Experimental** — This project is under active development. Expect breaking changes to commands, APIs, and output formats. Ready for early adopter feedback — [open an issue](https://github.com/microsoft/agentrc/issues).
9
+ > **Experimental** — Under active development. Expect breaking changes. [Open an issue](https://github.com/microsoft/agentrc/issues) with feedback.
10
10
 
11
- AI coding agents are only as effective as the context they receive. AgentRC is a CLI and VS Code extension that closes the gap — from a single repo to hundreds across your org.
11
+ ---
12
12
 
13
- **Measure** — Analyze repo structure and score AI readiness across a 5-level maturity model.
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
- ![AgentRC — Measure, Generate, Maintain cycle](docs/assets/agentrc-overview.png)
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
- 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
- ## 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:
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
- ```
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 AI instructions exist |
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+.
97
22
 
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
+ ![AgentRC — Measure, Generate, Maintain cycle](docs/assets/agentrc-overview.png)
99
24
 
100
- | 3 | Standardized | CI/CD, security policies, CODEOWNERS, observability |
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
- ### `agentrc instructions` — Generate Instructions
27
+ ### Measure
105
28
 
106
- Generate `copilot-instructions.md` or `AGENTS.md` using the Copilot SDK:
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 instructions # copilot-instructions.md (default)
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
- ### `agentrc eval` — Evaluate Instructions
35
+ ### Generate
118
36
 
119
- Measure how instructions improve AI responses with a judge model:
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.
120
38
 
121
39
  ```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%
40
+ npx github:microsoft/agentrc instructions
126
41
  ```
127
42
 
128
- ### `agentrc generate` — Generate Configs
129
-
130
- ```bash
131
- agentrc generate mcp # .vscode/mcp.json
132
- agentrc generate vscode --force # .vscode/settings.json (overwrite)
133
- ```
134
-
135
- ### `agentrc batch` / `agentrc pr` — Batch & PRs
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
- ### `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.
146
46
 
147
47
  ```bash
148
- agentrc tui
48
+ npx github:microsoft/agentrc eval
149
49
  ```
150
50
 
151
- ### `agentrc init` — Guided Setup
51
+ ## Works at every scale
152
52
 
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.
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` |
154
60
 
155
- ### Global Options
61
+ Works with **GitHub** and **Azure DevOps**. Supports monorepos, multi-root VS Code workspaces, and custom [policies](docs/policies.md).
156
62
 
157
- All commands support `--json` (structured JSON to stdout) and `--quiet` (suppress stderr). JSON output uses a `CommandResult<T>` envelope:
63
+ ## What gets generated
158
64
 
159
- ```json
160
- { "ok": true, "status": "success", "data": { ... } }
161
- ```
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 |
162
71
 
163
- ### Readiness Policies
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).
164
73
 
165
- Policies customize scoring criteria, override metadata, and tune thresholds:
74
+ ## Works with APM
166
75
 
167
- ```bash
168
- agentrc readiness --policy ./examples/policies/strict.json
169
- agentrc readiness --policy ./examples/policies/strict.json,./my-overrides.json # chain multiple
170
- ```
76
+ [APM](https://github.com/microsoft/apm) (Agent Package Manager) distributes agent instructions, skills, and prompts across repos — like npm for AI agent configs.
171
77
 
172
- ```json
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
- ```
78
+ AgentRC generates the content. APM distributes it:
183
79
 
184
- Policies can also be set in `agentrc.config.json` (`{ "policies": ["./my-policy.json"] }`).
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
- ```
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
206
83
 
207
- - **`areas`** — standalone areas with glob patterns (relative to repo root)
208
- - **`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.
209
- - `agentrc init` auto-detects workspaces (via `.vscode` folders and sibling-area grouping) and bootstraps this file.
84
+ The `.instructions.md` format is shared by both tools — no conversion needed when moving instructions into APM packages.
210
85
 
211
- > **Security:** Config-sourced policies are restricted to JSON files only — JS/TS module policies must be passed via `--policy`.
86
+ ## Documentation
212
87
 
213
- See [docs/plugins.md](docs/plugins.md) for the full plugin authoring guide, including imperative TypeScript plugins, lifecycle hooks, and the trust model.
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 |
214
100
 
215
- ## Development
216
-
217
- ```bash
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
- ```
225
-
226
- ### VS Code Extension
227
-
228
- ```bash
229
- cd vscode-extension
230
- npm install && npm run build
231
- # Press F5 to launch Extension Development Host
232
- ```
233
-
234
- See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and code style guidelines.
235
-
236
- ## Project Structure
237
-
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
- ```
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)
264
102
 
265
103
  ## Troubleshooting
266
104
 
267
- **"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`.
268
108
 
269
- **"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login` to authenticate.
109
+ **"GitHub auth required"** — `brew install gh && gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`).
270
110
 
271
- **"GitHub authentication required"** — Install GitHub CLI (`brew install gh && gh auth login`) or set `GITHUB_TOKEN` / `GH_TOKEN`.
111
+ **"Azure DevOps auth required"** — Set `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
272
112
 
273
113
  ## License
274
114