@microsoft/agentrc 2.0.1-2 → 2.0.1-4

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.
Files changed (4) hide show
  1. package/README.md +53 -226
  2. package/dist/index.js +307 -131
  3. package/dist/index.js.map +1 -1
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,274 +1,101 @@
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:
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
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 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
18
+ npx github:microsoft/agentrc
73
19
  ```
74
20
 
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 |
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.
99
-
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 |
103
-
104
- ### `agentrc instructions` — Generate Instructions
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+.
105
22
 
106
- Generate `copilot-instructions.md` or `AGENTS.md` using the Copilot SDK:
23
+ ![AgentRC — Measure, Generate, Maintain cycle](docs/assets/agentrc-overview.png)
107
24
 
108
- ```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
115
- ```
25
+ ## What it does
116
26
 
117
- ### `agentrc eval` — Evaluate Instructions
27
+ ### Measure
118
28
 
119
- Measure how instructions improve AI responses with a judge model:
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.
120
30
 
121
31
  ```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%
32
+ npx github:microsoft/agentrc readiness
126
33
  ```
127
34
 
128
- ### `agentrc generate` — Generate Configs
35
+ ### Generate
129
36
 
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
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.
136
38
 
137
39
  ```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
40
+ npx github:microsoft/agentrc instructions
143
41
  ```
144
42
 
145
- ### `agentrc tui` — Interactive Mode
43
+ ### Maintain
146
44
 
147
- ```bash
148
- agentrc tui
149
- ```
150
-
151
- ### `agentrc init` — Guided Setup
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.
154
-
155
- ### Global Options
156
-
157
- All commands support `--json` (structured JSON to stdout) and `--quiet` (suppress stderr). JSON output uses a `CommandResult<T>` envelope:
158
-
159
- ```json
160
- { "ok": true, "status": "success", "data": { ... } }
161
- ```
162
-
163
- ### Readiness Policies
164
-
165
- Policies customize scoring criteria, override metadata, and tune thresholds:
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.
166
46
 
167
47
  ```bash
168
- agentrc readiness --policy ./examples/policies/strict.json
169
- agentrc readiness --policy ./examples/policies/strict.json,./my-overrides.json # chain multiple
170
- ```
171
-
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
- }
48
+ npx github:microsoft/agentrc eval
182
49
  ```
183
50
 
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
- ```
206
-
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.
210
-
211
- > **Security:** Config-sourced policies are restricted to JSON files only — JS/TS module policies must be passed via `--policy`.
51
+ ## Works at every scale
212
52
 
213
- See [docs/plugins.md](docs/plugins.md) for the full plugin authoring guide, including imperative TypeScript plugins, lifecycle hooks, and the trust model.
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` |
214
60
 
215
- ## Development
61
+ Works with **GitHub** and **Azure DevOps**. Supports monorepos, multi-root VS Code workspaces, and custom [policies](docs/policies.md).
216
62
 
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
- ```
63
+ ## What gets generated
225
64
 
226
- ### VS Code Extension
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 |
227
71
 
228
- ```bash
229
- cd vscode-extension
230
- npm install && npm run build
231
- # Press F5 to launch Extension Development Host
232
- ```
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).
233
73
 
234
- See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and code style guidelines.
74
+ ## Documentation
235
75
 
236
- ## Project Structure
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 |
237
87
 
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
- ```
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)
264
89
 
265
90
  ## Troubleshooting
266
91
 
267
- **"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`.
268
95
 
269
- **"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login` to authenticate.
96
+ **"GitHub auth required"** — `brew install gh && gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`).
270
97
 
271
- **"GitHub authentication required"** — Install GitHub CLI (`brew install gh && gh auth login`) or set `GITHUB_TOKEN` / `GH_TOKEN`.
98
+ **"Azure DevOps auth required"** — Set `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
272
99
 
273
100
  ## License
274
101