diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f1d1318 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.install-config diff --git a/skills/epic/SKILL.md b/skills/epic/SKILL.md new file mode 100644 index 0000000..932958a --- /dev/null +++ b/skills/epic/SKILL.md @@ -0,0 +1,64 @@ +--- +name: harness-epic +description: Create or update an epic-level roadmap under docs/exec-plans/current/ from informal source material. Use when an epic is composed of multiple feature slices and needs a parent plan.md that sequences child work items, rather than a phase-by-phase implementation plan for a single feature. +examples: + - "$harness-epic docs/exec-plans/current/epics/ab_testing" + - "$harness-epic docs/exec-plans/current/epics/math" +when_to_use: + - "An informal epic description exists and the user wants an epic roadmap." + - "The work spans multiple features or child work items." + - "The output should guide later PRD/FDD/requirements/implementation plans per feature slice." +when_not_to_use: + - "A single feature already has PRD/FDD and needs an implementation plan; use $harness-plan." + - "The user wants implementation or coding." +--- + +# Harness Epic + +Create an epic-level roadmap, usually `/plan.md`, from `informal.md`, existing parent docs, and relevant child feature docs. + +## Required Inputs + +Load these when present: + +- `/informal.md` +- `/requirements.md` +- `/approach.md` +- `/plan.md` if updating +- Child feature `informal.md`, `prd.md`, `fdd.md`, `plan.md`, and `requirements.yml` only as needed to understand current decomposition +- `references/roadmap_guidance.md` +- `assets/templates/epic_plan_template.md` + +If repo-level guidance exists, skim only the relevant files needed for documentation conventions, such as `AGENTS.md`, `harness.yml`, or nearby epic examples. + +## Workflow + +1. Resolve the epic directory under `docs/exec-plans/current/`. +2. Read the informal source and nearby parent docs. +3. Inspect sibling or child feature directories enough to infer established documentation style and decomposition. +4. Decide whether the output is a new roadmap or an update to an existing roadmap. +5. Write or update `/plan.md` as a parent roadmap, not an implementation plan. +6. Sequence feature slices by dependency and risk. +7. For each feature slice, describe scope, exclusions, ordering rationale, and expected child artifacts. +8. Include a slice dependency graph when there is more than one non-linear dependency or when the graph would clarify parallelizable versus serial work. +9. Call out cross-cutting concerns, migration/cutover, observability, testing posture, and open questions. +10. Do not create child PRDs/FDDs/requirements/plans unless the user explicitly asks. + +## Output Rules + +- Use repository-relative paths in roadmap text. +- Keep implementation tasks high-level. Do not write detailed phase tasks, test commands, or line-item coding checklists for the whole epic. +- Preserve clear slice boundaries so follow-up skills can operate on one child feature at a time. +- Make dependencies explicit: "this comes before X because..." +- Add a Mermaid dependency graph for multi-slice epics when it improves readability; keep node labels concise and aligned with the feature slice names. +- Include likely child directories when helpful, but avoid creating empty directories unless requested. +- If updating an existing roadmap, preserve useful existing structure and revise only what the new source requires. + +## Hand-Off Pattern + +End with the recommended next child slice to document and which Harness skill should be used next: + +- `harness-analyze` for a child `prd.md` +- `harness-architect` for a child `fdd.md` +- `harness-requirements` for child `requirements.yml` +- `harness-plan` for a child implementation `plan.md` diff --git a/skills/epic/assets/templates/epic_plan_template.md b/skills/epic/assets/templates/epic_plan_template.md new file mode 100644 index 0000000..e84cb57 --- /dev/null +++ b/skills/epic/assets/templates/epic_plan_template.md @@ -0,0 +1,75 @@ +# Roadmap + +## Purpose + +Describe what this roadmap coordinates and make clear that this is not a phase-by-phase implementation plan. + +## Core Direction + +Summarize the epic's product and technical direction in a few bullets. + +## Current Foundation + +Describe what already exists and what should be treated as a dependency or constraint. + +## Sequencing Principles + +- Principle 1 +- Principle 2 +- Principle 3 + +## Feature Sequence + +### 1. + +Likely directory: `/` + +Deliver: + +- ... + +Defer: + +- ... + +Dependencies: + +- ... + +Why this comes here: + +- ... + +Expected child artifacts: + +- `/prd.md` +- `/fdd.md` +- `/requirements.yml` +- `/plan.md` + +## Slice Dependency Graph + +```mermaid +flowchart TD + FIRST["First Slice"] + SECOND["Second Slice"] + + FIRST --> SECOND +``` + +## Cross-Cutting Concerns + +- Migration/cutover +- Data ownership and persistence +- Security/privacy +- Performance/reliability +- Observability/auditability +- Testing and verification + +## Open Questions + +- ... + +## Recommended Next Slice + +Name the next child slice to document and the appropriate follow-up Harness skill. diff --git a/skills/epic/references/roadmap_guidance.md b/skills/epic/references/roadmap_guidance.md new file mode 100644 index 0000000..adb270b --- /dev/null +++ b/skills/epic/references/roadmap_guidance.md @@ -0,0 +1,60 @@ +# Epic Roadmap Guidance + +An epic roadmap is a parent planning artifact for a body of work composed of multiple feature slices. It should explain what order the slices should be tackled in and why. It should not be a tactical implementation plan for the entire epic. + +## Roadmap Shape + +Use this structure unless the repository has a stronger local convention: + +- Purpose +- Core Direction +- Current Foundation +- Sequencing Principles +- Feature Sequence +- Slice Dependency Graph, when useful for multi-slice dependency clarity +- Cross-Cutting Concerns +- Suggested Child Artifacts +- Open Questions + +## Feature Slice Entry + +For each feature slice, include: + +- slice name and likely directory slug +- what the slice delivers +- what it intentionally excludes +- dependencies +- why it comes at this point in the sequence +- likely follow-up artifacts, usually `informal.md`, `prd.md`, `fdd.md`, `requirements.yml`, and `plan.md` + +## Good Slices + +Good feature slices are bounded by stable interfaces or dependency layers. Examples: + +- shared contract before runtime behavior +- runtime behavior before authoring UI +- persistence and migration before cutover +- outcome/reward plumbing before adaptive algorithms +- analytics after assignment/exposure data exists + +Avoid slices that are only team names, vague phases, or arbitrary time boxes. + +## Roadmap Versus Implementation Plan + +An epic roadmap says: + +- what feature slices exist +- why their order matters +- what each slice should produce +- what risks and unknowns affect the sequence +- how slices depend on each other, optionally summarized in a concise Mermaid graph + +An implementation plan says: + +- exact phases +- engineering tasks +- test commands +- gates for one feature +- definitions of done + +If the requested artifact is for a single feature with PRD/FDD, use `harness-plan` instead.