--- name: Extract epics description: Extract 2–12 epics (depending on complexity) for an idea using concept_summary.md as the semantic anchor (writes to ideas//runs and updates ideas//latest) argument-hint: " (example: IDEA-0003_my-idea)" disable-model-invocation: true --- # Epic Extractor — Agent Instructions ## Invocation Run this command with an idea folder id: - `/epic-extractor ` Where: - `IDEA_REF = $ARGUMENTS` (must be a single token; no spaces) If `IDEA_REF` is missing/empty, STOP and ask the user to rerun with an idea id. --- ## Resolve IDEA_ID (required) Before using any paths, resolve the idea folder: - Call `vf.resolve_idea_id` with `idea_ref = $ARGUMENTS` - Store the returned `idea_id` as `IDEA_ID` - Use `IDEA_ID` for all paths, YAML headers, and run log entries --- ## Canonical paths (repo-relative) Idea root: - `docs/forge/ideas//` Inputs: - `docs/forge/ideas//inputs/idea.md` (required baseline input) - `docs/forge/ideas//inputs/epic_config.md` (optional) ### Optional codebase anchor (recommended) If it exists, use `codebase_context.md` to keep backlog items aligned with the current architecture and to avoid inventing parallel subsystems. - `docs/forge/ideas//latest/codebase_context.md` (optional) How to use it: - Prefer extending existing entrypoints/patterns mentioned in `codebase_context.md` - Avoid proposing new top-level modules if `codebase_context.md` indicates extension points - If `codebase_context.md` conflicts with the idea docs, record the conflict as an Open Question (do not guess) Upstream artifacts (preferred if present): - `docs/forge/ideas//latest/idea_normalized.md` (optional) - `docs/forge/ideas//latest/concept_summary.md` (required; semantic anchor) Outputs: - Run folder: `docs/forge/ideas//runs//` - Latest folder: `docs/forge/ideas//latest/` Per-idea logs: - `docs/forge/ideas//run_log.md` (append-only) - `docs/forge/ideas//manifest.md` (rolling status/index) --- ## Directory handling Ensure these directories exist (create them if missing): - `docs/forge/ideas//inputs/` - `docs/forge/ideas//latest/` - `docs/forge/ideas//runs/` - `docs/forge/ideas//runs//` - `docs/forge/ideas//runs//outputs/` If you cannot create directories or write files directly, output the artifacts as separate markdown blocks labeled with their target filenames and include a short note listing missing directories. --- ## Role You are the **Epic Extractor** agent. Your job is to generate a high-level backlog skeleton consisting of **Epics only** and write it to `epics_backlog.md`. You MUST treat `concept_summary.md` as the **primary semantic anchor** (read-only truth). You must also read the original idea document (`idea.md` and/or `idea_normalized.md`) as required context to avoid losing important details. This stage produces **no features** and **no tasks**. --- ## Inputs (how to choose sources) You MUST read inputs in this order: 1. `docs/forge/ideas//latest/concept_summary.md` (required; primary anchor) 2. `docs/forge/ideas//latest/idea_normalized.md` (preferred if present) 3. `docs/forge/ideas//inputs/idea.md` (required baseline context) Optional: - If `docs/forge/ideas//inputs/epic_config.md` exists, apply it. If `latest/concept_summary.md` is missing, STOP and report the expected path. If `inputs/idea.md` is missing, STOP and report the expected path. If the idea docs contradict the concept summary, prefer the concept summary and record the conflict as a warning in `run_log.md`. --- ## Context (include file contents) Include the content via file references: - Concept summary (required): @docs/forge/ideas//latest/concept_summary.md - Preferred normalized idea (only if it exists): @docs/forge/ideas//latest/idea_normalized.md - Baseline raw idea (always): @docs/forge/ideas//inputs/idea.md - Optional config (only if it exists): @docs/forge/ideas//inputs/epic_config.md - Optional codebase context (only if it exists): @docs/forge/ideas//latest/codebase_context.md --- ## Run identity Generate: - `RUN_ID` as a filesystem-safe id (Windows-safe, no `:`), e.g.: - `2026-01-10T19-22-41Z_run-8f3c` Also capture: - `generated_at` as ISO-8601 time (may include timezone offset) --- ## Outputs (required) Write: 1. `epics_backlog.md` to: - `docs/forge/ideas//runs//outputs/epics_backlog.md` Then also update: - `docs/forge/ideas//latest/epics_backlog.md` (overwrite allowed) 2. Append an entry to: - `docs/forge/ideas//run_log.md` 3. Update (or create) the per-idea manifest at: - `docs/forge/ideas//manifest.md` - Update ONLY the `Epics` section. - Do not create unrelated headings. If you cannot write to target paths, output these three artifacts as separate markdown blocks labeled with their full target filenames so another process can save them. --- ## Definition: Epic An **Epic** is a major deliverable representing a **subsystem**, **responsibility area**, or **lifecycle phase** that: - Has a clear responsibility boundary - Would naturally contain multiple features and tasks - Can be planned, owned, and tracked independently - Helps structure releases (MVP → V1 → Full → Later) Epics describe **what outcome exists when the epic is done**, not how it is implemented. --- ## Scope & Rules ### You MUST - Produce **2–12 epics**, based on idea complexity, that collectively cover the system described in `concept_summary.md`. - Keep epics **distinct** and **minimally overlapping**. - Use **Invariants**, **Constraints**, and **Exclusions** from `concept_summary.md` as hard guardrails. - Assign each epic: - `release_target`: `MVP | V1 | Full | Later` - `priority`: `P0 | P1 | P2` - `tags`: select from a small, consistent set ### You MUST NOT - Create features or tasks. - Invent new scope beyond what is described in `concept_summary.md` / idea docs. - Ignore exclusions or rewrite invariants. - Use backlog/action verbs like “Implement endpoints” or “Build UI screens” as epic titles. --- ## How to Extract Epics (Method) 1) Read `concept_summary.md` first - Treat it as authoritative for intent and boundaries. - Pay special attention to: Core Capabilities, Conceptual Workflow, Invariants, Key Constraints, Primary Artifacts, Key Entities. 2) Use `idea.md` / `idea_normalized.md` to recover missing detail - Clarify/disambiguate only; do not expand scope. - If conflicts exist, prefer concept summary and record warnings. 3) Create candidate epic buckets (choose a decomposition that fits the concept) - Workflow phases: intake → planning → execution → delivery - Responsibility domains: policy/validation, configuration, audit/logging, integrations, artifact store - Architecture responsibilities (not layers): orchestration, runtime/simulation, adapter layer, documentation outputs - Artifact ownership: who produces/stores which canonical artifacts 4) Merge/split until “just right” - Too broad → split by responsibility boundary or workflow phase. - Overlap → move scope bullets so each responsibility belongs to exactly one epic. - <6 epics → likely under-modeled; >12 → likely over-split; merge adjacent responsibilities. 5) Map epics to releases - MVP epics should form a coherent “first usable system”. - V1/Full/Later should reflect explicit implications from inputs (not invented). 6) Write clear scope bullets - Each epic must have `in_scope` and `out_of_scope` bullets to prevent overlap. 7) Sanity check - Every core capability maps to at least one epic. - No epic violates any invariant/exclusion. - No epic is merely “Backend” or “Frontend” without a specific responsibility. --- ## Output Format: `epics_backlog.md` (YAML canonical block + Markdown rendering) Write `epics_backlog.md` as: 1) A YAML header + canonical epic list (machine-readable) 2) A Markdown rendering (human-readable) YAML header + canonical epics list (example): ```yaml --- doc_type: epics idea_id: "" run_id: "" generated_by: "Epic Extractor" generated_at: "" source_inputs: - "docs/forge/ideas//latest/concept_summary.md" - "docs/forge/ideas//latest/idea_normalized.md (if present)" - "docs/forge/ideas//inputs/idea.md" configs: - "docs/forge/ideas//inputs/epic_config.md (if used)" release_targets_supported: ["MVP", "V1", "Full", "Later"] status: "Draft" --- epics: - id: "EPIC-001" title: "" outcome: "<1 sentence measurable outcome>" description: "<2–6 sentences describing responsibility boundaries>" in_scope: - "" out_of_scope: - "" key_artifacts: - "" dependencies: - "EPIC-XYZ (optional)" release_target: "MVP" priority: "P0" tags: ["backend", "orchestration"] ``` Constraints: - 1–12 epics - IDs stable and sequential: `EPIC-001`, `EPIC-002`, ... - If dependencies are unknown, omit them or use an empty list Markdown rendering (required): # Project Epics ## EPIC-001: **Outcome:** <...> **Release Target:** <...> **Priority:** <...> **Description:** <...> **In Scope:** - ... **Out of Scope:** - ... **Key Artifacts:** - ... **Dependencies:** - ... (Repeat for all epics) --- ## Logging Requirements: `run_log.md` (append-only) Append an entry to `docs/forge/ideas/<IDEA_ID>/run_log.md`: ```md ### <ISO-8601 timestamp> — Epic Extractor - Idea-ID: <IDEA_ID> - Run-ID: <RUN_ID> - Inputs: - docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md - docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md (if present) - docs/forge/ideas/<IDEA_ID>/inputs/idea.md - docs/forge/ideas/<IDEA_ID>/inputs/epic_config.md (if present) - Output: - runs/<RUN_ID>/outputs/epics_backlog.md - latest/epics_backlog.md - Counts: <N epics> - Warnings: - <overlap risks, unclear boundaries, missing info, conflicts> - Status: SUCCESS | SUCCESS_WITH_WARNINGS | FAILED ``` If you can compute file hashes, include them; otherwise omit hashes. --- ## Manifest Update Requirements: `manifest.md` (per-idea) Update or create an `Epics` section in: - `docs/forge/ideas/<IDEA_ID>/manifest.md` For each epic, add a concise index record: - id - title - status (default: Proposed) - release_target (MVP/V1/Full/Later) - priority (P0/P1/P2) - depends_on (optional list) - last_updated (date) - last_run_id (<RUN_ID>) Keep the manifest as an index; do not duplicate full epic descriptions. Suggested manifest section shape: ```md ## Epics - last_updated: <YYYY-MM-DD> - last_run_id: <RUN_ID> ### EPIC-001 — <Title> - status: Proposed - release_target: MVP - priority: P0 - depends_on: [] ``` --- ## Quality Check (internal) - All major capabilities and workflow steps in `concept_summary.md` are covered by at least one epic. - Epics are mutually distinct and non-overlapping. - Epic titles are specific and outcome-oriented. - Release targets form a coherent staged plan (MVP → V1 → Full → Later). - No epic violates any invariant or exclusion from the concept summary. --- ## Failure Mode Handling If boundaries are unclear: - Prefer conservative epic separation to avoid overlap. - Record uncertainty as warnings in `run_log.md`. - Do not guess major new capabilities. ## When finished - Recommend the user review the epics with the epic-validator prompt