dot-do avatar

workers-do

Core skills for workers.do platform development

version
0.1.0
GitHub stars
6

Install

/plugin install workers-do@workers-do-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dot-do/workers.

Contents

Discovered from source

Skills 5

Beads Issue Tracking with TDD Workflow

Overview

Beads (bd) is a git-native issue tracker that lives in your repository. Use it to track multi-session work with dependency graphs. For TDD workflows, create separate issues for each phase: RED, GREEN, REFACTOR.

When to Use Beads vs TodoWrite

Use BeadsUse TodoWrite
Multi-session workSingle session tasks
Complex dependenciesLinear task lists
Needs persistent contextEphemeral tracking
TDD phase trackingSimple checklists
Collaborative workSolo quick tasks

TDD Workflow with Beads

Phase 1: RED (Failing Tests)

Create an issue for writing the failing test:

bd create --title="RED: [Feature] tests" --type=task --priority=0 --labels="tdd-red,[feature-area]"

Issue content should include:

  • What behavior the test should verify
  • Expected inputs and outputs
  • Edge cases to cover

Mark in_progress when starting:

bd update [issue-id] --status=in_progress

Close when test is written and failing:

bd close [issue-id] --reason="Test written, failing as expected"

Phase 2: GREEN (Minimal Implementation)

Create an issue for the implementation (depends on RED):

bd create --title="GREEN: Implement [Feature]" --type=task --priority=0 --labels="tdd-green,[feature-area]"
bd dep add [green-id] [red-id]  # GREEN depends on RED

Issue content should include:

  • Link to the RED issue
  • Minimal approach to make tests pass
  • No extra features (YAGNI)

Close when tests pass:

bd close [issue-id] --reason="Tests passing"

Phase 3: REFACTOR (Clean Up)

Create an issue for refactoring (depends on GREEN):

bd create --title="REFACTOR: Clean up [Feature]" --type=task --priority=1 --labels="tdd-refactor,[feature-area]"
bd dep add [refactor-id] [green-id]  # REFACTOR depends on GREEN

Issue content should include:

  • What needs cleaning (duplication, naming, extraction)
  • Keep tests green throughout

Close when refactoring complete:

bd close [issue-id] --reason="Refactored, tests still green"

Essential Commands

Finding Work

bd ready                    # Show issues with no blockers
bd list --status=open       # All open issues
bd list --status=in_progress # Active work
bd blocked                  # See what's blocked and why

Creating Issues

bd create --title="..." --type=task|bug|feature|epic --priority=0-4
# Priority: 0=critical, 1=high, 2=medium, 3=low, 4=backlog

Managing Dependencies

bd dep add [issue] [depends-on]  # issue is blocked by depends-on
bd show [issue]                   # See dependencies and dependents

Updating Status

bd update [id] --status=in_progress  # Claim work
bd update [id] --status=blocked      # Mark blocked
bd close [id]                        # Complete work
bd close [id1] [id2] [id3]          # Close multiple at once

Syncing

bd sync --from-main    # Pull beads updates from main branch
bd sync --status       # Check sync status

TDD Labels Convention

Use these labels consistently:

LabelPhaseDescription
tdd-redREDWriting failing tests
tdd-greenGREENImplementing to pass tests
tdd-refactorREFACTORCleaning up while green

Plus feature-area labels like: auth, api, ui, database, etc.

Example: Adding User Authentication

# 1. Create RED issue
bd create --title="RED: User authentication tests" \
  --type=task --priority=0 \
  --labels="tdd-red,auth" \
  --description="Write tests for login, logout, session management"

# 2. Create GREEN issue (blocked by RED)
bd create --title="GREEN: Implement user authentication" \
  --type=task --priority=0 \
  --labels="tdd-green,auth"
bd dep add workers-xxxx workers-yyyy  # GREEN blocked by RED

# 3. Create REFACTOR issue (blocked by GREEN)
bd create --title="REFACTOR: Clean up auth module" \
  --type=task --priority=1 \
  --labels="tdd-refactor,auth"
bd dep add workers-zzzz workers-xxxx  # REFACTOR blocked by GREEN

# 4. Work through in order
bd update workers-yyyy --status=in_progress  # Start RED
# ... write tests ...
bd close workers-yyyy --reason="Tests written, failing"

bd update workers-xxxx --status=in_progress  # Start GREEN
# ... implement ...
bd close workers-xxxx --reason="Tests passing"

bd update workers-zzzz --status=in_progress  # Start REFACTOR
# ... refactor ...
bd close workers-zzzz --reason="Refactored, tests green"

Parallel TDD with Subagents

For large features, use parallel subagents to create TDD issue chains:

Launch parallel agents to create beads issues for each module:
- Agent 1: Create RED/GREEN/REFACTOR chain for Module A
- Agent 2: Create RED/GREEN/REFACTOR chain for Module B
- Agent 3: Create RED/GREEN/REFACTOR chain for Module C

Each agent creates 3 issues with proper dependencies.

Session Management

Starting a Session

bd ready                    # Find available work
bd show [id]               # Review issue details
bd update [id] --status=in_progress

Ending a Session

bd close [completed-ids]   # Close finished work
bd sync --from-main        # Pull latest from main
git add . && git commit    # Commit changes

Key Principles

  1. One issue per TDD phase - Don't combine RED/GREEN/REFACTOR
  2. Dependencies enforce order - GREEN blocked by RED, REFACTOR blocked by GREEN
  3. Close immediately - Mark done as soon as phase completes
  4. Labels for filtering - Use tdd-* labels to find phase-specific work
  5. Sync regularly - Keep beads in sync with main branch

Brainstorming Ideas Into Designs

Overview

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.

The Process

Understanding the idea:

  • Check out the current project state first (files, docs, recent commits)
  • Ask questions one at a time to refine the idea
  • Prefer multiple choice questions when possible, but open-ended is fine too
  • Only one question per message - if a topic needs more exploration, break it into multiple questions
  • Focus on understanding: purpose, constraints, success criteria

Exploring approaches:

  • Propose 2-3 different approaches with trade-offs
  • Present options conversationally with your recommendation and reasoning
  • Lead with your recommended option and explain why

Presenting the design:

  • Once you believe you understand what you're building, present the design
  • Break it into sections of 200-300 words
  • Ask after each section whether it looks right so far
  • Cover: architecture, components, data flow, error handling, testing
  • Be ready to go back and clarify if something doesn't make sense

After the Design

Documentation:

  • Write the validated design to docs/plans/YYYY-MM-DD-<topic>-design.md
  • Use elements-of-style:writing-clearly-and-concisely skill if available
  • Commit the design document to git

Implementation (if continuing):

  • Ask: "Ready to set up for implementation?"
  • Use superpowers:using-git-worktrees to create isolated workspace
  • Use superpowers:writing-plans to create detailed implementation plan

Key Principles

  • One question at a time - Don't overwhelm with multiple questions
  • Multiple choice preferred - Easier to answer than open-ended when possible
  • YAGNI ruthlessly - Remove unnecessary features from all designs
  • Explore alternatives - Always propose 2-3 approaches before settling
  • Incremental validation - Present design in sections, validate each
  • Be flexible - Go back and clarify when something doesn't make sense

Parallel Code Review

Overview

Conduct a comprehensive code review by dispatching 5 parallel subagents, each with a specialized focus. Results are synthesized into a unified review.

When to Use

  • Before merging significant changes
  • After completing feature implementation
  • When reviewing PRs from others
  • Before deployment of major features

The Process

Step 1: Gather Context

First, collect the changes to review:

  • For PRs: gh pr diff
  • For local changes: git diff main...HEAD or git diff --staged
  • Identify modified files and their purposes

Step 2: Launch Parallel Subagents

Launch 5 parallel Sonnet agents using the Task tool, each with a specialized review focus:

Use the Task tool to launch 5 agents IN PARALLEL (single message, multiple tool calls):
Agent 1: General Code Review
Review these changes for:
- Obvious bugs and logic errors
- Error handling gaps
- Edge cases not covered
- Code clarity and readability
- Test coverage for new code
- Security vulnerabilities (injection, auth, data exposure)

Focus on issues that would cause runtime failures or incorrect behavior.
Ignore style/formatting issues caught by linters.

Return a list of issues with:
- Severity (critical/high/medium/low)
- File and line reference
- Description and suggested fix
Agent 2: Architectural Review
Review these changes for architectural concerns:
- Does this follow existing patterns in the codebase?
- Are dependencies appropriate (no circular deps, correct layer boundaries)?
- Is the abstraction level correct (not too abstract, not too concrete)?
- Does this scale appropriately?
- Are there better existing utilities/helpers that should be used?
- Does this introduce technical debt?

Check consistency with CLAUDE.md and ARCHITECTURE.md if present.

Return architectural concerns with:
- Impact level (breaking/significant/minor)
- Description of the concern
- Recommended approach
Agent 3: TypeScript Review
Review these TypeScript changes for:
- Type safety issues (any abuse, unsafe casts, missing null checks)
- Generic usage (correct constraints, inference issues)
- Interface/type design (appropriate use of interfaces vs types)
- Import organization and module boundaries
- Async/await correctness (missing awaits, unhandled promises)
- Potential runtime type mismatches

Assume the code compiles - focus on semantic type issues.

Return TypeScript issues with:
- File and line reference
- The problematic pattern
- Type-safe alternative
Agent 4: Product/Vision/Roadmap Review
Review these changes against the project's vision and direction:
- Read README.md, CLAUDE.md, and any docs/ for project context
- Check recent git history to understand where the project is heading
- Does this change align with the project's goals?
- Does it conflict with planned features or recent direction changes?
- Are there naming/API inconsistencies with the broader product?
- Does this maintain the project's design philosophy?

Return alignment concerns with:
- What aspect of vision/roadmap it affects
- How the change diverges
- Suggestion to realign (or note if intentional evolution)
Agent 5: TDD & Beads Compliance Review
Review these changes for TDD discipline and beads issue tracking:

**TDD Compliance:**
- Are there corresponding test files for new code?
- Do tests follow RED-GREEN-REFACTOR pattern?
- Were tests written BEFORE implementation? (check git history/commits)
- Are test names clear and behavior-focused?
- Is test coverage adequate for the changes?
- Are there any implementation files without corresponding tests?

**Beads Issue Tracking:**
- Check `bd list` for related issues
- Are changes linked to beads issues?
- Do beads issues follow TDD labeling convention?
  - `tdd-red` labels for failing test issues
  - `tdd-green` labels for implementation issues
  - `tdd-refactor` labels for refactoring issues
- Are there orphaned changes not tracked in beads?
- Should new beads issues be created for discovered work?

**Workflow Compliance:**
- Is work being done in the right order? (red → green → refactor)
- Are dependencies between issues correct?
- Are issues being closed as work completes?

Return TDD/beads compliance issues with:
- Type (missing-test / wrong-order / untracked-work / missing-issue)
- File or feature affected
- Recommended action (create issue, add test, update labels)

Step 3: Synthesize Results

After all agents complete:

  1. Deduplicate: Remove issues flagged by multiple agents
  2. Prioritize: Sort by severity/impact
  3. Filter: Remove likely false positives:
    • Pre-existing issues not introduced by this change
    • Issues that linters/compilers would catch
    • Purely stylistic concerns not in CLAUDE.md
  4. Verify: For critical issues, spot-check the code yourself

Step 4: Present Findings

Format the review as:

## Code Review Summary

**Files reviewed**: [list]
**Overall assessment**: [APPROVE / REQUEST CHANGES / COMMENT]

### Critical Issues (must fix)
1. [Issue] - [File:Line] - [Which review found it]

### Recommended Changes
1. [Issue] - [File:Line] - [Which review found it]

### Minor Suggestions
1. [Suggestion] - [File:Line]

### Positive Observations
- [What was done well]

Key Principles

  • Parallel execution: All 5 agents run simultaneously for speed
  • Specialized focus: Each agent has deep expertise in their domain
  • Synthesis over duplication: Consolidate overlapping findings
  • Signal over noise: Filter aggressively to surface real issues
  • Actionable feedback: Every issue should have a clear resolution path

Agent Configuration

When launching agents:

  • Use model: "sonnet" for thorough analysis
  • Include the full diff/changes in each agent's prompt
  • Include relevant context files (CLAUDE.md, README.md, package.json)
  • Set clear expectations for output format

Example Invocation

I need to review the changes in this PR. Let me launch 5 parallel review agents.

[Launch Task tool 5 times in a SINGLE message with the specialized prompts above]

Development Loop - The Outer Loop for Ralph

Overview

A complete development workflow that wraps Ralph with planning, review, and feedback cycles. Think of it as an "outer loop" that ensures quality through iterative refinement.

┌─────────────────────────────────────────────────────────────┐
│                    DEVELOPMENT LOOP                          │
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────────┐  │
│  │BRAINSTORM│───▶│  PLAN    │───▶│   RALPH IMPLEMENT    │  │
│  │          │    │(superthink)   │   (inner loop)       │  │
│  └──────────┘    └──────────┘    └──────────┬───────────┘  │
│                                              │              │
│                                              ▼              │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────────┐  │
│  │ APPROVED │◀───│  REVIEW  │◀───│   5-AGENT REVIEW     │  │
│  │  (exit)  │    │(decision)│    │                      │  │
│  └──────────┘    └────┬─────┘    └──────────────────────┘  │
│                       │ needs work                          │
│                       ▼                                     │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              FEEDBACK LOOP                            │  │
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐       │  │
│  │  │ FEEDBACK │───▶│  RALPH   │───▶│  REVIEW  │──┐    │  │
│  │  │  PLAN    │    │   FIX    │    │          │  │    │  │
│  │  └──────────┘    └──────────┘    └──────────┘  │    │  │
│  │       ▲                                        │    │  │
│  │       └────────── needs more work ─────────────┘    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

The Phases

Phase 1: BRAINSTORM

Goal: Understand what to build through collaborative dialogue.

  • Invoke workers-do:brainstorming skill
  • Ask questions one at a time
  • Explore approaches and trade-offs
  • Output: Design document in docs/plans/

Exit criteria: User approves the design

Phase 2: PLAN (Superthink)

Goal: Create TDD beads issues with extended thinking.

Use extended thinking to:

  1. Break design into implementable modules
  2. For each module, create beads issue chain:
    • RED: [Module] tests (tdd-red label)
    • GREEN: Implement [Module] (tdd-green label, blocked by RED)
    • REFACTOR: Clean up [Module] (tdd-refactor label, blocked by GREEN)
  3. Set up cross-module dependencies
  4. Prioritize order of work

Output: Beads issues with full dependency graph

Exit criteria: Issue plan reviewed and approved

Phase 3: IMPLEMENT (Ralph Loop)

Goal: Autonomous implementation following TDD.

Start Ralph loop with prompt:

Work through beads issues in dependency order.
For each issue:
1. Claim it (bd update --status=in_progress)
2. Follow TDD: write test (RED), implement (GREEN), refactor
3. Close it (bd close)
4. Move to next ready issue (bd ready)

Continue until all issues are closed.
Output <promise>IMPLEMENTATION COMPLETE</promise> when done.

Exit criteria: All beads issues closed, tests passing

Phase 4: REVIEW (5-Agent)

Goal: Comprehensive quality check.

Launch 5 parallel review agents:

  1. General code review
  2. Architectural review
  3. TypeScript review
  4. Product/vision review
  5. TDD/beads compliance review

Output: Synthesized review with findings

Decision point:

  • APPROVED → Exit loop, work is done
  • NEEDS WORK → Continue to Phase 5

Phase 5: FEEDBACK PLAN (Superthink)

Goal: Convert review feedback into actionable issues.

Use extended thinking to:

  1. Analyze each review finding
  2. Create beads issues for fixes:
    • FIX: [Finding description] with appropriate labels
  3. Set priorities based on severity
  4. Add dependencies if fixes depend on each other

Output: New beads issues for fixes

Phase 6: FIX (Ralph Loop)

Goal: Address review findings.

Start Ralph loop with prompt:

Work through fix issues from code review.
For each issue:
1. Claim it
2. Implement the fix following TDD
3. Verify tests pass
4. Close it

Output <promise>FIXES COMPLETE</promise> when all fix issues closed.

Phase 7: FINAL REVIEW

Goal: Verify fixes and decide if done.

Run 5-agent review again, focused on:

  • Were the findings addressed?
  • Any new issues introduced?
  • Overall quality assessment

Decision:

  • APPROVED → Exit, publish/merge
  • NEEDS MORE WORK → Loop back to Phase 5

State Management

The loop tracks state in .claude/dev-loop.local.md:

---
phase: IMPLEMENT  # Current phase
iteration: 1      # Which review cycle
started_at: "2024-01-01T00:00:00Z"
design_doc: "docs/plans/2024-01-01-feature-design.md"
initial_issues: ["workers-xxx", "workers-yyy"]
fix_issues: []
review_findings: []
---

Original task description here...

Commands

/dev-loop "task description"

Start a new development loop.

/dev-loop-status

Show current phase and progress.

/dev-loop-advance

Manually advance to next phase (for human checkpoints).

/dev-loop-cancel

Cancel the loop and clean up.

Human Checkpoints

The loop pauses for human approval at:

  1. After BRAINSTORM - Approve design before planning
  2. After PLAN - Review issues before implementation
  3. After REVIEW - Decide: approved or needs work
  4. After FINAL REVIEW - Final approval or more iteration

Extended Thinking Integration

Phases 2 and 5 use "superthink" - extended thinking mode for:

  • Deep analysis of requirements
  • Comprehensive issue breakdown
  • Thorough dependency mapping
  • Quality feedback analysis

Enable with: thinking: extended in prompts or model configuration.

Example Usage

# Start the loop
/dev-loop "Add user authentication with JWT tokens, SSO support, and session management"

# Loop will:
# 1. Brainstorm with you about auth requirements
# 2. Create TDD issues for auth module
# 3. Ralph-loop implement the auth system
# 4. 5-agent review the implementation
# 5. Create fix issues from feedback
# 6. Ralph-loop the fixes
# 7. Final review → approve or iterate

Key Principles

  1. Quality over speed - Multiple review cycles ensure quality
  2. TDD throughout - Every implementation follows RED-GREEN-REFACTOR
  3. Tracked work - All work captured in beads issues
  4. Human oversight - Key decisions require human approval
  5. Autonomous execution - Ralph handles implementation phases
  6. Comprehensive review - 5 specialized perspectives catch issues

When to Use

Good for:

  • Significant features (multi-day work)
  • Complex implementations
  • High-quality requirements
  • Work that needs documentation

Not good for:

  • Quick fixes (use simple TDD)
  • Exploratory work (use just brainstorming)
  • Urgent hotfixes (skip the loop)

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Violating the letter of the rules is violating the spirit of the rules.

When to Use

Always:

  • New features
  • Bug fixes
  • Refactoring
  • Behavior changes

Exceptions (ask your human partner):

  • Throwaway prototypes
  • Generated code
  • Configuration files

Thinking "skip TDD just this once"? Stop. That's rationalization.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete

Implement fresh from tests. Period.

Red-Green-Refactor

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

RED - Write Failing Test

Write one minimal test showing what should happen.

```typescript test('retries failed operations 3 times', async () => { let attempts = 0; const operation = () => { attempts++; if (attempts < 3) throw new Error('fail'); return 'success'; };

const result = await retryOperation(operation);

expect(result).toBe('success'); expect(attempts).toBe(3); });

Clear name, tests real behavior, one thing
</Good>

<Bad>
```typescript
test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

Vague name, tests mock not code

Requirements:

  • One behavior
  • Clear name
  • Real code (no mocks unless unavoidable)

Verify RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

  • Test fails (not errors)
  • Failure message is expected
  • Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

GREEN - Minimal Code

Write simplest code to pass the test.

```typescript async function retryOperation(fn: () => Promise): Promise { for (let i = 0; i < 3; i++) { try { return await fn(); } catch (e) { if (i === 2) throw e; } } throw new Error('unreachable'); } ``` Just enough to pass ```typescript async function retryOperation( fn: () => Promise, options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (attempt: number) => void; } ): Promise { // YAGNI } ``` Over-engineered

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

  • Test passes
  • Other tests still pass
  • Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

REFACTOR - Clean Up

After green only:

  • Remove duplication
  • Improve names
  • Extract helpers

Keep tests green. Don't add behavior.

Repeat

Next failing test for next feature.

Good Tests

QualityGoodBad
MinimalOne thing. "and" in name? Split it.test('validates email and domain and whitespace')
ClearName describes behaviortest('test1')
Shows intentDemonstrates desired APIObscures what code should do

Why Order Matters

"I'll write tests after to verify it works"

Tests written after code pass immediately. Passing immediately proves nothing:

  • Might test wrong thing
  • Might test implementation, not behavior
  • Might miss edge cases you forgot
  • You never saw it catch the bug

Test-first forces you to see the test fail, proving it actually tests something.

"I already manually tested all the edge cases"

Manual testing is ad-hoc. You think you tested everything but:

  • No record of what you tested
  • Can't re-run when code changes
  • Easy to forget cases under pressure
  • "It worked when I tried it" ≠ comprehensive

Automated tests are systematic. They run the same way every time.

"Deleting X hours of work is wasteful"

Sunk cost fallacy. The time is already gone. Your choice now:

  • Delete and rewrite with TDD (X more hours, high confidence)
  • Keep it and add tests after (30 min, low confidence, likely bugs)

The "waste" is keeping code you can't trust. Working code without real tests is technical debt.

"TDD is dogmatic, being pragmatic means adapting"

TDD IS pragmatic:

  • Finds bugs before commit (faster than debugging after)
  • Prevents regressions (tests catch breaks immediately)
  • Documents behavior (tests show how to use code)
  • Enables refactoring (change freely, tests catch breaks)

"Pragmatic" shortcuts = debugging in production = slower.

"Tests after achieve the same goals - it's spirit not ritual"

No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"

Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.

Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).

30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.

Common Rationalizations

ExcuseReality
"Too simple to test"Simple code breaks. Test takes 30 seconds.
"I'll test after"Tests passing immediately prove nothing.
"Tests after achieve same goals"Tests-after = "what does this do?" Tests-first = "what should this do?"
"Already manually tested"Ad-hoc ≠ systematic. No record, can't re-run.
"Deleting X hours is wasteful"Sunk cost fallacy. Keeping unverified code is technical debt.
"Keep as reference, write tests first"You'll adapt it. That's testing after. Delete means delete.
"Need to explore first"Fine. Throw away exploration, start with TDD.
"Test hard = design unclear"Listen to test. Hard to test = hard to use.
"TDD will slow me down"TDD faster than debugging. Pragmatic = test-first.
"Manual test faster"Manual doesn't prove edge cases. You'll re-test every change.
"Existing code has no tests"You're improving it. Add tests for existing code.

Red Flags - STOP and Start Over

  • Code before test
  • Test after implementation
  • Test passes immediately
  • Can't explain why test failed
  • Tests added "later"
  • Rationalizing "just this once"
  • "I already manually tested it"
  • "Tests after achieve the same purpose"
  • "It's about spirit not ritual"
  • "Keep as reference" or "adapt existing code"
  • "Already spent X hours, deleting is wasteful"
  • "TDD is dogmatic, I'm being pragmatic"
  • "This is different because..."

All of these mean: Delete code. Start over with TDD.

Example: Bug Fix

Bug: Empty email accepted

RED

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Verify RED

$ npm test
FAIL: expected 'Email required', got undefined

GREEN

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

Verify GREEN

$ npm test
PASS

REFACTOR Extract validation for multiple fields if needed.

Verification Checklist

Before marking work complete:

  • Every new function/method has a test
  • Watched each test fail before implementing
  • Each test failed for expected reason (feature missing, not typo)
  • Wrote minimal code to pass each test
  • All tests pass
  • Output pristine (no errors, warnings)
  • Tests use real code (mocks only if unavoidable)
  • Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

When Stuck

ProblemSolution
Don't know how to testWrite wished-for API. Write assertion first. Ask your human partner.
Test too complicatedDesign too complicated. Simplify interface.
Must mock everythingCode too coupled. Use dependency injection.
Test setup hugeExtract helpers. Still complex? Simplify design.

Debugging Integration

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.

Never fix bugs without a test.

Testing Anti-Patterns

When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:

  • Testing mock behavior instead of real behavior
  • Adding test-only methods to production classes
  • Mocking without understanding dependencies

Final Rule

Production code → test exists and failed first
Otherwise → not TDD

No exceptions without your human partner's permission.

Commands 4

Invoke the workers-do:beads skill and follow it exactly as presented to you

Invoke the workers-do:brainstorming skill and follow it exactly as presented to you

Parallel Code Review

Invoke the workers-do:code-review skill and follow it exactly.

Launch 5 parallel Sonnet agents to review the changes:

  1. General: Bugs, logic errors, security, test coverage
  2. Architectural: Patterns, dependencies, abstraction, scaling
  3. TypeScript: Type safety, generics, async correctness
  4. Product/Vision: Alignment with project goals, naming, roadmap
  5. TDD/Beads: Test discipline, RED-GREEN-REFACTOR, beads issue tracking

After gathering results, synthesize into a unified review with prioritized findings.

Invoke the workers-do:test-driven-development skill and follow it exactly as presented to you

Agents 2

agents.do

You're building something great. You need a team.

You're a founder. You have the vision. But right now it's just you, or maybe a tiny crew. You need people who can turn ideas into reality.

Meet your team:

import { priya, ralph, tom, rae, mark, sally, quinn } from 'agents.do'

priya`what should we build first?`
ralph`build that for me`
tom`review Ralph's work`

That's it. Just talk to them.

Your Core Team

Priya is your product partner. Tell her what you're thinking, and she'll help you shape it.

priya`I want to build a marketplace for freelance designers`
priya`what's the simplest version we could ship this week?`
priya`prioritize these features for me: ${ideas}`

Ralph is your developer. Give him a task, he builds it.

ralph`build user authentication`
ralph`add Stripe payments`
ralph`fix that bug where users can't upload images`

Tom is your tech lead. He keeps the code clean and catches issues.

tom`review what Ralph just built`
tom`is this architecture going to scale?`
tom`check for security issues`

Rae is your frontend specialist. She makes it beautiful and accessible.

rae`design the user dashboard`
rae`make this form more intuitive`
rae`ensure our app is accessible`

Mark is your marketing voice. He writes copy that converts.

mark`write the landing page copy`
mark`create documentation for this API`
mark`draft the launch announcement`

Sally is your sales closer. She helps you land customers.

sally`reach out to these leads: ${prospects}`
sally`prepare a demo for this customer`
sally`help me close this deal`

Quinn is your QA engineer. She finds the bugs before your users do.

quinn`test the checkout flow`
quinn`what edge cases are we missing?`
quinn`verify this works on mobile`

Talk Like They're Real

Because they are. No special syntax. No configuration. Just say what you need:

// Be specific
ralph`implement OAuth with Google and GitHub using Better Auth`

// Or be vague
ralph`add social login`

// They figure it out

Work Flows Naturally

Hand off work from one teammate to the next:

const plan = await priya`plan our MVP`
const code = await ralph`build ${plan}`
const review = await tom`review ${code}`

Parallel When You Need It

Get multiple perspectives at once:

const feedback = await Promise.all([
  priya`does this solve the user problem?`,
  tom`is the implementation solid?`,
])

Real GitHub Accounts

When Tom reviews your PR, you'll see @tom-do commenting. When Ralph pushes code, it's from his account. They're real team members with real identities.

priya.github // 'priya-do'
ralph.github // 'ralph-do'
tom.github   // 'tom-do'
rae.github   // 'rae-do'
mark.github  // 'mark-do'
sally.github // 'sally-do'
quinn.github // 'quinn-do'

Your Journey

Week 1: You have an idea.

priya`help me think through this idea: ${pitch}`

Week 2: You have a plan.

const mvp = await priya`what's the smallest thing we can ship?`
await ralph`build ${mvp}`

Week 4: You have a product.

await tom`make sure everything is production-ready`

Month 2: You have customers.

Month 6: You hire your first human. Your agents trained them on the codebase.


They're not replacing the humans you'll eventually hire. They're giving you leverage until you get there.

Welcome to your team.

agents.do | priya.do | ralph.do | tom.do | rae.do | mark.do | sally.do | quinn.do

Code Reviewer Agent

You are a specialized code review agent. Your role is to thoroughly review code changes and identify issues.

Your Focus Area

You will be given a specific focus area (general, architectural, TypeScript, or product/vision). Stay within your assigned scope.

Review Guidelines

  1. Be thorough but practical - Flag real issues, not theoretical concerns
  2. Provide evidence - Cite specific lines and explain why it's an issue
  3. Suggest fixes - Don't just identify problems, propose solutions
  4. Respect context - Consider the project's existing patterns and constraints
  5. Prioritize - Distinguish critical bugs from nice-to-haves

Output Format

Return your findings as a structured list:

### [Focus Area] Review

**Issues Found**: N

1. **[Severity: critical/high/medium/low]** - `file.ts:123`
   - **Issue**: Description of the problem
   - **Why it matters**: Impact explanation
   - **Suggested fix**: How to resolve it

2. ...

**No issues found in scope** (if applicable)

What NOT to Flag

  • Pre-existing issues not in this change
  • Style/formatting (handled by linters)
  • Missing features (unless breaking existing contracts)
  • Hypothetical future problems (YAGNI)

Sponsors

Details

Marketplace
dot-do/workers
Author
workers.do
Category
Community

More from dot-do/workers

All 3