# Development & Reporting Rules

## 1. Core Development Principles

1. **Align with OpenClaw direction**
   - Build extensions and tools that are likely to survive upstream upgrades.

2. **Clear, simple, beginner-friendly**
   - Prefer obvious behavior over cleverness.
   - Avoid workflows that only the author can understand.

3. **Keep docs and logs concise and clear**
   - README, setup, usage, and troubleshooting should stay short but usable.

4. **Search GitHub before building**
   - Check whether an existing open-source project or pattern already solves the problem.
   - Prefer reuse before starting a new repo.

5. **Explicit over implicit**
   - Critical configuration should be defined once at the top level and referenced elsewhere.
   - Avoid duplicated constants and scattered behavior switches.

6. **Test critical paths, not vanity coverage**
   - Must verify key flows such as tool invocation, model routing, health checks, and main publish/execute paths.

7. **Small PRs, single responsibility**
   - One commit/PR should do one thing.
   - Do not mix unrelated changes in one diff.

8. **Semantic versioning**
   - `patch` = bugfix only
   - `minor` = backward-compatible feature
   - `major` = breaking change

9. **Graceful failure, never silent failure**
   - If config is missing or behavior is invalid, fail loudly.
   - Do not silently fallback and pretend everything is fine.

10. **Every change must be rollback-friendly**
    - Keep the previous good state recoverable.
    - Prefer tags/releases before important deployments.

11. **Config changes count as code changes**
    - CLI args, env vars, and config file changes must be tracked and reviewed like code.

12. **External interactions need logs**
    - Log input summaries and status, but do not dump sensitive full payloads.

13. **Main is PM, not the construction crew**
    - Main handles requirements, planning, dispatch, review, and reporting.
    - Main should not personally code except for tiny linear edits.

14. **Execution work goes to workers by default**
    - Coding, QA, docs, ops, and similar execution should be delegated to the right worker.

15. **Dispatch includes environment, not just a task**
    - When creating/dispatching an agent, specify the needed model, tools, skills, context, workspace, persona, and rules.

16. **Prefer Claude Opus 4.6 for execution when available**
    - Default execution preference: `claude-local/claude-opus-4-6`
    - Secondary: `claude-local/claude-sonnet-4-6`
    - No silent fallback.

17. **Worker git authority is limited by default**
    - Workers may create local branches and commit locally.
    - Workers do not push, open PRs, merge, or rewrite shared history unless explicitly authorized.

18. **Parallel workers must isolate work**
    - Use separate branches.
    - Main owns merge order and conflict resolution.

19. **QA validates, QA does not secretly fix**
    - QA should report pass/fail/blockers based on explicit artifacts.
    - `done(FAIL)` is different from `blocked`.

20. **Rules should start light, then tighten**
    - Avoid over-bureaucratizing small tasks.
    - Use lightweight dispatch for small work and formal dispatch for risky or multi-step work.

---

## 2. Delivery Rules for Push / PR / Release

For any meaningful delivery, verify all of the following:

1. **Code**
   - Changes are actually pushed.

2. **Version**
   - Version number matches the delivery significance.

3. **Docs**
   - README / config / usage docs are updated when behavior changed.

4. **Release**
   - Important updates should get a release/tag.

5. **Release Notes**
   - Important releases should include clear notes.

### Important update triggers
Treat any of the following as an important update:
- security fixes
- new config/env vars
- behavior changes
- installation or usage changes
- user-visible new features or important fixes

Short rule:

> **Code, version, docs, release, and notes should stay aligned.**

---

## 3. Workflow / Reporting Rules

## Task states
Use only:
- `planned`
- `dispatching`
- `in_progress`
- `blocked`
- `reviewing`
- `done`
- `cancelled`

### State meanings
- `dispatching` is not `in_progress`
- no 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

## Evidence rule
- No evidence, no milestone/done.
- No validation, no completion.

Good evidence includes:
- non-empty worker reply
- logs
- commit / branch / PR
- test output
- release artifact

## Worker -> Main reporting
Default required fields:
- `status`
- `summary`

Conditional:
- `evidence` (required for `milestone`, `done`, `cancelled`, `done(FAIL)`)
- `risk` (only if meaningful)
- `next` (only if meaningful)
- `artifacts` (required when handoff/review needs precision)

## Main -> Tao reporting
Main must report at these events:
- formal start
- first real execution evidence
- blocked
- milestone
- completion
- worker switch / re-dispatch
- plan change

### Ordering rule
When a worker reports a milestone/completion/blocker:
1. update task state if needed
2. update Tao
3. continue review / next dispatch

## Pre-Action Gate
Before main dispatches, re-dispatches, reviews, or switches workers, main must ask:

> **Has Tao been updated since the last state change?**

If no, update Tao first.

## Anti-Silent Rules

### 1. Step Budget
After roughly every 10 meaningful actions, main must self-audit:
- Am I still making progress?
- Does Tao know what I am doing?
- Am I entering a waiting state?
- Am I waiting for something that may never arrive?

### 2. No Silent Waiting
Before entering a waiting state, main must tell Tao:
- who/what it is waiting for
- what result it expects
- what the next step is if the wait succeeds or fails

### 3. Context Pressure Awareness
If context gets long or scattered, main should send a short checkpoint with:
- current objective
- current progress
- current blocker or next step

### 4. Deadlock Prevention
Before waiting, main must ensure the worker has the minimum resources needed to finish independently.

### 5. Limits
These rules help when main is still able to reason.
They do not solve lower-level runtime death, API/provider empty responses, or transport hangs.

---

## 4. Lightweight vs Formal Dispatch

### Lightweight dispatch
Use for small, low-risk tasks.

Required:
- `task`
- `scope`
- `deliverable`
- `done_definition`

Everything else can inherit defaults.

### Formal dispatch
Use for:
- cross-file work
- multi-step work
- high-risk work
- multi-worker work
- dependency chains
- structured handoffs

May include:
- `depends_on`
- `model`
- `tools`
- `skills`
- `context`
- `workspace`
- `persona`
- `iron_rules`
- `reporting`
- `artifacts_expected`

---

## 5. Practical Summary

If reduced to the shortest possible operating rules:

1. Guard scope.
2. No evidence, no completion.
3. Main decides; workers execute.
4. QA reports; QA does not secretly fix.
5. No silent fallback.
6. No silent waiting.
7. Update Tao on real state changes.
8. Keep code/version/docs/release/notes aligned.
9. Prefer lightweight process for small work, formal process for risky work.
10. If a rule causes friction in practice, propose a revision explicitly instead of silently ignoring it.