The Four-Agent Pipeline

.claude/
├── agents/
│   ├── planner.md      # Agent 1  (model: opus)
│   ├── coder.md        # Agent 2  (model: sonnet)
│   ├── tester.md       # Agent 3  (model: sonnet)
│   └── reviewer.md     # Agent 4  (model: opus)
└── commands/
    └── ship.md         # Orchestrator: the /ship command

.pipeline/              # shared workbench (handoff files)
├── spec.md
├── changes.md
├── test-results.md
└── review.md

---
name: planner
description: Turns a feature request into an implementation spec. Use as the first stage of the feature pipeline.
tools: Read, Grep, Glob, Write
model: opus
---

You are a planning specialist. You do NOT write implementation code.

Given a feature request:
1. Read the relevant parts of the codebase to understand current patterns.
2. Write a spec to `.pipeline/spec.md` containing:
   - Files to create or modify, with exact paths
   - The interface or function signatures needed
   - Edge cases the implementation must handle
   - Which existing patterns to follow (name the file to copy from)
3. Flag anything ambiguous as an OPEN QUESTION at the top of the spec.

Keep the spec tight. The Coder reads this and nothing else, so leave
no gaps and invent no requirements that weren't asked for.

---
name: coder
description: Implements the spec at .pipeline/spec.md. Use as the second stage of the feature pipeline, after the planner.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

You are an implementation specialist.

1. Read `.pipeline/spec.md` in full. If it has OPEN QUESTIONS, stop and
   surface them instead of guessing.
2. Implement exactly what the spec describes. Follow the patterns it
   names. Do not add features it didn't ask for.
3. Write a short summary to `.pipeline/changes.md`: which files changed,
   what each change does, and anything the Tester should focus on.

You write code that matches the repo. You do not refactor unrelated
code or "improve" things outside the spec's scope.

---
name: tester
description: Writes and runs tests for changes described in .pipeline/changes.md. Third stage of the feature pipeline.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

You are a test specialist.

1. Read `.pipeline/changes.md` to see what was built and where.
2. Read the changed files and the spec at `.pipeline/spec.md`.
3. Write tests covering: the happy path, the edge cases the spec named,
   and at least one failure case. Match the repo's test framework.
4. Run the tests. If any fail, write the failures to
   `.pipeline/test-results.md` and STOP. Do not fix the code yourself.
5. If all pass, note that in `.pipeline/test-results.md`.

You test behavior, not implementation details. A failing test means
the pipeline pauses for the Reviewer, not that you patch around it.

---
name: reviewer
description: Final review of the full pipeline output. Fourth and last stage before human sign-off.
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior reviewer. You are read-only. You do not edit code.

1. Read the spec, the changes summary, and the test results from
   `.pipeline/`.
2. Run `git diff` to see the actual changes.
3. Assess: does the code match the spec? Are the tests meaningful or
   superficial? Any security, performance, or correctness issues?
4. Write a verdict to `.pipeline/review.md`:
   - VERDICT: SHIP / NEEDS WORK / BLOCK
   - For NEEDS WORK or BLOCK, list exactly what to fix and where.

Be the last line of defense. If the tests are green but the code is
wrong, say BLOCK. Green tests are not the same as correct behavior.

Run the full feature pipeline for: $ARGUMENTS

Execute these stages in order. Do not skip ahead. After each stage,
confirm the handoff file exists before starting the next.

1. Delegate to the `planner` subagent with the feature request above.
   Wait for `.pipeline/spec.md`.
2. If the spec has OPEN QUESTIONS, stop and show them to me. Otherwise
   delegate to the `coder` subagent. Wait for `.pipeline/changes.md`.
3. Delegate to the `tester` subagent. Wait for `.pipeline/test-results.md`.
   If tests failed, stop and show me the failures.
4. Delegate to the `reviewer` subagent. Show me `.pipeline/review.md`.

Report the final verdict. Do not merge anything. Leave the branch for
my morning review.

/ship add rate limiting to the login endpoint

# Spec: Rate limiting for the login endpoint

## Goal
Protect POST /login from brute-force by limiting attempts per client IP.

## Files to modify
- `src/Api/Program.cs`  (register limiter + apply policy)

## Approach (follow built-in ASP.NET Core rate limiting)
- Use `AddRateLimiter` with a named policy "login".
- Partition by client IP (Connection.RemoteIpAddress).
- Fixed window: PermitLimit = 5, Window = 1 minute, QueueLimit = 0.
- RejectionStatusCode = 429 (Too Many Requests).
- Call `app.UseRateLimiter()` before endpoint mapping.
- Apply `.RequireRateLimiting("login")` to the /login endpoint only.

## Edge cases
- Null RemoteIpAddress (proxied/local) -> fall back to "unknown" key.
- Successful logins still count toward the limit (brute-force protection).
- 429 response must include a Retry-After header.

## Existing pattern to follow
- Endpoint style mirrors the existing POST /register in Program.cs.

## OPEN QUESTIONS
- (none)

using System.Threading.RateLimiting;
using Microsoft.AspNetCore.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

// --- Rate limiting: named "login" policy, partitioned by client IP ---
builder.Services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

    options.AddPolicy("login", httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: httpContext.Connection.RemoteIpAddress?.ToString()
                          ?? "unknown",
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 5,
                Window      = TimeSpan.FromMinutes(1),
                QueueLimit  = 0
            }));

    // Add a Retry-After header on rejection.
    options.OnRejected = async (ctx, token) =>
    {
        if (ctx.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retry))
            ctx.HttpContext.Response.Headers.RetryAfter =
                ((int)retry.TotalSeconds).ToString();
        await ctx.HttpContext.Response.WriteAsync(
            "Too many login attempts. Try again later.", token);
    };
});

var app = builder.Build();

app.UseRateLimiter();   // must come before endpoint mapping

app.MapPost("/login", (LoginRequest req) =>
{
    // ... existing authentication logic ...
    return Results.Ok(new { token = "..." });
})
.RequireRateLimiting("login");

app.Run();

public record LoginRequest(string Username, string Password);
public partial class Program { }   // exposes Program to the test project

# Changes

## Program.cs
- Registered `AddRateLimiter` with a fixed-window "login" policy
  (5 requests / 1 minute), partitioned by client IP.
- Added `OnRejected` to emit a Retry-After header + 429 body.
- Applied `.RequireRateLimiting("login")` to POST /login only.
- Added `public partial class Program {}` so the test host can boot it.

## For the Tester to focus on
- The 6th request from the same IP within 60s must return 429.
- The first 5 must NOT return 429.
- The 429 response should carry a Retry-After header.

using System.Net;
using System.Net.Http.Json;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;

public class LoginRateLimitTests
    : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;

    public LoginRateLimitTests(WebApplicationFactory<Program> factory)
        => _factory = factory;

    private static readonly LoginRequest Payload =
        new("[email protected]", "wrong-password");

    [Fact] // happy path: first 5 attempts are allowed
    public async Task Allows_First_Five_Attempts()
    {
        var client = _factory.CreateClient();

        for (int i = 1; i <= 5; i++)
        {
            var res = await client.PostAsJsonAsync("/login", Payload);
            Assert.NotEqual(HttpStatusCode.TooManyRequests, res.StatusCode);
        }
    }

    [Fact] // failure case: the 6th attempt is blocked with 429
    public async Task Blocks_Sixth_Attempt_With_429()
    {
        var client = _factory.CreateClient();

        for (int i = 1; i <= 5; i++)
            await client.PostAsJsonAsync("/login", Payload);

        var blocked = await client.PostAsJsonAsync("/login", Payload);

        Assert.Equal(HttpStatusCode.TooManyRequests, blocked.StatusCode);
    }

    [Fact] // edge case: rejection carries a Retry-After header
    public async Task Rejection_Includes_RetryAfter_Header()
    {
        var client = _factory.CreateClient();

        for (int i = 1; i <= 6; i++)
            await client.PostAsJsonAsync("/login", Payload);

        var res = await client.PostAsJsonAsync("/login", Payload);
        Assert.True(res.Headers.Contains("Retry-After"));
    }
}

# Test results

$ dotnet test
Passed!  - Failed: 0, Passed: 3, Skipped: 0, Total: 3

- Allows_First_Five_Attempts ............ PASS
- Blocks_Sixth_Attempt_With_429 ......... PASS
- Rejection_Includes_RetryAfter_Header .. PASS

All green. Pipeline continues to the Reviewer.

# Review

VERDICT: NEEDS WORK

The implementation matches the spec and tests are meaningful
(they assert behavior, not internals). However:

1. [Correctness] IP partitioning trusts RemoteIpAddress directly.
   Behind a reverse proxy (nginx/Cloudflare) every request shares the
   proxy IP, so ALL users would share one bucket. Fix: enable
   ForwardedHeaders middleware and read X-Forwarded-For, OR document
   that this limiter sits in front of the proxy.

2. [Design] An in-memory fixed-window limiter does not survive a
   restart and is per-instance only. For multi-instance deploys, note
   that a distributed store (e.g. Redis) is needed. Acceptable for now
   if single-instance — but say so in the spec.

3. [Minor] Consider SlidingWindow over FixedWindow to avoid the
   burst-at-window-boundary problem (10 requests across 2 windows).

Action: address (1) before merge. (2) and (3) can be follow-ups.