Dev Workflow

Engineering standards for code changes. Follow these phases in order.

Core Principles

1. Code is truth — Read code first. Docs drift over time; the running code is what actually ships.
2. Design before code — Write tests before implementation. Tests force you to define "done" before you start, preventing scope creep and rework.
3. Tests are design — Tests define behavior, not just verify it. A well-written test suite IS the specification.
4. Minimal blast radius — Touch only necessary files. Every changed file is a potential regression; keep the change surface small.

Priority Stack

Security → Correctness → Data Integrity → Availability → Performance → Docs → Speed

Phase 1: Exploration

Do this FIRST before any planning or coding.

Required Steps

0. Update task status: If the project uses GitHub Issues, update the issue status/labels. If it uses ISSUES.md, mark the task as In Progress
1. Create branch: git checkout -b feature/<name> or fix/<name>
2. Read relevant code — Understand patterns, find insertion points
3. Check if already exists — Search for similar implementations
4. Verify docs ↔ code sync — If drift found, fix docs first

Exploration Order

Choose your path: Adding new functionality or changing behavior → Phase 2 (Design). Fixing a reported bug → Phase 2-B (Bug Fix).

Phase 2: Design

Write tests before implementation. Tests define what "correct" means — without them, you're guessing whether your code works. Skipping this step is the #1 cause of rework.

Required Steps

1. Define behavior: What does it do? Input → Output?
2. Identify test cases:
   • Happy path (normal success flow)
   • Edge cases (empty, max, concurrent)
   • Error cases (what should fail?)
3. Write tests FIRST — Tests must fail before implementation exists

Minimum Tests by Change Type

If writing a test feels impossible, that usually means the requirement itself isn't clear yet. Clarify before coding — it's cheaper than debugging later.

Phase 2-B: Bug Fix (Alternative to Phase 2)

Reproduce the bug first. If you can't see it fail, you can't verify your fix actually works — and you risk "fixing" something that wasn't broken while the real bug persists.

Required Steps

1. Reproduce — Confirm bug exists; if cannot reproduce, ask for more info
2. Write failing test — The test IS your bug report
3. Understand root cause — Why it fails, not just where
4. Fix minimally — Smallest change that makes test pass
5. Verify — Failing test passes; full suite passes

When Fix Attempt Fails

When a fix fails, resist the urge to add another patch. Each failed attempt usually means your mental model of the bug is wrong — step back and re-examine assumptions from scratch.

Phase 3: Implementation

Prerequisite: Tests are written and failing.

Required Steps

1. Run failing tests — Confirm they fail for expected reason
2. Write minimal code — Just enough to make tests pass
3. Run tests again — Confirm they pass
4. Refactor if needed — Tests must still pass

Code Standards

• Type annotations on function signatures
• Small, testable functions
• Explicit error handling (no silent except:)
• No secrets in code — use env vars

If tests don't pass, stop and investigate. Moving forward with failing tests means you're building on a broken foundation — every subsequent change compounds the problem.

Phase 4: Pre-Commit

Complete these steps before committing. Each one catches a different class of mistake — skipping any of them means that class of error ships silently.

Required Checklist

[ ] All tests pass
[ ] CHANGELOG.md updated (if user-facing change)
[ ] README.md updated (if CLI/config changed)
[ ] No debug code (console.log, print, commented code)
[ ] No secrets in code

CHANGELOG Sections

Commit Format

type(scope): summary

Types: feat | fix | docs | test | chore | refactor

git commit -m "feat(auth): add OAuth2 support"
git commit -m "fix(parser): handle empty input"

Phase 5: Pull Request

Prerequisite: Pre-commit checklist complete.

PR Guidelines

• One PR = One concern — Don't mix features, fixes, refactors
• Small PRs — Aim for <400 lines; split large changes
• Complete — Code + Tests + Docs in same PR

PR Description

## What
Brief description.

## Why
Link to issue or explain motivation.
Closes #123  <!-- if applicable -->

## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing (if applicable)

Self-Review Before Submit

1. Read your own diff
2. Remove debug code
3. Check for secrets
4. Verify CI passes

Code Review (for reviewers)

Review Checklist

Feedback Severity

Refactoring

Refactor = change structure, NOT behavior.

Before Refactoring

Ask: "If I break something, will existing tests catch it?"

Without confidence that existing tests will catch regressions, refactoring is risky — you could break behavior without knowing. Add tests first, then refactor safely.

Multi-Agent Collaboration

When multiple agents work in parallel:

# Each agent uses isolated worktree
git worktree add ../project-<role> <branch>

Each agent follows the full workflow for their role. Cutting corners in multi-agent mode is especially dangerous because no single agent has full context — the workflow compensates for that.

Domain Review (Conditional)

If the project's AGENTS.md contains ## Domain Review Protocol, load references/domain-review.md and apply these additional intervention points:

• Brief-In before exploration: explain what will be built and list upcoming domain decisions
• Checkpoint during design/implementation: pause at domain-laden decisions for human confirmation
• Brief-Out before commit: summarize embedded assumptions, structural vs tunable decisions

Checkpoints are blocking (wait for human). Brief-Out is a soft gate (no objection = proceed).

Skip checkpoint if the decision is already explicit in the design doc and confirmed during project-init. In non-interactive contexts, use design doc defaults and list all decisions in the PR description.

Quick Reference

How to Choose

• "I need to add something new" → Feature flow
• "Something is broken" → Bug Fix flow
• "The code works but needs restructuring" → Refactor flow
• "I need to review someone's code" → Code Review section
• "Multiple agents working together" → Multi-Agent section

Typical Flows

Feature: Exploration → Design → Implementation → Pre-Commit → PR

Bug Fix: Exploration → Bug Fix → Pre-Commit → PR

Refactor: Exploration → (verify test coverage) → Design → Implementation → Pre-Commit → PR

Task Status (if project uses tracking)

Pending → In Progress → In Review → Done

Roadmap format: | ID | Priority | Item | Status | GH |