write-implementation-plan

---
name: write-implementation-plan
description: Draft or update detailed implementation plans for authgear-server specs, design changes, and docs/plans files. Use when Codex needs to turn a spec or outdated plan into a concrete implementation plan with exact files, exact methods, runtime call flow, compatibility requirements, test coverage, and atomic commit steps.
---

# Write Implementation Plan

Write implementation plans as concrete engineering plans, not design notes.

## Never assume — ask

If anything needed to write the plan is unknown or uncertain — a behavioral
decision the spec doesn't settle, which of two existing patterns to follow,
an ambiguous naming/config choice, a tradeoff with no clearly-correct
default — stop and ask the user. Do not guess and write the plan around the
guess, and do not bury the uncertainty in an "open decisions" section for
the user to notice later (the Requirements section below already forbids
that). This applies even to small-seeming choices: a wrong assumption made
early (e.g. which Redis instance to use, what a field defaults to, whether
a check is save-time or runtime) propagates through every section of the
plan and is expensive to unwind once implementation has started from it.
Ask before writing the section that depends on the answer, not after the
plan is done.

## Workflow

1. Read the current spec, the existing plan, and the relevant code paths before writing the plan.
2. **Consult related skills** to understand implementation conventions:
   - Check the `add-go-test` skill to understand unit testing patterns and whether the package uses Convey BDD-style tests
   - Check the `write-e2e-test` skill to understand e2e testing requirements and patterns
   - Check domain-specific skills (e.g., `update-portal-ui`, `new-siteadmin-api`) if the plan touches those areas
3. Identify the real integration points in code:
   - config types and schema
   - runtime entry points
   - event and delivery paths
   - storage and migration behavior
   - tests
4. Rewrite the plan around the current spec and the current codebase, not around stale assumptions from an older plan.

## Requirements

Write the plan with exact implementation intent.

- Name the exact files to create or modify.
- Name the exact methods, structs, and helpers to add or change.
- Describe the exact method call flow for important runtime paths.
- Separate config-layer types from runtime-layer types.
- Preserve existing codebase conventions for file placement and naming.
- Include backward-compatibility requirements explicitly.
- Include deployment and data-compatibility behavior explicitly when storage keys, payloads, or persisted state are involved.
- Include test coverage requirements.
- Include an atomic commit plan.

Do not write the plan at a hand-wavy level.

- Do not say “support this somehow”.
- Do not say “add helpers as needed”.
- Do not say “or equivalent new file”.
- Do not add helper methods that are not used by the plan’s call flow.
- Do not leave known behavior in an “open decisions” section.

## Required Detail

For runtime-heavy changes, include all of the following.

### Config Plan

- exact config structs
- exact package and file placement
- schema changes
- merge behavior
- migration behavior for deprecated config

### Runtime Plan

- exact entry points
- exact handler/service/limiter method signatures
- exact internal helper method signatures
- exact call sequence from request entry point to storage and delivery

### Storage and Migration Plan

- exact storage key format
- compatibility with existing keys or persisted data
- rollout behavior during deploy
- whether backfill, dual-read, or dual-write is needed

### Script Plan

If Redis/Lua/SQL scripts are involved, document:

- exact inputs
- exact outputs
- exact call sites
- exact success and failure behavior

### API Compatibility Plan

If an API error or payload changes, document:

- old fields to keep
- new fields to add
- which fields are legacy
- exact type and value compatibility rules

## Method Call Plans

For important logic, write explicit call plans.

1. Name the current entry point file and method.
2. State the new method that will be called.
3. State what that method resolves or computes.
4. State what helper it calls next.
5. State the return behavior on success and failure.

When multiple periods, thresholds, or branches exist, spell out exactly:

- what loops over what
- what is called once per request
- what is called once per period
- what is called once per configured limit

Remove ambiguity that could cause overcounting or wrong behavior.

## Atomic Commit Plan

Always include a final section with atomic commits.

Each commit entry must include:

- commit purpose
- exact files
- exact behavior or refactor scope
- whether generated files or wiring must be updated in the same commit

Keep commit boundaries reviewable and bisect-safe.

If dependency wiring changes, require generated wiring updates in the same commit.

## Authgear-Server Specific Rules

- keep config structs in `pkg/lib/config`
- place feature config structs in `feature_xx.go`
- separate feature-config structs from app-config structs even if their shapes are parallel
- keep runtime-only structs separate from config structs when runtime needs a unified resolved shape
- preserve backward compatibility for legacy config, Redis keys, API payloads, and error fields unless the spec explicitly removes it
- when the plan references existing Redis key names or legacy values, state exactly where they come from in current code
- if e2e coverage is needed, include a dedicated e2e commit and list the cases that must be covered
- **for unit tests**: Identify the test style (Convey BDD vs standard testing.T) by inspecting existing `*_test.go` files in the same package — use the add-go-test skill for guidance and always match the local style
- **for e2e tests**: Use YAML-driven test format (not Go code) — use the write-e2e-test skill for patterns

## Output Location

Always write the plan to `docs/plans/{feature}/{date}-{part}-{name}.md`:

- `{feature}` — a short kebab-case slug for the feature (its own directory, shared by every part of its plan).
- `{date}` — `YYYY-MM-DD`, the date the plan is written.
- `{part}` — a two-digit part number (`01`, `02`, ...) when the plan is split into parts (e.g. config, runtime, e2e); omit if the plan is a single file.
- `{name}` — a short kebab-case slug for the part/plan itself.

Example: a three-part plan for an "audit log streaming" feature written on
2026-09-18 goes in `docs/plans/audit-log-streaming/2026-09-18-01-config.md`,
`docs/plans/audit-log-streaming/2026-09-18-02-runtime.md`,
`docs/plans/audit-log-streaming/2026-09-18-03-e2e.md`. Never write a plan to
any other location (repo root, `docs/` directly, next to the spec, etc.).

## Output Shape

Prefer this structure when it fits the task:

1. Goal / scope
2. Config model and schema
3. Runtime flow
4. Event / delivery flow
5. Compatibility and deployment behavior
6. File-level change plan
7. Test plan
8. Fixed behavioral decisions
9. Implementation order
10. Atomic commit plan

Adjust section names if needed, but keep the plan concrete.

More agent context in authgear/authgear-server

20 other files this repository gives its agents.