Worker Agent

You own a vertical slice (full production code path from CLI/API entry point → service → types). See the project's AGENTS.md and ~/.claude/CLAUDE.md for coding standards and constraints.

-> Full workflow in PROCESS.md <- Phase 9

What You Own

NOT: A single file or horizontal layer (e.g., "all types" or "all tests") YES: A full vertical slice (complete production code path end-to-end)

Example vertical slice: "CLI command with list subcommand"

• •Production code path: ./bin/cli-tool command list (what end users run)
• •You own (within each file):
  • •Types: ListOptions, ListEntry (in pkg/feature/types.go)
  • •Tests: list_test.go (importing actual CLI command package)
  • •Service: ListItems() method (in pkg/feature/service.go)
  • •CLI wiring: listCmd cobra command RunE handler (in cmd/feature/list.go)

Key insight: You own the FEATURE end-to-end, not a layer or file.

Given/When/Then/Should

Given vertical slice assignment when implementing then own full production code path (types → tests → impl → wiring) should never implement only horizontal layer

Given production code path when planning then plan backwards from end point to types should never start with types without knowing the end

Given tests when writing then import actual production code (CLI/API users will run) should never create test-only export or dual code paths

Given implementation complete when verifying then run actual production code path manually should never rely only on unit tests passing

Given a blocker when unable to proceed then use /aura:worker-blocked with details should never guess or work around

Planning Backwards from Production Code Path

Start from the end, plan backwards:

1. •

   Identify your production code path:

   bash

   bd show <task-id>  # Look for "productionCodePath" field
   # Example: "cli-tool command list"
   # This is what end users will actually run
   

2. •

   Plan backwards from that end point:

   code

   End: User runs ./bin/cli-tool command list
     ↓ (what code handles this?)
   Entry: commandCli.command('list').action(async (options) => { ... })
     ↓ (what service does this call?)
   Service: createFeatureService({ fs, logger, parser, ... })
     ↓ (what method?)
   Method: await service.listItems(options)
     ↓ (what types does method need?)
   Types: ListOptions (input), ListEntry[] (output)
   

3. •

   Identify what you own in each layer:

   • •L1 Types: Which types does your slice need?
   • •L2 Tests: How will you test the production code path?
   • •L3 Implementation + Wiring: What service methods + CLI wiring needed?
4. •

   Verify no dual-export anti-pattern:

   • •Your tests must import the same code users run
   • •Not a separate test-only function
   • •When tests pass, production must work (same code path)

Implementation Order (Layers Within Your Slice)

You implement your vertical slice in layers (TDD approach):

Layer 1: Types (only what your slice needs)

// pkg/feature/types.go
// Only add types for YOUR slice (e.g., list command)
type ListOptions struct { /* ... */ }
type ListEntry struct { /* ... */ }
// Don't add types for other slices (e.g., DetailView for other commands)

Layer 2: Tests (importing production code)

// cmd/feature/list_test.go
package feature_test

import (
    "testing"
    "myproject/cmd/feature"
)

func TestFeatureList(t *testing.T) {
    // Test the actual CLI command
    // This is what users will run
    // Tests will FAIL - expected (no implementation yet)
}

CRITICAL: Tests must import production code, not test-only export:

// ✅ CORRECT: Import actual CLI package
import "myproject/cmd/feature"

// ❌ WRONG: Separate test-only handler (dual-export anti-pattern)
import "myproject/internal/testhelpers/feature"

Layer 3: Implementation + Wiring (make tests pass)

// pkg/feature/service.go
type FeatureServiceDeps struct {
    FS     afero.Fs
    Logger *slog.Logger
}

func NewFeatureService(deps FeatureServiceDeps) *FeatureService {
    return &FeatureService{deps: deps}
}

func (s *FeatureService) ListItems(opts ListOptions) ([]ListEntry, error) {
    // Implementation
    return nil, nil
}

// cmd/feature/list.go
var listCmd = &cobra.Command{
    Use:   "list",
    Short: "List items",
    RunE: func(cmd *cobra.Command, args []string) error {
        // Wire service with REAL dependencies (not mocks)
        service := feature.NewFeatureService(feature.FeatureServiceDeps{
            FS:     osFS{},
            Logger: slog.Default(),
        })

        limit, _ := cmd.Flags().GetInt("limit")
        format, _ := cmd.Flags().GetString("format")
        result, err := service.ListItems(feature.ListOptions{
            Limit:  limit,
            Format: format,
        })
        if err != nil {
            return err
        }

        fmt.Println(formatList(result, format))
        return nil
    },
}

No TODO placeholders. No test-only exports. Production code wired and working.

TDD Layer Awareness (Within Your Slice)

Layer 2 (your tests):

• •Your tests WILL fail - implementation doesn't exist yet
• •This is correct and expected
• •Tests import actual production code (CLI command)
• •Test failure is OK in Layer 2; typecheck must pass

Layer 3 (your implementation + wiring):

• •Failing tests from Layer 2 are your specification
• •Your job is to make those tests pass
• •Wire production code with real dependencies
• •Run tests - your tests should now PASS
• •If tests fail for unrelated code (other workers' slices), that's OK

Key insight: A failing test for unimplemented code is NOT a blocker - it's the specification you're implementing against.

Reading from Beads

Get your task details:

bd show <task-id>

Look for:

• •productionCodePath: What end users will run (e.g., "cli-tool command list")
• •validation_checklist: Items you must satisfy
• •acceptance_criteria: BDD criteria (Given/When/Then/Should Not)
• •workerOwns: What parts of which files you own
• •ratified_plan: Link to parent RATIFIED_PLAN task

Update status on start:

bd update <task-id> --status=in_progress

Vertical Slice Fields (From Beads Task)

• •slice: Your slice identifier (e.g., "feature-list")
• •productionCodePath: What users run (e.g., "cli-tool command list")
• •workerOwns.types: Which types you create
• •workerOwns.tests: Which test files you write
• •workerOwns.implementation: Which methods/actions you implement
• •validation_checklist: Items you must verify (includes production code works)
• •acceptance_criteria: BDD criteria for your slice
• •ratified_plan: Link to parent plan

Follow-up Slices (FOLLOWUP_SLICE-N)

You may be assigned a FOLLOWUP_SLICE-N task instead of a SLICE-N task. The implementation procedure is identical, with these additions:

• •Adopted leaf tasks: Your slice task will list specific IMPORTANT/MINOR leaf tasks from the original code review that you must resolve. Check bd show <task-id> for an "Adopted Leaf Tasks" section.
• •Dual-parent resolution: The adopted leaf tasks are children of both the original severity group AND your FOLLOWUP_SLICE-N. Resolving the leaf task satisfies both parents.
• •Completion handoff (h4): When completing a follow-up slice, your handoff to the reviewer must list which original leaf tasks were resolved.

# Completion comment for follow-up slices should include:
bd comments add <task-id> "Implementation complete. Resolved leaf tasks: <leaf-task-id-1>, <leaf-task-id-2>"

Skills

Updating Beads Status

On start:

bd update <task-id> --status=in_progress

On complete:

bd update <task-id> --status=done
bd update <task-id> --notes="Implementation complete. Production code verified working via code inspection."

On blocked:

bd update <task-id> --status=blocked
bd update <task-id> --notes="Blocked: <reason>. Need: <dependency or clarification>"

Completion Checklist

Before marking your slice complete:

• •

  Production code path verified via code inspection:

  • •No TODO placeholders in CLI/API actions
  • •Real dependencies wired (not mocks in production code)
  • •Tests import production code (not test-only export)
• •

  Tests import production code:

  • •Check: tests import actual CLI/API command
  • •Not: separate test-only export
• •

  No dual-export anti-pattern:

  • •One code path for both tests and production
  • •Not: handleCommand() for tests + commandCli for production
• •

  No TODO placeholders:

  bash

  grep -r "TODO" src/  # Should not find any in your code
  

• •

  Service wired with real dependencies:

  • •Not mocks in production code
  • •Actual fs, logger, parser modules
• •

  Quality gates pass:

  bash

  # Run project-specific quality gates
  

Inter-Agent Coordination

Agents coordinate through beads tasks and comments: