epic-to-feature-specs

Epic to Feature Specs

Break epic documents into 3-5 implementation-ready feature specs with TypeScript handoff contracts, then optionally decompose each into 3-5 sub-specs sized for AI coding harnesses like hoangsa. Adapts to your role — whether you're a PM handing off to engineering, a tech lead decomposing your own work, or a solo dev breaking an epic into AI-codeable chunks.

Works with Claude Code, OpenAI Codex, and Google Gemini out of the box — same workflow, native entry-point per agent (see Install).

What it does

Takes an epic doc (a grouped set of user stories with a shared goal) and produces a two-layer decomposition:

Layer 1 — Feat specs (team contracts)

1. 3 to 5 feature specs (ceiling of 5, default of 3), one per team-ownership boundary
2. A typed handoff contract (contracts/*.ts) that is the seam between teams or layers
3. A narrative companion (BE-HANDOFF.md) for Notion review and onboarding (multi-team setups)
4. UI design references — component inventory, screen-to-story mapping, and design-spec mismatch resolution (when Figma/Pencil designs are provided)

Layer 2 — Sub-specs (shippable-PR units, optional, new in v0.3)

After the feat specs are written, the skill optionally decomposes each into:

5. 3 to 5 sub-specs per feat spec (cap .A through .E), each one shippable PR sized for one AI cook session
6. Notion pages — sub-specs are written into your Notion task database via the Notion MCP (property schema is discovered per-database, so it adapts to your existing setup)
7. Plan Split annotations — when a sub-spec's logical scope would exceed the ~250k-token AI sweet spot, the skill embeds a substrate/wiring or domain/transport split that hoangsa's /hoangsa:prepare honors

Each feat spec and sub-spec passes the SMART independence test: specific scope, measurable with siblings mocked, achievable in one session, relevant to the epic goal, time-bound.

What's new in v0.4

Multi-agent support — Codex and Gemini adapters. The skill now ships with first-class adapters for OpenAI Codex (CLI + Cloud) and Google Gemini (CLI + Code Assist) alongside the existing Claude Code plugin. Same 11-step workflow, same templates, same SMART validation — just a native entry-point file per agent (AGENTS.md for Codex, GEMINI.md for Gemini).

Agent-agnostic workflow. The canonical workflow now lives in adapters/WORKFLOW.md — Claude-isms stripped (AskUserQuestion → plain explicit questions, hardcoded MCP tool names → operation descriptions). Any AI coding agent that reads context files from the working directory can execute it. The Claude Code plugin's SKILL.md remains the structured-question version for Claude users.

One-command install per agent. A single script (adapters/install.sh codex|gemini /path/to/project) copies the workflow + references + templates into your project and wires up the entry file with an idempotent marker block. Re-run any time to pick up upstream updates without touching the rest of your AGENTS.md / GEMINI.md.

Why this matters. Teams rarely standardize on one AI coding agent across an org — engineering uses Claude Code, product uses Codex, design uses Gemini Code Assist, etc. v0.4 means the same epic decomposition discipline travels with the team, not the tool.

What's new in v0.3

Sub-spec layer — the missing rung between feat spec and hoangsa session. Feat specs are now correctly sized as team contracts (30+ stories per spec); sub-specs are sized as shippable PRs (5–15 stories per spec) that an AI coding agent can hold in one bounded session. The skill writes sub-specs into Notion via the Notion MCP, with property schema discovered per-database so it adapts to your existing setup.

Stub-first as default cutting principle — the first sub-spec from any FE feat spec ships the structural skeleton (provider chain, navigation root, base services) with stubs for everything siblings will fill in. Each later sub-spec replaces stubs from earlier sub-specs. Out of Scope sections explicitly name sibling sub-specs by ID so the boundaries are unambiguous.

Plan Split annotations — when a sub-spec's logical scope would exceed the ~250k-token AI sweet spot (where AI output quality starts to degrade — "AI-rot"), the skill embeds a Plan Split section in the sub-spec body. Hoangsa's /hoangsa:prepare uses this annotation to plan two sequential cook sessions instead of one oversized one. The skill names boundaries by REQ + file category; hoangsa runs the actual token math.