TDD Agent

Agent Phases

Phase 1: Context & Test Design

1. context/load-context: Load schema, routes, and patterns.
2. testing/plan-tests: Choose the best first failing spec.
3. testing/write-tests: Write test and verify failure.

HARD GATE — tdd-process (from ruby-core-skills)

• Test EXISTS and is RUN.
• FAILS for correct reason (e.g., undefined method 'full_name').
• If FAIL is incorrect (syntax, config), return to write-tests.

Phase 2: Implementation

1. Proposal Checkpoint: Propose implementation (e.g., "Concatenate first + last name").
2. User Approval: Wait for explicit confirmation.
3. Minimal Implement: Smallest change to pass test.
4. Verify PASS: bundle exec rspec spec/path/to/spec.rb.

If test does not pass, fix minimal changes and re-verify.

Phase 3: Iterate (Optional)

Return to Phase 1 for next behavior or proceed to Phase 4.

Phase 4: Finish

1. Quality Check: bundle exec rubocop && bundle exec brakeman && bundle exec rspec.
2. write-yard-docs (from ruby-core-skills): Document public Ruby API.
3. code-quality/code-review: Self-review PR diff.
4. Open PR: Feature complete.

Concrete Example

Below is an abbreviated end-to-end walkthrough for adding a full_name method to a User model.

For a complete end-to-end example, see assets/example.md.

Step 1 — Write the failing spec (spec/models/user_spec.rb):

RSpec.describe User, type: :model do
  describe '#full_name' do
    it 'returns first and last name joined by a space' do
      user = User.new(first_name: 'Jane', last_name: 'Doe')
      expect(user.full_name).to eq('Jane Doe')
    end
  end
end

Run: bundle exec rspec spec/models/user_spec.rb Expected failure: NoMethodError: undefined method 'full_name' for #<User ...> ✅

Step 2 — Propose & confirm implementation

Proposal: Add def full_name = "#{first_name} #{last_name}" to app/models/user.rb. Proceed?

Step 3 — Minimal implementation (app/models/user.rb):

class User < ApplicationRecord
  # @return [String] the user's full name
  def full_name
    "#{first_name} #{last_name}"
  end
end

Run: bundle exec rspec spec/models/user_spec.rb Expected: 1 example, 0 failures ✅

Step 4 — Quality check:

bundle exec rubocop && bundle exec brakeman && bundle exec rspec

All green → write YARD docs → self-review → open PR.