Pet agent rules

Document version	Date	Summary
v1	2026-07-17	Initial mandatory agent workflow

Status: Mandatory development baseline

Every agent reads this document before changing the repository. The repository is durable memory. Previous chat context is not a source of truth.

1. Source of truth

Use this precedence for product and implementation decisions:

1. product specification
2. general architecture
3. active version architecture under docs/arch/
4. milestones
5. epics
6. assigned PBI in 03-pbis.md
7. task specific notes and prompts

Code rules remain mandatory for implementation and prose.

A lower document cannot silently override a higher document. If a task explicitly changes a higher contract, update that contract with the change. Otherwise stop before implementing the conflicting part and report the conflict.

Do not infer requirements from a milestone or epic title. Use the assigned PBI, its acceptance criteria, and its linked source sections.

2. Task start procedure

Read in this order:

1. this file
2. relevant sections of code-rules.md
3. project-context.md, if present
4. the assigned PBI
5. only the specification and architecture sections linked by that PBI
6. last-development.md, if it concerns the same area
7. relevant component knowledge files and ADRs
8. current code and tests in the task area

Do not read every project document by default. Read the full specification, architecture, or epic file only when the task changes their scope or the PBI lacks enough context.

Before editing, identify:

• target PBI and epic
• intended outcome
• in scope and out of scope work
• acceptance criteria
• dependencies
• affected architecture boundaries
• required verification

3. Scope and implementation

• make the smallest coherent change that completes the PBI
• do not implement future PBIs early
• do not add speculative services, abstractions, fields, or dependencies
• do not perform unrelated refactoring
• inspect existing code and tests before designing replacements
• preserve existing user changes
• keep tests with the behaviour they verify
• update higher level documentation only when semantics or architecture actually change

If a small defect blocks the assigned PBI, fix it with a regression test when the fix remains inside the same scope. Record larger or unrelated defects in bugs.md.

Record an intentionally deferred constraint in known-limitations.md and link it to a PBI where possible.

4. Architecture work

Architecture documents under docs/arch/ follow the architecture policy.

When changing an architecture document:

• keep all mandatory arc42 top level sections
• place information in the correct section
• update Mermaid diagrams affected by the change
• use standard relative Markdown links
• add a revision history row for an accepted meaningful revision
• record significant alternatives and decisions in an ADR
• update the active version architecture when implementation differs from its documented design

Do not copy the full specification into architecture documents.

5. Component knowledge files

Major implemented components may have a compact knowledge file:

docs/components/component-<name>.md

Create one only when the component has durable context that future agents would otherwise need to rediscover. Do not create empty component files during initial scaffolding.

A component file may contain:

• purpose and ownership
• explicit non-responsibilities
• public contracts
• important data structures
• lifecycle and invariants
• interactions
• current implementation
• deferred work
• risks and limitations

Keep it short. Do not paste large code blocks, duplicate the specification, or turn it into a changelog.

Update a component file when a task changes its contract, ownership, lifecycle, data model, or interaction boundary. Formatting, typo fixes, isolated test cleanup, and behaviour preserving internal refactors do not require an update.

The final task summary states which component files changed or says:

no component knowledge files required updates

6. Task handover

After every completed task, overwrite:

docs/last-development.md

This file contains only the latest handover. It is not a changelog and should normally fit on one screen.

Use this structure:

# Last development
 
## Task
 
## Changed areas
 
## What changed
 
## Tests and checks
 
## Component files updated
 
## Known limitations
 
## Suggested commits
 
## Suggested next step

Append one concise row to docs/progress.md after a completed task. Progress records history. Last development records only the latest state.

If a task stops before completion, write a short handover under docs/handoffs/<PBI-ID>.md instead of recording false progress.

7. Commit plan

Agents never run git add, git commit, or git push unless the maintainer explicitly requests that exact operation.

Everything under docs/ stays out of Git staging and commits. The directory remains visible in git status by design. Never include docs/, or a path beneath it, in a git add command or suggested commit.

Every completed task includes a ## Suggested commits section in last-development.md.

Each suggested commit contains:

1. one git add command with exact paths
2. one Conventional Commits 1.0.0 message as plain text

Do not wrap the message in a git commit command. Use the allowed types and prose rules from code-rules.md.

Split commits by intent. Each proposed commit must leave the tree consistent with the checks reported for it.

Example:

### 1. Core lifecycle
 
```bash
git add include/pet/world.h src/world.c tests/test_world.c
```
 
feat: add explicit world lifecycle

8. Completion procedure

Before finishing a completed task:

1. confirm the work stayed inside PBI scope
2. check every acceptance criterion
3. run relevant tests and quality checks
4. update affected source documents, architecture, ADRs, and component files
5. record deferred bugs and limitations
6. overwrite last-development.md
7. append the progress row
8. prepare suggested commits
9. review the final diff for unrelated changes

The final report states:

• outcome
• changed files
• exact tests and checks run
• checks not run and why
• known limitations
• component knowledge files updated

Never report that a check passed when it was not run.

9. Documentation record brevity

Across all repository documentation:

• add a changelog or document-version row only for a major document-level change
• major changes include new release baselines and substantial contract, structure, or source-of-truth revisions
• do not add a version row for routine status updates, completion markers, wording changes, or individual PBI completion
• keep every changelog, revision history, and document history table description to about 12 words or fewer
• treat the 12-word target as a general brevity rule, not a hard validation limit
• limit each row appended to docs/progress.md to at most three sentences across all content cells

10. Context efficiency

• follow PBI links instead of loading full documents
• use project-context.md for stable project context
• use component files for durable component facts
• use last-development.md only for the latest handover
• use Git history for detailed change history
• avoid copying the same rule into several documents
• keep task notes temporary unless they contain durable information
• remove stale handover files after their task is completed

The goal is enough context for a correct change with the smallest useful reading set.

11. Agent definition of done

An agent task is done only when:

1. the assigned outcome and acceptance criteria are satisfied
2. implementation follows code-rules.md
3. source of truth documents remain consistent
4. relevant tests and checks were run or clearly reported as unavailable
5. required knowledge and handover files were updated
6. bugs and limitations were recorded when deferred
7. suggested commits were prepared
8. no unrelated change was included

12. Completion markers

When a PBI or epic is completed, append [+] to its heading in 03-pbis.md and 02-epics.md so finished items are easy to scan at a glance.