tomevault-io Dev Workflow
Engineering standards for code changes. Follow these phases in order.
Core Principles
- Code is truth — Read code first. Docs drift over time; the running code is what actually ships.
- Design before code — Write tests before implementation. Tests force you to define "done" before you start, preventing scope creep and rework.
- Tests are design — Tests define behavior, not just verify it. A well-written test suite IS the specification.
- 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
- 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 - Create branch:
git checkout -b feature/<name>orfix/<name> - Read relevant code — Understand patterns, find insertion points
- Check if already exists — Search for similar implementations
- Verify docs ↔ code sync — If drift found, fix docs first
Exploration Order
| Step | What to Find |
|---|---|
| 1 | Entry points: main.py, index.ts, main.go |
| 2 | Routes/API handlers |
| 3 | Config files |
| 4 | Related modules (follow imports) |
| 5 | Existing tests |
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
- Define behavior: What does it do? Input → Output?
- Identify test cases:
- Happy path (normal success flow)
- Edge cases (empty, max, concurrent)
- Error cases (what should fail?)
- Write tests FIRST — Tests must fail before implementation exists
Minimum Tests by Change Type
| Change Type | Required Tests |
|---|---|
| New feature | Happy path + edge cases + error handling |
| Bug fix | Reproduces bug + regression guard |
| Refactor | Existing tests must pass; add if coverage insufficient |
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
- Reproduce — Confirm bug exists; if cannot reproduce, ask for more info
- Write failing test — The test IS your bug report
- Understand root cause — Why it fails, not just where
- Fix minimally — Smallest change that makes test pass
- Verify — Failing test passes; full suite passes
When Fix Attempt Fails
| Signal | Action |
|---|---|
| Test passes but bug persists | You're testing wrong thing → get real user data |
| Fix works but breaks something | Patching symptoms → find actual root cause |
| Adding more edge cases | Approach flawed → consider architecture change |
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
- Run failing tests — Confirm they fail for expected reason
- Write minimal code — Just enough to make tests pass
- Run tests again — Confirm they pass
- 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
| Change Type | Section |
|---|---|
| New feature | ### Added |
| Bug fix | ### Fixed |
| Breaking change | ### Changed |
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
- Read your own diff
- Remove debug code
- Check for secrets
- Verify CI passes
Code Review (for reviewers)
Review Checklist
| Priority | Check |
|---|---|
| 1. Security | No secrets, input validation |
| 2. Correctness | Logic matches intent, edge cases handled |
| 3. Tests | Tests exist for changes, CI green |
| 4. Docs | CHANGELOG/README updated |
Feedback Severity
| Severity | Action |
|---|---|
| Security/Logic error | Block merge |
| Missing tests/docs | Block merge |
| Style/naming | Comment as nit; don't block |
Refactoring
Refactor = change structure, NOT behavior.
Before Refactoring
Ask: "If I break something, will existing tests catch it?"
| Answer | Action |
|---|---|
| Yes | Proceed |
| No / Unsure | Add tests first |
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>
| Role | Workflow |
|---|---|
| Planning | Exploration → define scope |
| Implementation | Exploration → Design → Implementation → Commit → PR |
| Bug fix | Exploration → Bug Fix → Commit → PR |
| Review | Review checklist |
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 |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.