Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 23 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ npx reins-cli@latest audit .
```json
{
"total_score": 6,
"max_score": 22,
"max_score": 24,
"maturity_level": "L1: Inloop",
"recommendations": [
"Create ARCHITECTURE.md with domain map and layer rules",
Expand Down Expand Up @@ -95,7 +95,7 @@ Most agent rollouts fail for one boring reason: agents can edit code, but the re

Reins gives you a repeatable operating system for agent work:
- **A map** (`AGENTS.md`, architecture docs, indexed decisions)
- **A score** (0-22 maturity audit with concrete gaps)
- **A score** (0-24 maturity audit with concrete gaps)
- **A plan** (next-step evolution path by maturity level)
- **A guardrail model** (`risk-policy.json` + CI enforcement signals)

Expand Down Expand Up @@ -138,28 +138,31 @@ block-beta

**Use them together.** Reins scaffolds your repo so `AGENTS.md` tells the agent where everything is, `ARCHITECTURE.md` defines the rules, and golden principles are enforced in CI. Then a session orchestrator runs the actual coding work on top of that well-structured repo.

## The four commands
## The five commands

```mermaid
graph LR
Init["reins init\nScaffold"] --> Audit["reins audit\nScore 0-22"]
Init["reins init\nScaffold"] --> Audit["reins audit\nScore 0-24"]
Audit --> Evolve["reins evolve\nLevel up"]
Evolve --> Doctor["reins doctor\nHealth check"]
Doctor --> Audit
Audit --> Compare["reins compare\nBaseline diff"]

style Init fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
style Audit fill:#1e3a5f,stroke:#60a5fa,color:#e2e8f0
style Evolve fill:#1e3a5f,stroke:#818cf8,color:#e2e8f0
style Doctor fill:#1e3a5f,stroke:#a78bfa,color:#e2e8f0
style Compare fill:#1e3a5f,stroke:#c084fc,color:#e2e8f0
```

```bash
reins init . # Scaffold the full structure
reins init . --pack auto # Adaptive pack selection from project signals
reins init . --pack agent-factory # Optional advanced automation pack
reins audit . # Score against harness principles (0-22)
reins audit . # Score against harness principles (0-24)
reins evolve . # Roadmap to next maturity level
reins doctor . # Health check with prescriptive fixes
reins compare <path> <baseline.json> # Compare current audit against a baseline
```

## The maturity model
Expand All @@ -168,10 +171,10 @@ Every repo sits on a maturity spectrum. The audit tells you where you are. The e

```mermaid
graph LR
L0["L0: Manual\n0-5"] --> L1["L1: Inloop\n6-11"]
L1 --> L2["L2: Guided Outloop\n12-16"]
L2 --> L3["L3: Full Outloop\n17-19"]
L3 --> L4["L4: Zero Touch\n20-22"]
L0["L0: Manual\n0-6"] --> L1["L1: Inloop\n7-12"]
L1 --> L2["L2: Guided Outloop\n13-18"]
L2 --> L3["L3: Full Outloop\n19-21"]
L3 --> L4["L4: Zero Touch\n22-24"]

style L0 fill:#1e293b,stroke:#475569,color:#94a3b8
style L1 fill:#1e293b,stroke:#3b82f6,color:#93c5fd
Expand All @@ -182,11 +185,11 @@ graph LR

| Score | Level | What it means |
|-------|-------|---------------|
| 0-5 | **L0: Manual** | Traditional engineering, no agent infra |
| 6-11 | **L1: Inloop** | Agents help, humans still write code |
| 12-16 | **L2: Guided Outloop** | Humans steer, agents execute most code |
| 17-19 | **L3: Full Outloop** | Agents handle full lifecycle |
| 20-22 | **L4: Zero Touch** | System maintains and improves itself |
| 0-6 | **L0: Manual** | Traditional engineering, no agent infra |
| 7-12 | **L1: Inloop** | Agents help, humans still write code |
| 13-18 | **L2: Guided Outloop** | Humans steer, agents execute most code |
| 19-21 | **L3: Full Outloop** | Agents handle full lifecycle |
| 22-24 | **L4: Zero Touch** | System maintains and improves itself |

## What `reins init` scaffolds

Expand Down Expand Up @@ -232,16 +235,16 @@ reins init . --pack agent-factory

## The six audit dimensions

Scored across six dimensions, totaling 0-22:
Scored across six dimensions, totaling 0-24:

```mermaid
graph TD
Score["Total Score\n0-22"]
Score["Total Score\n0-24"]
RK["Repository Knowledge\n0-4"]
AE["Architecture Enforcement\n0-3"]
AL["Agent Legibility\n0-4"]
AL["Agent Legibility\n0-5"]
GP["Golden Principles\n0-3"]
AW["Agent Workflow\n0-5"]
AW["Agent Workflow\n0-6"]
GC["Garbage Collection\n0-3"]

RK --> Score
Expand Down Expand Up @@ -269,14 +272,14 @@ graph TD
| **Agent Workflow** | Agent config, risk policy, PR templates, CI enforcement, orchestration readiness |
| **Garbage Collection** | Debt tracking, doc-gardening, quality grades, docs drift rules |

## Self-audit: 19/22
## Self-audit: 19/24

Reins audits itself in CI. Current score:

```json
{
"total_score": 19,
"max_score": 22,
"max_score": 24,
"maturity_level": "L3: Full Outloop"
}
```
Expand Down
30 changes: 21 additions & 9 deletions cli/reins/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,26 +67,26 @@ Pack modes:

### `reins audit <path>`

Score a project against harness engineering principles (0-22):
Score a project against harness engineering principles (0-24):

```bash
reins audit .
```

Scores six dimensions (variable max per dimension, 22 total):
Scores six dimensions (variable max per dimension, 24 total):
1. **Repository Knowledge** (0-4) — AGENTS.md, docs/, versioned plans
2. **Architecture Enforcement** (0-3) — ARCHITECTURE.md, dependency rules, linters
3. **Agent Legibility** (0-4) — Bootable app, observability, lean dependencies
3. **Agent Legibility** (0-5) — Bootable app, observability, lean dependencies
4. **Golden Principles** (0-3) — Documented rules, CI enforcement, cleanup process
5. **Agent Workflow** (0-5) — Agent config, PR templates, merge gates, orchestration readiness
5. **Agent Workflow** (0-6) — Agent config, PR templates, merge gates, orchestration readiness
6. **Garbage Collection** (0-3) — Debt tracking, doc-gardening, quality grades

Returns a maturity level:
- **L0: Manual** (0-5) — Traditional engineering
- **L1: Inloop** (6-11) — Agents help, humans still code
- **L2: Guided Outloop** (12-16) — Humans steer, agents execute
- **L3: Full Outloop** (17-19) — Agents handle full lifecycle
- **L4: Zero Touch** (20-22) — System maintains itself
- **L0: Manual** (0-6) — Traditional engineering
- **L1: Inloop** (7-12) — Agents help, humans still code
- **L2: Guided Outloop** (13-18) — Humans steer, agents execute
- **L3: Full Outloop** (19-21) — Agents handle full lifecycle
- **L4: Zero Touch** (22-24) — System maintains itself

### `reins evolve <path>`

Expand All @@ -109,6 +109,18 @@ reins doctor .

Returns pass/fail/warn for each check with specific fix instructions.

### `reins compare <path> <baseline.json>`

Compare the current audit score against a saved baseline:

```bash
reins audit . > baseline.json
# ... make changes ...
reins compare . baseline.json
```

Returns a dimension-by-dimension diff showing score deltas and maturity level changes, useful for tracking progress over time or validating that a set of changes improved readiness.

## Output

All commands output deterministic JSON, making them composable with other tools:
Expand Down
5 changes: 3 additions & 2 deletions cli/reins/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "reins-cli",
"version": "0.1.4",
"version": "0.1.5",
"description": "Scaffold, audit, and evolve projects using the Harness Engineering methodology",
"type": "module",
"license": "MIT",
Expand Down Expand Up @@ -36,7 +36,8 @@
],
"scripts": {
"start": "bun src/index.ts",
"test": "bun test"
"test": "bun test",
"typecheck": "tsc --noEmit"
},
"devDependencies": {
"@types/bun": "latest"
Expand Down
173 changes: 171 additions & 2 deletions cli/reins/src/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ describe("reins audit", () => {

const result = JSON.parse(stdout);
expect(result.total_score).toBe(0);
expect(result.max_score).toBe(22);
expect(result.max_score).toBe(24);
expect(result.maturity_level).toBe("L0: Manual");
expect(result.scores.repository_knowledge.score).toBe(0);
expect(result.scores.architecture_enforcement.score).toBe(0);
Expand Down Expand Up @@ -268,7 +268,7 @@ describe("reins audit", () => {
expect(result).toHaveProperty("max_score");
expect(result).toHaveProperty("maturity_level");
expect(result).toHaveProperty("recommendations");
expect(result.max_score).toBe(22);
expect(result.max_score).toBe(24);
});

test("fails on nonexistent directory", async () => {
Expand Down Expand Up @@ -1056,3 +1056,172 @@ describe("docs contract — skill/cli/human model clarity", () => {
expect(cliReadme).toContain("npx skills add WellDunDun/reins");
});
});

// ─── Compare Command ─────────────────────────────────────────────────────────

describe("reins compare", () => {
test("outputs score deltas against a baseline", async () => {
const dir = tmpDir("compare-basic");
await runCli(`init ${dir}`);

// Save a baseline
const { stdout: baselineJson } = await runCli(`audit ${dir}`);
const baselinePath = join(dir, "baseline.json");
writeFileSync(baselinePath, baselineJson);

// Add linter to change score
writeFileSync(join(dir, "biome.json"), "{}");

const { stdout, exitCode } = await runCli(`compare ${dir} ${baselinePath}`);
expect(exitCode).toBe(0);

const result = JSON.parse(stdout);
expect(result.command).toBe("compare");
expect(result.score_delta).toBeGreaterThanOrEqual(0);
expect(result.dimensions).toBeInstanceOf(Array);
expect(result.dimensions.length).toBe(6);
expect(result.dimensions[0]).toHaveProperty("dimension");
expect(result.dimensions[0]).toHaveProperty("delta");
});

test("shows maturity level change", async () => {
const dir = tmpDir("compare-level");

// Baseline with empty dir (L0)
const { stdout: baselineJson } = await runCli(`audit ${dir}`);
const baselinePath = join(dir, "baseline.json");
writeFileSync(baselinePath, baselineJson);

// Scaffold to raise score
await runCli(`init ${dir} --force`);

const { stdout } = await runCli(`compare ${dir} ${baselinePath}`);
const result = JSON.parse(stdout);

expect(result.before_level).toBe("L0: Manual");
expect(result.level_changed).toBe(true);
});

test("fails with missing baseline", async () => {
const dir = tmpDir("compare-missing");
const { stderr, exitCode } = await runCli(`compare ${dir} ${dir}/nonexistent.json`);
expect(exitCode).toBe(1);
expect(stderr).toContain("Baseline file not found");
});

test("fails without baseline argument", async () => {
const dir = tmpDir("compare-no-arg");
const { stderr, exitCode } = await runCli(`compare ${dir}`);
expect(exitCode).toBe(1);
expect(stderr).toContain("Missing baseline file");
});
});

// ─── MCP Tool Proliferation ─────────────────────────────────────────────────

describe("MCP tool proliferation detection", () => {
test("warns when more than 10 MCP servers configured", async () => {
const dir = tmpDir("mcp-proliferation");
mkdirSync(join(dir, ".claude"), { recursive: true });
const servers: Record<string, unknown> = {};
for (let i = 0; i < 12; i++) {
servers[`tool-${i}`] = { command: "echo" };
}
writeFileSync(join(dir, ".claude", "mcp.json"), JSON.stringify({ mcpServers: servers }));

const { stdout } = await runCli(`audit ${dir}`);
const result = JSON.parse(stdout);

expect(result.scores.agent_workflow.findings).toEqual(
expect.arrayContaining([expect.stringContaining("proliferation warning: 12 servers")]),
);
});

test("reports healthy tool count when under 10", async () => {
const dir = tmpDir("mcp-healthy");
mkdirSync(join(dir, ".claude"), { recursive: true });
writeFileSync(
join(dir, ".claude", "mcp.json"),
JSON.stringify({ mcpServers: { tool1: {}, tool2: {}, tool3: {} } }),
);

const { stdout } = await runCli(`audit ${dir}`);
const result = JSON.parse(stdout);

expect(result.scores.agent_workflow.findings).toEqual(
expect.arrayContaining([expect.stringContaining("MCP tools configured: 3 servers (healthy)")]),
);
});
});

// ─── Custom Checks Plugin ───────────────────────────────────────────────────

describe("custom checks plugin", () => {
test("file-exists check appears in audit findings", async () => {
const dir = tmpDir("custom-file-exists");
mkdirSync(join(dir, ".reins"), { recursive: true });
writeFileSync(join(dir, "SECURITY.md"), "# Security policy");
writeFileSync(
join(dir, ".reins", "custom-checks.json"),
JSON.stringify({
checks: [
{ name: "Security policy", type: "file-exists", path: "SECURITY.md", dimension: "repository_knowledge" },
],
}),
);

const { stdout } = await runCli(`audit ${dir}`);
const result = JSON.parse(stdout);

expect(result.scores.repository_knowledge.findings).toEqual(
expect.arrayContaining([expect.stringContaining("[custom] Security policy: SECURITY.md exists")]),
);
});

test("file-exists check reports missing file", async () => {
const dir = tmpDir("custom-file-missing");
mkdirSync(join(dir, ".reins"), { recursive: true });
writeFileSync(
join(dir, ".reins", "custom-checks.json"),
JSON.stringify({
checks: [
{ name: "Missing file", type: "file-exists", path: "NOPE.md", dimension: "repository_knowledge" },
],
}),
);

const { stdout } = await runCli(`audit ${dir}`);
const result = JSON.parse(stdout);

expect(result.scores.repository_knowledge.findings).toEqual(
expect.arrayContaining([expect.stringContaining("[custom] Missing file: NOPE.md missing")]),
);
});

test("file-contains check matches pattern", async () => {
const dir = tmpDir("custom-contains");
mkdirSync(join(dir, ".reins"), { recursive: true });
writeFileSync(join(dir, "README.md"), "# My Project\n\nThis project uses TypeScript.");
writeFileSync(
join(dir, ".reins", "custom-checks.json"),
JSON.stringify({
checks: [
{
name: "TypeScript mentioned",
type: "file-contains",
path: "README.md",
pattern: "TypeScript",
dimension: "agent_legibility",
},
],
}),
);

const { stdout } = await runCli(`audit ${dir}`);
const result = JSON.parse(stdout);

expect(result.scores.agent_legibility.findings).toEqual(
expect.arrayContaining([expect.stringContaining("[custom] TypeScript mentioned: pattern found")]),
);
});
});
Loading
Loading