Armature

The invisible skeleton that gives shape to what AI coding agents produce.

Armature is a harness engineering framework for AI coding agents. It wraps agents (Claude Code, Cursor, Copilot, Windsurf, Aider) in automated guides, sensors, budget controls, architectural enforcement, garbage collection, and self-healing pipelines.

System Architecture

Usage Flow

Quick Start

pip install armature-harness

# Initialize in your project
cd your-project/
armature init

# Run quality checks
armature check

# Wire into Claude Code
armature hooks --claude-code

# Self-heal lint violations
armature heal --failures lint

The 6 Pillars

Quality Checks (v0.2.1)

8 weighted checks with configurable gates:

Scoring: weighted_score = sum(score * weight) / sum(weight)

Gates: Draft (70%) | Review Ready (85%) | Merge Ready (95%)

Configuration

Everything is configured in armature.yaml:

project:
  name: "my-project"
  language: python
  src_dir: "src/"

quality:
  enabled: true
  checks:
    lint: { tool: ruff, weight: 25 }
    type_check: { tool: mypy, weight: 25 }
    test: { tool: pytest, weight: 20, coverage_min: 85 }
    security: { tool: bandit, weight: 20 }
    complexity: { kind: internal, weight: 15, threshold: 10.0 }
    dependency_audit: { tool: pip-audit, weight: 15 }
    docstring: { kind: internal, weight: 10 }
    test_ratio: { kind: internal, weight: 10, threshold: 0.5 }
  post_write:
    enabled: true  # shift-left: check on every file write

budget:
  enabled: true
  providers:
    strategy: cost_optimized
    enabled_models: [claude-sonnet, claude-haiku, claude-opus]
  cache: { enabled: true }
  calibration: { enabled: true, auto_calibrate: true }

architecture:
  enabled: true
  layers:
    - { name: models, dirs: ["src/models/"] }
    - { name: services, dirs: ["src/services/"] }
    - { name: routes, dirs: ["src/routes/"] }
  boundaries:
    - { from: models, to: [routes] }

heal:
  enabled: true
  healers:
    lint: { auto_fix: true }

integrations:
  claude_code: { enabled: true }

Implementation Roadmap

IDE Integrations

armature hooks --claude-code      # .claude/settings.local.json
armature hooks --cursor           # .cursor/rules
armature hooks --copilot          # .github/copilot-instructions.md
armature hooks --github-actions   # .github/workflows/armature.yml
armature hooks --pre-commit       # .pre-commit-config.yaml

The Harness Engineering Model

Armature implements the harness engineering 2x2 grid:

Claude Code Skills

Armature provides slash commands for Claude Code:

• /armature-check -- Run quality sensors
• /armature-heal -- Self-healing pipeline
• /armature-gc -- Garbage collection sweep
• /armature-budget -- Cost tracking and reporting

Budget Control

Track and optimize AI coding costs:

# Log usage
armature budget --spec SPEC-001 --phase build --tokens 50000 --cost 1.25

# Generate report
armature budget --report SPEC-001

Armature analyzes phase distribution, per-request token usage, and suggests optimizations: batch file reads, narrow context, progressive disclosure.

References

• Ossature -- Spec-driven development with validate/audit/build
• OpenAI Harness Engineering -- Harness patterns for AI coding agents
• Martin Fowler's Exploring Gen AI -- Bockeler/Fowler harness engineering series

License

MIT