engineeringagent 0.1.1

Feature-driven harness for human-gated coding loops

Engineering Agent

EngineeringAgent is a human-guided harness for running reliable coding loops with an agent.

Primary flow: application spec -> run loop

Command styles

• Package usage (PyPI, no clone): uvx engineeringagent <command>
• Package usage (version pinned): uvx engineeringagent@<version> <command>
• Contributor usage (from this repository): uvx --from . engineeringagent <command>

Quickstart from PyPI (no clone)

Run directly from the published package:

uvx engineeringagent --help
uvx engineeringagent validate
uvx engineeringagent gates run --profile loop_fast

Pin to a specific release when you need reproducible onboarding or CI runs:

uvx engineeringagent@<version> --help
uvx engineeringagent@<version> validate

Contributor setup (local checkout, first 10 minutes)

The steps below assume contributor usage from this repository checkout.

1. Install dependencies.

   uv sync
   

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

3. Validate the setup and run gates.

   uvx --from . engineeringagent validate
   uvx --from . engineeringagent gates run --profile loop_fast
   

4. Do a safe dry run first.

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

5. Run for real by removing --dry-run.

Bootstrapping a new repository with init

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

uvx --from . engineeringagent init

init defaults to the language-agnostic core scaffold profile. Use python_uv only when you intentionally want Python/uv-oriented bootstrap defaults:

uvx --from . engineeringagent init --scaffold-profile python_uv

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

Warning: treat init as experimental scaffolding. Always inspect generated files, run uvx --from . 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.
• TTY terminals show light styling for scanability; redirected output stays ANSI-free.
• Set NO_COLOR=1 (or TERM=dumb) to force plain output.

Human docs vs agent docs

• README.md: first-run, human onboarding.
• Harness Engineering Principles: deeper human context.
• AGENTS.md and docs/references/*-llms.md: agent execution rules and deterministic procedures.

Core files to know

• docs/spec/features/: active feature specs (backlog, in_progress, blocked)
• docs/spec/features_done/: archived completed specs (done)
• docs/spec/schemas/feature.schema.json: feature schema contract
• 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
• Docs architecture for agents

Curated external context

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