diff --git a/.github/agents/dev-loop.agent.md b/.github/agents/dev-loop.agent.md index d79a5eb..9304097 100644 --- a/.github/agents/dev-loop.agent.md +++ b/.github/agents/dev-loop.agent.md @@ -162,7 +162,7 @@ Break the approved design into bite-sized tasks (2-5 minutes each). Each task in - Exact test commands with expected output - Commit message -The file format, slug convention, and lifecycle for `tasks/-plan.md` +The file format, slug convention, and lifecycle for `tasks/--plan.md` are defined authoritatively in **`plan.agent.md` § Saving the Plan to `tasks/`**. Do not duplicate that spec here. @@ -172,17 +172,17 @@ updates the existing file in place** -- expand each skeleton checklist item into the bite-sized tasks described above. Treat unchecked items as the next tasks to execute. -If `tasks/-prd.md` exists (written by `@prd`), ingest it as +If `tasks/--prd.md` exists (written by `@prd`), ingest it as authoritative requirements input alongside the GitHub issue. -If `tasks/-plan.md` does not exist (e.g., the issue was +If `tasks/--plan.md` does not exist (e.g., the issue was filed manually, bypassing `@plan`), create it now using the format from `plan.agent.md` § Saving the Plan to `tasks/`. After expansion, get user approval and update the GitHub issue with the expanded task checklist. -**Exit criteria:** Plan saved/updated in `tasks/-plan.md`, +**Exit criteria:** Plan saved/updated in `tasks/--plan.md`, user approved, issue updated. ### Phase 3 -- TDD (Red -> Green) diff --git a/.github/agents/plan.agent.md b/.github/agents/plan.agent.md index 2cfeadc..26656dc 100644 --- a/.github/agents/plan.agent.md +++ b/.github/agents/plan.agent.md @@ -35,13 +35,13 @@ MUST present it and get approval. You MUST complete these steps in order: -1. **Explore project context** — check files, docs, recent commits; **scan `tasks/`** for prior PRDs or plans on the same feature slug (`tasks/-prd.md`, `tasks/-plan.md`). If found, surface them and offer to refine the existing design rather than propose a brand-new one. +1. **Explore project context** — check files, docs, recent commits; **scan `tasks/`** for prior PRDs or plans on the same feature (`tasks/--prd.md`, `tasks/--plan.md`; fall back to a glob `tasks/*--*.md` when the issue number is unknown). If found, surface them and offer to refine the existing design rather than propose a brand-new one. 2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria 3. **Propose 2-3 approaches** — with trade-offs and your recommendation 4. **Present design** — in sections scaled to complexity, get user approval after each section 5. **Declare the Evidence Plan** — every plan must name the change type, the artifact format, the exact capture command, and the entry-point file the reviewer will open (see "Evidence Plan" below). The dev-loop's Phase 5b verifies the produced artifact matches this declaration. 6. **Create GitHub issue** — save the approved design as a GitHub issue (the primary output) -7. **Save the plan to `tasks/-plan.md`** — durable, in-repo artifact mirroring the issue body. Format defined in **Saving the Plan to `tasks/`** below. This is the single authoritative spec for the `tasks/-plan.md` file -- `@dev-loop` Phase 2 *resumes / expands* this file, it does not redefine the format. +7. **Save the plan to `tasks/--plan.md`** — durable, in-repo artifact mirroring the issue body. Format defined in **Saving the Plan to `tasks/`** below. This is the single authoritative spec for the `tasks/--plan.md` file -- `@dev-loop` Phase 2 *resumes / expands* this file, it does not redefine the format. 8. **Transition to implementation** — hand off to `@dev-loop` for the full quality cycle ## The Process @@ -139,7 +139,7 @@ attestation markdown still serves as the entry-point file. ## Saving the Plan to `tasks/` -**This section is the authoritative spec for `tasks/-plan.md`.** +**This section is the authoritative spec for `tasks/--plan.md`.** `@dev-loop` Phase 2 references this section by name -- it does not redefine the file format. @@ -150,9 +150,14 @@ and expands it. ### Path and Slug Convention -- Path: `tasks/-plan.md` at the repo root. -- `` = `-` matching the GitHub issue - number and the eventual feature branch name (`feat/-`). +- Path: `tasks/--plan.md` at the repo root. +- `` = the GitHub issue number; `` = a short kebab-case + description. Together `-` is the shared identifier carried by + the GitHub issue, the feature branch (`feat/-`), and the PR. + Derive both from the current branch name. +- Look up an existing plan by the exact `tasks/--plan.md` first, + then fall back to a glob `tasks/*--plan.md`, then to a bare + `tasks/-plan.md` for legacy files predating the issue-number prefix. - Create the `tasks/` directory if it does not yet exist. - See `tasks/README.md` (consumer-owned) for the project's local conventions; do not contradict it. @@ -164,7 +169,7 @@ and expands it. - Issue: https://github.com///issues/ - PR: (filled in once the PR exists) -- Slug: +- Slug: - ## Overview [1-2 sentence description -- mirrors the issue body] diff --git a/.github/agents/prd.agent.md b/.github/agents/prd.agent.md index b6ab392..f442d25 100644 --- a/.github/agents/prd.agent.md +++ b/.github/agents/prd.agent.md @@ -12,13 +12,13 @@ This agent uses the default model. No specific model override is required. Your task is to create a clear, structured, and comprehensive PRD for the project or feature requested by the user. -Save the PRD to `tasks/-prd.md` at the repo root. Create the `tasks/` directory first if it does not yet exist (`mkdir tasks` or `New-Item -ItemType Directory -Path tasks -Force`). If the user specifies a different location, use that instead. +Save the PRD to `tasks/--prd.md` at the repo root, where `` is the GitHub issue number and `` is a short kebab-case description -- the same `-` identifier used by the feature branch (`feat/-`). Derive both from the current branch name when one exists. If no issue has been filed yet (a PRD spike), save to the bare `tasks/-prd.md` and rename it to add the `-` prefix once the issue is created. Create the `tasks/` directory first if it does not yet exist (`mkdir tasks` or `New-Item -ItemType Directory -Path tasks -Force`). If the user specifies a different location, use that instead. Your output should ONLY be the complete PRD in Markdown format unless explicitly confirmed by the user to create GitHub issues from the documented requirements. ## Instructions for Creating the PRD -0. **Check for an existing PRD**: At the start of the workflow, look for `tasks/-prd.md` using the slug the user has chosen (or one derivable from the branch name `feat/-`). If a PRD already exists for this feature, read it and offer to **update** it rather than overwrite. Surface the existing content to the user and ask whether to revise sections in place, append new sections, or start fresh. +0. **Check for an existing PRD**: At the start of the workflow, look for an existing PRD before writing a new one. Derive `` and `` from the current branch (`feat/-`) and check `tasks/--prd.md` first. If not found, fall back to a glob `tasks/*--prd.md` (issue number differs or is unknown), then to the bare `tasks/-prd.md` for legacy files predating the issue-number prefix. If a PRD already exists for this feature, read it and offer to **update** it rather than overwrite. Surface the existing content to the user and ask whether to revise sections in place, append new sections, or start fresh. 1. **Ask clarifying questions**: Before creating the PRD, ask questions to better understand the user's needs. diff --git a/tasks/README.md b/tasks/README.md index cf1b697..95259f1 100644 --- a/tasks/README.md +++ b/tasks/README.md @@ -11,16 +11,23 @@ session and the project can be reconstructed from these files alone. ## Filename Convention -One feature per slug. Each slug matches its branch name -(`feat/-`), so the PRD, plan, GitHub issue, branch, and PR -all share an identifier. +One feature per `-` identifier, shared by the PRD, plan, GitHub +issue, branch (`feat/-`), and PR: + +- `` -- the GitHub issue number; the leading token is identical to the + branch name, so `tasks/` sorts naturally by issue number. +- `` -- a short kebab-case description. | File | Written by | Purpose | |-------------------------------|--------------------------|------------------------------------------------------| -| `-prd.md` | `@prd` agent | Product requirements: user stories, acceptance criteria, metrics. | -| `-plan.md` | `@dev-loop` Phase 2 | Implementation plan: ordered tasks with file paths, code snippets, commit messages. | +| `--prd.md` | `@prd` agent | Product requirements: user stories, acceptance criteria, metrics. | +| `--plan.md` | `@dev-loop` Phase 2 | Implementation plan: ordered tasks with file paths, code snippets, commit messages. | | `MIGRATION.md` | `Consolidate-Tasks.ps1` | Audit trail of files imported from legacy locations. | +A PRD spike filed before an issue exists may use the bare `-prd.md` and +get renamed to add the `-` prefix once the issue is created. Legacy +files predating this convention may also appear as a bare `-{prd,plan}.md`. + ## Cross-Referencing Each artifact should link to its companion GitHub issue and PR. Recommended @@ -31,11 +38,11 @@ top-of-file header: - Issue: https://github.com///issues/ - PR: https://github.com///pull/ -- Slug: +- Slug: - ``` When a PRD or plan references stories or tasks by identifier, prefer the -GitHub issue number once it exists; use a local `-NN` form only +GitHub issue number once it exists; use a local `--NN` form only until the issues are filed. ## Sync Immunity @@ -49,8 +56,8 @@ so its contents are **never** touched by upstream sync. Edit freely; the next The repo-root script `Consolidate-Tasks.ps1` imports historical spec artifacts into this directory: -- `docs/designs/*.md` -> moved (`git mv`) and renamed to `-plan.md` -- `docs/prd/*.md` -> moved (`git mv`) and renamed to `-prd.md` +- `docs/designs/*.md` -> moved (`git mv`) and renamed to `-plan.md` +- `docs/prd/*.md` -> moved (`git mv`) and renamed to `-prd.md` - Root `PRD.md`, `plan.md`, `IMPLEMENTATION_PLAN.md` -> moved - `~/.copilot/session-state/*/plan.md` -> copied (repo-scoped via the session-store DB), default ON - `~/.claude/...` session notes -> copied, opt-in (`-IncludeClaudeSessions`)