Agent workflows

This section defines how human contributors and AI agents plan, implement, review, and deliver changes in Habiter. It is the detailed source of truth for agent behavior; AGENTS.md is the mandatory, compact entry point.

Rule hierarchy

1. Explicit owner instructions for the current task.
2. AGENTS.md.
3. The most specific page in this section and the applicable engineering contract.
4. General repository documentation.

An agent must stop and request direction when two applicable rules cannot both be followed. It must not silently choose the less safe interpretation.

Required task declaration

Before changing files, state the following in the task record, implementation plan, or pull request:

Mode: Plan | Inspect | Diagnose | Review | Implement | Verify | Deliver | Monitor
Flow: Standard | Yeet | Hotfix | Release
Scope: what is included and explicitly excluded
Acceptance: observable completion criteria
Batches: number and intended outcome of each batch
Validation: focused checks and the broader merge gate
Remote actions: none | push | pull request | merge | release | deploy

Remote actions is an authorization record. Listing an action does not authorize it; the owner must explicitly authorize each remote action in the task request or an approved handoff.

Read in this order

1. Agent modes
2. Roles and authority
3. Planning when the work is not trivial
4. Batches and commits
5. Delivery flows
6. The relevant playbook, handoff pattern, and engineering contract

The branch naming and cleanup mechanics are maintained in the branch workflow. Quality evidence is maintained in testing and quality.

Working pages

Need	Page
Decide what an agent is allowed to do now	Agent modes
Decide who owns a decision or approval	Roles and authority
Design a multi-step change	Planning
Split work and create commits	Batches and commits
Choose Standard, Yeet, Hotfix, or Release	Delivery flows
Start a GitHub issue from !issue	Issue trigger
Start a common type of development task	Change playbooks
Transfer work without losing evidence	Handoffs
Execute a task reliably	Checklists