Skip to content

Adopt standard docs/ spec structure (docs/specs + docs/designs), retire tasks/ convention#183

Merged
MarkMichaelis merged 1 commit into
mainfrom
feat/182-docs-spec-convention
Jun 5, 2026
Merged

Adopt standard docs/ spec structure (docs/specs + docs/designs), retire tasks/ convention#183
MarkMichaelis merged 1 commit into
mainfrom
feat/182-docs-spec-convention

Conversation

@MarkMichaelis

Copy link
Copy Markdown
Contributor

Summary

Replaces the bespoke tasks/ "durable spec archive" convention with the
industry-standard docs/ structure across the whole framework. The goal is a
durable requirements corpus you could hand to a fresh AI to rebuild the app
from scratch -- docs/specs/ (the what) + docs/designs/ (the how) reads
as the standard convention, whereas tasks/ reads as transient work items.

Mapping

Old New
tasks/<issue#>-<slug>-prd.md docs/specs/<issue#>-<slug>-prd.md
tasks/<issue#>-<slug>-plan.md docs/designs/<issue#>-<slug>-plan.md
tasks/README.md docs/README.md (consumer-owned, same-name scaffold)
tasks/MIGRATION.md docs/MIGRATION.md

Changes

  • Pull-SDLC.ai.ps1 -- TemplateScaffoldMap, UpstreamManagedPaths and
    AlwaysLocalPaths now carry docs/README.md, docs/specs/, docs/designs/.
    Carve-out comments updated.
  • Consolidate-Tasks.ps1 -- inverted: consolidates legacy locations
    (tasks/*, docs/prd/*, root PRD.md/plan.md/IMPLEMENTATION_PLAN.md,
    copilot/claude sessions) into docs/specs/ and docs/designs/; manifest
    at docs/MIGRATION.md. Filename intentionally kept to avoid churning the
    meta-script lists.
  • Agents (@prd, @plan, @dev-loop), README.md, .gitignore
    updated to the new paths.
  • git mv tasks/README.md docs/README.md + content rewrite; removed
    tasks/.gitkeep and the empty tasks/ dir.

Testing

  • Invoke-Pester Consolidate-Tasks.Tests.ps1 -- 33 passed, 0 failed
  • Invoke-Pester Pull-SDLC.ai.Tests.ps1 -- 190 passed, 0 failed
  • Behavior-first: tests updated to encode the new behavior before the scripts.
  • CRLF/LF endings preserved per-file to keep diffs minimal.

Closes #182

…tion Replace the bespoke tasks/ durable-spec-archive convention with the industry-standard docs/ structure: - docs/specs/ -- PRDs / requirements (the *what*), written by @prd - docs/designs/ -- implementation plans (the *how*), written by @dev-loop/@plan - docs/README.md -- consumer-owned archive guide (same-name scaffold)  Pull-SDLC.ai.ps1: TemplateScaffoldMap, UpstreamManagedPaths and AlwaysLocalPaths now carry docs/README.md, docs/specs/ and docs/designs/ instead of tasks/. Consolidate-Tasks.ps1 inverts direction -- it now consolidates legacy locations (tasks/*, docs/prd/*, root docs, sessions) INTO docs/specs/ and docs/designs/, writing docs/MIGRATION.md. The script filename is intentionally unchanged to avoid churning the meta-script lists.  Agents (@prd, @plan, @Dev-Loop), README.md and .gitignore updated to the new paths. tasks/README.md moved to docs/README.md and rewritten.  Closes #182
@MarkMichaelis MarkMichaelis force-pushed the feat/182-docs-spec-convention branch from 7360aba to eeb9f48 Compare June 5, 2026 17:23
@MarkMichaelis MarkMichaelis merged commit 69aa259 into main Jun 5, 2026
2 checks passed
@MarkMichaelis MarkMichaelis deleted the feat/182-docs-spec-convention branch June 5, 2026 17:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt standard docs/ spec structure (docs/specs + docs/designs), retire tasks/ convention

1 participant