WellDunDun · WellDunDun · Feb 23, 2026 · Feb 23, 2026 · Feb 23, 2026 · Feb 23, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -12,6 +12,10 @@
 - [ ] `bun src/index.ts audit ../..` score maintained or improved
 - [ ] No new external dependencies added
 
+## Merge Readiness
+
+- [ ] All PR conversations are resolved (GitHub review threads, CodeRabbit threads, and agent comments when applicable)
+
 ## Audit Impact
 
 <!-- If this changes audit scoring, note the before/after. -->
diff --git a/AGENTS.md b/AGENTS.md
@@ -4,6 +4,15 @@
 
 reins — Open-source CLI that operationalizes harness engineering. Scaffold, audit, evolve, and doctor any project's agent-readiness. Zero dependencies, Bun-powered.
 
+## Product Model (Must Keep Clear)
+
+- `cli/reins` is the product engine. It is the only source of truth for readiness scoring and JSON outputs.
+- `skill/Reins` is the control-plane wrapper for coding agents. It decides when/how to call CLI commands and how to parse results.
+- Humans steer outcomes. Agents execute the loop using Reins outputs.
+- Reins exists to transfer proven harness patterns into any repo so agents can become more autonomous and consistent over time.
+
+When updating docs or workflows, preserve this separation explicitly. Do not duplicate scoring logic in the skill layer.
+
 ## Architecture
 
 See ARCHITECTURE.md for domain map, module structure, and dependency rules.
@@ -14,6 +23,9 @@ See ARCHITECTURE.md for domain map, module structure, and dependency rules.
 |-------|----------|--------|
 | Architecture | ARCHITECTURE.md | Current |
 | CLI Source | cli/reins/src/index.ts | Current |
+| CLI Modules | cli/reins/src/lib/ | Current |
+| CLI Commands | cli/reins/src/lib/commands/ | Current |
+| Audit Engine | cli/reins/src/lib/audit/ | Current |
 | CLI Tests | cli/reins/src/index.test.ts | Current |
 | Claude Skill | skill/Reins/SKILL.md | Current |
 | Harness Methodology | skill/Reins/HarnessMethodology.md | Current |
@@ -35,20 +47,22 @@ See ARCHITECTURE.md for domain map, module structure, and dependency rules.
 
 1. Receive task via prompt
 2. Read this file, then follow pointers to relevant docs
-3. All CLI logic lives in `cli/reins/src/index.ts` (single-file design)
+3. Keep CLI command routing in `cli/reins/src/index.ts`; put reusable internals in `cli/reins/src/lib/` (especially `lib/commands/` and `lib/audit/`)
 4. Run tests: `cd cli/reins && bun test`
 5. Self-audit: `cd cli/reins && bun src/index.ts audit ../..`
 6. Self-review changes for correctness and style
 7. Open PR with concise summary
+8. Resolve all PR conversations/comments before merge (GitHub review threads, CodeRabbit threads, and agent comments when applicable)
 
 ## Key Constraints
 
 - Zero external runtime dependencies — stdlib only (fs, path)
-- Single-file CLI at `cli/reins/src/index.ts`
+- Single entrypoint CLI at `cli/reins/src/index.ts` with shared internals in `cli/reins/src/lib/`
 - All commands output deterministic JSON
 - Tests are co-located (`index.test.ts` next to `index.ts`)
 - All knowledge lives in-repo, not in external tools
 - Bun is the runtime; Node.js/tsx fallback via `bin/reins.cjs`
+- Merge discipline: treat unresolved PR conversations as a hard block when branch protection requires conversation resolution
 
 ## Golden Principles
 

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -10,29 +10,40 @@
 
 ## Module Structure
 
-reins is a single-file CLI tool. The architecture is function-based, not layered.
+reins uses a single CLI entrypoint with modular internals.
 
 ```
-cli/reins/src/index.ts
-  |
-  +-- Types (interfaces: AuditScore, AuditResult, InitOptions, EvolutionStep, EvolutionPath)
-  +-- Templates (agentsMdTemplate, architectureMdTemplate, goldenPrinciplesTemplate, ...)
-  +-- Commands (init, runAudit, audit, doctor, evolve)
-  +-- CLI Router (main, printHelp, flag parsing)
+cli/reins/src/
+  index.ts                 # CLI router + command orchestration
+  index.test.ts            # End-to-end command tests
+  lib/
+    commands/
+      init.ts              # init command handler
+      audit.ts             # audit scoring + command output
+      doctor.ts            # doctor checks + command output
+      evolve.ts            # evolve command handler
+    audit/
+      context.ts           # audit runtime context and repo signal collection
+      scoring.ts           # scoring functions and maturity resolution
+    types.ts               # Shared CLI domain types
+    templates.ts           # Scaffold/templates for docs/scripts/workflows
+    filesystem.ts          # Safe file walking and discovery helpers
+    detection.ts           # Workflow/CLI/monorepo signal detection
+    automation-pack.ts     # Pack normalization/recommendation/scaffolding
+    scoring-utils.ts       # Shared scoring helpers
 ```
 
 ### Dependency Direction
 
-Forward-only within the file:
+Forward-only between modules:
 
 ```
-Types → Templates → Commands → CLI Router
+lib/helpers + lib/commands → index.ts router → CLI output
 ```
 
-- Types are pure interfaces, no imports
-- Templates depend on nothing (return strings)
-- Commands import Types, call Templates, use fs/path
-- CLI Router calls Commands based on argv
+- `lib/*` modules are reusable helpers with narrow responsibilities
+- `lib/commands/*` own command semantics and JSON response contracts
+- `index.ts` focuses on argument parsing and routing only
 
 ### Skill Structure
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,29 +1,5 @@
 # CLAUDE.md
 
-## Project
+Canonical project instructions live in `AGENTS.md`.
 
-reins — Harness Engineering CLI. Scaffold, audit, evolve, and doctor agent-readiness for any project.
-
-## Quick Start
-
-```bash
-cd cli/reins
-bun install
-bun test                        # Run tests
-bun src/index.ts audit ../..    # Self-audit
-```
-
-## Key Files
-
-- `cli/reins/src/index.ts` — All CLI logic (single file)
-- `cli/reins/src/index.test.ts` — Test suite (36 tests)
-- `AGENTS.md` — Repository map (start here)
-- `ARCHITECTURE.md` — Domain map and structure
-
-## Rules
-
-- Zero external runtime dependencies
-- All commands output deterministic JSON
-- Tests co-located with source
-- Run `bun test` before committing
-- Self-audit with `bun src/index.ts audit ../..` to verify score
+If `CLAUDE.md` and `AGENTS.md` ever differ, follow `AGENTS.md`.
diff --git a/README.md b/README.md
@@ -12,6 +12,22 @@ The open-source toolkit for [Harness Engineering](https://openai.com/index/harne
 
 OpenAI published the methodology. We built the tooling.
 
+## Why Reins exists
+
+Reins came from real project pressure: as the harness improved, coding agents became more autonomous, consistent, and reliable. The problem was portability. Those gains were trapped in one repo.
+
+Reins packages the same approach so you can apply it to any project: scaffold the harness, score readiness, diagnose gaps, and iteratively evolve toward stronger agent autonomy.
+
+## The model (for humans and agents)
+
+| Layer | Role | Source of truth |
+|------|------|-----------------|
+| **Skill** | Control plane. Teaches the agent *when* to run Reins and *how* to interpret output. | `skill/Reins/SKILL.md` |
+| **CLI** | Execution plane. Produces deterministic JSON for `init`, `audit`, `doctor`, `evolve`. | `cli/reins/src/lib/commands/` (+ routed via `cli/reins/src/index.ts`) |
+| **Human** | Steering plane. Sets goals, accepts tradeoffs, and decides product/taste direction. | Prompts + repo decisions |
+
+If this split is unclear, agents drift: they either skip Reins or use it incorrectly. Reins is designed so agents can repeatedly improve repo quality with explicit, machine-readable feedback loops.
+
 ## Quick start
 
 **1. Install the skill** so your agent knows how to use Reins:
@@ -36,7 +52,8 @@ Agent: runs audit, identifies current level, executes the evolution path
 **2. Or run the CLI directly** for a quick score without the skill:
 
 ```bash
-npx reins-cli audit .
+# "." means "current directory"
+npx reins-cli@latest audit .
 ```
 
 ```json
@@ -52,6 +69,26 @@ npx reins-cli audit .
 }
 ```
 
+## Keep Reins fresh
+
+```bash
+# Check whether your installed skills are outdated
+npx skills check
+
+# Update installed skills (including Reins) when updates are available
+npx skills update
+```
+
+If you run Reins directly (without the skill), prefer `npx reins-cli@latest ...` so agents always use the latest published CLI.
+
+## The steering loop
+
+```text
+Install/refresh skill -> Audit -> Doctor/Evolve -> Apply changes -> Re-audit
+```
+
+That loop is the product: repeatedly steering agents toward a better repository state.
+
 ## Why teams adopt Reins
 
 Most agent rollouts fail for one boring reason: agents can edit code, but the repository doesn't teach them how to reason safely.
@@ -118,6 +155,8 @@ graph LR
 
 ```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-18)
 reins evolve .         # Roadmap to next maturity level
 reins doctor .         # Health check with prescriptive fixes
@@ -170,6 +209,25 @@ docs/
   generated/                     # Auto-generated docs (schema, API specs)
 ```
 
+Optional pack:
+
+```bash
+reins init . --pack auto
+reins init . --pack agent-factory
+```
+
+`--pack auto` keeps base scaffold for unknown stacks and selects `agent-factory` when the repo looks Node/JS compatible.
+
+`--pack agent-factory` adds an advanced automation layer:
+- `scripts/lint-structure.mjs` (hard structural gate)
+- `scripts/doc-gardener.mjs` + `scripts/check-changed-doc-freshness.mjs` (docs freshness loop)
+- `scripts/pr-review.mjs` (soft golden-principles reviewer)
+- `.github/workflows/risk-policy-gate.yml` (risk-tier + docs drift checks)
+- `.github/workflows/pr-review-bot.yml` (PR feedback loop)
+- `.github/workflows/structural-lint.yml` (CI enforcement gate)
+
+`reins evolve` now includes pack recommendations and `reins evolve . --apply` can scaffold compatible pack automation into an existing repo.
+
 ## The six audit dimensions
 
 Each scored 0-3, totaling 0-18:
@@ -230,7 +288,9 @@ For CLI repositories, Reins treats strong diagnosability signals (for example `d
 ```
 reins/
   cli/reins/            # The CLI tool (Bun + TypeScript, zero deps)
-    src/index.ts        # Single-file CLI
+    src/index.ts        # Thin CLI router
+    src/lib/commands/   # Command handlers (init/audit/doctor/evolve)
+    src/lib/audit/      # Audit runtime context + scoring internals
     package.json
   skill/                # Agent skill (Claude Code)
     Reins/

diff --git a/cli/reins/README.md b/cli/reins/README.md
@@ -2,6 +2,18 @@
 
 Scaffold, audit, and evolve projects using the [Harness Engineering](https://openai.com/index/harness-engineering/) methodology.
 
+## Relationship to the Reins skill
+
+- `reins-cli` is the execution engine (deterministic JSON commands).
+- The Reins skill is the control plane that teaches coding agents when/how to call this CLI.
+- Human operators steer intent; agents execute with Reins command outputs.
+
+For end-user agent workflows, install the skill first:
+
+```bash
+npx skills add WellDunDun/reins
+```
+
 ## What is Harness Engineering?
 
 A development methodology where **humans steer and agents execute**. All code — application logic, tests, CI, docs, tooling — is written by AI agents. Humans design environments, specify intent, and build feedback loops.
@@ -11,7 +23,7 @@ A development methodology where **humans steer and agents execute**. All code
 ```bash
 # From npm
 # "." means "current directory"
-npx reins-cli audit .
+npx reins-cli@latest audit .
 
 # Or clone and link
 git clone https://github.com/WellDunDun/reins.git
@@ -32,6 +44,8 @@ Scaffold the full harness engineering structure in a directory:
 reins init .
 reins init ./my-project --name "My Project"
 reins init . --force  # Overwrite existing files
+reins init . --pack auto  # Adaptive pack selection from project signals
+reins init . --pack agent-factory  # Optional advanced automation pack
 ```
 
 Creates:
@@ -45,6 +59,12 @@ Creates:
 - `docs/references/` — External LLM-friendly reference docs
 - `docs/generated/` — Auto-generated documentation
 
+Pack modes:
+- `--pack auto` selects a compatible pack when stack signals are clear, otherwise keeps base scaffold.
+- `--pack agent-factory` explicitly scaffolds advanced automation:
+- `scripts/lint-structure.mjs`, `scripts/doc-gardener.mjs`, `scripts/check-changed-doc-freshness.mjs`, `scripts/pr-review.mjs`
+- `.github/workflows/risk-policy-gate.yml`, `.github/workflows/pr-review-bot.yml`, `.github/workflows/structural-lint.yml`
+
 ### `reins audit <path>`
 
 Score a project against harness engineering principles (0-18):

diff --git a/cli/reins/package.json b/cli/reins/package.json
@@ -1,6 +1,6 @@
 {
   "name": "reins-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Scaffold, audit, and evolve projects using the Harness Engineering methodology",
   "type": "module",
   "license": "MIT",