docs(agents): standardize task filenames on issue-number prefix#177
Merged
Conversation
Unify the tasks/ naming convention across the agents and README on
tasks/<issue#>-<slug>-{prd,plan}.md. Previously plan.agent.md included
the issue number in <feature> while prd.agent.md and the README treated
the slug as the bare description, so files landed with neither a stable
identifier nor chronological order.
Define explicit <issue#> and <slug> placeholders, derive both from the
branch name (feat/<issue#>-<slug>), and document exact/glob/bare-slug
lookup fallbacks for legacy and pre-issue files.
Closes #176
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Standardize the
tasks/filename convention on a single, explicit form across the agents and the README:tasks/<issue#>-<slug>-prd.md tasks/<issue#>-<slug>-plan.mdPreviously the convention was documented three different ways:
plan.agent.mdfolded the issue number into<feature>, whileprd.agent.mdandtasks/README.mdtreated the slug as the bare description. In practice files landed with neither a stable identifier nor chronological order -- which is what surfaced during theConsolidate-Tasks.ps1date-stripping discussion (#174).Changes
prd.agent.md-- save path and existing-PRD lookup now usetasks/<issue#>-<slug>-prd.mdwith explicit derive-from-branch + glob/bare-slug fallbacks.plan.agent.md-- scan/save steps and the authoritative "Path and Slug Convention" section define<issue#>and<slug>as distinct placeholders and document lookup fallbacks.dev-loop.agent.md-- Phase 2 references updated to the new path.tasks/README.md-- Filename Convention table, cross-referencing header, and migration notes updated; bare-slug fallback for legacy/pre-issue files documented.Convention
<issue#>-- GitHub issue number; same leading token as branchfeat/<issue#>-<slug>, sotasks/sorts by issue number.<slug>-- short kebab-case description.<issue#>-<slug>-> glob*-<slug>-> bare<slug>(legacy / pre-issue spikes).Docs-only; no code changes. Edits kept generic per the upstream-instructions rule.
How to test
These are agent instruction files -- there is no automated test. Verify by inspecting the synced files and exercising an agent.
Option A -- inspect this branch directly:
`powershell
git fetch origin docs/176-task-filename-convention
git checkout docs/176-task-filename-convention
gh pr checks 177
read .github/agents/{prd,plan,dev-loop}.agent.md and tasks/README.md
`
Option B -- test as a consuming project (sync from this branch instead of main):
`powershell
./Pull-SDLC.ai.ps1 -Branch docs/176-task-filename-convention -WhatIf # preview
./Pull-SDLC.ai.ps1 -Branch docs/176-task-filename-convention # apply
git switch -c feat/999-demo-feature
invoke @prd or @plan, then confirm the filename:
Get-ChildItem tasks/ # expect 999-demo-feature-prd.md / -plan.md
`
Caveat:
.github/agents/*.mdare upstream-managed and sync to consumers;tasks/README.mdis in\and is scaffolded once, so existing consumers will not receive the README change via sync (only a fresh bootstrap or Option A shows it). The agents are the enforcing mechanism, so the behavior still propagates.Closes #176