A small, reusable workspace for an AI agent to take software, hardware, or integrated engineering projects from an objective to a validated result. The files provide operating instructions and durable memory. Use an agent that can inspect files and use your project's tools; the template itself does not run an agent, schedule work, or grant device access. A single capable agent is sufficient.
Discussion with agent → project setup → persistent engineering loop.
- Talk to the agent about what you want to build. Discuss the objective, desired behavior, constraints, acceptance criteria, available resources, hardware access, safety limits, and important unknowns naturally. Start with what you know; the agent helps clarify what matters. You do not need to design the implementation or write a detailed engineering plan.
- Let the agent configure the engineering workspace. Use this repository as a template, clone it, or copy the core files below into your project. Give the agent access to the project directory and relevant code, manuals, schematics, data, or references, then send the setup prompt in the discussion. Keep credentials outside tracked files.
- Run the persistent engineering loop. Review the captured intent in PROJECT.md, correct anything needed, then send the reusable loop prompt. The agent chooses the implementation and maintains progress in files.
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px', 'lineColor': '#768390'}}}%%
flowchart TD
D[Discuss the objective] --> S[Setup prompt:<br/>capture intent]
S --> L[Loop prompt:<br/>autonomous engineering]
RS[Interrupted, or a new agent] --> L
L --> G{Hardware project?}
G -->|No| V[VALIDATED]
G -->|Yes| RG[Candidate review gate]
RG -->|Explicit approval| HV[Hardware validation]
HV --> V
Setup runs once per project. The loop prompt is reusable: every later session, including a fresh agent, re-enters at the same point using the saved files.
Use our preceding discussion and this template to configure this repository for
the engineering task. Read the existing files first. Translate the discussion
into PROJECT.md: objective, desired behavior, observable requirements and
acceptance criteria, constraints, resources, hardware access, permissions, safety
limits, and known unknowns. Preserve human intent and distinguish assumptions
from agreed facts; do not invent permissions or safety limits. Make reasonable
low-risk decisions yourself; ask only about ambiguities that materially affect
scope, acceptance, safety, or a major tradeoff. Adapt the template only where
the project genuinely requires it, preserve existing work and the STATE.md /
records / evidence workflow and hardware review gate, and avoid unnecessary
scaffolding. Initialize STATE.md with requirements, validation methods, and the
next useful action, leaving the repository ready for autonomous engineering.
Take ownership of the engineering objective in this repository and drive it to a
validated result.
Read AGENTS.md first and follow it. It defines the workflow, the evidence and
record conventions, your authority limits, and the review gates. Let it route
your other reading; PROJECT.md holds the intent and STATE.md the current
checkpoint. Reconcile that checkpoint against the actual artifacts before you
act on it.
Work in many actions, not one: pick the most consequential useful gap, close it,
record the evidence, then pick the next. Decide routine reversible things
yourself instead of asking permission for work you are already authorized to do.
Do not interact with physical hardware before the explicit approval AGENTS.md
requires.
Stop only when the requirements are validated, a review gate in AGENTS.md is
reached, or every remaining useful action depends on a human decision or an
external dependency. Checkpoint STATE.md before stopping and record exactly what
you need and what happens next.
The repository is the source of truth, not this conversation. Leave nothing a
successor would need only in chat.
Reuse the loop prompt after interruptions, context loss, or agent replacement. Project continuity comes from repository state, not chat history; setup is only needed to configure the project, not each time work resumes.
project/
├── README.md Start, operate, and resume the workspace
├── PROJECT.md Human intent and available resources
├── AGENTS.md Agent operating instructions
├── ARCHITECTURE.md Engineering loop and workspace boundaries
├── STATE.md Agent's concise current checkpoint
├── records/
│ ├── RECORDS.md Evidence E001… and decisions D001…
│ └── HUMAN_INPUTS.md Consequential human inputs H001… and their sources
└── outputs/
└── REPORT.md Candidate review, validated result, or blocked handoff
Humans supply and review intent; direct edits to PROJECT.md are also welcome. Agents maintain the checkpoint, records, report, and engineering artifacts. Record the actual system architecture in STATE.md and the report. Keep existing project conventions and add directories or design documents only when useful.
Agents preserve consequential steering in HUMAN_INPUTS.md: human wording and source, separate from interpretation, with links to affected intent, state, or evidence. Routine chat and transcripts are omitted. STATE.md tracks the last applied input so successors can find newly recorded steering.
The repository also has a .gitignore, historical requests in prompt-log/, and
maintainer notes in docs/TEMPLATE_REVIEW.md. These are optional extras; the two
prompts above and AGENTS.md provide current operating guidance.
For Claude Code users, CLAUDE.md points at these same files and
.claude/commands/setup.md and .claude/commands/loop.md expose the two prompts
above as /setup and /loop. Maintainers can run
python3 tools/validate_template.py . to check the template's structure and that
STATE.md / outputs/REPORT.md remain uninitialized; the same check runs in CI
(.github/workflows/validate.yml). See CHANGELOG.md for template history and
LICENSE (MIT) for reuse terms.
Requirements → inspect current state → identify the most consequential gap → choose an action → design / implement → test / measure → diagnose / evaluate → update state → requirements satisfied? → repeat or validate completion.
Evidence changes the plan. Each requirement links to a validation method, result, and evidence for the relevant configuration. The current agent coordinates any specialists and integrates their results into one checkpoint. See the architecture diagram.
Hardware access is not required to start. Complete all meaningful hardware-free
work, then review the candidate and prepare outputs/REPORT.md with evidence,
limitations, assumptions, physical validation procedures, and shutdown/rollback.
Resolve software gaps before saving AWAITING_HUMAN_REVIEW. Even connected devices
wait for explicit candidate approval before any interaction; general device
permissions do not bypass the gate. See the hardware phase rules.
Software-only projects use SOFTWARE_DEVELOPMENT → VALIDATED after required
validation, without a hardware gate.
Read STATE.md for requirement statuses (PASS, FAIL, UNTESTED, BLOCKED),
current configuration, priority, next action, and any exact human action needed.
Follow its evidence links for details.
STATE.md's Loop continuity section is what makes a long-running project safe to interrupt: it names the current checkpoint owner, any in-flight action whose outcome is unknown, how many attempts the current gap has taken, and the approaches already ruled out. A successor resolves that section before dependent work, so an interrupted operation is verified rather than assumed and a known dead end is not retried. See the persistent loop robustness rules.
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '18px', 'lineColor': '#768390'}}}%%
flowchart TD
R[Session starts or resumes] --> RC[Reconcile Loop continuity]
RC --> IF{In-flight action?}
IF -->|Yes| VF[Outcome UNKNOWN:<br/>verify actual state]
IF -->|No| CH[Choose next action:<br/>skip what is ruled out]
VF --> CH
CH --> WA[Record intent, then act]
WA --> WR[1. Write records and artifacts]
WR --> US[2. Update STATE.md]
US --> CL[3. Clear in-flight entry]
CL --> PG{New evidence?}
PG -->|Yes| CH
PG -->|No| ES[Change approach,<br/>rule out, or escalate]
ES --> CH
The numbered write order is what makes an interruption detectable: a crash leaves unreferenced evidence that reconciliation finds, rather than a checkpoint claiming evidence that was never written.
A fresh agent using the persistent loop prompt checks the checkpoint against actual artifacts and relevant evidence, reconciling unfinished operations and stale validation before continuing. A restart does not bypass AWAITING_HUMAN_REVIEW; applicable recorded approval is retained within its scope. A stopped agent must be restarted by a human or an external runner; these files preserve progress between sessions.
If a user provides this repository because they want help with an engineering problem, first help them formulate the engineering task.
Keep the interaction short, conversational, and progressive.
- Ask one question per message.
- Ask at most four initial questions total.
- Ask only the next most useful question based on what the user has already said.
- Skip questions whose answers are already known.
- Stop asking questions early if the task is sufficiently clear.
- Keep responses concise. Do not explain the entire framework, present a long checklist, or dump multiple questions at once.
- Do not ask the user to write a specification.
- Do not require the user to know engineering terminology.
The initial conversation should establish, as needed:
- Objective — What does the user want to build, change, fix, automate, or understand?
- Existing system and resources — What relevant hardware, software, components, instruments, code, data, interfaces, or designs already exist?
- Success criteria — What observable or measurable behavior matters?
- Constraints and boundaries — What important limits must be respected, such as budget, dimensions, available parts, environment, schedule, safety, standards, or hardware-access restrictions?
Do not ask these four questions as a list. Select and ask them one at a time, adapting each next question to the user's previous answer.
If the user does not know an exact requirement, do not force them to invent one. Help determine reasonable requirements later from calculations, research, tests, or engineering context.
Briefly synthesize the discussion into a preliminary engineering task covering:
- objective
- desired behavior
- success criteria
- available resources
- important constraints and safety boundaries
- important unknowns
- initial engineering direction
Keep this synthesis concise. Clearly distinguish user-provided facts, agent assumptions, and unresolved requirements.
Do not continue questioning merely to remove uncertainty. Proceed with reasonable, reversible assumptions when possible.
Ask an additional question later only when the answer is necessary for safety, materially changes the scope or acceptance criteria, or determines a major irreversible engineering decision.
Once the task is sufficiently defined, transition directly into the engineering agentic system setup instructions in the "Start a project" section of this README.