SuperAPI AI Directory

feature-workflow

Coding & development

View repository

Updated 11-16 16:09

About this skill

Feature Workflow

Working memory that survives sessions, agents, and parallel features. One line: plans hold the work; docs hold the truth.

  • .plans/<name>.md = working memory for ONE piece of work. Live, brainstorm-friendly, ephemeral. Deleted when shipped.
  • _docs/ = source of truth. How the system works today, third-party API behavior, established patterns. Durable, authoritative.
  • Plans link to docs, never duplicate them. A durable fact discovered while working gets promoted into _docs/ before the plan is deleted. Never let truth die with the plan.

Tool-agnostic: the same files serve Claude Code, Codex, or any agent (reference this procedure from AGENTS.md so every agent follows it).

Entry point — invoked with a feature name

When asked to start or resume work on <feature> (e.g. "feature-workflow risk-profiling", "pick up the bottom-nav work"), hydrate in this order — do not touch code before step 4:

  1. _docs/features/<feature>/roadmap.md — the feature's items, statuses, debt sections. Create it if starting something new.
  2. The linked plan (→ .plans/<name>.md on the in-progress item), or create one from the format below (and set the roadmap item [in-progress]).
  3. Every doc the plan's Source of Truth section links.
  4. Run reconcile-on-open (below). Only then act.
  5. Report to the human: current state, drift found, next step about to be taken.

Plan format

# Plan: <name>
Status: brainstorm | approved | in-progress | blocked | shipped
Last reconciled: <date> — <matches reality? what drifted?>

## Goal
## Decisions          ← locked choices + why (crystallized brainstorm)
## Open Questions     ← still-live brainstorm (resolve → move to Decisions)
## Current State      ← VERIFIED ground truth now, not assumed
## Next Steps         ← ordered resume point: exact place to pick up
## Regression Guard   ← how to avoid breaking existing behavior
## Out of Scope
## Source of Truth    ← links to _docs/, API docs, key file:line

Task lists, test cases, data models slot under Next Steps / Current State. One-line, actionable, agent-register (terse facts, file:line — plans are agent-read; docs for humans stay prose).

Reconcile-on-open — never stale

The resume guarantee is a cheap ritual, not "the agent remembers":

read plan → VERIFY each "done" claim against real code/db → note drift in
Current State → rewrite Next Steps → stamp Last reconciled → then act

Never trust a checkbox. A plan whose "done" you haven't verified is a rumor. During work: update the plan in the same turn as the change, never batched for later. On stop/handoff: Next Steps points at the exact resume point; no done that isn't.

Brainstorm in the plan

The plan is where thinking out loud lives — options weighed, discussion recorded. Keep it from rotting: resolved → one-line Decision with the why; unresolved → Open Questions; loose musing either crystallizes or dies.

Roadmap contract

Every plan implements a roadmap item:

  1. Find (or create) _docs/features/<feature>/roadmap.md
  2. Set the item [in-progress] and link it: → .plans/<name>.md
  3. On ship: [shipped], remove the plan link, promote durable facts, delete the plan
  4. On abandon: revert to [planned], delete the plan

Tech debt and product debt live in the same roadmap.md under their own sections — one place per feature, not a separate debts folder. Cross-cutting infra debt → _docs/architecture/roadmap.md.

Don't invent

Before touching a third-party integration or existing subsystem, read its _docs/ entry — it is authoritative. If docs and reality disagree, reality wins: fix the docs and cite the source (API URL, file:line, commit) so the correction is verifiable, not another invention.

With gated-build

For high-stakes adversarial builds (see the gated-build skill), the feature's plan file IS that build's anchor document — the grill trail, evidence ledger, and tombstones live as sections inside it. Multiple concurrent gated builds = multiple plans, each hydrated by name through the entry point above.


Provenance: production workflow from a live Laravel/fintech monorepo (mfstack), where multiple concurrent features + two agents (Claude Code, Codex) share the same plans and docs.