/plan-maker

← Back to index

Summary

Creates and updates detailed, actionable implementation plans with the smallest possible tasks, full test specifications, and explicit dependency chains.

When to use

Use /plan-maker whenever you need to break down work into structured, implementable tasks. It drives an architectural challenge round before writing anything, ensuring decisions are made explicitly and edge cases are surfaced before implementation begins.

Trigger phrases (from SKILL.md):

Also triggers on any request to decompose a feature, fix, refactor, or initiative into actionable steps — even short or casual planning requests.

Workflow context: /plan-maker is a key entry point in the 9-step agentic workflow pipeline. See agentic-workflow-en.html for how it fits alongside /feature-refinement and /implement.

Invocation

Invoke as a slash command, optionally followed by a brief description of what to plan:

/plan-maker [feature description or goal]

The skill will gather context interactively, run architecture challenge rounds (raising concerns as options with pros/cons and a recommendation), then write the plan to the project's plan directory.

Parameters: none required. If you provide a description it is used as the starting point for context gathering; otherwise the skill asks.

Updating an existing plan: say "update the plan for X" — the skill finds the existing file and appends new tasks rather than creating a duplicate.

Example 1 — New feature plan

Input:

/plan-maker Add OAuth2 login to the API so users can sign in with Google or GitHub

Output / Result:

# FEAT-012 — OAuth2 Login
**Purpose**: Allow users to authenticate via Google or GitHub instead of email/password
**Audience**: API consumers and end users
**Status**: To Do

## Background
The current auth system requires email/password accounts. Adding OAuth2 removes signup
friction and delegates credential management to trusted providers.

## Goal
Users can initiate OAuth2 login, exchange the callback code for a session token, and
access protected endpoints — with no change to the existing password-login path.

## Scope
### In Scope
- Google and GitHub OAuth2 providers
- Token exchange endpoint, session creation, user upsert

### Out of Scope
- OAuth2 for admin accounts (separate system)
- Mobile deep-link callbacks (deferred)

## Task breakdown

### Phase 1 — OAuth2 core
#### Task 1.1 — OAuth2 provider config loader
- [ ] **File**: `src/auth/oauth_config.py`
...
#### Task 1.2 — Callback endpoint
...
#### Task 1.N — Final verification & documentation update
...

Example 2 — Update an existing plan

Input:

update the plan for FEAT-012 — we also need to support Apple Sign In

Output / Result:

Found existing plan: plans/FEAT-012-oauth2-login.md

Architectural concern raised:
  Apple Sign In uses a different token format (JWT, not opaque) and requires
  client-secret rotation every 6 months.
  - Option A: reuse the existing provider abstraction — Pro: minimal change;
    Con: abstraction leaks Apple-specific JWT handling
  - Option B: add an AppleProvider subclass with dedicated JWT validation —
    Pro: clean separation; Con: slightly more code
  - Recommendation: Option B — cleaner long-term

New tasks appended to Phase 1:
  Task 1.5 — AppleProvider JWT validator
  Task 1.6 — Apple client-secret rotation script
  Task N.N — Final verification updated with Apple AC

Plan saved: plans/FEAT-012-oauth2-login.md (6 tasks, 2 new)

Related tools