Project Loop#

Use for approved multi-step work that must survive resets, compaction, interruption, approval gates, and stalled execution.

Do not use for trivial one-turn work, open-ended autonomy, or projects without a clear owner.

Core Rules#

• Project files, not chat, are the source of truth
• Trust this order: state.json > manifest.md > validation.md > handoff.md > memory > chat
• Only the owner_agent in state.json executes project tasks
• Other agents may improve the skill, but do not run the loop
• Do not wait for human confirmation between self-clearable tasks
• Keep executing until an approval gate, blocker, or stop condition is reached
• After completing a chunk and successfully updating state, immediately begin the next eligible self-clearable chunk in the same turn
• Do not wait for a human response between self-clearable tasks after a successful state update
• Stop only for a real blocker, approval gate, failed state update, or explicit stop condition
• Before starting any task, check whether the output already exists
• If the work already landed, mark it done and advance
• On every resume, verify state.json against actual reality before executing
• During active execution, send a status update at least every 5 minutes
• A 5-minute update must include one of: artifact created, task completed, blocker, or exact next action in progress
• Do not send empty “still working” updates

Required Project Files#

Project path:

text

agents/<agent-id>/projects/<project-slug>/

Required:

text

README.md
manifest.md
state.json
validation.md

Optional:

text

handoff.md
notes.md
artifacts/
logs/

state.json Minimum Fields#

• project_id
• owner_agent
• status
• phase
• current_task_id
• last_checkpoint
• next_action
• blocked_reason
• awaiting_approval
• approval_items
• retry_count
• max_retries
• last_session_note
• resume_instructions
• interrupted
• active_loop

Recommended additions:

• approved_objective
• scope_guardrails
• task_queue_snapshot
• completed_tasks
• blocked_tasks
• deferred_tasks
• artifacts
• validation_status
• last_error
• last_error_at
• budget_hints
• resume_history
• watchdog

Session Start and Resume#

Read in this order:

1. state.json
2. manifest.md
3. validation.md
4. handoff.md if present
5. only then memory or chat if still needed

Never start by asking “what were we doing?” if project files exist.

On resume:

• read status, phase, current_task_id, next_action, resume_instructions
• verify state against actual reality before doing anything
• continue from recorded state, not guesswork

State Machine#

States:

• Draft
• Ready
• Running
• Validating
• AwaitingApproval
• Blocked
• Paused
• Done
• Abandoned

Allowed transitions:

text

Draft -> Ready
Ready -> Running
Running -> Validating
Validating -> Running
Validating -> Done
Running -> AwaitingApproval
Validating -> AwaitingApproval
Running -> Blocked
Validating -> Blocked
Running -> Paused
AwaitingApproval -> Running
Blocked -> Running
Paused -> Running
Any state -> Abandoned

Rules:

• Draft -> Ready only when objective, scope, manifest, and validation exist
• Ready -> Running only when the next chunk is sized and eligible
• Running -> Validating only after outputs are recorded
• Validating -> Running only after pass and a next task is eligible
• Validating -> Done only when required tasks are complete and final checks pass
• Running/Validating -> AwaitingApproval for true human-cleared boundaries
• Running/Validating -> Blocked when a blocker cannot be self-cleared within retry rules
• Running -> Paused only for interruption, manual pause, or no eligible task

Execution Rules#

• One chunk = one objective + one validation target
• If a task has more than one verb, split it
• Split at boundary changes: local prep -> remote write, remote write -> validation, planning -> execution, authenticated action -> read-back
• Never bundle multiple operations into one command if they can be independent
• If any command or execution step is denied for obfuscation or size, split it into smaller independent steps and retry
• This applies to file writes, API calls, shell commands, browser actions, and any other execution path

A chunk is too large if it:

• has more than one primary deliverable
• crosses multiple boundaries
• mixes planning, execution, and validation
• touches too many pages, endpoints, or files at once
• cannot be described with one clear done condition

Progress Rules#

• Updating state.json, manifest.md, validation.md, or handoff.md alone does not count as execution progress unless the current task is explicitly documentation-only
• Do not claim forward execution unless the external world changed or a required artifact for the current task was created
• When marking a task complete, record concrete evidence in state and in your reply when relevant: artifact path, file changed, page changed, validation evidence, or blocker artifact
• If you cannot point to the output, the task is not done
• Do not spend more than 2 consecutive project turns on planning, loop setup, or state reshaping without either executing, validating, or escalating
• If the user questions silence or progress, stop meta narration and report only: what changed, what artifact exists, what blocker exists, and what exact action is next
• Do not report system status theatrically. Report concrete project facts only

Validation Rules#

No task is complete until validation passes and the result is recorded.

Validation may include:

• artifact existence/content check
• file diff or file review
• browser verification of rendered state
• API read-back
• log/command review
• human review for customer-facing release steps

Validation records should capture:

• task ID
• method
• pass/fail
• timestamp
• evidence location
• next step

If validation fails:

• do not advance
• record exact failure
• retry only with a bounded corrective chunk or move to Blocked

Approval and Pause Rules#

Self-clearable work may continue if it stays in scope.

Human-cleared work includes:

• credential handling
• auth construction
• authenticated remote writes
• WordPress REST writes
• installs or config changes
• third-party sends
• publish/live-release steps unless already pre-approved
• actions requiring manual login or privileged access

When a true approval gate is reached:

• set status to AwaitingApproval
• record the exact pending action in approval_items
• record what prep is already done
• continue only if another independent task is eligible
• otherwise pause cleanly

Do not pause at routine internal chunk boundaries. Pause only for:

• real blocker
• missing access or credentials
• meaningful human decision
• explicit stop/pause
• genuine risk or scope boundary

Interruption and Recovery#

If interrupted by unrelated work:

• finish any atomic write already in progress if safe
• update state.json immediately
• set interrupted=true
• set active_loop=false
• set status=Paused unless already AwaitingApproval or Blocked

When updating state.json, use a full-file write by default, not a partial edit. state.json changes frequently and exact-match edit operations are brittle on high-churn files. Use partial edit only if you have just read the current file and the change is truly small, stable, and low-risk.

If state.json cannot be updated:

• stop execution immediately
• this is a hard stop, not a soft warning
• do not continue the loop, do not start another chunk, and do not claim progress until state is repaired or successfully rewritten
• report the exact failure and recovery step

If a task may have partially executed:

• verify actual reality first
• do not blindly rerun
• choose next action from observed state, not assumptions

If state is missing or inconsistent:

• reconstruct from manifest, validation, artifacts, and handoff
• rewrite state before resuming

Watchdog Rules#

Cron is a watchdog only, never the main workflow engine.

• When creating a new project, automatically create a watchdog cron for that project
• When a project moves to Done or Abandoned, remove the watchdog
• The watchdog only reports when it takes an action or finds something worth surfacing
• If there is nothing to resume, retry, or escalate, stay silent

Watchdog may:

• detect stale Running
• detect resumable Paused
• detect approval-cleared states ready to continue
• trigger one bounded resume pass

Watchdog must not:

• invent new work
• rewrite scope
• cross approval gates without clearance
• spam retries
• chain arbitrary timer-based work

Recommended cap:

• one automatic resume attempt per cycle
• no more than two automatic recovery attempts without new evidence

Operating Sequence#

1. Read state.json
2. Read manifest.md
3. Read validation.md
4. Read handoff.md if present
5. Verify current state against actual reality
6. Check whether the target output already exists
7. Pick one eligible chunk
8. Apply chunk sizing rules
9. Execute
10. Validate
11. Update state.json
12. Continue if self-clearable, otherwise pause or escalate cleanly