@aerem/ai-harness

Claude Code extension for autonomous feature delivery — a CLI plus a pair of slash-command plugins that scaffold project state, drive a 13-phase feature pipeline, introspect brownfield repos, and orchestrate polyrepo workspaces.

Install

# 1. Install the CLI globally
npm install -g @aerem/ai-harness
# or:  pnpm add -g @aerem/ai-harness
# or:  yarn global add @aerem/ai-harness

# 2. Register the Claude Code slash commands (one-time, per machine)
aerem-ai-harness setup

After step 2, /harness:* and /aerem:* slash commands resolve in any Claude Code session.

Quick start

# Scaffold the harness into a project
cd my-project
aerem-ai-harness init                # auto-detects greenfield vs brownfield
                                      # — brownfield: also runs deep introspection
                                      #   + emits .aerem/repo-map.json + .aerem/next-steps.md
aerem-ai-harness init --no-deep       # brownfield: shallow only (just scaffold + MIGRATION-MAP)

# Verify
aerem-ai-harness doctor

# Start a feature (creates a campaign in .aerem/campaigns/<ulid>/state.json)
aerem-ai-harness feature "add user impersonation"

# Move it through the 13-phase pipeline
aerem-ai-harness advance             # research → tb
aerem-ai-harness advance             # tb → design
aerem-ai-harness decision R1 approved "TB + Design coherent; ADR captures the choice."
aerem-ai-harness advance             # ...etc through compound

# Operate across many projects in a polyrepo container
cd ~/Code/sunstore                   # parent of multiple harness-initialized children
aerem-ai-harness workspace doctor
aerem-ai-harness workspace cost --parallel 3

Inside Claude Code, the same flows are available as slash commands:

/harness:init [--no-deep]
/harness:doctor
/harness:feature "<intent>"
/harness:advance
/harness:decision <gate> <outcome> "<rationale>"
/harness:pause
/harness:resume
/harness:checkpoint
/harness:cost
/harness:workspace <subcommand> [args...]
/aerem:knowledge-author --section=<name>  | --all
/aerem:spec-author --discipline=tb | design | fe | be | qa
/aerem:adr-author --stage=draft | final
/aerem:architecture-doc-updater --module=<name>
/aerem:vendor-doc-author --vendor=<name>
/aerem:learnings-backfill
/aerem:backfill-orchestrator

What gets scaffolded by init

<your-project>/
├── .aerem/
│   ├── memory/constitution.md       (R-rules + machine checks)
│   ├── ratchets.json                (R-rule baselines)
│   ├── state.json                   (master pointer to active campaign; gitignored)
│   ├── repo-map.md                  (shallow structural index)
│   ├── repo-map.json                (brownfield default — omit with --no-deep)
│   ├── next-steps.md                (brownfield default — omit with --no-deep)
│   ├── specs/                       (per-feature spec directories)
│   ├── campaigns/<ulid>/            (per-feature state + checkpoint + progress)
│   ├── cards/reject-log.jsonl       (R1/R2/R3 reject audit log)
│   └── backups/                     (artifact backups; gitignored)
├── .claude/
│   ├── settings.json                (hooks block, relative paths)
│   └── hooks/                       (3 lifecycle hooks as CJS bundles)
├── docs/{adrs,architecture,references,solutions}/INDEX.md
├── AGENTS.md
├── CLAUDE.md                        (one-line @AGENTS.md redirect)
├── harness.config.yml               (cost caps, parallelism, review gate weights)
└── harness.lock.yml                 (installed version + detected stack)

Plus, for brownfield repos, a MIGRATION-MAP.md listing detected AI artifacts that were backed up.

The 13-phase pipeline

research → tb → design → fe → be → spec-pair → qa
        → tasks → impl → verify → arch-update → pr → compound

State machine is forward-only — phases cannot be skipped or rewound. Each campaign records phase timestamps, gate decisions, and accumulated token cost atomically. Crash-safe writes use the tmp + fsync + rename pattern.

Three review gates fire at fixed points:

• R1 (heavy, after design) — forced-rationale review of TB + Design + ADR
• R2 (light, after qa) — default-approve if specs are green
• R3 (adaptive, after verify) — diff-sized review of impl + arch update

Programmatic API

import { RepoMapSchema, HARNESS_VERSION } from "@aerem/ai-harness";

const data = JSON.parse(readFileSync(".aerem/repo-map.json", "utf-8"));
const repoMap = RepoMapSchema.parse(data);   // Zod-validated

Requirements

• Node.js ≥ 18
• Claude Code (for slash commands)

License

UNLICENSED (proprietary — Aerem internal). Contact for licensing.

Links

• Issues: https://github.com/aerem/aerem-ai-harness/issues
• Source: https://github.com/aerem/aerem-ai-harness