ADR-006: SDLC Document Structure¶
Audience: host — see ADR index.
Date: 2026-06-23 Status: Accepted Related features: All features
Context¶
The repository has two audiences for documentation:
-
Agents and team members during development -- specs, plans, tasks, ADRs, research, test reports. These are process artifacts that drive the SDLC workflow (SPEC -> PLAN -> TASKS -> IMPLEMENTATION). They are reviewed, iterated on, and referenced by both humans and AI agents throughout the development lifecycle.
-
Users and operators after shipping -- developer guides, migration guides, API references, onboarding documentation. These are consumed by customers, partners, and community contributors who deploy and operate the product.
Previously, both types lived in specs/ and docs/ at the repo root, making it unclear which documents were process artifacts vs user-facing, and scattering SDLC content across multiple directories.
Decision¶
Two trees: process source vs public canonical ADRs¶
This file is the public copy of a host SDLC decision. Two locations exist; they are not interchangeable:
| Tree | Where | Role |
|---|---|---|
| Process source | .sdlc/adrs/ in the Portal team’s private SDLC repository |
Speckit drafts, review, and iteration. Not this GitHub repository. |
| Public canonical | docs/adrs/ in this repository, split by audience (common/, third-party/, host/) |
What third-party authors and this MkDocs site use. Canonical for published decisions. |
When they diverge, docs/adrs/ in this repository wins for readers of this project. Process drafts stay in the private .sdlc/ tree until they are copied here.
.sdlc/ for process artifacts¶
All documents generated or consumed during the development lifecycle in the process repository live under .sdlc/:
.sdlc/
├── specs/ Feature specifications (spec.md, plan.md, design.md, tasks.md)
├── adrs/ Architecture Decision Records (numbered, append-only)
├── research/ Research and investigation reports (numbered)
└── speckit-workflow-guide.md
This includes any document that:
- Is generated by an agent (specs, plans, task breakdowns, ADRs, research)
- Requires team review before or during implementation
- Drives the SDLC workflow (speckit commands operate on
.sdlc/) - May become stale after the feature ships (plans, task lists)
docs/ for user-facing documentation¶
All documentation intended for end users, operators, and external contributors lives under docs/. In this repository that includes the public ADR tree:
docs/
├── adrs/ Public canonical ADRs (common / third-party / host)
└── guides/ Developer guides, migration guides, operational docs
This includes any document that:
- Is read by someone deploying or operating the product
- Should stay current after the feature ships
- May be referenced from upstream public repos or product documentation
- Agents should reference when implementing features that affect documented behavior
Agent behavior¶
- When creating SDLC artifacts (specs, plans, ADRs, research) in the process repository, write to
.sdlc/ - When a decision is ready to publish, copy the ADR into
docs/adrs/{common,third-party,host}/in this repository - When implementing features, check
docs/for user-facing documentation that may need updating - When a feature ships, consider whether any
.sdlc/content should produce a correspondingdocs/guides/entry (migration guide, developer guide) - The
/speckit.*commands operate exclusively on.sdlc/specs/and.sdlc/adrs/in the process repository
Alternatives Considered¶
Keep specs/ and docs/ at root (status quo)¶
Flat structure, no nesting. Process and user docs mixed in docs/. Agents must infer which docs are process artifacts vs user-facing.
Rejected: Breaks discoverability. New contributors don't know where to put things. Agents scan unrelated files.
Use docs/sdlc/ subdirectory¶
Nest SDLC under docs/. Keeps everything under one root.
Rejected: docs/ implies user-facing content. Nesting process artifacts under it sends the wrong signal about audience.
Phase-based structure (1-spec/, 2-design/, 3-code/)¶
Number directories by SDLC phase.
Rejected: Too rigid. Features don't move linearly through phases. ADRs and research span multiple features.
Consequences¶
Positive¶
- Single location (
.sdlc/) for all process artifacts -- agents scan one root - Clear separation of audience:
.sdlc/= team,docs/= users - Speckit commands have a predictable, consistent root directory
- Dot-prefix signals "tooling/process" (consistent with
.claude/,.specify/,.github/)
Negative¶
- Dot-prefix hides the directory in
lsoutput (visible withls -aand on GitHub) - Existing links from external systems (Jira tickets, Slack messages) to process-repo
specs/or private.sdlc/drafts may not match this public tree.docs/adrs/here is the canonical published location, not an obsolete path. - Contributors familiar with the old layout need to learn the new convention