# loop-engineering-bootstrap

**Repository Path**: tigerran/loop-engineering-bootstrap

## Basic Information

- **Project Name**: loop-engineering-bootstrap
- **Description**: 多agent协助项目开发闭环skill
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Loop Engineering Bootstrap

Portable Codex-first operating layer for project-local planning, execution,
evidence, delegation, recovery, and knowledge lifecycle records.

Version 0.4.0 turns the generated `.agent` directory into an interactive
execution loop. A normal fix or implementation request is enough: Codex creates
or resumes the Task, records the plan and route, performs scoped work, records
tests and gates, and closes the Attempt. The Python CLI owns deterministic
records and policy; it does not edit application code or dispatch agents.

## Boundaries

- `L1/report_only` forbids unattended mutation, commit, push, merge, and deploy.
- An explicit interactive request permits scoped file changes and test commands.
- S0/S1 runs in the root Codex conversation.
- S2/S3 requires a real Codex Worker and a different non-editing Verifier.
- Missing S2/S3 capability records `blocked_delegation`; there is no single-agent fallback.
- S3 additionally requires explicit, scoped human approval.
- No workflow automatically commits, pushes, merges, or deploys.

Claude Code and Hermes adapters are future work. Version 0.4.0 ships only the
Codex logical capability contract.

## Install And Initialize

Install from [GitHub](https://github.com/578281451/loop-engineering-bootstrap)
or the [Gitee mirror](https://gitee.com/tigerran/loop-engineering-bootstrap),
then run from this Skill repository:

```powershell
python scripts/bootstrap_loop.py --root <project>
```

Initialization creates or updates the marked Loop block in `AGENTS.md`, copies
the managed runtime into `.agent/compiler/loop_runtime`, installs record
schemas, and preserves project-owned files. Upgrade unchanged managed files with:

```powershell
python scripts/bootstrap_loop.py --root <project> --upgrade
```

Modified managed files are reported as conflicts rather than overwritten.

## Interactive Lifecycle

Every command accepts `--root <project>` and `--json`.

```powershell
python .agent/compiler/cli.py doctor --json
python .agent/compiler/cli.py status --json
python .agent/compiler/cli.py preflight --task "rename label" --scope src/ui.py --accept "label visible" --json
python .agent/compiler/cli.py plan-record --attempt-id ATT-1 --plan-file plan.json --json
python .agent/compiler/cli.py route --attempt-id ATT-1 --json
python .agent/compiler/cli.py context --task-id TASK-id --budget 50000 --json
python .agent/compiler/cli.py evidence-record --attempt-id ATT-1 --evidence-file evidence.json --json
python .agent/compiler/cli.py gate --attempt-id ATT-1 --stage completion src/ui.py --json
python .agent/compiler/cli.py task-finish --task-id TASK-id --attempt-id ATT-1 --json
```

For S2/S3, Codex first records observed logical capabilities, then calls its
real collaboration tools and records returned identities and results:

```powershell
python .agent/compiler/cli.py capability-record --attempt-id ATT-1 --available spawn_worker wait_worker independent_verifier --actual-tool spawn_agent --json
python .agent/compiler/cli.py delegation-start --attempt-id ATT-1 --worker-id <real-child-id> --scope frontend --accept "UI works" --required-evidence focused_test --json
python .agent/compiler/cli.py delegation-result --attempt-id ATT-1 --result-file worker-result.json --json
python .agent/compiler/cli.py verifier-record --attempt-id ATT-1 --result-file verifier-result.json --json
```

The CLI records host actions; it never claims that it dispatched a child itself.
Failure and recovery commands are `task-fail`, `task-interrupt`,
`attempt-retry`, `reconcile`, `status`, `doctor`, and `validate`. Exit codes are
0 success, 1 warning, 2 policy block, 3 recovery required, 4 host capability
unavailable, and 5 internal error.

```powershell
python .agent/compiler/cli.py task-status --task-id TASK-id --json
python .agent/compiler/cli.py task-fail --attempt-id ATT-1 --checkpoint test_failed --json
python .agent/compiler/cli.py task-interrupt --attempt-id ATT-1 --checkpoint permission_missing --json
python .agent/compiler/cli.py attempt-retry --task-id TASK-id --json
python .agent/compiler/cli.py reconcile --attempt-id ATT-2 path/observed.py --json
python .agent/compiler/cli.py human-approval-record --attempt-id ATT-1 --approver user --decision approved --operation security --scope src/security --json
python .agent/compiler/cli.py validate --json
```

## Development

```powershell
python -m pip install -r requirements-dev.txt
python scripts/validate_package.py .
python -m pytest tests -q
```

See [interaction contract](docs/interaction-contract.md), [continuation
guide](docs/continuation-guide.md), and [runtime contract](references/runtime-contract.md).