Flow — Agentic Software Delivery Manual

flow/ is the operating manual for how humans and agents work in a repository.

Its job is to remove hidden process assumptions. A new agent should be able to land in a repo cold, read this directory, and work safely without inventing workflow rules.

Core Operating Principles

1. main is protected. All meaningful changes move through pull requests.
2. One scoped task maps to one branch and one PR.
3. The comparison base is the remote default branch, usually origin/main, not a stale local branch.
4. If more than one PR is active at once, use separate git worktree directories or separate clones.
5. Agents work from explicit scope contracts: issues, handoffs, or both.
6. Validation is required before review, and validation should avoid dirtying tracked runtime state unless that side effect is intended.
7. Review is findings-first. Summaries do not substitute for diff review.
8. Reflection is part of delivery. Durable process lessons should be written down, not left in chat.

Who This Is For

• AI agents executing bounded work in a repo
• lead agents orchestrating multiple workers
• human maintainers reviewing, merging, and releasing

Reading Paths

Worker quick start

1. Repo Structure
2. Git Workflow
3. Naming Conventions
4. PR Flow
5. Agent Coordination
6. Closeout and Learning

Lead quick start

1. Issue Lifecycle
2. PR Flow
3. Code Review Standards
4. Agent Coordination
5. Closeout and Learning

Full reading order

#	File	Topic
01	Repo Structure	Durable vs generated vs ephemeral files
02	Git Workflow	Branching, rebasing, worktrees, recovery
03	Naming Conventions	Branch, commit, PR, handoff, artifact naming
04	Issue Lifecycle	How work is defined, assigned, and closed
05	PR Flow	Draft PR to merge and cleanup
06	Code Review Standards	Findings-first review rules
07	CI/CD Pipeline	Required checks, branch protection, deploy gates
08	Testing Standards	Test strategy and change verification
09	Release Process	Versioning, tagging, rollback, post-release
10	Agent Coordination	Lead/worker model, handoffs, concurrency
11	Obsidian Integration	What belongs in the vault vs the repo
12	Glossary	Shared vocabulary
13	Closeout and Learning	Reflection, success/friction/updates, durable corrections
14	Orchestrator Log	Append-only observations and workflow corrections

Update Policy

1. Update flow/ through a PR, not directly on main.
2. If a workflow failure happens in practice, fix the docs that allowed it.
3. If a lesson changes durable team behavior, encode it here or in the repo's standing docs.
4. If a note only matters temporarily, keep it in the PR, issue, or handoff instead of bloating the manual.