Evyasys Plan

---
name: evyasys-plan
description: Use this skill to plan work end to end in one command. Reads the live board once and decides whether the work attaches to an existing epic or needs a new one; plans and drafts several stories under that epic; reads the real code once and writes expert-level tasks per story (architecture decisions, DB schema with migration and rollback, API contract, frontend design, security, performance, failure modes, tests); records reusable knowledge in .evyasys/knowledge/. Five gates — epic decision, story plan, story drafts, task drafts, publish. A deterministic quality gate (AC coverage, required sections, schema/rollback, dependency cycles, estimates) rejects incomplete plans before anything is saved. Publishing to the PM tool is idempotent and top-down (Epic → Stories → Tasks → dependency links); re-running updates changed items and never duplicates. Triggered by `/evyasys:Plan`.
trigger: /evyasys:Plan
---

# Skill: evyasys-plan

`/evyasys:Plan` plans epics, stories and tasks in one run — with
a stronger quality bar. The two original commands are unchanged and still work.

## The five gates

| Gate | Phase | Confirms |
|---|---|---|
| 1 | Epic decision | Attach to an existing epic, or create a new one — with evidence from the live board |
| 2 | Story plan | IDs, scope, points, ordering |
| 3 | Story drafts | Full stories with labelled acceptance criteria |
| 4 | Task drafts | Per-story expert tasks, AC coverage matrix, estimates, dependencies |
| 5 | Publish (hook) | Exactly what will be created / updated in the PM tool and notified |

## What makes it different

- **One board read.** A single cached snapshot (epics + stories, PM tool and local merged) drives the epic
  decision and allocates collision-free IDs. No repeated queries.
- **Grounded tasks.** The agent reads the real migrations, controllers, services and components once, finds a
  reference implementation for each unit of work, and searches for reuse before proposing anything new.
- **Expert task depth.** Every task carries the design decision and rejected alternatives, data model (table +
  migration + rollback), API contract, frontend design, security, performance and an error-behaviour table.
- **Deterministic quality gate.** The hook lints the plan — every AC covered, sections substantive, no placeholders
  or code, schema has rollback, dependencies acyclic, tasks ≤ 8 h, QA scenarios complete — and saves nothing if it fails.
- **Idempotent publish.** Items are keyed by an `evya:<ID>` tag and a content hash (content + parent + dependencies).
  Unchanged items make no request; changed items are updated in one PATCH (tags and parent come from one batch read,
  a moved story is re-parented); a failed parent skips its children; a failed dependency link is retried next run;
  an item deleted in the PM tool is re-created; existing epics are only tagged and commented, never rewritten.
  A new epic is created once and is human-owned afterwards — later edits to the PM epic are never overwritten.
- **No ID collisions.** Just before saving, the hook re-reads the board once and rejects any "new" ID that already
  belongs to a different item (a stale snapshot or a teammate's concurrent run), so nobody's work is overwritten.
- **Quiet notifications.** Only what this run created or changed is announced; re-running an unchanged plan notifies nobody.
- **Knowledge base.** Epic design notes, data model, API contracts, decisions (ADRs) and glossary accumulate in
  `.evyasys/knowledge/` and are read by later planning runs instead of re-deriving them.

## What reaches the PM tool

| Level | Content |
|---|---|
| Epic | Goal, outcome, scope, linked stories; tag `evya:EP-xxx` |
| Story | Functional description; the real **Acceptance Criteria** field; story points; impact tags |
| Task | Full technical specification; original estimate / remaining work; activity; layer tag; predecessor links |

Every description ends with the repo path of its source of truth. Titles carry the Evyasys ID
(`EVYA-1042: …`, `EVYA-1042-T2: …`), the ADO number is written back into the local files, and `.evyasys/.ado-map.json`
keeps the mapping — so every command that follows resolves the same item.

## Output

| Artefact | Path |
|---|---|
| Epic | `.evyasys/board/epics/{epicId}/{epicId}_Epic.md` |
| Story | `.evyasys/board/epics/{epicId}/stories/{storyId}/{storyId}_UserStory.md` |
| Tasks | `.evyasys/board/epics/{epicId}/stories/{storyId}/subtasks/{storyId}_Subtasks.md` |
| Knowledge | `.evyasys/knowledge/**` (+ generated `index.md`) |
| Mapping | `.evyasys/.ado-map.json` (epics, stories, tasks; content hashes) |

Files and formats are stable (the same names and places every earlier release used), so `Build`, `Qa` and the rest consume
them unchanged.

## PM tools

Azure DevOps gets the full idempotent upsert. Jira and GitHub Projects use create-only sync guarded by the map
(no duplicates for items already mapped; no in-place updates). `local` saves everything and publishes nothing.

## Failure handling

- Lint failure → nothing saved; the agent is told exactly what to fix.
- Gate 5 declined → local files stay; re-run to publish later.
- Partial PM failure → completed items are kept and mapped; failed items are listed; re-run retries only those.
- Truncated agent output → detected and rejected before any write.