@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 CHANGED
@@ -1,283 +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 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 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` — 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.
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
- ### `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:**
23
+ ![AgentRC — Measure, Generate, Maintain cycle](docs/assets/agentrc-overview.png)
119
24
 
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)
25
+ ## What it does
123
26
 
124
- ### `agentrc eval` — Evaluate Instructions
27
+ ### Measure
125
28
 
126
- 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.
127
30
 
128
31
  ```bash
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%
32
+ npx github:microsoft/agentrc readiness
133
33
  ```
134
34
 
135
- ### `agentrc generate` — Generate Configs
35
+ ### Generate
136
36
 
137
- > **Note:** `generate instructions` and `generate agents` are deprecated — use `agentrc instructions` directly.
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 generate mcp # .vscode/mcp.json
141
- agentrc generate vscode --force # .vscode/settings.json (overwrite)
40
+ npx github:microsoft/agentrc instructions
142
41
  ```
143
42
 
144
- ### `agentrc batch` / `agentrc pr` — Batch & PRs
43
+ ### Maintain
145
44
 
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
- ```
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 tui
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
- ### Readiness Policies
51
+ ## Works at every scale
173
52
 
174
- Policies customize scoring criteria, override metadata, and tune thresholds:
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
- ```bash
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
- ```json
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
- - **`areas`** — standalone areas with glob patterns (relative to repo root)
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.
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
- > **Security:** Config-sourced policies are restricted to JSON files only — JS/TS module policies must be passed via `--policy`.
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
- See [docs/plugins.md](docs/plugins.md) for the full plugin authoring guide, including imperative TypeScript plugins, lifecycle hooks, and the trust model.
74
+ ## Works with APM
223
75
 
224
- ## Development
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
- ```bash
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
- ### VS Code Extension
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
- ```bash
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
- See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and code style guidelines.
86
+ ## Documentation
244
87
 
245
- ## Project Structure
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
- **"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`).
279
110
 
280
- **"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`.
281
112
 
282
113
  ## License
283
114