--- name: engy:milestone-plan description: "This skill should be used when the user asks to 'plan my project', 'plan milestones', 'break down into tasks', or 'create tasks for milestone'. Plans spec milestones in detail — task groups, tasks, dependencies, and priorities." --- # Milestone Planner The spec already contains a high-level list of milestones. This skill plans **one milestone at a time** in detail — defining task groups, individual tasks, dependencies, and priorities. Everything is presented to the user for approval before creating anything in the system. ## EARS-BDD Mode Check whether EARS-BDD is enabled for this workspace — the agent's appended system prompt or `getWorkspaceDetails` will indicate it (`earsBdd: true`). When enabled, each TG's `### Requirements` lists the durable `FR--` ids it delivers (drawn from the SRS, reused verbatim — replacing the `FR-TG1.N` local numbering); allocate a new durable id only for milestone-level detail the SRS did not capture. Follow the planning augmentations in `plugins/engy/skills/implement/references/ears-bdd.md` for FR-graph orientation (use the area's existing FRs + `trace` to find current behaviour, tests, and code before exploring), the id scheme, allocation rule, and funnel discipline. When disabled, use the hierarchical `FR-TG1.N` scheme below unchanged. ## Multi-Repo Task Scoping When a workspace manages multiple repos, task scoping rules apply: - **Task groups** can span multiple repos — set their `repos` field to all repos the group's tasks touch. - **Tasks must each target a single repo.** Never create a task that requires working across multiple repos simultaneously. Mention the target repo/package in the task title or description (e.g., "Implement auth middleware in `web/`"). - **Cross-repo dependencies** within a group use `blockedBy` — upstream repo tasks (e.g., shared types in `common/`) should be completed before downstream consumers (e.g., `web/`). ### Discovering Repos Call `getProjectDetails(projectId)` and inspect `workspace.repos` (an array of local repo paths). If the array has more than one entry, apply the multi-repo rules above when planning task groups and tasks. For single-repo workspaces, these rules are effectively no-ops — all tasks naturally target the same repo. ## Planning Levels ### Level 1: Identify Which Milestone to Plan 1. Get the project's `specDir` via `getProjectDetails` (returned at `paths.specDir`). 2. Read `{specDir}/spec.md` and extract the existing milestone list. 3. **Determine which milestone to plan:** - If the user specified a milestone, use that one. - Otherwise, check for existing milestone plan docs via `Glob("{specDir}/milestones/m*-*.plan.md")` or task groups via `listTaskGroups`. Find the **next unplanned milestone** in sequence. 4. Present the selected milestone and its scope to the user for confirmation before proceeding. **Do NOT create task groups or tasks yet.** Level 1 is purely about selecting and confirming which milestone to plan. **One milestone per run.** Do not plan multiple milestones unless the user explicitly asks. ### Level 1.5: Research Prior Knowledge Before writing the milestone plan body, dispatch the `engy:research` subagent to surface relevant prior decisions, patterns, and architectural context from the workspace knowledge graph. **Resolve `workspaceId` first.** If not already known from context, call `listWorkspaces` (or `getWorkspaceDetails`) to obtain it before dispatching — `engy:research` hard-errors without it. ``` Task({ subagent_type: 'engy:research', prompt: ' — context: project=, milestone=, repo= workspaceId=' }) ``` The subagent returns a digest with 3–8 cited findings. Fold it into the milestone plan document in the **Codebase Context** section or immediately after the **Overview**, wrapped in markers: ```markdown ``` The markers let future readers identify LLM-synthesized content and re-run the research step. If the subagent returns `No relevant prior knowledge found for this question.` (i.e., `Distinct findings: 0 (after dedup)` in the footer), omit the marker block entirely — do not write an empty block. When the milestone is repo-local, mention the repo path in the prompt so the subagent applies `filters.repo`. This step runs after Level 1 (milestone selection confirmed) and before writing the plan document. ### Level 2: Plan Milestone Details (Groups and Tasks) For the selected milestone: 0. **Confirm the correct projectId.** Use `listProjects` to find the project whose `specDir` matches the spec you're working with. Do NOT assume projectId=1. 1. **Discover workspace repos.** Call `getProjectDetails(projectId)` and check `workspace.repos`. If the workspace has multiple repos, apply the multi-repo task scoping rules (see above) throughout the remaining steps. 2. Review the milestone scope against the spec. 3. Break the milestone into **task groups**. Each group is a single deliverable — think one PR. Groups are ordered so they can be reviewed and merged as stacked PRs, making large milestones easier to review incrementally. For multi-repo workspaces, set the `repos` field on each group to the repos its tasks touch. **For each group, define its functional requirements** using hierarchical numbering (e.g., `FR-DC.1` for Dev Containers group) — or, in EARS-BDD mode, durable `FR--` ids (see "EARS-BDD Mode" above). FRs live under each TG, not at the top level — this keeps each group self-contained for agent dispatch. 4. Within each group, define 1 or more tasks that together produce that deliverable. Follow the vertical slicing and granularity guidelines below. **Each task must target a single repo** — include the target repo/package in the task title or description (e.g., "Implement auth middleware in `web/`"). For cross-repo dependencies, use `blockedBy` to order upstream tasks before downstream consumers. 5. For each task, specify: - Title and description (including target repo for multi-repo workspaces) - **File ownership** — list the files this task creates or modifies. This is critical for parallel execution: agents need to know what they own and what siblings touch. - **Acceptance criteria** — derived from the task group's FRs. These are what the implementer tests against. - **FR references** — which FRs this task implements (e.g., "Implements FR-TG1.1, FR-TG1.2") - Type (`ai` or `human`) - Importance and urgency (using the Eisenhower matrix) - Dependencies on other tasks (`blockedBy`) 6. **Present the full breakdown to the user and wait for explicit approval.** 7. Write the milestone plan document (`m{N}-{slug}.plan.md` with `status: draft`) using the template below. This doc *is* the presentation — approval happens on this doc. 8. **Stop and wait** for the user to request TG planning (e.g., "plan TG1 stories"). ### Task Group Planning When the user asks to plan a specific TG: 1. Read the milestone doc's TG section (requirements, task outline, file ownership) as context. Update milestone doc status to `planning` if still `draft`. 2. **For each task, decide whether `/engy:plan` is warranted.** A separate planning pass is only needed when the milestone doc's task block leaves real ambiguity. Run `/engy:plan` if **any** of the following apply: - The task touches more than 2 files of non-trivial size. - The task description is vague — contains "TBD", "implementer's choice", "decide between X and Y", or leaves a key design choice open. - The task spans architectural boundaries (e.g., adds a new layer, changes a cross-cutting protocol, introduces a new pattern other tasks will follow). Otherwise, the milestone doc's task block (title, file ownership, FR refs, acceptance criteria, brief description) is sufficient — skip `/engy:plan`. 3. Create the task group and tasks via `createTaskGroup` / `createTask`. - Set `milestoneRef` on every task (e.g., `"m3"`) to link it to the milestone. - Set `specId` to the spec directory name so the task resolves to the correct spec path. - For multi-repo workspaces, pass the `repos` array when calling `createTaskGroup`. - **For tasks that got a `/engy:plan` pass:** set `needsPlan: false` and store the plan doc path in the task description. - **For tasks that didn't:** set `needsPlan: true` and copy the milestone doc's task block (files, FR refs, description, acceptance criteria) into the task description as-is. The implementer agent can still spin up its own plan pass at implementation time if it hits ambiguity. 4. Verify structure via `listTasks` and `listTaskGroups`. 5. When all TGs are planned and created, update milestone doc status to `complete`. #### Example: when to plan, when to skip Both tasks below come from the same TG. The first warrants `/engy:plan`; the second does not. - **Plan-warranted:** *"Wire spawn-event replay into mobile terminal sheet."* Touches `web/src/components/terminal/*`, `web/src/server/ws/handlers.ts`, and `client/src/terminal/session.ts` (3 files, 2 layers, cross-cutting protocol change). Run `/engy:plan`, store the plan path, `needsPlan: false`. - **Skip:** *"Add `status: 'planning'` to milestone plan doc frontmatter type."* Touches one file, the milestone doc's task block already lists the exact field, file, and acceptance criteria. Copy the task block into the description, `needsPlan: true` as a safety net. ## Vertical Slicing **Use vertical slices, not horizontal layers.** Each task should deliver a thin, end-to-end slice of functionality that touches all necessary layers (database, service, API, UI). A good slice is small but complete — something that can be tested and verified independently. Bad (horizontal): "Create all database tables" then "Build all API endpoints" then "Add all UI components" Good (vertical): "User can create a task and see it in a list" then "User can mark a task complete" then "User can filter tasks by status" ### Execution Order Within a Slice Within each vertical slice, order subtasks as: 1. Schema / data model changes 2. Data access layer (repositories / queries) 3. Service / business logic 4. API endpoints 5. UI components 6. Integration tests ## Task Granularity - **Target size**: 1-4 hours of work, or 5-8 concrete implementation steps - **Maximum**: 6 tasks per feature/story - **Minimum viable**: Each task must produce something testable - **Context budget**: Tasks should complete within ~10-20 minutes of autonomous agent work - If a task has more than 8 steps, split it. If it has fewer than 3 steps, combine with related work. ## Task Quality Checklist Each task should be: - **Self-sufficient for simple tasks, plan-ready for complex ones**: The milestone task block should be detailed enough that simple, single-file tasks can skip `/engy:plan` entirely (see Task Group Planning's conditional flow). For multi-file or architecturally cross-cutting tasks, the block must still be a good launching pad — a `/engy:plan` pass with the task description + milestone plan context should produce a complete implementation plan. The milestone task always defines *what* and *where*; the planning pass (when needed) discovers *how*. - **Explicit**: Reference specific files, functions, and patterns from the existing codebase. **Never reference line numbers** — they go stale. Reference by function name, class name, or pattern description instead. - **File-owned**: List every file the task creates or modifies. This lets parallel agents know what they own and what siblings touch. - **Feature-traced**: Reference which FRs this task covers, so nothing is missed and nothing is invented - **Verifiable**: Include what shell commands prove the task is done (e.g., `pnpm test`, `pnpm lint`) - **Repo-scoped**: In multi-repo workspaces, each task targets a single repo (mentioned in title or description) - **File-conflict-free**: No two parallel tasks modify the same file. Identify shared touchpoint files (routers, protocol types, schema definitions, composition roots) and ensure tasks touching them are serialized via `blockedBy` or combined into a single task - **Atomically testable**: If you can't test a task independently (e.g., protocol changes without handlers, dispatch without pending maps), it's not a real task — combine it with its dependencies into one task ## Anti-Patterns to Flag When reviewing the breakdown, watch for and restructure: - Tasks that only touch one layer (pure DB, pure UI) — prefer vertical slices - Tasks with vague acceptance criteria ("works correctly") - Tasks with 10+ steps (too large) - Circular dependencies - Tasks that span multiple repos — split into separate single-repo tasks with `blockedBy` for ordering - Tasks that require context from many previous tasks (context rot risk) - **Parallel tasks that modify the same file** — tasks that create or modify the same file MUST be serialized via `blockedBy`, never placed in the same parallel wave. If two tasks both need to add to the same file (e.g., both add routes to a router or message types to a protocol), either combine them into one task or serialize them explicitly via `blockedBy`. - **Tasks that reference patterns created by siblings** — if task B says "follow the pattern in X" and task A creates that pattern, B must `blockedBy` A. Pattern-establishing tasks must be identified and serialized before pattern-consuming tasks. - **Untestable splits** — protocol changes, dispatch functions, pending maps, and handlers are one atomic unit. If you can't run a test after completing the task alone, it's not a valid split. Combine into one task. ## Eisenhower Matrix for Prioritization Use importance and urgency to classify tasks: | | Urgent | Not Urgent | |---|---|---| | **Important** | Critical path, blockers | Architecture, quality | | **Not Important** | Quick wins, polish | Nice-to-haves, defer | - Mark critical-path tasks and blockers as `important` + `urgent` - Architecture and quality work is `important` + `not_urgent` - Quick wins and polish are `not_important` + `urgent` - Nice-to-haves are `not_important` + `not_urgent` (consider deferring) ## Milestone Plan Document Template After the task breakdown is approved and created, produce a `m{N}-{slug}.plan.md` document at `{specDir}/milestones/m{N}-{slug}.plan.md` (where `specDir` is resolved from `getProjectDetails`'s `paths.specDir`). This is the canonical location where `/engy:implement` and `/engy:implement-milestone` look for plan docs. ```markdown --- title: {Milestone Name} status: draft --- # Plan: M{N} {Milestone Name} ## Overview {1-2 paragraphs: what this milestone delivers and its boundary. End with an explicit "Boundary: no X, no Y, no Z." sentence listing what is NOT included.} ## Codebase Context {Key existing files, patterns, and components that this milestone builds on. Reference actual paths and describe what each does — this orients the implementer. Include a note on what previous milestones shipped if relevant.} ## Task Group Sequencing {Dependency graph between TGs. Which TGs can start immediately, which depend on others, and what specifically they depend on.} - **TG1: {Name}** — no dependencies. Can start immediately. - **TG2: {Name}** — depends on TG1 ({what specifically}). - ... ## TG1: {Task Group Name} {One paragraph: what this group delivers and why it's sequenced here.} ### Requirements 1. The system shall {concrete, testable behavior}. *(source: user request | inferred | elicited)* (FR-TG1.1) 2. ... ### Tasks 1. **{Task title}** - Files: `path/to/file.ts` [NEW], `path/to/other.ts` [MODIFY] - Implements FR-TG1.1, FR-TG1.2 - {Brief description of what to build} 2. **{Task title}** (depends on task 1) - Files: `path/to/another.ts` [NEW] - Implements FR-TG1.3 - {Brief description} **Parallelizable:** Tasks 1, 3 have no dependencies and can run concurrently. ### Completion Summary {Updated after TG completes — what was actually shipped, key APIs/patterns created, anything the next TG's agents need to know. Leave blank until done.} ## TG2: {Task Group Name} {Repeat structure. Can reference TG1's completion summary for context.} ... ## Out of Scope - {Feature} (deferred to M{X}) - ... ``` ### Template Notes - **Frontmatter status**: `draft` → `planning` → `complete` - **No top-level Affected Components or FR sections** — these live under each TG, making each group self-contained for agent dispatch - **Hierarchical FR numbering**: `FR-TG1.1`, `FR-TG2.1`, etc. — scoped to task group number, deletions in one TG don't affect another - **Source attribution** on each FR: `(user request)`, `(inferred: reason)`, or `(elicited)` — tracks provenance - **Codebase Context** prevents the implementer from reimplementing what exists or breaking established patterns - **Completion Summary** per TG is updated after implementation — gives the next TG's agents context on what shipped without them having to read the code - **File ownership per task** — every task lists its files so parallel agents know boundaries - **Never use line numbers** in task descriptions — they go stale. Reference by function/class/pattern name ## Key Principles - **Never auto-create.** Always present the full breakdown and wait for explicit user approval before calling `createTaskGroup` or `createTask`. - Ask clarifying questions when scope is ambiguous. - Keep milestones independent and shippable. - Set realistic dependencies — avoid over-constraining. - Plan content should explain the "how" and "why", not just list tasks. - **Milestone-doc detail absorbs `/engy:plan`.** A well-written milestone task block (file ownership, FR refs, acceptance criteria, concrete step-level intent) IS the plan for 1–4 hr tasks. Reserve `/engy:plan` for tasks with real ambiguity — multi-file, vague, or architecturally cross-cutting. When in doubt, lean on `needsPlan: true` so the implementer can plan at execution time if it hits friction. ## Flow Position **Previous:** `write-spec` | **Next:** `implement` (with `plan` invoked conditionally per task) Once the milestone plan doc is written and approved, the user typically asks to plan a specific TG ("plan TG1"). Within that TG planning pass, run `/engy:plan` only for tasks that warrant it (see the Task Group Planning criteria); simple tasks ship straight to `/engy:implement` with `needsPlan: true` as a safety net.