
workers-do
Core skills for workers.do platform development
- version
- 0.1.0
- GitHub stars
- 6
Install
/plugin install workers-do@workers-do-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add dot-do/workers.
Contents
Discovered from sourceSkills 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 Beads | Use TodoWrite |
|---|---|
| Multi-session work | Single session tasks |
| Complex dependencies | Linear task lists |
| Needs persistent context | Ephemeral tracking |
| TDD phase tracking | Simple checklists |
| Collaborative work | Solo 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:
| Label | Phase | Description |
|---|---|---|
tdd-red | RED | Writing failing tests |
tdd-green | GREEN | Implementing to pass tests |
tdd-refactor | REFACTOR | Cleaning 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
- One issue per TDD phase - Don't combine RED/GREEN/REFACTOR
- Dependencies enforce order - GREEN blocked by RED, REFACTOR blocked by GREEN
- Close immediately - Mark done as soon as phase completes
- Labels for filtering - Use
tdd-*labels to find phase-specific work - 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...HEADorgit 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:
- Deduplicate: Remove issues flagged by multiple agents
- Prioritize: Sort by severity/impact
- 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
- 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:brainstormingskill - 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:
- Break design into implementable modules
- 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)
- Set up cross-module dependencies
- 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:
- General code review
- Architectural review
- TypeScript review
- Product/vision review
- 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:
- Analyze each review finding
- Create beads issues for fixes:
FIX: [Finding description]with appropriate labels
- Set priorities based on severity
- 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:
- After BRAINSTORM - Approve design before planning
- After PLAN - Review issues before implementation
- After REVIEW - Decide: approved or needs work
- 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
- Quality over speed - Multiple review cycles ensure quality
- TDD throughout - Every implementation follows RED-GREEN-REFACTOR
- Tracked work - All work captured in beads issues
- Human oversight - Key decisions require human approval
- Autonomous execution - Ralph handles implementation phases
- 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-engineeredDon'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
| Quality | Good | Bad |
|---|---|---|
| Minimal | One thing. "and" in name? Split it. | test('validates email and domain and whitespace') |
| Clear | Name describes behavior | test('test1') |
| Shows intent | Demonstrates desired API | Obscures 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
| Excuse | Reality |
|---|---|
| "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
| Problem | Solution |
|---|---|
| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
| Test too complicated | Design too complicated. Simplify interface. |
| Must mock everything | Code too coupled. Use dependency injection. |
| Test setup huge | Extract 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:
- General: Bugs, logic errors, security, test coverage
- Architectural: Patterns, dependencies, abstraction, scaling
- TypeScript: Type safety, generics, async correctness
- Product/Vision: Alignment with project goals, naming, roadmap
- 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
- Be thorough but practical - Flag real issues, not theoretical concerns
- Provide evidence - Cite specific lines and explain why it's an issue
- Suggest fixes - Don't just identify problems, propose solutions
- Respect context - Consider the project's existing patterns and constraints
- 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