@clawdia/code-factory

🏭 Machine-verifiable code review and validation infrastructure for AI coding agents.

Transform your repo into a Code Factory where agents handle implementation, validation, and review with deterministic, auditable standards.

Quick Start

# Initialize Code Factory in your project
npx @clawdia/code-factory init

This will:

• Create harness/ folder with validation scripts
• Create code-factory.json configuration
• Add GitHub workflows for risk-policy-gate, auto-remediate, and auto-resolve-threads
• Update package.json with harness scripts

Core Concept

The Code Factory model creates a single loop:

1. Coding agent writes code
2. Repo enforces risk-aware checks before merge
3. Code review agent validates the PR
4. Evidence (tests + browser + review) is machine-verifiable
5. Findings turn into repeatable harness cases

Commands

After initialization, these npm scripts are available:

Core Validation

npm run harness:risk-tier       # Compute risk tier for changed files
npm run harness:docs-drift      # Check control-plane docs drift
npm run harness:smoke           # Run smoke tests

SHA Discipline

npm run harness:sha-assert      # Assert review matches current HEAD
npm run harness:sha-record      # Record review completion
npm run harness:sha-status      # Check current state

Review Management

npm run harness:wait-for-review     # Wait for review agent
npm run harness:assert-clean-review # Assert no actionable findings
npm run harness:rerun-request       # Request review rerun (with dedupe)
npm run harness:resolve-bot-threads # Resolve bot-only threads

Auto-Remediation

npm run harness:remediate -- --findings='[...]' --effort=medium

Browser Evidence

npm run harness:ui:capture -- --base-url=http://localhost:3000
npm run harness:ui:verify -- --max-age=24
npm run harness:ui:summary

Incident Loop

npm run harness:incident:create -- --title="Bug" --severity=high
npm run harness:incident:update -- --id=gap-123 --case-added
npm run harness:incident:status
npm run harness:weekly-metrics

Configuration

code-factory.json

{
  "version": "1",
  "riskTierRules": {
    "critical": ["wallet/**", "SOUL.md"],
    "high": ["app/api/**", "lib/tools/**"],
    "medium": ["lib/**", "components/**"],
    "low": ["*.md", "**"]
  },
  "mergePolicy": {
    "critical": {
      "requiredChecks": ["risk-policy-gate", "code-review-agent"],
      "requireHumanApproval": true
    },
    "high": {
      "requiredChecks": ["risk-policy-gate", "code-review-agent"],
      "requireHumanApproval": true
    },
    "medium": {
      "requiredChecks": ["risk-policy-gate"],
      "requireHumanApproval": false
    },
    "low": {
      "requiredChecks": ["ci-pipeline"],
      "requireHumanApproval": false
    }
  },
  "reviewAgent": {
    "name": "greptile",
    "rerunMarker": "<!-- review-agent-auto-rerun -->",
    "rerunCommand": "@greptile please re-review"
  }
}

GitHub Workflows

The following workflows are created:

| Workflow | Trigger | Purpose | |----------|---------|---------| | risk-policy-gate.yml | PR open/sync | Preflight checks before CI | | auto-remediate.yml | Manual dispatch | Auto-fix review findings | | auto-resolve-threads.yml | Review success | Clean up bot threads | | browser-evidence.yml | UI file changes | Capture visual evidence |

Key Principles

1. SHA discipline — Never accept stale review evidence
2. Single rerun writer — One canonical requester prevents duplicates
3. Bot-only resolution — Never auto-resolve human threads
4. Effort levels — Limit remediation blast radius
5. SLA tracking — Every incident becomes a test case
6. Machine-verifiable — No trust, only evidence

Review Agents

Code Factory works with:

• Greptile — AI code review
• CodeRabbit — AI code review
• Custom LLM — Your own integration
• Manual — Human reviewers

Configure your agent in code-factory.json:

{
  "reviewAgent": {
    "name": "greptile",
    "rerunCommand": "@greptile please re-review"
  }
}

CLI Commands

npx @clawdia/code-factory init     # Initialize in your project
npx @clawdia/code-factory status   # Check configuration status
npx @clawdia/code-factory update   # Update harness scripts to latest
npx @clawdia/code-factory help     # Show help

Health Score

The weekly health score (0-100) factors:

• Open harness gaps (-5 each, max -20)
• SLA breaches (-10 each, max -30)
• Missing browser evidence (-15)
• Stale evidence >24h (-10)
• Failing smoke tests (-25)
• Active development bonus (+5)

Run npm run harness:weekly-metrics to see your score.

Migration from Existing Projects

1. Run npx @clawdia/code-factory init
2. Review and customize code-factory.json
3. Configure branch protection in GitHub
4. Choose and integrate your review agent
5. Run npm run harness:smoke to verify

License

MIT

Contributing

Issues and PRs welcome at github.com/clawdia-ai/code-factory

Built by Clawdia AI — Machine-verifiable code review for AI coding agents.