engineeringagent 0.2.0

A framework for running coding agents as long running tasks - with deterministic feedback loops and agent reviewers

Engineering Agent

Engineeringagent is a CLI that helps you implement code changes directly from feature specs. It pairs an agent loop with repository-owned harnesses (validators, gates, fitness functions, and optional reviewer agents).

You will still need to implement/configure the harness for your repository. If you are just starting out, the first few specs you run should usually be harness improvements.

Primary flow: feature spec -> run loop.

Command styles

• Package usage (PyPI, no clone): uvx engineeringagent <command>
• Package usage (version pinned): uvx engineeringagent@<version> <command>

Quickstart from PyPI (no clone)

1. If you are starting in a fresh repository, scaffold the baseline harness first.

   uvx engineeringagent init
   

   Warning: init is experimental scaffolding. Inspect generated files, run uvx engineeringagent validate, and review the git diff before committing.

   We recommend you do this in a separate branch or toy project the first time you try out the process.

2. Create or pick one feature spec in docs/spec/features/.

   If you are just getting started, create a minimal example feature file that satisfies docs/spec/schemas/feature.schema.json:

3. Validate the setup and run gates.

   uvx engineeringagent validate
   uvx engineeringagent gates run --profile loop_fast
   

4. Do a safe dry run first.

   uvx engineeringagent run docs/spec/features/FEAT-001-example.yaml --dry-run
   

Run for real by removing --dry-run.

1. Test that implemented gates run at commit (remember to init a git repo - if it is not already)

Bootstrapping a new repository with init

If you are starting in a fresh repository, you can scaffold a baseline harness with:

uvx engineeringagent init

init defaults to the language-agnostic core scaffold profile.

Use python_uv when you want the scaffolded .pre-commit-config.yaml to assume an uv-based workflow (including a commit-msg hook); it does not add gate definitions to harness/gates.yaml.

uvx engineeringagent init --scaffold-profile python_uv

init creates a starter structure for docs/spec/ and harness/gates.yaml and handles existing docs/ or AGENTS.md through explicit conflict choices.

Warning: treat init as experimental scaffolding. Always inspect generated files, run uvx engineeringagent validate, and review the git diff before committing anything produced by init.

What this gives you

• Deterministic progress: one spec file at a time.
• Human control: you set priorities and scope; agents execute loops.
• Built-in quality checks: validation, gates, and commit hooks.

Run output tips

• Default output is concise; full implement/gate output stays in progress/run-feature-<FEATURE_ID>.txt.
• Use --verbose-output if you want full implement/gate output in the terminal.

OpenCode default agent contract

• Default loop execution uses the engineeringagent OpenCode agent, specified under: .opencode/agents/engineeringagent.md.

Human docs vs agent docs

• README.md: first-run, for you the developer.
• Harness Engineering Principles: deeper for you the developer.
• AGENTS.md and docs/references/*-llms.md: agent execution rules and deterministic procedures.

Reviewer agents (optional)

• Reviewer agents are a harness-managed complement to deterministic gates, configured in harness/reviewers.yaml.
• engineeringagent init does not scaffold reviewer config or prompts; keep reviewer policy repository-owned through committed harness files.
• Use uvx engineeringagent reviewers init to scaffold a baseline config and prompt files under harness/reviewers/prompts/.
• Use uvx engineeringagent reviewers list|plan|run to inspect and test reviewer behavior.
• For setup and migration guidance, see Reviewer authoring guide.
• For full contract, policy semantics, decision-envelope examples, and troubleshooting, see Reviewer agents reference.

Core files to know

• docs/spec/features/: active feature specs (backlog, in_progress, blocked)
• docs/spec/features_done/: archived completed specs (done)
• harness/gates.yaml: gate and profile definitions
• progress/runs.jsonl: append-only loop execution history

Contributing

• Pull requests are not accepted for this repository.
• Code changes are implemented through the project agent workflow.
• If you want a new capability, open a GitHub issue with the problem, desired outcome, and constraints.
• Feature requests from issues may be promoted into a formal spec under docs/spec/features/.

Go deeper

• CLI workflow details
• Agent execution map (scaffolded by init)
• Docs architecture for agents

Curated external context

• Harness engineering overview (OpenAI)
• Ralph Loop background
• Agent loop patterns (Anthropic)