@microsoft/agentrc 2.0.1-1 → 2.0.1-100

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,131 @@
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
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.
20
16
 
21
17
  ```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
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
- ```
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 22+.
90
22
 
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.
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
118
-
119
- Measure how instructions improve AI responses with a judge model:
120
-
121
- ```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%
126
- ```
35
+ ### Generate
127
36
 
128
- ### `agentrc generate` — Generate Configs
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.
129
38
 
130
39
  ```bash
131
- agentrc generate mcp # .vscode/mcp.json
132
- agentrc generate vscode --force # .vscode/settings.json (overwrite)
40
+ npx github:microsoft/agentrc instructions
133
41
  ```
134
42
 
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
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.
51
+ ## AgentRC maintains itself with GitHub Agentic Workflows
154
52
 
155
- ### Global Options
53
+ This repository dogfoods [GitHub Agentic Workflows](https://github.github.com/gh-aw/) for recurring maintenance and demos:
156
54
 
157
- All commands support `--json` (structured JSON to stdout) and `--quiet` (suppress stderr). JSON output uses a `CommandResult<T>` envelope:
55
+ | Workflow | Purpose | Output |
56
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------ |
57
+ | [AgentRC Readiness Report](.github/workflows/agentrc-readiness-report.md) | Runs AgentRC against this repository and explains the highest-impact gaps | One short-lived issue |
58
+ | [AgentRC Readiness Upgrade](.github/workflows/agentrc-readiness-upgrade.md) | Improves one evidence-backed instruction and verifies the result | One draft PR |
59
+ | [Issue Triage](.github/workflows/issue-triage.md) | Classifies new issues and asks for missing information | Bounded labels and one comment |
60
+ | [CI Failure Doctor](.github/workflows/ci-doctor.md) | Diagnoses failed CI from logs and repository changes | One issue or one comment |
158
61
 
159
- ```json
160
- { "ok": true, "status": "success", "data": { ... } }
161
- ```
62
+ The source workflows are Markdown. `gh aw compile` generates the reviewable `.lock.yml` workflows that GitHub Actions executes. CI fails when those generated files drift.
162
63
 
163
- ### Readiness Policies
64
+ See [Agentic Workflows](docs/agentic-workflows.md) for the architecture and maintenance commands. Use the [golden demo runbook](docs/agentic-workflows-demo.md) for the lone-maintainer narrative, exact stage flow, and fallback plan.
164
65
 
165
- Policies customize scoring criteria, override metadata, and tune thresholds:
66
+ ## Works at every scale
166
67
 
167
- ```bash
168
- agentrc readiness --policy ./examples/policies/strict.json
169
- agentrc readiness --policy ./examples/policies/strict.json,./my-overrides.json # chain multiple
170
- ```
68
+ | Workflow | Command |
69
+ | ------------------------- | ----------------------------------------- |
70
+ | Interactive hub | `agentrc` |
71
+ | One-time setup | `agentrc init` |
72
+ | CI quality gate | `agentrc readiness --fail-level 3 --json` |
73
+ | Batch across an org | `agentrc batch` |
74
+ | Automated PR for any repo | `agentrc pr owner/repo` |
171
75
 
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
- ```
76
+ Works with **GitHub** and **Azure DevOps**. Supports monorepos, multi-root VS Code workspaces, and custom [policies](docs/policies.md).
183
77
 
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
- ```
78
+ ## What gets generated
206
79
 
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.
80
+ | File | Purpose |
81
+ | --------------------------------- | ------------------------------------------ |
82
+ | `.github/copilot-instructions.md` | Teaches AI agents your repo's conventions |
83
+ | `.vscode/mcp.json` | Connects AI to your stack's tools and data |
84
+ | `.vscode/settings.json` | Tunes VS Code for AI-assisted development |
85
+ | `agentrc.eval.json` | Test cases to measure instruction quality |
210
86
 
211
- > **Security:** Config-sourced policies are restricted to JSON files only — JS/TS module policies must be passed via `--policy`.
87
+ > 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).
212
88
 
213
- See [docs/plugins.md](docs/plugins.md) for the full plugin authoring guide, including imperative TypeScript plugins, lifecycle hooks, and the trust model.
89
+ ## Works with APM
214
90
 
215
- ## Development
91
+ [APM](https://github.com/microsoft/apm) (Agent Package Manager) distributes agent instructions, skills, and prompts across repos — like npm for AI agent configs.
216
92
 
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
- ```
93
+ AgentRC generates the content. APM distributes it:
225
94
 
226
- ### VS Code Extension
95
+ - **In your project** — run `agentrc init` to generate instructions, then `apm install org/standards` to pull in shared agent packages from your team
96
+ - **For your team** — create a dedicated APM package with your best instructions and skills, then teammates install it with `apm install`
97
+ - **At scale** — `apm audit` scans for security issues; `apm-policy.yml` enforces org standards across all repos
227
98
 
228
- ```bash
229
- cd vscode-extension
230
- npm install && npm run build
231
- # Press F5 to launch Extension Development Host
232
- ```
99
+ The `.instructions.md` format is shared by both tools — no conversion needed when moving instructions into APM packages.
233
100
 
234
- See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and code style guidelines.
101
+ ## Documentation
235
102
 
236
- ## Project Structure
103
+ | | |
104
+ | -------------------------------------------------- | ------------------------------------------------------- |
105
+ | **[Getting Started](docs/getting-started.md)** | Prerequisites and first run |
106
+ | **[Concepts](docs/concepts.md)** | Maturity model, readiness pillars, how generation works |
107
+ | **[Commands](docs/commands.md)** | Full CLI reference |
108
+ | **[Configuration](docs/configuration.md)** | Areas, workspaces, monorepos |
109
+ | **[Policies](docs/policies.md)** | Custom readiness scoring |
110
+ | **[At Scale](docs/at-scale.md)** | Batch processing across orgs |
111
+ | **[CI Integration](docs/ci-integration.md)** | GitHub Actions & Azure Pipelines |
112
+ | **[VS Code Extension](docs/extension.md)** | Sidebar views, commands, settings |
113
+ | **[Agent Plugin](plugin/README.md)** | Install as a Copilot agent plugin with built-in skills |
114
+ | **[Agentic Workflows](docs/agentic-workflows.md)** | Dogfooding, maintenance, and live demo guide |
115
+ | **[Golden Demo](docs/agentic-workflows-demo.md)** | Lone-maintainer story and stage-ready runbook |
116
+ | **[Examples](examples/)** | Configs, evals, and policies |
237
117
 
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
- ```
118
+ [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
119
 
265
120
  ## Troubleshooting
266
121
 
267
- **"Copilot CLI not found"** — Install the GitHub Copilot Chat extension in VS Code. The CLI is bundled with it.
122
+ **"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.
123
+
124
+ **"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login`.
268
125
 
269
- **"Copilot CLI not logged in"** — Run `copilot` in your terminal, then `/login` to authenticate.
126
+ **"GitHub auth required"** — `brew install gh && gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`).
270
127
 
271
- **"GitHub authentication required"** — Install GitHub CLI (`brew install gh && gh auth login`) or set `GITHUB_TOKEN` / `GH_TOKEN`.
128
+ **"Azure DevOps auth required"** — Set `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
272
129
 
273
130
  ## License
274
131