STD-001: Project Structure Standard

The standard structure for project documentation in domus-captures. Extracted from 60 projects, refined through the ThinkPad P16g deployment restructure (Apr 2026). Every new project MUST follow this standard.

Principles

  1. Partials hold content, pages are shells. All project content lives in partials/projects/<slug>/. Container pages in pages/projects/ are 6-line shells that include:: one partial each.

  2. One concern per file. A partial that serves two audiences or two access patterns should be split. The 699-line monolithic field-notes anti-pattern is dead.

  3. metadata + summary are non-negotiable. Every project has a metadata table and a status summary. No exceptions.

  4. Appendices replace field-notes. Split by concern: issues, deviations, commands, TODOs. Each is independently navigable.

  5. Nav reflects information architecture. Phases are flat, appendices are nested.

Directory Layout

Partials (content)

partials/projects/<project-slug>/
├── metadata.adoc                  # REQUIRED — project metadata table
├── summary.adoc                   # REQUIRED — status table, deployment/feature status
├── assessment.adoc                # OPTIONAL — pre-work assessment, risk analysis
│
│   # --- Content partials (choose archetype) ---
│
│   # Phased archetype (deployments, migrations, rollouts)
├── phase-NN-<slug>.adoc           # Numbered sequential phases
│
│   # Feature archetype (software, configs, tools)
├── <feature-name>.adoc            # Domain-specific partials
│
│   # --- Appendices (reference material) ---
├── appendix-scope-creep.adoc      # Backlog items discovered during work
├── appendix-hardware.adoc         # Hardware specs, baseline snapshots
├── appendix-commands-learned.adoc # Commands discovered during the project
├── appendix-deviations.adoc       # Plan vs reality divergences
├── appendix-issues.adoc           # Problems encountered with resolutions
├── appendix-stow-audit.adoc       # Deployment audit (stow, configs, etc.)
└── appendix-todos.adoc            # Post-completion TODOs + improvement proposals

Container Pages (shells)

pages/projects/<category>/<project-slug>/
├── index.adoc                     # REQUIRED — includes summary, metadata, assessment
├── phase-NN.adoc                  # One per phase (phased archetype)
├── <feature-name>.adoc            # One per feature (feature archetype)
└── appendix-<topic>.adoc          # One per appendix

Required Files

Every project, regardless of archetype, MUST have:

File Purpose Where Included

metadata.adoc

Project ID, author, dates, status, category, priority

index.adoc

summary.adoc

Status table with per-phase or per-feature progress tracking

index.adoc

Project Archetypes

Phased (Deployments, Migrations)

For work that progresses through sequential stages. Each phase is a numbered partial.

Naming: phase-NN-<slug>.adoc where NN is zero-padded (00-99).

Examples: workstation deployments, infrastructure migrations, security rollouts.

Pattern When to Use

phase-00 through phase-NN

Sequential work where order matters

Split phases (e.g., phase-08-secrets, phase-08-eaptls)

Two distinct concerns within the same logical phase

New phases (12, 13, …​)

Scope grew during execution — extend, don’t renumber completed phases

Never renumber completed phases. If scope grows, add phases at the end. Phase history is an audit trail.

Phase content MUST live in separate phase-NN-<slug>.adoc partials — not as checkboxes inside appendix-todos.adoc. The TODOs appendix is for backlog items not tied to a specific phase. Each phase partial contains its own objective, steps, checklist, and verification criteria. This ensures phases are independently navigable and the nav reflects the actual work structure.

Anti-pattern: Putting all phase steps as * [ ] items in appendix-todos.adoc. This creates a flat list that hides structure, prevents direct navigation to a specific phase, and violates the "one concern per file" principle.

Reference implementations:

  • association-engine — 10 phases, Python learning curriculum

  • thinkpad-t16g-deploy — 14 phases, workstation deployment

  • rhel9-workstation — 13 phases, server deployment

  • eve-ng-lab — 8 phases, network simulation

Feature-Based (Software, Configs)

For work organized by domain or subsystem rather than temporal sequence.

Naming: <feature-name>.adoc — descriptive, kebab-case.

Examples: tmux-quantum (architecture, keybindings, themes, deployment), domus-antora-ui (css-architecture, theme-system, navigation-system).

Partial tmux-quantum Example

architecture.adoc

System design, module boundaries

keybindings.adoc

Domain-specific feature documentation

deployment.adoc

Installation, validation, rollback

decision-log.adoc

Why decisions were made (not how)

Appendices Standard

Appendices replace the monolithic field-notes.adoc pattern. Each appendix is a focused, independently navigable reference document.

Required Appendices

Not all appendices apply to every project. Use what fits:

Appendix Content When to Include

appendix-issues.adoc

Problems encountered + resolutions (table format)

Always — every project hits issues

appendix-todos.adoc

Post-completion TODOs + improvement proposals

Always — nothing is ever truly done

appendix-scope-creep.adoc

Items discovered that weren’t planned

Phased projects with scope growth

appendix-deviations.adoc

Plan vs reality divergences

Phased projects — feeds future templates

appendix-commands-learned.adoc

Commands discovered during the project

Projects involving new tools or techniques

appendix-hardware.adoc

Hardware specs, baseline snapshots

Hardware deployments only

appendix-stow-audit.adoc

Deployment audit, package status

dotfiles/stow projects only

Anti-Pattern: Monolithic Field Notes

Before (anti-pattern) After (standard)

field-notes.adoc (699 lines, 8 sections)

7 focused appendices (~60-175 lines each)

Scroll past hardware to find issues

Direct nav link to Issues page

One file, one audience

Each appendix serves its own audience

Grows unbounded

Each concern has natural boundaries

Container Page Template

Every container page follows this exact pattern:

= Page Title
:description: One-line description for SEO
:navtitle: Short Nav Title
:icons: font

include::partial$projects/<project-slug>/<partial-name>.adoc[]

Rules:

  • No :toc: attributes — Antora UI provides the sidebar TOC

  • No content in the container page itself — all content in the partial

  • One include per container page (with rare exceptions for index.adoc)

index.adoc Template

The overview page is the only container page that includes multiple partials:

= Project Title
:description: Brief project description
:navtitle: Overview
:revdate: YYYY-MM-DD
:icons: font

include::partial$projects/<slug>/summary.adoc[]

include::partial$projects/<slug>/assessment.adoc[]

include::partial$projects/<slug>/metadata.adoc[]

== Related

* xref:case-studies/changes/CR-YYYY-MM-DD-slug.adoc[CR: Title]
* xref:other-project/index.adoc[Related Project]

Nav Structure

Phased Project

*** Project Name (Priority)
**** xref:...index.adoc[Overview]
**** xref:...phase-0.adoc[Phase 0: Title]
**** xref:...phase-1.adoc[Phase 1: Title]
**** ...
**** xref:...phase-N.adoc[Phase N: Title]
**** Appendices
***** xref:...appendix-scope-creep.adoc[Scope Creep & Backlog]
***** xref:...appendix-issues.adoc[Issues Encountered]
***** xref:...appendix-todos.adoc[Post-Deploy TODOs]

Feature-Based Project

*** Project Name (Priority)
**** xref:...index.adoc[Overview]
**** xref:...architecture.adoc[Architecture]
**** xref:...feature-a.adoc[Feature A]
**** xref:...feature-b.adoc[Feature B]
**** xref:...deployment.adoc[Deployment]
**** xref:...field-notes.adoc[Field Notes]
Feature-based projects with fewer than 5 appendix-worthy sections may keep a single field-notes.adoc. Split when any section exceeds ~150 lines or the total exceeds ~400 lines.

Summary Table Standard

The summary.adoc status table tracks progress at the phase or feature level:

Phased

[cols="1,3,1,2"]
|===
| Phase | Description | Status | Notes

| 0: Pre-Work
| Backups, prerequisites
| ✅ Done
| —

| 1: Foundation
| Core setup
| ⚠️ Partial
| Blocked on X

| 2: Configuration
| Feature config
| ❌ Not started
| —

| **SEC-NNN**
| **Security finding title**
| **🟡 In progress**
| Now tracked as Phase N. xref:...[CR link].
|===

Feature-Based

[cols="1,3,1"]
|===
| Feature | Description | Status

| Architecture
| Module boundaries, file layout
| ✅ Done

| Keybindings
| 121 bindings across 4 tables
| ✅ Done

| Themes
| Variable-based theming system
| ⚠️ Partial
|===

Case Study Integration

Projects generate case studies. Cross-reference them from index.adoc and summary.adoc:

Type Prefix When to Create

Change Request

CR-YYYY-MM-DD-<slug>

Planned changes with implementation phases

Incident Report

INC-YYYY-MM-DD-<slug>

Unplanned issues requiring investigation

Root Cause Analysis

RCA-YYYY-MM-DD-NNN

Post-incident analysis with prevention steps

Cross-reference pattern:

xref:case-studies/changes/CR-YYYY-MM-DD-slug.adoc[CR: Title]
xref:case-studies/incidents/INC-YYYY-MM-DD-slug.adoc[INC: Title]

Metadata Table Standard

[cols="1,3"]
|===
| Field | Value

| PRJ ID | PRJ-YYYY-MM-<slug>
| Author | {author}
| Created | YYYY-MM-DD
| Updated | YYYY-MM-DD
| Status | Draft / Active / Operational / Complete / Archived
| Category | Workstation Deployment / Software / Infrastructure / Migration
| Priority | P0 / P1 / P2
|===

Migration Path: field-notes to Appendices

For existing projects still using monolithic field-notes.adoc:

  1. Identify distinct sections (scope creep, issues, commands, TODOs, etc.)

  2. Create appendix-<topic>.adoc partials for sections exceeding ~100 lines

  3. Create matching container pages

  4. Update nav: replace Field Notes entry with Appendices group

  5. Delete the monolithic field-notes.adoc partial and container page

  6. Verify build: make 2>&1 | grep -E "WARN|ERROR"

Trigger for migration: Any field-notes file exceeding 400 lines or containing 4+ distinct sections.

Related