You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A lightweight setup protocol for making software repositories easier to use with coding agents.
It adds a small repo-local control layer so agents can orient themselves, remember project state, and route natural-language requests to repeatable workflows.
You should not have to type exact one-word commands. The command names are convenient aliases, but the intended behavior is natural-language intent routing.
For example, all of these should work after setup:
orient
where are we?
can you catch up on the repo?
next
what next?
ok so can you tell me what the next steps are?
what should we do now?
status textures
where are we on textures?
what was already decided about the texture system?
plan feature X
how would feature X fit in the current architecture?
do we already have something like X?
The goal is to make a repository self-orienting for future agents without accumulating AI-generated bureaucracy.
Usage
Copy AGENT_BOOTSTRAP.md into the root of your repository.
Then open your coding agent and say:
Read AGENT_BOOTSTRAP.md and bootstrap this repo.
Ask me the setup questions first.
Do not edit source code yet.
The agent will inspect the repo, ask a few setup questions, and create or update:
can you tell me what the next steps are?
where are we on the renderer refactor?
what was decided about the Python API?
how would we add async texture uploads?
turn this idea into tasks
implement A014
investigate the crash on close, don't edit code yet
review this branch for bloat
compress the project memory files
record this decision
switch this branch to aggressive refactor mode
what can run in parallel?
The shorter aliases also work:
orient
next
status <topic>
decisions <topic>
plan <feature>
task <idea>
do <task-id>
investigate <bug>
review
review bloat
compress
record
mode aggressive
mode minimal
parallel
integrate
Typical workflow
Copy AGENT_BOOTSTRAP.md into your repo.
Ask your coding agent to bootstrap the repo.
Answer the setup questions.
Review the generated files.
Commit AGENTS.md, .agent/*, and any docs/dev/ files you want to keep.
Use natural-language requests in future agent sessions.
Core principle
The repo should contain compact, current, durable project memory.
Git preserves history.
Markdown preserves current state.
Do not store chat transcripts. Do not create long planning logs. Keep project memory short, actionable, and easy for a fresh agent to read.
Copy this file into the root of a software repository.
Then tell your coding agent:
Read AGENT_BOOTSTRAP.md and bootstrap this repo.
Ask me the setup questions first.
Do not edit source code yet.
The agent should inspect the repository, ask a few questions, and create or update the repo-local agent workflow files.
After setup, future agents should understand both short aliases and natural-language requests.
The user should not have to type exact one-word commands. The command names are examples of intent categories.
Examples:
orient
where are we?
can you catch up on the repo?
next
what next?
ok so can you tell me what the next steps are?
what should we do now?
status <topic>
where are we on <topic>?
what was already decided about <topic>?
plan <feature>
how would <feature> fit in the current architecture?
do we already have something like <feature>?
Agent instructions
This document defines how to set up or retrofit this repository for disciplined work with coding agents.
The goal is to make the repository self-orienting for future agents, while keeping all coordination, design, and planning files compact, current, and low-noise.
Do not modify source code while applying this bootstrap unless the user explicitly asks for source-code changes.
1. Purpose
Set up this repository so that a fresh coding agent can quickly answer:
What project mode are we in?
What was done recently?
What is being worked on now?
What has already been decided?
What remains open?
What should be done next?
What files or areas are risky to touch?
Are we allowed to refactor aggressively, or should changes be minimal?
What natural-language workflows and command aliases does the user expect the agent to understand?
The repository should contain enough durable context to support AI-assisted development, but not so much text that agents waste context or follow stale instructions.
2. First action: inspect the repository
Before creating or editing files, inspect the repository.
Do not create empty design files unless they are immediately useful.
Do not create elaborate process directories unless the user asks for them.
6. File responsibilities
AGENTS.md
Permanent instructions for coding agents.
It should contain:
project overview;
build/test commands;
coding rules;
verification rules;
intent routing protocol;
orientation protocol;
project memory update protocol;
anti-bloat rules;
final report format.
It should not contain:
long architecture discussions;
task backlog;
chronological logs;
chat transcripts;
stale plans.
Target length: under 150 lines.
.agent/MODE.md
Current operating mode for this branch or repo.
It answers:
Are breaking changes allowed?
Should agents favor minimal patches or aggressive cleanup?
Is this release stabilization, exploration, or active architecture work?
What constraints still apply?
Target length: 30-80 lines.
.agent/STATE.md
Compact current project state.
It answers:
current focus;
recently done;
current state;
next good tasks;
blockers/risks;
pointers to relevant design/ADR/task files.
Target length: 50-120 lines.
This file is not a diary. It should be rewritten to stay current.
.agent/TASKS.md
Current task queue.
It contains:
active tasks;
ready tasks;
blocked tasks;
recently done tasks.
Each task should have:
ID;
status;
priority;
size;
goal;
likely files;
branch/worktree if applicable;
done condition;
dependencies.
Target length: under 200 lines.
Archive or compress old done tasks.
.agent/COMMANDS.md
Intent router for short aliases and natural-language requests.
It maps terse user prompts like orient, next, status textures, do A014, or review bloat to full workflows.
This file is what makes short prompts reliable.
Target length: 150-250 lines.
docs/dev/design/*.md
Living design notes for unsettled design/spec topics.
Use these for:
current proposed architecture;
constraints;
rejected alternatives;
open questions;
next tasks.
These are not transcripts.
Target length: under 150 lines per file.
docs/dev/adr/*.md
Architecture Decision Records.
Use these for accepted durable decisions.
Each ADR should contain:
title;
status;
date;
context;
decision;
consequences;
rejected alternatives;
open questions, if any.
Target length: 40-100 lines.
7. Create or update AGENTS.md
Create or update AGENTS.md with compact instructions like this.
Adapt the project overview and build/test commands to this repo.
# Agent instructions## Project
Briefly describe this repository here.
## Operating mode
Read `.agent/MODE.md` before making recommendations or changes.
The current mode controls whether to favor aggressive refactoring, balanced changes, minimal safe patches, release stabilization, or exploration only.
## Intent routing protocol
The user may give short aliases or natural-language requests.
Before asking for clarification, check `.agent/COMMANDS.md` and map the user's request to the closest workflow.
Command names are examples, not strict syntax. The user should not have to type exact one-word commands.
Examples:
-`orient`, `where are we?`, `can you catch up on the repo?`-`next`, `what next?`, `can you tell me what the next steps are?`-`status textures`, `where are we on textures?`-`decisions renderer`, `what was decided about the renderer?`-`plan feature X`, `how would feature X fit here?`-`task feature X`, `turn this idea into tasks`-`do A014`, `implement A014`-`investigate crash on close`, `debug the close crash without editing code`-`review memory`, `review this branch for memory issues`-`compress`, `clean up the project memory files`-`record`, `save this decision in the repo`-`mode aggressive`, `switch this branch to aggressive refactor mode`-`parallel`, `what can run in parallel?`-`integrate`, `plan the merge order`
If the request is low-risk and does not edit source code, proceed using the closest matching workflow.
If the request would edit source code and the target is ambiguous, ask one concise clarification.
## Orientation protocol
When the user asks what was done, what to do next, what was decided, or how a new feature fits, first inspect:
1.`.agent/MODE.md`2.`.agent/STATE.md`3.`.agent/TASKS.md`4.`.agent/COMMANDS.md`5. relevant files in `docs/dev/design/`6. relevant files in `docs/dev/adr/`7.`git status`8. recent `git log --oneline`
Do not answer from memory alone.
When answering, be concise:
- current mode;
- relevant previous work;
- current code/design state;
- recommended next tasks;
- risks or blocked decisions.
## Build and test
Record the actual commands for this repo.
Examples:
- Configure:
- Build:
- Test:
- Lint:
- Format:
- Docs:
- Examples:
If a command is unknown, say so instead of inventing it.
## Coding rules- Keep changes scoped to the task.
- Do not reformat unrelated files.
- Do not add dependencies without approval.
- Do not create compatibility layers unless the current mode requires them.
- Prefer deleting obsolete code over preserving dead paths when in aggressive refactor mode.
- Prefer minimal local fixes when in minimal safe changes or release stabilization mode.
- Keep source code simpler after the change when possible.
## Parallel agent rules- One agent = one task = one branch = one worktree.
- Do not run multiple agents in the same working tree.
- Record active work in `.agent/TASKS.md`.
- Avoid parallel edits to locked or high-risk files.
- Do not merge another agent's branch unless explicitly assigned as integrator.
## Project memory update protocol
Before finishing any non-trivial session, decide whether durable project knowledge changed.
Durable project knowledge includes:
- operating mode;
- accepted design decision;
- rejected design alternative;
- architectural constraint;
- public API direction;
- implementation plan;
- task priority;
- new task;
- completed task;
- known blocker or risk.
If durable knowledge changed, update the smallest relevant file:
-`.agent/MODE.md` for operating mode;
-`.agent/STATE.md` for high-level current project state;
-`.agent/TASKS.md` for active/ready/done tasks;
-`docs/dev/design/*.md` for unsettled design/spec work;
-`docs/dev/adr/*.md` for accepted architecture decisions.
Rules:
- Do not append chat transcripts.
- Do not keep chronological logs unless explicitly requested.
- Replace stale text with a shorter current summary.
- Let git preserve history; Markdown should preserve current state.
- Prefer bullets over prose.
- Keep updates compact.
- Mark uncertainty as `Open questions`, not as decisions.
## Anti-bloat rules- Keep coordination and design files lean.
- Prefer editing existing files over creating new files.
- Remove stale or duplicated text when adding new durable information.
- Do not increase any coordination/design file by more than 20 lines without good reason.
- Do not write long summaries of obvious changes.
- Do not preserve temporary reasoning.
- Summarize completed work in at most 5 bullets.
## Required final report
End every non-trivial session with:
- Changed code:
- Verification:
- Project notes updated:
- Next suggested task:
- Risks:
8. Create .agent/MODE.md
Create .agent/MODE.md according to the user's chosen mode.
Use one of these templates and adapt as needed.
Aggressive refactor mode
# Project mode
Status: active
Last updated: YYYY-MM-DD
## Current mode
Aggressive refactor.
## Meaning- API/ABI compatibility is not required unless explicitly stated.
- Prefer long-term architecture over short-term compatibility.
- Remove obsolete code instead of preserving wrappers.
- Rename concepts, files, and APIs when this improves the architecture.
- Update examples, tests, and docs to match the new architecture.
- Avoid compatibility shims unless explicitly requested.
## Still required- Keep the repo buildable at the end of each implementation task.
- Keep changes scoped enough to review.
- Avoid unrelated rewrites.
- Do not add dependencies without approval.
- Keep coordination/design notes compact.
## Non-goals- No legacy compatibility layer.
- No deprecation period unless explicitly requested.
- No support for old user code unless explicitly requested.
Balanced mode
# Project mode
Status: active
Last updated: YYYY-MM-DD
## Current mode
Balanced development.
## Meaning- Improve architecture where it clearly helps.
- Avoid unnecessary breaking changes.
- Prefer incremental refactors over large rewrites.
- Public API changes require explicit justification.
- Keep examples, tests, and docs aligned with behavior.
## Still required- Keep the repo buildable.
- Keep tasks scoped and reviewable.
- Do not add dependencies without approval.
- Keep coordination/design notes compact.
Minimal safe changes mode
# Project mode
Status: active
Last updated: YYYY-MM-DD
## Current mode
Minimal safe changes.
## Meaning- Preserve public API and ABI unless explicitly approved.
- Prefer local fixes over refactors.
- Do not rename public functions, structs, files, or concepts.
- Do not reformat unrelated files.
- Do not change examples unless directly required.
- Add regression tests when practical.
## Non-goals- No architecture rewrite.
- No speculative cleanup.
- No public API redesign.
Release stabilization mode
# Project mode
Status: active
Last updated: YYYY-MM-DD
## Current mode
Release stabilization.
## Meaning- Prioritize correctness, regressions, packaging, docs, and tests.
- Avoid risky refactors.
- Preserve API/ABI unless explicitly approved.
- Fix only release-relevant issues.
- Prefer small, easily reviewable patches.
## Non-goals- No major new features.
- No architectural redesign.
- No broad cleanup.
Exploration-only mode
# Project mode
Status: active
Last updated: YYYY-MM-DD
## Current mode
Exploration only.
## Meaning- Investigation and design only.
- Do not edit source code unless explicitly asked.
- Produce compact findings, options, risks, and suggested tasks.
- Prefer reading code, docs, tests, and history before proposing changes.
## Non-goals- No implementation.
- No refactor.
- No source edits.
9. Create .agent/STATE.md
Create .agent/STATE.md:
# Project state
Last updated: YYYY-MM-DD
## Current focus
Briefly describe the current focus.
## Recently done- None recorded yet.
## Current state- Summarize the current technical/project state in a few bullets.
## Next good tasks1. Add first suggested task here.
2. Add second suggested task here.
## Blocked / risky- List known blockers or risky files if any.
## Pointers- Mode: `.agent/MODE.md`- Tasks: `.agent/TASKS.md`- Commands: `.agent/COMMANDS.md`- Design notes: `docs/dev/design/`- ADRs: `docs/dev/adr/`
If this is an existing repo, derive a better initial state from README, docs, existing issues, TODOs, and recent git history.
Keep it compact.
10. Create .agent/TASKS.md
Create .agent/TASKS.md:
# Tasks## Active
None.
## Ready### A001 orient repository- Status: ready
- Priority: P1
- Size: S
- Goal: inspect project structure, build/test commands, and existing docs
- Files: README, build files, docs
- Done when: `.agent/STATE.md` accurately summarizes the repo and build/test commands are recorded in `AGENTS.md`## Blocked
None.
## Done
None.
Use these status values:
ready
active
blocked
review
done
abandoned
Use these priorities:
P0: broken main, security, data loss, release blocker
P1: blocks important development or users
P2: important improvement
P3: cleanup
P4: idea
Use these sizes:
S: small, less than about one hour
M: medium, half day
L: multi-day
XL: needs design first
11. Create .agent/COMMANDS.md
Create .agent/COMMANDS.md:
# Agent commands and intent routing
This file defines workflow intents and how agents should interpret both short aliases and natural-language user requests.
The user is not required to type exact command names. Treat command names as convenient aliases for broader intents.
When the user gives a short command or natural-language request, map it to the closest workflow in this file. Do not ask for a longer prompt unless the intent is genuinely ambiguous.
Always read first:
1.`AGENTS.md`2.`.agent/MODE.md`3.`.agent/STATE.md`4.`.agent/TASKS.md`
Also read relevant `docs/dev/design/`, `docs/dev/adr/`, code, tests, docs, and git history depending on the command.
## `orient`
Meaning:
- Orient yourself in the repo.
- Do not edit files.
Do:
1. Read the standard control files.
2. Inspect `git status`.
3. Inspect recent git history.
4. Summarize current mode, recently done, active/ready tasks, recommended next tasks, and risks/blockers.
Do not:
- edit files;
- create tasks unless explicitly asked.
## `next`
Aliases and natural-language examples:
-`what next`-`now what`-`todo`-`can you tell me what the next steps are?`-`what should we do now?`-`where should we go from here?`
Meaning:
- Recommend what to do next.
Do:
1. Read the standard control files.
2. Check active/ready/blocked tasks.
3. Consider current mode.
4. Recommend 1-5 next actions, ordered by priority.
Do not:
- implement anything;
- rewrite the task list unless explicitly asked.
## `status <topic>`
Aliases and natural-language examples:
-`state <topic>`-`where are we on <topic>`-`what about <topic>`-`can you remind me what happened with <topic>?`-`what was already done for <topic>?`
Meaning:
- Explain current state of a topic.
Do:
1. Read standard control files.
2. Search `.agent/TASKS.md`, `.agent/STATE.md`, design notes, ADRs, docs, tests, code, and git history for `<topic>`.
3. Summarize current decision/state, what was done, what remains open, relevant files, and recommended next task.
Do not:
- edit files unless explicitly asked.
## `decisions <topic>`
Aliases:
-`adr <topic>`-`what was decided about <topic>`
Meaning:
- Summarize durable decisions about a topic.
Do:
1. Read relevant design notes and ADRs.
2. Search tasks and recent git history.
3. Distinguish accepted decisions, draft directions, rejected alternatives, and open questions.
4. Recommend whether an ADR should be created or updated.
Do not:
- create or edit ADRs unless the user says `record`, `update`, or `create adr`.
## `plan <feature/topic>`
Aliases and natural-language examples:
-`how would we do <feature/topic>`-`design <feature/topic>`-`do we already have something like <feature/topic>?`-`how would <feature/topic> fit with the current code?`
Meaning:
- Propose an implementation or design plan.
- Do not edit source code.
Do:
1. Orient from standard control files.
2. Search existing code/docs/tests/design/ADR/task files.
3. Determine whether the feature already exists.
4. Explain how it fits the current architecture and mode.
5. Propose a compact implementation plan.
6. Suggest the first task.
Do not:
- implement;
- create many tasks unless user says `task`.
## `task <idea/topic>`
Aliases:
-`make tasks <idea/topic>`-`split <idea/topic>`
Meaning:
- Convert an idea or plan into small tasks.
Do:
1. Read current mode/state/tasks.
2. Search relevant code/design files if needed.
3. Create or update entries in `.agent/TASKS.md`.
4. Keep tasks small, scoped, and verifiable.
5. Update `.agent/STATE.md` only if high-level state changes.
Do not:
- implement code.
## `do <task-id>`
Aliases:
-`implement <task-id>`-`work on <task-id>`
Meaning:
- Implement the named task.
Do:
1. Read standard control files.
2. Read the task entry.
3. Mark task active in `.agent/TASKS.md`.
4. Implement minimal scoped changes according to `.agent/MODE.md`.
5. Run relevant verification commands.
6. Update project memory files if durable state changed.
7. Mark task review or done, depending on verification.
8. Return the required final report.
Do not:
- expand scope unless blocked;
- modify unrelated files.
## `investigate <topic/bug>`
Aliases:
-`debug <topic/bug>`-`why <topic/bug>`
Meaning:
- Investigate without editing source code.
Do:
1. Read standard control files.
2. Inspect relevant code/tests/docs/history.
3. Return likely cause, evidence, relevant files/functions, and suggested fix.
4. Add or update a task only if a concrete next step is identified.
Do not:
- edit source code unless explicitly told.
## `test <bug/feature/task>`
Meaning:
- Add or propose tests.
Default:
- If the user says only `test X`, write or propose regression tests first.
- Do not implement production code unless explicitly asked.
Do:
1. Inspect existing test style.
2. Add minimal tests if the command clearly asks to modify files.
3. Otherwise propose test plan.
4. Update tasks if needed.
## `review`
Aliases:
-`review branch`-`check diff`
Meaning:
- Review current branch diff.
Do:
1. Read current mode.
2. Inspect `git diff` against the appropriate base branch.
3. Review for correctness, scope creep, mode violations, tests, risky files, and obvious bugs.
4. Return concrete findings.
Do not:
- edit files unless explicitly asked.
## `review <lens>`
Examples:
-`review memory`-`review api`-`review tests`-`review bloat`-`review mode`-`review performance`-`review security`
Meaning:
- Review current diff with a narrow focus.
Lens meanings:
-`memory`: memory lifetime, allocation/free, ownership, leaks.
-`api`: public API/ABI compatibility.
-`tests`: test adequacy and missing edge cases.
-`bloat`: unnecessary abstraction, verbose docs, duplicated code, overengineering.
-`mode`: whether the diff follows `.agent/MODE.md`.
-`performance`: avoid obvious performance regressions.
-`security`: check for unsafe input handling, secret leakage, and dangerous behavior.
Do not edit files.
## `compress`
Aliases:
-`clean memory`-`compact notes`
Meaning:
- Compress project memory files.
Do:
1. Review `.agent/STATE.md`, `.agent/TASKS.md`, relevant design notes, and ADRs.
2. Remove stale, duplicated, superseded, or overly verbose text.
3. Preserve current decisions, open questions, tasks, risks, and pointers.
4. Prefer shorter files.
Do not:
- edit source code;
- erase active tasks or accepted decisions.
## `record`
Aliases:
-`save this`-`record decision`-`update notes`
Meaning:
- Persist durable information from the current discussion.
Do:
1. Classify information as mode, state, task, design, ADR, or transient.
2. Update the smallest relevant file.
3. Keep the update compact.
4. Do not save transient reasoning or chat transcript.
## `mode <mode>`
Allowed modes:
-`aggressive`-`balanced`-`minimal`-`release`-`explore`
Meaning:
- Change or report project operating mode.
Do:
1. Update `.agent/MODE.md`.
2. Update `.agent/STATE.md` if current focus or constraints changed.
3. Do not edit source code.
Mode mappings:
-`aggressive` -> aggressive refactor
-`balanced` -> balanced development
-`minimal` -> minimal safe changes
-`release` -> release stabilization
-`explore` -> exploration only
## `adr <topic>`
Meaning:
- Work with Architecture Decision Records.
Default:
- If no clear decision has been accepted, summarize whether an ADR is needed.
- If the user says `create adr <topic>`, create a proposed ADR.
- If the user says `accept adr <id>`, mark it accepted and update state/design pointers.
Do not:
- invent accepted decisions.
## `parallel`
Aliases:
-`parallelize`-`multi-agent`
Meaning:
- Identify safe parallel work.
Do:
1. Read tasks, current mode, locked/risky files.
2. Group tasks that can run in parallel.
3. Identify sequential dependencies.
4. Suggest branch/worktree names.
Do not:
- launch work unless explicitly asked.
## `integrate`
Aliases:
-`merge plan`
Meaning:
- Act as integration planner for completed task branches.
Do:
1. Inspect listed branches or completed tasks.
2. Summarize diffs and verification status.
3. Identify conflicts/risks.
4. Recommend merge order.
Do not:
- merge unless explicitly asked.
## `bootstrap`
Meaning:
- Set up or repair this agent workflow in the repo.
Do:
1. Read `AGENT_BOOTSTRAP.md` if present.
2. Inspect existing AI files.
3. Ask required setup questions if needed.
4. Create/update canonical agent files.
5. Do not edit source code.
## Default behavior for unclear requests
If the request is unclear:
1. Try to map it to the closest workflow.
2. State the assumed workflow in one short sentence.
3. Proceed if the risk is low and no code edits are involved.
4. Ask for clarification before editing source code.
12. Standard design note template
When creating a design note, use:
# Topic
Status: draft
Last updated: YYYY-MM-DD
## Problem
Short problem statement.
## Current decision
Current best decision or direction, if any.
## Constraints- Constraint 1
- Constraint 2
## Non-goals- Non-goal 1
## Rejected alternatives- Alternative: reason rejected.
## Open questions- Question 1
## Next tasks- Axxx task name
Only create a design note if there is real design content.
13. Standard ADR template
When creating an ADR, use:
# ADR NNNN: Title
Status: proposed
Date: YYYY-MM-DD
## Context
What problem or decision context led to this ADR?
## Decision
What decision was made?
## Consequences- Consequence 1
- Consequence 2
## Rejected alternatives- Alternative: reason rejected.
## Open questions- Question, if any.
ADR statuses:
proposed
accepted
superseded
deprecated
14. Handling existing AI instruction files
If existing instruction files are found, do not overwrite them immediately.
Instead:
Summarize them.
Identify duplicated or conflicting instructions.
Propose a consolidation.
Ask before deleting or radically rewriting tool-specific files.
Preferred structure:
AGENTS.md is canonical.
Tool-specific files either disappear or contain only a short pointer to AGENTS.md.
Example tool-specific pointer:
Read `AGENTS.md` first. It is the canonical instruction file for this repository.
If a tool requires a specific filename, keep the file but avoid duplicated instructions.
15. Handling new repos
For a brand-new repo:
Create the standard structure.
Keep .agent/STATE.md minimal.
Add build/test commands once they exist.
Start with A001 orient repository or A001 define initial architecture.
Do not create premature ADRs unless the user has already made real decisions.
Do not create empty design files.
16. Handling existing repos with no AI setup
For an existing repo with no AI setup:
Inspect README, build files, tests, docs, and recent git history.
Create the standard structure.
Fill AGENTS.md with actual build/test commands if discoverable.
Fill .agent/STATE.md with a compact summary of current project state.
Fill .agent/TASKS.md with one or more realistic next tasks.
Create design notes only for already-visible architectural topics.
Do not invent project goals that are not supported by repo evidence or user input.
17. Handling existing repos with AI setup
For an existing repo with AI setup:
Inspect all existing AI instruction files.
Preserve important constraints.
Remove or consolidate duplication where safe.
Create .agent/MODE.md, .agent/STATE.md, .agent/TASKS.md, and .agent/COMMANDS.md.
Update AGENTS.md to reference those files.
Do not discard existing instructions without asking if they seem intentional.
Make the final result shorter and clearer than the original.
18. Parallel agent workflow rules
If the user expects multiple agents to work in parallel:
Use one worktree per task.
Use one branch per task.
Record active ownership in .agent/TASKS.md.
Avoid parallel edits to high-risk files.
Prefer an explicit integrator for merging.
Recommended invariant:
One agent = one task = one branch = one worktree.
For example:
git worktree add ../repo-a014 -b agent/a014
Do not run multiple implementation agents in the same working tree.
19. Compression rules
When updating any coordination or design file:
Remove stale or superseded text first.
Merge duplicate bullets.
Add only durable information.
Prefer replacing old summaries over appending new chronology.
Keep files shorter or roughly the same length where possible.
Do not save chat transcripts.
Do not preserve temporary reasoning.
Durable information includes:
accepted decisions;
rejected alternatives that explain a decision;
constraints;
non-goals;
open questions;
next tasks;
risks/blockers;
branch/repo mode.
Transient information should not be saved.
20. Final bootstrap report
After applying this bootstrap, report:
## Bootstrap report
Created/updated:
- ...
Detected project type:
- ...
Current mode:
- ...
Build/test commands recorded:
- ...
Existing AI instructions:
- none / summarized here
Initial next tasks:
- ...
Needs user decision:
- ...
Risks:
- ...
Do not implement feature work during bootstrap unless explicitly asked.
