Dev Workflow

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

Core Principles

1. •Code is truth — Read code first; docs may be outdated
2. •Design before code — Write tests before implementation
3. •Tests are design — Tests define behavior, not just verify it
4. •Minimal blast radius — Touch only necessary files

Priority Stack

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

Phase 1: Exploration

Do this FIRST before any planning or coding.

Required Steps

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

Phase 2: Design

STOP. Do not write implementation code until tests are written.

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

Rule: If you can't write a test, you don't understand the requirement yet.

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

STOP. Do not touch code until you can reproduce the bug.

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

Rule: When a fix fails, don't patch it. Re-examine assumptions.

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

Rule: If tests don't pass, don't move forward.

Phase 4: Pre-Commit

Complete ALL steps before git commit.

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?"

Rule: No test coverage confidence = no permission to refactor.

Multi-Agent Collaboration

When multiple agents work in parallel:

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

Rule: Each agent still follows full workflow for their role.

Quick Reference

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 |