Workflow

Workflow

The general loop

issue → open a branch → develop → test → PR → review → squash merge → issue closes

Rule: an issue is opened before writing code. No exceptions. Reason: writing down what you'll do forces you to think about it; it also lets your partner see what you're working on.

1. Issue

Template	When
📋 Development task	A work item from the roadmap
🐛 Bug report	Something is broken
✨ Feature request	A new idea
📚 Learning goal	A commitment to learn a concept

Every issue gets these labels: type: *, area: *, month: N, owner: *.

2. Branch

git switch main && git pull
git switch -c feat/42-agent-step-index

Prefixes: feat/ fix/ docs/ refactor/ perf/ test/ chore/

3. Commit

feat(runtime): add max_steps limit to the agent loop

Infinite loops are the most common production failure of agent systems and
burn money directly. We add the limit together with the behavior.

Closes #17

In the body, write why you did it, not what you did. The diff already shows what you did.

4. PR

git push -u origin feat/42-agent-step-index
gh pr create --fill

Fill in the PR template completely. Keep PRs small: diffs larger than 400 lines don't get reviewed well.

5. Review

The reviewer's job

• Understand (first priority)
• Check contract, schema, and security impact
• Check that tests are adequate
• Ask about what they don't understand

Not the reviewer's job

• Style debates (ruff and the formatter handle those)
• Demanding it be written the way they would write it

Comment tone: not "this is wrong", but "how does this behave in this scenario?"

6. Merge

Squash and merge. The branch is deleted after merge. The issue closes automatically (Closes #NN).

Protection of main

• Direct push disabled
• PR + 1 approval required
• CI (python, java, compose) must be green
• Conversations must be resolved
• Force push disabled

These settings are applied by scripts/setup-github.sh.

Which file needs whose approval

.github/CODEOWNERS: architectural decisions, the service contract, and docker-compose.yml require both people's approval. One approval is enough for the rest.

Versioning

No version tag is used until Month 6. SemVer starts at launch: v0.1.0.