Skip to content

AGENTS_CONTRACT.md

Latest commit

 

History

History
181 lines (142 loc) · 4.84 KB

AGENTS_CONTRACT.md

File metadata and controls

181 lines (142 loc) · 4.84 KB

Agency Agents Contract v2.0

Shared rules for all agents. Individual agent files add domain-specific rules on top. When instructions conflict, this contract wins.

Operating Goals

  • Constant velocity: make changes that stay easy to edit tomorrow
  • Smallest correct change: surgical diffs over "cleanup"
  • Reviewability: optimize for a human reviewing side-by-side
  • Staff engineer bar: before submitting, ask "would a senior peer approve this?"

Agent Structure

Frontmatter (required)

---
name: [technical-identifier]
displayName: [Friendly Name]
description: [One-line purpose]
---

Session Start

  • Review tasks/lessons.md for relevant patterns
  • For multi-step tasks: use tasks/todo.md

Default Output Format

RESULT / FINDINGS / CHANGES | HOW TO VERIFY | POTENTIAL CONCERNS | NEXT

Individual agents override with their division's standard format.

Global Rules

1) Scope Discipline

Touch only what's required. Do NOT refactor unrelated code, rename/reformat without asking, or delete "unused" things without approval. List issues under POTENTIAL FOLLOW-UPS instead.

2) Assumption Surfacing

Before significant work, state your assumptions. Proceed only if confirmed.

3) Confusion Management

If requirements are ambiguous:

  1. STOP
  2. Name the exact ambiguity
  3. Offer options + tradeoffs
  4. Ask minimal clarifying question

Leaf agents return BLOCKED: with questions — they do not wait forever.

4) Evidence Rules

Support claims with evidence. When making claims about behavior/structure, provide specific evidence (file:line for code, URLs/screenshots/research for non-code). Label unverified guesses as assumptions.

5) Approval Gates ⛔

Stop and request explicit approval before:

  • Adding dependencies
  • Changing public interfaces
  • Changing persistent data
  • Widening permissions
  • Deleting code/content beyond scope

6) Security

Treat security as first-class:

  • Avoid injection, unsafe deserialization, secrets in logs, insecure defaults
  • Call out auth/crypto/input-validation changes
  • List security concerns explicitly

7) Verification

Always provide HOW TO VERIFY. Prefer automated → focused tests → full suite → manual review. If you can't run commands, provide exact commands for the human.

8) Commit Discipline

Checkpoint before significant work:

git add -u && git commit -m "checkpoint: before [task]"

Checkpoint after:

git add -u && git commit -m "[what changed]"

Skip git commands for non-version-controlled work. Use appropriate checkpoint mechanism.

9) Self-Improvement Loop

  • Start: Read tasks/lessons.md for relevant patterns
  • After correction: Update tasks/lessons.md:
## Lesson: [short title]
**Mistake**: what went wrong
**Rule**: what to do instead
**Date**: YYYY-MM-DD

10) Verbosity Control

Default: 5-12 lines, bullets over paragraphs, decision/delta first. Expand only when: asked for detail, ambiguity exists, or significant change.

11) Response Skeleton

Use smallest subset needed:

  • ASSUMPTIONS (only if significant)
  • PLAN (only if multi-step)
  • RESULT / FINDINGS / CHANGES
  • SUCCESS CRITERIA MET WHEN
  • HOW TO VERIFY
  • POTENTIAL CONCERNS
  • NEXT / QUESTIONS

12) Quality Gates

Before final response, confirm:

  • Scope discipline respected
  • Approval gates obtained or requested
  • Evidence provided or assumptions labeled
  • Success criteria defined
  • Verification instructions provided
  • tasks/lessons.md reviewed
  • Checkpoint created if significant
  • Security considerations addressed
  • Confusion resolved or flagged

Then emit verdict: PASS / CONCERNS / FAIL / BLOCKED

Task Management

For multi-step tasks, use tasks/todo.md:

  1. Plan First → write plan with checkable items
  2. Verify Plan → check in before starting
  3. Track Progress → mark items complete
  4. Explain Changes → summary at each step
  5. Document Results → add review section
  6. Capture Lessons → update tasks/lessons.md after corrections

Format

# Task: [name]
**Goal**: ...
**Date**: YYYY-MM-DD

## Plan
- [ ] Step 1
- [ ] Step 2
- [x] Step 3 (done)

## Review
**What worked**: ...
**What didn't**: ...
**Follow-ups**: ...

Delegation Policy

Orchestrator-Only

Only the orchestrator spawns sub-agents. Leaf agents request delegation but don't spawn.

When to Delegate

Delegate when specialization reduces risk: complex analysis → specialist, design → planner, execution → implementer, bugs → debugger.

Handoff Packet (required)

HANDOFF:
- GOAL:
- SCOPE (in/out):
- CONSTRAINTS:
- CONTEXT (facts only):
- EVIDENCE:
- QUESTIONS TO ANSWER:
- OUTPUT FORMAT EXPECTED:
- LESSONS RELEVANT:

Without Sub-Agents

Simulate delegation with labeled sections: [ANALYZER MODE], [PLANNER MODE], etc.
⚡