Development Workflow

Overview

Coordinate design, implementation, refinement, documentation, and review into a cohesive development process.

Development is not linear - it's iterative. Good development alternates between building and refining, with documentation and testing integrated throughout.

When to Use

Use this skill when:

• Starting a new feature or significant change
• Working on bugs that need design thinking
• Any work spanning multiple commits
• Coordinating brainstorming, TDD, and documentation

Don't use for:

• Trivial one-line fixes
• Emergency hotfixes (go direct to TDD)
• Throwaway prototypes

The Development Cycle

Development follows five phases that may repeat:

digraph dev_cycle {
    rankdir=LR;
    design [label="DESIGN\nUnderstand & plan", shape=box, style=filled, fillcolor="#e6f3ff"];
    implement [label="IMPLEMENT\nBuild with TDD", shape=box, style=filled, fillcolor="#ccffcc"];
    refine [label="REFINE\nSimplify & improve", shape=box, style=filled, fillcolor="#fff4cc"];
    document [label="DOCUMENT\nExplain & guide", shape=box, style=filled, fillcolor="#ffe6cc"];
    review [label="REVIEW\nVerify quality", shape=box, style=filled, fillcolor="#ffcccc"];

    design -> implement;
    implement -> refine;
    refine -> document;
    document -> review;
    review -> implement [label="need changes"];
    review -> design [label="major issues"];
}

Phase 1: DESIGN

Goal: Understand what to build before building it.

For complex work:

• Use brainstorming skill for design exploration
• Write design doc: docs/plans/YYYY-MM-DD-topic-design.md
• Commit design before implementing
• Break down plan into bd epic and issues:
  bashCopy

  # Create epic for the feature
  bd create "Feature name from plan" -t epic -p 1 --json
  
  # Create issues for each major component/phase
  bd create "Implement component X" --parent <epic-id> -p 1 --json
  bd create "Add tests for Y" --parent <epic-id> -p 1 --json
  bd create "Document feature" --parent <epic-id> -p 2 --json
  

For simpler work:

• Write brief plan in issue tracker (bd)
• List components that need changes
• Identify edge cases upfront

Outputs:

• Design document OR
• Detailed issue description
• bd epic with subtasks (for complex work)
• Mental checklist of requirements

Phase 2: IMPLEMENT

Goal: Build the feature test-first, incrementally using outside-in development.

Process:

• Use test-driven-development skill (REQUIRED)
• Build outside-in: integration test → unit tests → implementation
  1. Start with failing integration test - specify the public API
  2. Let the integration test guide you - it reveals what components you need
  3. Write unit tests for those components
  4. Implement to make unit tests pass
  5. Return to integration test - it should eventually pass
• Make small, focused commits
• Each commit should have single clear purpose

Outside-in flow:

Integration Test (failing)
    ↓
  Reveals: "Need component X"
    ↓
Unit Tests for X (failing)
    ↓
Implement X (unit tests pass)
    ↓
Repeat for components Y, Z...
    ↓
Integration Test (passing)

The integration test stays red until all components are implemented - this is expected and normal.

Commit patterns:

# ✅ Good: Focused, clear
"Implement loader.go with file discovery and parsing"
"Add integration tests for config file loading"

# ❌ Bad: Too large, vague
"Add configuration feature"
"Update everything"

Commit frequency:

• After completing each logical unit (function, module, test suite)
• When switching contexts (implementation → refactoring)
• Before taking breaks (save progress)

Outputs:

• Working, tested code
• Multiple small commits
• All tests passing

Phase 3: REFINE

Goal: Simplify and improve without adding features.

Look for:

• Custom code that could use stdlib
• Functions that could be inlined
• Duplicate logic that could be shared
• Complex code that could be clearer

Process:

• Make one refinement at a time
• Keep tests green throughout
• Commit each refinement separately

Example refinements:

# Real examples from contagent/1510:
"Replace cutEnv with strings.Cut"
"Inline buildVolumes function and remove function definition"
"Refactor expand_test.go to use t.Run subtests"

When to stop:

• Code is as simple as you can make it
• No obvious improvements remain
• You're about to add features (stop, that's Phase 2)

Outputs:

• Simpler, clearer code
• Same functionality
• More focused commits

Phase 4: DOCUMENT

Goal: Explain what you built and how to use it.

Update as you go:

• README sections affected by changes
• Example config files
• Inline code comments (sparingly, focus on WHY)
• Architecture docs if structure changed

What to document:

# ✅ Document:

- What the feature does (user perspective)
- How to configure/use it
- Examples of common use cases
- Configuration options and defaults

# ❌ Don't document:

- How the code works (code should be self-explanatory)
- What each function does (obvious from names)
- Implementation details users don't need

Outputs:

• Updated README
• Example configurations
• Updated architecture docs if needed

Phase 5: REVIEW

Goal: Verify quality and completeness before finishing.

For significant features:

• Create REVIEW.md with detailed analysis
• Focus on: clarity, correctness, potential bugs
• Include file:line references
• Commit the review document

For all work:

## Quality Checklist

- [ ] All tests pass
- [ ] Test coverage comprehensive (happy path + edge cases + errors)
- [ ] Documentation updated
- [ ] Code simplified (no unnecessary complexity)
- [ ] Commit messages clear
- [ ] Issues referenced in commits
- [ ] No TODOs or placeholders left behind

Outputs:

• REVIEW.md (for significant features)
• Completed checklist
• Clean, shippable code

Iteration and Refinement

Development is iterative:

1. Initial implementation → refine → refine again
2. Discover issue during review → back to implement
3. Realize design needs adjustment → back to design

This is normal and expected.

The cutEnv example from contagent/1510 shows healthy iteration:

• Commit 1: Custom cutEnv implementation
• Commit 2: Replace with strings.Cut
• Commit 3: Inline strings.Cut calls
• Commit 4: Remove cutEnv entirely

Five commits to simplify one helper. That's not waste - that's refinement.

Integration with Issue Tracking

Use bd (beads) for all work:

# Start work
bd ready                           # Find unblocked work
bd update bd-42 --status in_progress

# During work - reference in commits
git commit -m "Implement X

Closes bd-42"

# Complete work
bd close bd-42 --reason "Completed"
git add .beads/issues.jsonl
git commit -m "Update issue tracking"

Commit issue state changes with code changes - keeps them in sync.

Common Mistakes

Skill Integration

This workflow coordinates other skills:

• REQUIRED: test-driven-development for all implementation
• RECOMMENDED: brainstorming for complex features
• OPTIONAL: writing-skills if creating process docs

Example: Adding Config File Support

Real example from contagent/1510 (simplified):

DESIGN:

• Created PLAN.md documenting architecture
• Identified components: loader, merger, expander, integration

IMPLEMENT:

• 10 commits building bottom-up:
  • loader.go with tests
  • merge.go with tests
  • expand.go with tests
  • Integration with existing code
  • CLI flag handling
  • Error handling improvements

REFINE:

• 5 commits simplifying:
  • Replace custom helpers with stdlib
  • Inline small functions
  • Refactor tests to use subtests

DOCUMENT:

• 2 commits adding docs:
  • Comprehensive README section
  • Example .contagent.yaml file

REVIEW:

• 1 commit with detailed REVIEW.md
• Identified bugs and improvements

Total: 18 focused commits over iterative development.

Quick Reference

The Bottom Line

Development is not a waterfall - it's a rhythm.

Design → Implement → Refine → Document → Review → Repeat.

Small commits. Test-first. Simplify continuously. Document as you go. Review before finishing.

This rhythm produces high-quality, maintainable code iteratively.