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
50 changes: 26 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ npx reins-cli@latest audit .
```json
{
"total_score": 6,
"max_score": 18,
"maturity_level": "L1: Assisted",
"max_score": 22,
"maturity_level": "L1: Inloop",
"recommendations": [
"Create ARCHITECTURE.md with domain map and layer rules",
"Add linter configuration to enforce architectural constraints",
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-18 maturity audit with concrete gaps)
- **A score** (0-22 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 @@ -142,7 +142,7 @@ block-beta

```mermaid
graph LR
Init["reins init\nScaffold"] --> Audit["reins audit\nScore 0-18"]
Init["reins init\nScaffold"] --> Audit["reins audit\nScore 0-22"]
Audit --> Evolve["reins evolve\nLevel up"]
Evolve --> Doctor["reins doctor\nHealth check"]
Doctor --> Audit
Expand All @@ -157,7 +157,7 @@ graph LR
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-18)
reins audit . # Score against harness principles (0-22)
reins evolve . # Roadmap to next maturity level
reins doctor . # Health check with prescriptive fixes
```
Expand All @@ -168,10 +168,10 @@ Every repo sits on a maturity spectrum. The audit tells you where you are. The e

```mermaid
graph LR
L0["L0: Manual\n0-4"] --> L1["L1: Assisted\n5-8"]
L1 --> L2["L2: Steered\n9-13"]
L2 --> L3["L3: Autonomous\n14-16"]
L3 --> L4["L4: Self-Correcting\n17-18"]
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"]

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

| Score | Level | What it means |
|-------|-------|---------------|
| 0-4 | **L0: Manual** | Traditional engineering, no agent infra |
| 5-8 | **L1: Assisted** | Agents help, humans still write code |
| 9-13 | **L2: Steered** | Humans steer, agents execute most code |
| 14-16 | **L3: Autonomous** | Agents handle full lifecycle |
| 17-18 | **L4: Self-Correcting** | System maintains and improves itself |
| 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 |

## What `reins init` scaffolds

```
AGENTS.md # Concise map (~100 lines) for agents
ARCHITECTURE.md # Domain map, layer rules, dependency direction
WORKFLOW.md # Agent workflow and orchestration config
SPEC.md # Project specification and constraints
risk-policy.json # Risk tiers + docs drift rules (policy-as-code)
docs/
golden-principles.md # Mechanical taste rules enforced in CI
Expand Down Expand Up @@ -230,16 +232,16 @@ reins init . --pack agent-factory

## The six audit dimensions

Each scored 0-3, totaling 0-18:
Scored across six dimensions, totaling 0-22:

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

RK --> Score
Expand All @@ -264,18 +266,18 @@ graph TD
| **Architecture Enforcement** | ARCHITECTURE.md, dependency rules, linters, policy signals |
| **Agent Legibility** | Bootable app, observability (or CLI diagnosability), lean dependencies |
| **Golden Principles** | Documented taste rules, CI gate depth, cleanup process |
| **Agent Workflow** | Agent config, risk policy, PR templates, CI enforcement |
| **Agent Workflow** | Agent config, risk policy, PR templates, CI enforcement, orchestration readiness |
| **Garbage Collection** | Debt tracking, doc-gardening, quality grades, docs drift rules |

## Self-apply: 18/18
## Self-audit: 19/22

Reins audits itself in CI. Current score:

```json
{
"total_score": 18,
"max_score": 18,
"maturity_level": "L4: Self-Correcting"
"total_score": 19,
"max_score": 22,
"maturity_level": "L3: Full Outloop"
}
```

Expand Down
26 changes: 13 additions & 13 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-18):
Score a project against harness engineering principles (0-22):

```bash
reins audit .
```

Scores six dimensions (0-3 each):
1. **Repository Knowledge** — AGENTS.md, docs/, versioned plans
2. **Architecture Enforcement** — ARCHITECTURE.md, dependency rules, linters
3. **Agent Legibility** — Bootable app, observability, lean dependencies
4. **Golden Principles** — Documented rules, CI enforcement, cleanup process
5. **Agent Workflow** — Agent config, PR templates, merge gates
6. **Garbage Collection** — Debt tracking, doc-gardening, quality grades
Scores six dimensions (variable max per dimension, 22 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
4. **Golden Principles** (0-3) — Documented rules, CI enforcement, cleanup process
5. **Agent Workflow** (0-5) — 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-4) — Traditional engineering
- **L1: Assisted** (5-8) — Agents help, humans still code
- **L2: Steered** (9-13) — Humans steer, agents execute
- **L3: Autonomous** (14-16) — Agents handle full lifecycle
- **L4: Self-Correcting** (17-18) — System maintains itself
- **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

### `reins evolve <path>`

Expand Down
2 changes: 1 addition & 1 deletion cli/reins/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "reins-cli",
"version": "0.1.3",
"version": "0.1.4",
"description": "Scaffold, audit, and evolve projects using the Harness Engineering methodology",
"type": "module",
"license": "MIT",
Expand Down
4 changes: 2 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(21);
expect(result.max_score).toBe(22);
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(21);
expect(result.max_score).toBe(22);
});

test("fails on nonexistent directory", async () => {
Expand Down
115 changes: 96 additions & 19 deletions cli/reins/src/lib/audit/context.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
import { existsSync, readFileSync, readdirSync } from "node:fs";
import { join } from "node:path";
import { detectCliProject, detectMonorepoWorkspaces, scanWorkflowsForEnforcement } from "../detection";
import {
checkWorkflowConfigForPattern,
checkWorkflowsForMergeProtection,
detectCliProject,
detectMonorepoWorkspaces,
scanWorkflowsForEnforcement,
} from "../detection";
import { findFiles } from "../filesystem";
import type { AuditResult } from "../types";

Expand Down Expand Up @@ -28,6 +34,13 @@ export interface AuditRuntimeContext {
hasGlobBasedRules: boolean;
hierarchicalAgentContextCount: number;
hasSkillsManifest: boolean;
hasWorkflowConfig: boolean;
hasSkillsDirectory: boolean;
hasIsolationPolicy: boolean;
hasConcurrencyLimits: boolean;
hasMergeProtection: boolean;
hasSpecDocument: boolean;
frameworksDetected: string[];
}

export function createAuditResult(projectName: string): AuditResult {
Expand All @@ -40,13 +53,14 @@ export function createAuditResult(projectName: string): AuditResult {
architecture_enforcement: { score: 0, max: 3, findings: [] },
agent_legibility: { score: 0, max: 4, findings: [] },
golden_principles: { score: 0, max: 3, findings: [] },
agent_workflow: { score: 0, max: 4, findings: [] },
agent_workflow: { score: 0, max: 5, findings: [] },
garbage_collection: { score: 0, max: 3, findings: [] },
},
total_score: 0,
max_score: 21,
max_score: 22,
maturity_level: "L0",
recommendations: [],
frameworks_detected: [],
Comment thread
WellDunDun marked this conversation as resolved.
Resolved
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
};
}

Expand All @@ -61,6 +75,54 @@ export function readVerifiedDocs(targetDir: string): string[] {
});
}

function detectAgentCommands(targetDir: string): boolean {
const commandsDir = join(targetDir, ".claude", "commands");
if (!existsSync(commandsDir)) return false;
try {
return readdirSync(commandsDir).length > 0;
} catch {
return false;
}
}

function detectNonEmptySkillsDirectory(targetDir: string): boolean {
const skillsDirPaths = [
join(targetDir, ".codex", "skills"),
join(targetDir, ".claude", "skills"),
join(targetDir, ".claude", "commands"),
join(targetDir, "skills"),
];
return skillsDirPaths.some((d) => {
if (!existsSync(d)) return false;
try {
return readdirSync(d).length > 0;
} catch {
return false;
}
});
}

function detectConcurrencyLimits(targetDir: string, hasWorkflowConfig: boolean, hasRiskPolicy: boolean): boolean {
if (hasWorkflowConfig && checkWorkflowConfigForPattern(targetDir, /max_concurrent|concurrency/i)) return true;
if (!hasRiskPolicy) return false;
try {
const content = readFileSync(join(targetDir, "risk-policy.json"), "utf-8");
return /concurrency|maxConcurrentAgents/i.test(content);
} catch {
return false;
}
}

function detectFrameworks(targetDir: string): string[] {
const detected: string[] = [];
if (existsSync(join(targetDir, ".codex")) || existsSync(join(targetDir, "WORKFLOW.md"))) detected.push("symphony");
if (existsSync(join(targetDir, "CLAUDE.md")) || existsSync(join(targetDir, ".claude"))) detected.push("claude-code");
if (existsSync(join(targetDir, ".cursor"))) detected.push("cursor");
if (existsSync(join(targetDir, "conductor.json"))) detected.push("conductor");
if (existsSync(join(targetDir, "CODEX.md"))) detected.push("codex");
return detected;
}

export function buildAuditRuntimeContext(targetDir: string): AuditRuntimeContext {
const pkgJsonPath = join(targetDir, "package.json");
const docsDir = join(targetDir, "docs");
Expand All @@ -85,16 +147,7 @@ export function buildAuditRuntimeContext(targetDir: string): AuditRuntimeContext
const isCliRepo = detectCliProject(targetDir, pkgJsonPath);
const verifiedDocs = readVerifiedDocs(targetDir);
const hasCleanupDocs = existsSync(join(targetDir, "docs", "exec-plans", "tech-debt-tracker.md"));

const commandsDir = join(targetDir, ".claude", "commands");
let hasAgentCommands = false;
if (existsSync(commandsDir)) {
try {
hasAgentCommands = readdirSync(commandsDir).length > 0;
} catch {
// ignore read errors
}
}
const hasAgentCommands = detectAgentCommands(targetDir);

const hasSessionOrchestrator =
existsSync(join(targetDir, ".flow")) ||
Expand All @@ -108,20 +161,37 @@ export function buildAuditRuntimeContext(targetDir: string): AuditRuntimeContext
existsSync(join(targetDir, "mcp.json"));

const hasGlobBasedRules =
existsSync(join(targetDir, ".cursor", "rules")) ||
existsSync(join(targetDir, ".claude", "rules"));
existsSync(join(targetDir, ".cursor", "rules")) || existsSync(join(targetDir, ".claude", "rules"));

const agentContextFiles = [
...findFiles(targetDir, /^AGENTS\.md$/, 3),
...findFiles(targetDir, /^CLAUDE\.md$/, 3),
];
const agentContextFiles = [...findFiles(targetDir, /^AGENTS\.md$/, 3), ...findFiles(targetDir, /^CLAUDE\.md$/, 3)];
const hierarchicalAgentContextCount = agentContextFiles.length;

const hasSkillsManifest =
existsSync(join(targetDir, "skills.json")) ||
existsSync(join(targetDir, ".claude", "skills")) ||
existsSync(join(targetDir, ".cursor", "extensions"));

const hasWorkflowConfig =
existsSync(join(targetDir, "WORKFLOW.md")) ||
existsSync(join(targetDir, "workflow.yml")) ||
existsSync(join(targetDir, ".codex", "WORKFLOW.md"));

const hasSkillsDirectory = detectNonEmptySkillsDirectory(targetDir);

const hasIsolationPolicy =
existsSync(join(targetDir, "sandbox.json")) ||
existsSync(join(targetDir, ".sandbox")) ||
(hasWorkflowConfig && checkWorkflowConfigForPattern(targetDir, /sandbox|isolat|workspace.*root/i));

const hasConcurrencyLimits = detectConcurrencyLimits(targetDir, hasWorkflowConfig, hasRiskPolicy);

const hasMergeProtection =
existsSync(join(targetDir, ".github", "CODEOWNERS")) ||
existsSync(join(targetDir, "CODEOWNERS")) ||
checkWorkflowsForMergeProtection(workflowDir);

const hasSpecDocument = existsSync(join(targetDir, "SPEC.md")) || existsSync(join(targetDir, "spec.md"));

return {
targetDir,
pkgJsonPath,
Expand All @@ -146,5 +216,12 @@ export function buildAuditRuntimeContext(targetDir: string): AuditRuntimeContext
hasGlobBasedRules,
hierarchicalAgentContextCount,
hasSkillsManifest,
hasWorkflowConfig,
hasSkillsDirectory,
hasIsolationPolicy,
hasConcurrencyLimits,
hasMergeProtection,
hasSpecDocument,
frameworksDetected: detectFrameworks(targetDir),
};
}
Loading