Skip to content

01-repo-structure.md

Latest commit

 

History

History
78 lines (59 loc) · 3.57 KB

01-repo-structure.md

File metadata and controls

78 lines (59 loc) · 3.57 KB
Raw

Repo Structure

This file defines a recommended repository layout for agent-friendly software delivery.

The exact repo may differ, but the categories should stay clear: durable source, durable docs, generated output, and ephemeral working state must not be mixed casually.

Recommended Layout

/
├── .github/                     # CI workflows, issue templates, PR templates, CODEOWNERS
├── docs/                        # Durable human-readable docs that change repo behavior
│   ├── adr/                     # Architecture decisions
│   ├── handoffs/                # Active and completed worker assignments
│   └── artifacts/               # Durable closeout notes, retros, audits
├── flow/                        # Cross-repo operating manual
├── src/                         # Application or library source
├── tests/                       # Unit, integration, e2e, fixtures
├── scripts/                     # Operational automation and developer tooling
├── config/                      # Environment or tool configuration
├── .worktrees/                  # Optional local-only concurrent branch checkouts
├── dist/ or build/              # Generated artifacts, usually ignored
├── tmp/ or scratch/             # Local scratch outputs, ignored
├── README.md                    # Repo entry point
└── CHANGELOG.md                 # Release history when applicable

Durable vs Ephemeral

Category Examples Rule
Durable source src/, tests/, scripts/, docs/ Reviewed, versioned, part of the product or operating model
Durable records ADRs, handoffs, artifacts, changelog Keep if they explain future behavior or audit history
Generated output dist/, rendered docs, build outputs Regenerate when possible; do not hand-edit unless explicitly intended
Ephemeral state .worktrees/, temp files, caches, run logs Keep out of PRs unless the state itself is the deliverable

Placement Rules

  1. Operational rules belong in flow/ or durable repo docs, not only in chat.
  2. Task-specific scope contracts belong under docs/handoffs/ if the repo uses delegated workers.
  3. Reflection artifacts, retros, and closeout notes belong under docs/artifacts/ if they create durable learning.
  4. Generated files should live in clearly named generated directories.
  5. Scratch outputs and validation spillover should live in ignored paths.
  6. Do not create loose top-level files unless they are standard entry-point files or the repo has an explicit convention for them.

Decision Tree

Is it product or application code?
├── Yes -> `src/`

Is it a test or fixture?
├── Yes -> `tests/`

Is it a durable workflow, architecture, or operator rule?
├── Yes -> `docs/` or `flow/`

Is it a task-specific scope contract or closeout artifact?
├── Yes -> `docs/handoffs/` or `docs/artifacts/`

Is it automation or a repo utility?
├── Yes -> `scripts/`

Is it generated output?
├── Yes -> generated directory such as `dist/`, `build/`, or repo-specific rendered paths

Is it transient validation output or scratch state?
└── Yes -> ignored temp path such as `tmp/`, `scratch/`, or `.worktrees/`

Naming Expectations

  • Use predictable directory names.
  • Prefer kebab-case for docs and scripts unless the language ecosystem strongly prefers something else.
  • Mirror source structure in tests where practical.
  • Keep durable process docs discoverable by name alone.

See Naming Conventions for exact naming rules.