Smithery is now a part of Arcade.dev! Read more in our announcement here
Executes implementation tasks using Test-Driven Development, prevents code duplication through anti-duplication checks, and maintains quality through continuous testing...
Inputs: tasks.md (20-30 tasks), plan.md (implementation plan) Outputs: Implemented code, test suites, updated tracking files Expected duration: 2-10 days (varies by complexity)
Key principle: Test first, implement second. Never write code without tests.
Validate environment with test run before proceeding.
Before writing any code, load technology constraints from docs/project/tech-stack.md:
# Read tech stack documentation
cat docs/project/tech-stack.md
# Extract: database, framework, libraries, deployment platform
Prevents hallucinating wrong technologies (e.g., suggesting MongoDB when PostgreSQL required).
See resources/tech-stack-validation.md for validation checklist.
Analyze tasks.md for dependency relationships:
# Look for dependencies in tasks.md
T001: Create User model [no dependencies]
T002: Create AuthService [depends: T001]
T003: Create LoginController [depends: T002]
Identify parallel work opportunities:
See resources/task-batching.md for parallel execution strategy.
For complex features (>10 tasks, multiple components), use test-architect agent:
# Launch test-architect to convert acceptance criteria → tests
# Agent reads tasks.md acceptance criteria
# Generates comprehensive test suite (unit + integration + E2E)
Benefits:
See resources/tdd-workflow.md#test-architect for detailed usage.
For each task, follow RED → GREEN → REFACTOR cycle:
RED (Write Failing Test):
def test_user_can_login_with_valid_credentials():
"""Test user authentication with correct email/password"""
user = create_user(email="test@example.com", password="secure123")
result = auth_service.login("test@example.com", "secure123")
assert result.success is True
assert result.user.email == "test@example.com"
assert result.token is not None
GREEN (Minimal Implementation):
def login(email, password):
user = User.query.filter_by(email=email).first()
if user and user.check_password(password):
token = generate_jwt(user.id)
return LoginResult(success=True, user=user, token=token)
return LoginResult(success=False)
REFACTOR (Clean Up):
See resources/tdd-workflow.md for complete RED → GREEN → REFACTOR guide.
After completing each task, update NOTES.md:
## Implementation Progress
- [x] T001: Create User model (45min, 2025-11-19 10:00)
- [x] T002: Create AuthService (60min, 2025-11-19 11:30)
- [ ] T003: Create LoginController (est. 30min)
Track velocity for remaining tasks:
See resources/task-tracking.md for velocity tracking formulas.
Before writing new code, search for existing implementations:
# Search for similar functions
grep -r "function login" src/
# Search for similar components
grep -r "class AuthService" src/
# Search for similar patterns
grep -r "validate_email" src/
If found:
See resources/anti-duplication-checks.md for search patterns.
After completing task triplet (3 tasks), run full test suite:
# Run all tests
npm test # or pytest, cargo test, etc.
# Run type checker (TypeScript/Python)
npm run type-check
# Check coverage
npm run test:coverage
# Target: ≥80% coverage
Fix failing tests immediately (don't accumulate test debt).
See resources/continuous-testing.md for test cadence strategy.
For TypeScript projects, use type-enforcer agent to validate strict type safety:
# Invoke type-enforcer agent
# Scans for: implicit any, unguarded nulls, missing discriminated unions
# Reports violations with file:line locations
Blocks:
any types (requires explicit type annotations)See resources/continuous-testing.md#type-enforcer for strict mode requirements.
For security-sensitive code (auth, API, uploads), use security-sentry agent:
# Invoke security-sentry agent
# Scans for: SQL injection, XSS, CSRF, secret exposure, insecure dependencies
# Blocks deployment if critical vulnerabilities found
Critical scans:
See resources/continuous-testing.md#security-sentry for vulnerability patterns.
Commit after each task or task triplet:
git add src/services/AuthService.ts tests/AuthService.test.ts
git commit -m "feat: implement user authentication service
- Add login() with email/password validation
- Add JWT token generation
- Add password hashing with bcrypt
- Test coverage: 95% (unit + integration)
Implements: T002
Tests: test_user_can_login_with_valid_credentials"
Commit message format:
See resources/commit-strategy.md for commit best practices.
If task blocked (missing dependency, unclear requirement, external blocker):
Document blocker in NOTES.md:
## Blocked Tasks
- [ ] T005: Stripe payment integration (BLOCKED: awaiting API keys from DevOps)
Move to next independent task
Escalate blocker if critical path
Update state.yaml with blocker reason
See resources/handling-blocked-tasks.md for escalation strategies.
Before proceeding to /optimize:
# All tasks completed or blocked?
grep -c "\[ \]" specs/NNN-slug/tasks.md # Should be 0 or only blocked tasks
# All tests passing?
npm test # Should be green
# Coverage threshold met?
npm run test:coverage # Should be ≥80%
# Type check passing?
npm run type-check # Should be green
# No DRY violations?
# Manual review or use duplication detection tool
Update state.yaml: implementation.status = completed
Proceed to /optimize for code review and production readiness.
Why: Writing tests after code leads to:
Example (bad):
1. Write login() function
2. Manually test in browser
3. Write test afterward (test passes because code exists)
Example (good):
1. Write test_user_can_login() (fails - no implementation)
2. Implement login() to make test pass
3. Refactor for clarity
Why: Leads to:
Example (bad):
// New file: utils/emailValidator.js
function validateEmail(email) {
return /\S+@\S+\.\S+/.test(email);
}
// Didn't search - this already exists in utils/validation.js!
Example (good):
# Before writing validateEmail, search:
grep -r "validateEmail" src/
# Found: src/utils/validation.js already has validateEmail()
# Reuse existing function instead of duplicating
Why: Accumulating test failures leads to:
Example (bad):
T001: Implemented ✓ (tests passing)
T002: Implemented ✓ (1 test failing - ignore for now)
T003: Implemented ✓ (3 tests failing - will fix later)
# Now: which change broke which test? Unknown.
Example (good):
T001: Implemented ✓ (all tests passing)
T002: Implemented ✓ (1 test failing - STOP, fix immediately)
# Fix test before T003
T003: Implemented ✓ (all tests passing)
Why: Type errors indicate design issues:
Example (bad):
// @ts-ignore
const user = getUser(userId); // Type error suppressed
console.log(user.email); // May crash if user is null
Example (good):
const user: User | null = getUser(userId);
if (user) {
console.log(user.email); // Type-safe
} else {
console.error("User not found");
}
Why: Large uncommitted changes are risky:
Target: Commit every 1-3 tasks (30-90 minutes of work)
Result: Higher coverage, better design, fewer bugs
Result: Catch bugs early, maintain green build
Result: Clear history, easy rollback, reviewable diffs
Result: No hallucinated tech choices, consistency
Result: DRY codebase, lower maintenance burden
Ready to proceed to /optimize phase.
any types)Bad implementation:
@ts-ignore, any types)Issue: Code duplication detected Solution: Extract to shared utility, refactor duplicated logic, run anti-duplication checks before writing
Issue: Low test coverage (<80%) Solution: Write missing tests, use test-architect for complex features, follow TDD discipline
Issue: Task blocked (missing dependency, unclear requirement) Solution: Document blocker in NOTES.md, move to next independent task, escalate if critical path
Issue: Type errors accumulating Solution: Fix immediately, use type-enforcer agent for validation, enable TypeScript strict mode
Issue: Large uncommitted changes Solution: Commit frequently (after each task triplet), use small focused commits
Quality gates:
Advanced topics:
Reference:
