Metadata-Version: 2.4
Name: armature-harness
Version: 0.2.1
Summary: Harness engineering framework for AI coding agents -- the invisible skeleton that shapes agent output
Project-URL: Homepage, https://github.com/vivekgana/armature
Project-URL: Repository, https://github.com/vivekgana/armature
Project-URL: Documentation, https://github.com/vivekgana/armature#readme
Project-URL: Changelog, https://github.com/vivekgana/armature/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/vivekgana/armature/issues
Author: Armature Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,architecture,coding-agent,harness,linting,quality
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: bandit>=1.7.0; extra == 'all'
Requires-Dist: mypy>=1.8.0; extra == 'all'
Requires-Dist: pip-audit>=2.7.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: radon>=6.0.0; extra == 'all'
Requires-Dist: ruff>=0.3.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: python
Requires-Dist: bandit>=1.7.0; extra == 'python'
Requires-Dist: mypy>=1.8.0; extra == 'python'
Requires-Dist: pip-audit>=2.7.0; extra == 'python'
Requires-Dist: pytest>=8.0.0; extra == 'python'
Requires-Dist: radon>=6.0.0; extra == 'python'
Requires-Dist: ruff>=0.3.0; extra == 'python'
Provides-Extra: typescript
Description-Content-Type: text/markdown

# Armature

<!-- mcp-name: io.github.vivekgana/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.

## Quick Start

```bash
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

| Pillar | What | CLI |
|--------|------|-----|
| **Budget** | Token/cost tracking per spec/phase, optimization suggestions | `armature budget` |
| **Quality** | Lint + type + test checks, quality gates (draft/review/merge), shift-left hooks | `armature check` |
| **Context** | CLAUDE.md/AGENTS.md generation, progressive disclosure, cross-session memory | `armature hooks` |
| **Architecture** | Layer boundary enforcement, class conformance, schema sync | `armature check` |
| **GC** | Architecture drift, stale docs, dead code, budget audit | `armature gc` |
| **Self-Heal** | Auto-fix lint, report type/test errors, circuit breaker escalation | `armature heal` |

## Configuration

Everything is configured in `armature.yaml`:

```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 }
  post_write:
    enabled: true  # shift-left: check on every file write

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 }
```

## IDE Integrations

```bash
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:

|  | Computational (fast, deterministic) | Inferential (LLM-based) |
|---|---|---|
| **Feedforward (guides)** | `armature.yaml` rules, architecture config, type hints | CLAUDE.md rules, spec constraints |
| **Feedback (sensors)** | ruff, mypy, boundary checks, conformance, GC sweeps | LLM code review, eval judges |

## 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:

```bash
# 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](https://ossature.dev) -- Spec-driven development with validate/audit/build
- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) -- Harness patterns for AI coding agents
- [Martin Fowler's Exploring Gen AI](https://martinfowler.com/articles/exploring-gen-ai.html) -- Bockeler/Fowler harness engineering series

## License

MIT
