Skip to main content

Epic authoring

Review-first workflow for drafting Epics from a short product brief, then applying them into planning/epics/. Complements epic-decomposition.md, which covers Epic → Task decomposition for epics that already exist.

Flow​

brief → plan create-epic → validate → review → apply draft-epic → planning/epics/<id>.md

After apply, the epic behaves like any hand-authored artifact:

  • a2c show epic <id>
  • a2c plan decompose-epic <id>
  • a2c apply tasks-from-epic <id>

Automatic chaining is not implemented in this milestone.

Commands​

CommandPurpose
a2c plan create-epicPropose one epic draft from a brief (no writes)
a2c show draft-epic <id>Inspect the cached epic draft
a2c apply draft-epic <id>Write the validated draft into planning/epics/

Use --path / -C to point at a repository root (default: current directory).

Input modes​

Provide exactly one brief source:

FlagUse
--from-text "..."Inline one-paragraph brief
--from-file <path>Markdown or plain-text brief file
--stdinPiped input
a2c plan create-epic --from-text "Add dark mode for low-light usage."
a2c plan create-epic --from-file docs/briefs/dark-mode.md
echo "Improve onboarding completion." | a2c plan create-epic --stdin --provider mock

Providers​

Epic authoring reuses the Milestone 5 decomposition provider stack:

ProviderNotes
mockDefault; --fixture for deterministic JSON
openaiRequires OPENAI_API_KEY
localRequires --endpoint or A2C_LOCAL_LLM_ENDPOINT
ollamaPreset for Ollama /v1; probes OLLAMA_HOST

Resolution: --provider > decomposition.provider in .a2c/config.yaml > mock.

Review and apply​

After plan create-epic succeeds:

  1. Read the CLI summary (id, title, status, section previews).
  2. Optionally run a2c show draft-epic <id> for the full draft body.
  3. Run a2c apply draft-epic <id> to write planning/epics/<id>.md.

Drafts are cached under .a2c/cache/create-epic/<id>/ as Markdown plus meta.yaml. The draft id is the proposed epic id.

Guarantees​

  • Provider output is untrusted until validated through a2c_core.
  • plan never writes into planning/epics/.
  • apply re-validates the draft and refuses to overwrite an existing epic file unless --force.
  • Re-running plan create-epic with the same epic id replaces the cached draft.

Epic id handling​

  • The provider may suggest an id; A2C validates it against existing artifacts.
  • If the provider omits id, A2C allocates a deterministic epic-<slug> from the title.
  • Collisions with an existing epic id fail at plan time (or at apply if the file appeared later).

Example end-to-end​

# 1. Draft an epic
a2c plan create-epic --from-text "Add dark mode." --provider mock --fixture tests/fixtures/workflows/create_epic_valid.json

# 2. Review
a2c show draft-epic epic-dark-mode

# 3. Apply
a2c apply draft-epic epic-dark-mode

# 4. Continue with task decomposition
a2c plan decompose-epic epic-dark-mode --provider mock
a2c apply tasks-from-epic epic-dark-mode

Limitations (first version)​

  • One brief → one epic draft per run.
  • No multi-epic generation, sprint planning, or automatic Epic → Task chaining.
  • No interactive TUI flow yet.
  • Uses the same decomposition config block as epic decomposition (no separate provider config).