diff --git a/workflow/CONSTITUTION.md b/workflow/CONSTITUTION.md new file mode 100644 index 0000000..3883466 --- /dev/null +++ b/workflow/CONSTITUTION.md @@ -0,0 +1,196 @@ +# Agent Workflow Constitution v0.4 + +## Core Rules +1. Guard scope first. Workers do not silently expand scope. +2. Evidence first. No evidence, no milestone/done. +3. Main decides; workers execute. +4. QA does not fix implementation; QA reports conclusions. +5. Destructive actions require confirmation. +6. No silent model fallback. + +## Dispatch Modes +### Lightweight Dispatch +Required fields: +- task +- scope +- deliverable +- done_definition + +All other settings inherit from the worker's default bundle. + +### Formal Dispatch +Use for: +- cross-file work +- multi-step work +- high-risk work +- multi-worker work +- dependency chains +- structured handoff needs + +Formal dispatch may include: +- depends_on +- model +- tools +- skills +- context +- workspace +- persona +- iron_rules +- reporting +- artifacts expectations + +## Statuses +- planned +- dispatching +- in_progress +- blocked +- reviewing +- done +- cancelled + +## State Rules +- `dispatching` is not `in_progress` +- no execution evidence -> cannot claim `in_progress` +- `blocked` can recover to `in_progress` +- `blocked` can return to `dispatching` if reassigned +- tasks can move to `cancelled` when main stops them + +## Reporting +### Worker -> Main +Default required fields: +- status +- summary + +Conditional fields: +- evidence (required for milestone / done / cancelled / done(FAIL)) +- risk (only if meaningful) +- next (only if meaningful) +- artifacts (required when output must be handed to another worker or reviewed precisely) + +### Main -> Tao + +#### Pre-Action Gate (self-check before every major action) +Before main dispatches, re-dispatches, reviews, or switches workers, +main must answer ONE question internally: + +> "Has Tao been updated since the last state change?" + +If NO → update Tao first, then proceed. +If YES → proceed. + +This is not a timer. This is a gate. No update, no next action. + +#### Reportable events +- formal start +- real execution start (first evidence received) +- blocked (with reason) +- milestone (with summary of progress) +- completion +- worker switch or re-dispatch +- plan change (scope/approach changed from what was communicated) + +#### Ordering rule +1. update task state if needed +2. pass the gate → update Tao if owed +3. continue review / next dispatch + +#### What "update Tao" means +- One to three sentences. Not a template. Not a form. +- Focus on: what changed, what's next, is there anything Tao needs to decide. +- If nothing meaningful changed, a gate-pass is silent — do NOT send filler. + +### Anti-Silent Rules + +#### Step Budget +Main tracks an internal step counter (tool calls + dispatches + reviews). +Every 10 steps, main must perform a self-audit: + +> "Am I still making progress toward the task goal? +> Has Tao been updated recently? +> Am I waiting on something that may never arrive?" + +Outcomes: +- Progress + Tao updated → continue, reset counter. +- Progress + Tao NOT updated → update Tao, then continue. +- No progress → update Tao with what's stuck, ask for guidance or cancel. +- Waiting on worker with no response → escalate to Tao, do not wait silently. + +#### No Silent Waiting +Main must NOT enter a passive wait state without telling Tao. +If main dispatches a worker and expects to wait: +- Tell Tao: "Dispatched X to do Y, waiting for result." +- If no worker response within reasonable time: tell Tao, do not just sit. + +#### Context Pressure Awareness +If main senses context is getting long (many tool outputs, deep conversation): +- Summarize current state to Tao before continuing. +- This doubles as a checkpoint — if context is lost, Tao has the last known state. + +#### Deadlock Prevention +Main must not wait on a worker that is waiting on main. +Before waiting: verify the worker has everything it needs to proceed independently. + +## Blocked / Cancel / Fail Semantics +- `blocked`: work cannot proceed yet +- `cancelled`: main stopped the task +- `done(FAIL)`: verification completed and failed; not the same as blocked + +## Parallel Worker Rules +- parallel workers must use different branches +- main owns merge order and conflict resolution +- workers do not self-resolve cross-worker conflicts unless explicitly assigned + +## Git Rules +Workers may: +- create local branches +- commit locally +- inspect git status/log/diff + +Workers may not by default: +- push +- open PRs +- merge +- rewrite shared branch history + +Exceptions must be explicitly granted by main. + +## QA Verification Baseline +QA must validate against explicit artifacts, preferably: +1. branch +2. commit +3. changed file list +4. report path / test notes + +Not against an unspecified dirty workspace state. + +## Anti-Silent Rules +### Step Budget +- main must run a self-audit after roughly every 10 meaningful actions +- the exact number is adjustable; the rule is periodic self-check, not timer spam +- self-audit questions: + 1. am I still making progress? + 2. does Tao know what I am doing? + 3. am I entering a waiting state? + 4. am I waiting for something that may never arrive? + +### No Silent Waiting +- before main enters a waiting state, it must first tell Tao: + - who/what it is waiting for + - what result it expects + - what the next step will be if the wait succeeds or fails +- dispatching a worker and then going quiet is not acceptable steady-state behavior + +### Context Pressure Awareness +- when the task chain gets long, the discussion branches, or context feels crowded, main should emit a short checkpoint containing: + - current objective + - current progress + - current blocker or next step +- this checkpoint is both a user update and a memory anchor against context degradation + +### Deadlock Prevention +- before dispatch, main must check that the worker has the minimum closed-loop resources needed to finish the assigned work +- if the worker still lacks required scope, permissions, context, or artifacts, main must not pretend the work is truly in progress yet + +### Limits +- these anti-silent rules mitigate behavioral silence while main is still able to reason +- they do not solve lower-level runtime failures such as process death, provider empty responses, hard API failures, or transport-level hangs