Skip to content

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:

  1. 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.

  2. 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 corresponding docs/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 ls output (visible with ls -a and 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