# Usage Command Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add a built-in `/usage` command with a generic agent usage-reporting interface, and implement the first provider-backed version for Codex using ChatGPT OAuth quota data.

**Architecture:** The engine gains a new built-in command that depends only on an optional `UsageReporter` interface. Agents that implement the interface return a generic `UsageReport`; the engine formats that into text. The Codex agent reads ChatGPT OAuth credentials from `~/.codex/auth.json`, calls the `wham/usage` endpoint, and maps the response into the generic structure.

**Tech Stack:** Go, built-in command dispatch in `core/engine.go`, optional agent interfaces in `core/interfaces.go`, HTTP/JSON via Go standard library, table-driven tests.

---

### Task 1: Add generic usage-reporting types

**Files:**
- Modify: `core/interfaces.go`

**Step 1: Add the failing interface usage surface**

Define:

- `UsageReporter`
- `UsageReport`
- `UsageBucket`
- `UsageWindow`
- `UsageCredits`

The structure should cover provider identity, plan/tier, generic allowed/limit-reached flags, one or more windows, and credits metadata.

**Step 2: Run targeted compile check**

Run: `go test ./core/...`
Expected: compile failures in engine/tests until the command layer is wired.

**Step 3: Keep the types minimal**

Do not add provider-specific fields unless they are broadly useful.

**Step 4: Re-run compile check**

Run: `go test ./core/...`
Expected: still failing only because `/usage` command is not yet fully integrated.

### Task 2: Add `/usage` built-in command and output formatter

**Files:**
- Modify: `core/engine.go`
- Modify: `core/i18n.go`
- Test: `core/engine_test.go`

**Step 1: Write/extend failing tests**

Add tests for:

- `/usage` dispatch to a supporting agent
- unsupported-agent message
- successful output formatting with representative report data

**Step 2: Run the targeted tests**

Run: `go test ./core/... -run 'Test.*Usage|TestHandleCommand'`
Expected: FAIL because the command is not registered yet.

**Step 3: Implement command plumbing**

Update:

- built-in command registration
- command dispatch switch
- bot command listing
- help/i18n text

Add a `cmdUsage` implementation that:

- type-asserts `UsageReporter`
- fetches usage with timeout
- formats a concise text response

**Step 4: Run the targeted tests again**

Run: `go test ./core/... -run 'Test.*Usage|TestHandleCommand'`
Expected: PASS

### Task 3: Implement Codex usage retrieval against ChatGPT OAuth

**Files:**
- Modify: `agent/codex/codex.go`
- Add or Modify: `agent/codex/usage.go`
- Test: `agent/codex/usage_test.go`

**Step 1: Write failing tests for the mapper/fetcher**

Cover:

- successful parsing of a representative `wham/usage` payload
- missing `auth.json`
- missing token/account fields
- HTTP error response

**Step 2: Run the targeted tests**

Run: `go test ./agent/codex -run 'Test.*Usage'`
Expected: FAIL because the implementation does not exist yet.

**Step 3: Implement minimal production code**

Add:

- auth file path resolver
- auth JSON loader
- HTTP request builder
- response DTOs
- mapping into `core.UsageReport`

Prefer dependency injection for:

- auth file path / reader
- HTTP client / transport

So tests avoid live network and real user files.

**Step 4: Run the targeted tests again**

Run: `go test ./agent/codex -run 'Test.*Usage'`
Expected: PASS

### Task 4: End-to-end verification and cleanup

**Files:**
- Modify: `README.md`
- Modify: `README.zh-CN.md`
- Modify: `CHANGELOG.md`

**Step 1: Document the new command**

Add `/usage` to command lists and a short explanation that support depends on the current agent.

**Step 2: Run focused test suites**

Run: `go test ./core/... ./agent/codex`
Expected: PASS

**Step 3: Run broader verification**

Run: `go test ./...`
Expected: PASS, or identify unrelated pre-existing failures clearly.

**Step 4: Commit**

Run:

```bash
git add core/interfaces.go core/engine.go core/i18n.go core/engine_test.go agent/codex/codex.go agent/codex/usage.go agent/codex/usage_test.go README.md README.zh-CN.md CHANGELOG.md docs/plans/2026-03-12-usage-design.md docs/plans/2026-03-12-usage.md
git commit -m "feat: add usage command for codex oauth"
```