Implement

Implement - Automated Development Workflow

Coordinates specialist agents through a complete development cycle: requirements -> planning -> implementation -> refactoring -> QA -> documentation.

Workflow

1. Receive and clarify requirements

Gather requirements from user:

• What feature/bug/change is being requested?
• What are the acceptance criteria?
• Any constraints or preferences?

Ask clarifying questions if needed:

• Ambiguous requirements
• Missing information
• Multiple valid approaches

Loop back to user until requirements are clear.

2. Planning (Conditional)

Assess task complexity:

After requirements are clear, assess whether planning is warranted:

Invoke swe-planner agent for complex tasks:

• Large architectural changes (refactoring entire subsystems, technology migrations)
• Cross-cutting concerns (multi-tenancy, i18n, audit logging)
• Features touching many modules with unclear implementation path
• Changes requiring database migrations and backward compatibility
• Multiple valid approaches with significant trade-offs
• Tasks where diving straight into implementation risks going down wrong path

Skip planning for simple tasks:

• Single-file changes or small bug fixes
• Straightforward CRUD operations
• Simple refactorings (rename, extract method, remove duplication)
• Clear, well-defined changes with obvious implementation path
• Tasks that can be completed in <100 lines of code

Note: swe-planner has a safety valve to exit early if invoked for a task simpler than assessed. If planner reports "planning not needed," proceed directly to implementation with planner's brief recommendation.

If planning invoked:

• swe-planner will produce implementation plan with ordered sub-tasks
• Each sub-task includes: What/Why/How/Verify/Risks
• Plan identifies risk areas (prototyping needs, user decisions, performance/security concerns)
• Plan applies YAGNI, emphasizes starting small and working incrementally

Use plan to guide implementation:

• Implementation agent should follow plan's sequencing
• Implement one sub-task at a time
• Verify each sub-task before moving to next
• If plan identifies prototyping needs, create scratch repos in /tmp first

3. Implementation

Detect project language/framework:

• Check for language-specific files (go.mod, package.json, Cargo.toml, Dockerfile, Makefile, etc.)
• Determine which specialist agent to use

Spawn appropriate implementation agent:

• If Dockerfile changes: spawn swe-sme-docker agent
• If Makefile changes: spawn swe-sme-makefile agent
• If Golang project: spawn swe-sme-golang agent
• If GraphQL schema/resolvers: spawn swe-sme-graphql agent
• If Ansible playbooks/roles: spawn swe-sme-ansible agent
• If Zig project: spawn swe-sme-zig agent
• If TypeScript project (.ts files, tsconfig.json): spawn swe-sme-typescript agent
• If vanilla JavaScript (.js files, no TypeScript): spawn swe-sme-javascript agent
• If HTML/markup changes: spawn swe-sme-html agent
• If CSS/styling changes: spawn swe-sme-css agent
• Otherwise: implement directly with general best practices

Pass plan to implementation agent if planning was done:

• Implementation agent should follow plan's sequencing
• Work incrementally through sub-tasks
• Verify each step as specified in plan

Implementation agent responsibilities:

• Write code following language idioms
• Follow project conventions
• Handle edge cases and errors
• Write unit tests for pure functions as part of TDD (encouraged, not just QA's job)
• If following plan: implement sub-tasks sequentially, verify each before proceeding

4. Quality Assurance - Verify Acceptance Criteria (CRITICAL GATE)

Spawn qa-engineer agent:

• Pass original requirements and acceptance criteria to the agent
• The agent infers its mode from context: presence of acceptance criteria triggers acceptance verification
• Agent performs practical verification first - actually running/using the feature to confirm it works
• This means: executing CLI commands, spawning subagents to test MCP tools, making API calls, etc.
• Only AFTER practical verification confirms the feature works does the agent write unit tests
• This prevents the failure mode of "passing unit tests for broken code"

Practical verification by feature type:

• CLI tools: Run commands in subshell (skip destructive operations)
• MCP servers/Claude skills: Spawn subagent to actually use the feature
• API integrations: Make actual calls (with caution for dangerous operations)
• Libraries: Quick sanity checks, then unit tests

This is a CRITICAL GATE:

• Implementation must demonstrably work (practical test) AND have tests to proceed
• If practical verification fails: return to step 3 (implementation) immediately
• If verification passes but tests fail: debug tests, not implementation
• Track iteration count (max 3 attempts before escalating to user)

Expected output: Practical verification results, integration test recommendations, pass/fail determination with specific findings about each acceptance criterion.

5. Code Review (Conditional)

Only proceed to code review if acceptance verification passed. Don't review broken code.

Conditionally invoke specialized reviewers based on code changes and complexity. All reviewers provide feedback; implementation agent responds to all feedback in step 6.

5a. Security Review (Conditional - Has Authority)

If security-sensitive code changed (auth, crypto, input validation, data access):

Spawn sec-blue-teamer agent:

• Evaluates defensive security posture of changed code
• Checks control consistency, defense-in-depth, and configuration
• Identifies systemic gaps that enable vulnerability classes
• Has authority to demand changes - security issues should block or require explicit user approval

Output: Defense evaluation with severity levels (critical/high/low)

5b. Refactoring Review (Conditional - Advisory)

If non-trivial implementation (>50 lines changed, multiple files, or complex logic):

Spawn swe-code-reviewer agent:

• Reviews implementation for code quality issues
• Identifies refactoring opportunities (DRY violations, dead code, complexity, etc.)
• Provides structured recommendations organized by priority
• Agent will report "No refactoring needed" if code is already clean

Output: Refactoring recommendations (advisory only)

5c. Performance Review (Conditional - Advisory)

If performance-critical code changed (hot paths, loops, database queries, API endpoints):

Spawn swe-perf-reviewer agent:

• Reviews code for performance bottlenecks
• Identifies missing benchmarks and profiling gaps
• Provides optimization recommendations

Output: Performance metrics and recommendations (advisory only)

6. Implement Review Feedback

Aggregate all review feedback from step 5 and provide to implementation agent.

If specialist was used in step 3 (swe-sme-golang, swe-sme-graphql, etc.):

• Re-invoke the same specialist agent that did implementation
• Provide all review feedback (security, refactoring, performance)
• Specialist reviews all feedback and uses own discretion to implement
• Security findings: Must address or get explicit user approval to skip
• Other feedback: Advisory only - specialist has final authority
• Specialist may decline recommendations that conflict with language idioms
• Specialist implements accepted changes and commits

If no specialist (general implementation):

• Re-invoke the same agent that did implementation in step 3
• Provide all review feedback
• Agent addresses security issues and implements accepted recommendations
• Agent commits changes

Note: Security issues have authority to block; other feedback is advisory. Implementation agent makes final decisions on advisory feedback.

7. SME Peer Review (Conditional)

Condition: Non-trivial changes (>50 lines changed, multiple files, or complex logic).

Skip if:

• Changes are trivial (single file, <50 lines, simple logic)
• No language-specific SME was used in step 3 (general implementation)

If applicable, spawn a fresh instance of the same SME type used in step 3:

• Fresh context window - reviewer sees only current code state via git diff
• Reviews with "would I accept this PR" lens
• Focuses on: minor oversights, idiomatic patterns, naming, small cleanups
• Has authority to make small fixes directly

Scope constraints (critical):

• Small cleanups and nits only
• No architectural changes
• No re-implementing features
• No changing approaches or patterns chosen by original SME
• If something seems wrong at a deeper level, flag it rather than fix it

Expected output: Small fixes committed, or "no changes needed" if code is clean.

8. Quality Assurance - Coverage & Quality Verification

Spawn qa-engineer agent:

• The agent infers its mode from context: absence of acceptance criteria triggers general assessment
• Agent performs general QA assessment of all changed code (from steps 3, 6, and 7)
• Assess test coverage for new/modified code
• Identify gaps and write missing tests
• Run linters/formatters and fix issues
• Evaluate test quality (assertions, edge cases)
• Verify implementations from steps 6 and 7 didn't break tests - catches issues from refactoring, security fixes, or peer review cleanups

This is SUPPLEMENTARY:

• Issues found here don't block the workflow by default
• Agent documents issues and proposes fixes
• Minor issues: proceed to documentation
• Significant issues (tests broken, major bugs): return to step 6 (review feedback) or step 3 (implementation)

Expected output: Coverage metrics, tests added/modified, quality issues found, confirmation that all changes still pass tests.

Feedback Loops

Acceptance verification failure (step 4):

• Return to step 3 (implementation)
• Track iteration count (max 3 attempts before escalating to user)
• Report specific acceptance criteria that failed
• Report practical verification results (what was tried, what failed)

Security review findings (step 5a):

• Critical/High severity: Must address in step 6 or get explicit user approval to skip
• Medium/Low severity: Advisory - implementation agent decides in step 6

Code review feedback (steps 5b-5c):

• All refactoring and performance feedback is advisory
• Implementation agent in step 6 uses discretion to implement

Peer review issues (step 7):

• If peer review changes break tests: revert peer review changes and proceed (nits aren't worth breaking functionality)
• If peer review flags deeper issues: escalate to user for decision

Coverage & quality issues (step 8):

• Tests broken by changes from step 6: Return to step 6 to fix or revert
• Tests broken by changes from step 7: Revert step 7 changes (peer review nits shouldn't break tests)
• Major bugs found: Return to step 3 (implementation)
• Minor issues (low coverage in non-critical code, style nitpicks): document and proceed
• User can approve proceeding despite issues if acceptable

9. Documentation

Spawn doc-maintainer agent:

• Review git diff to identify which files/modules changed
• Determine which documentation is affected:
  • README.md if user-facing functionality changed
  • CLAUDE.md if architecture/integration points changed
  • API docs if public interfaces changed
  • Internal docs (doc/, adr/) if implementation details relevant to architecture changed
• Focus review on documentation related to changed code
• Verify code examples in affected docs still work
• Check for broken links in modified documentation

Agent should be targeted, not comprehensive:

• Only review documentation relevant to the changes made
• Skip full codebase documentation scan
• Report "no documentation changes needed" if changes are purely internal with no doc impact

10. Final verification

Run comprehensive checks:

• Execute full test suite (must pass)
• Run all linters and formatters
• Verify no new warnings introduced
• Check git status (document any uncommitted changes)

Present summary to user:

• Files changed
• Tests added/modified
• Coverage improvements
• Any remaining TODOs or follow-ups

If verification fails:

• Determine root cause (implementation bug vs. refactoring issue vs. test issue)
• Return to appropriate step (step 3 for implementation bugs, step 5 for refactoring issues)
• Report specific failures to user

11. Workflow Completion (Optional)

After presenting summary from step 10, ask user if they want to complete the workflow.

User may also explicitly request workflow completion at any point after step 10 succeeds.

If user confirms, perform housekeeping tasks:

11a. Commit Changes

If uncommitted changes exist:

• Review git status to see what changed
• Create commit with descriptive message
• If ticket number is known (from branch name, prior context, or user input):
  • Reference ticket in commit message (e.g., "Fixes #123" or "Closes: #123")
• Use heredoc format for multi-line commit messages

Example commit message format:

Add user authentication with JWT tokens

Implements login/logout endpoints with refresh token rotation.
Includes rate limiting and CSRF protection.

Fixes #123

11b. Update/Close Issue Tracker Ticket (Conditional)

Detect tracker, recover the ticket number, and post the close-out per references/trackers.md (Detection Procedure + "Comment / update (close-out)" + "Close" operations).

Close-out comment content (skill-specific):

• List of files changed
• Key changes made
• Tests added
• Documentation updated

11c. Sync with Main Branch (Conditional)

Check branch state:

• Identify main branch name (master or main)
• Check if current branch is not main
• Check if there are new commits on main that current branch doesn't have

If current branch is behind main:

• Ask user: "Your branch is behind main. Would you like to rebase on main?"
• If user confirms:
  • Perform: git fetch origin main && git rebase origin/main
  • If conflicts arise, report to user and halt (don't auto-resolve)
  • If rebase succeeds, report success

Skip if:

• Current branch is main/master
• Current branch is up to date with main
• No main/master branch exists

Present final status:

• ✓ Changes committed
• ✓ Ticket #123 updated and closed
• ✓ Branch rebased on main
• Ready to push or move to next task

Agent Coordination

Sequential execution:

• Agents run one at a time (no parallel spawning)
• Each agent completes before next begins
• Use Task tool to spawn agents

State management:

• Track current workflow step
• Track QA iteration count (for acceptance verification failures)
• Accumulate summary information
• Preserve original requirements for passing to QA acceptance verification

Agent self-skipping:

• Agents should skip work if not applicable
• Report "nothing to do" rather than making unnecessary changes

Planning pass-through:

• If swe-planner produces a plan, pass it to implementation agent
• Implementation agent should acknowledge plan and follow it
• Plan helps coordinate implementation approach

TDD coordination:

• SWE agents are encouraged to write unit tests for pure functions during implementation
• QA agent focuses on practical verification and integration tests
• This prevents duplicate test-writing while ensuring comprehensive coverage

Iteration Limits

Maximum iterations:

• Acceptance verification loop (step 4): 3 attempts, then escalate to user
• Overall workflow: 10 total agent spawns (safety limit)

Escalation to user:

• Present current state
• Explain what's blocking progress
• Request guidance