Skip to main content

File Layout

Standard conventions for organising APS documents in your project.

project/
├── plans/
│   ├── aps-rules.md              # AI agent guidance (APS-managed)
│   ├── project-context.md        # Project-specific context (you own this)
│   ├── index.aps.md              # Root index
│   ├── issues.md                 # Dev-time discoveries (ISS-NNN / Q-NNN)
│   ├── completed.aps.md          # Shipped work roll-up (optional)
│   ├── modules/
│   │   ├── auth.aps.md
│   │   └── payments.aps.md
│   ├── execution/
│   │   └── AUTH-001.actions.md   # Action plans for complex work items
│   ├── designs/
│   │   └── 2026-01-05-auth.design.md
│   ├── releases/
│   │   └── v0.4.0.md
│   └── decisions/
│       └── 001-use-jwt.md
└── .aps/
    ├── config.yml                # Project contract
    └── context/                  # Ephemeral context packages (gitignored)
        └── AUTH-001.md

Directory purposes​

plans/​

Root directory for all planning documents. Keeps plans separate from code.

plans/modules/​

One file per module. Each file contains:

  • Module metadata table
  • Purpose, scope, interfaces
  • Work items (when Ready)

plans/execution/​

Action plan breakdowns for complex work items. Used when:

  • A work item has many actions
  • Multiple agents or humans work concurrently (waves)
  • Granular progress tracking is needed

plans/designs/​

Technical design documents for non-obvious architecture. Named YYYY-MM-DD-slug.design.md.

plans/releases/​

Release narratives — theme, what ships, success criteria, risks. Named v<version>.md.

plans/decisions/​

Architecture Decision Records (ADRs). Not strictly APS, but useful context.

.aps/​

APS-owned tooling root. Contains config.yml (required) and ephemeral context/ packages generated by aps start.

File naming​

Index​

index.aps.md

Always named index.aps.md at the plans root.

Modules​

{module-name}.aps.md

Examples: auth.aps.md, payments.aps.md, 01-auth.aps.md (numbered by dependency order in larger projects). Use kebab-case for multi-word names.

Action plans​

{WORK-ITEM-ID}.actions.md

Examples: AUTH-001.actions.md, PAY-002.actions.md

Designs​

YYYY-MM-DD-slug.design.md

Example: 2026-01-05-auth-architecture.design.md

Releases​

v<version>.md

Example: v0.4.0.md

Minimal layout​

For small projects, a single file works:

project/
├── plans/
│   └── index.aps.md    # Contains everything
└── .aps/
    └── config.yml

Contents:

# My Project

## Work Items

### CORE-001: Initial setup

- **Intent:** Project builds successfully
- **Expected Outcome:** `npm run build` exits 0
- **Validation:** `npm run build`

Growing the structure​

Step 1: Extract modules​

<!-- Before: inline module -->

## Module: Auth

### AUTH-001: Login

<!-- After: reference -->

## Modules

| Module                        | ID   | Status |
| ----------------------------- | ---- | ------ |
| [auth](./modules/auth.aps.md) | AUTH | Draft  |

Step 2: Extract action plans​

When work items get complex:

### AUTH-001: Login endpoint

- **Intent:** Users can log in
- **Validation:** `npm test -- auth.test.ts`

Action plan: [AUTH-001.actions.md](../execution/AUTH-001.actions.md)

Version control​

Commit practices​

git commit -m "plan(auth): add AUTH-003 password reset work item"
git commit -m "plan(payments): mark PAY-001 complete"
git commit -m "plan: add notifications module"

Convention: plan({module}): {description}

Code review​

Plans are code. Review them:

  • Is the outcome clear?
  • Is the validation correct?
  • Are checkpoints observable?

Multi-team layouts​

For large organisations:

plans/
├── index.aps.md
├── teams/
│   ├── platform/
│   │   ├── index.aps.md
│   │   └── modules/
│   └── product/
│       ├── index.aps.md
│       └── modules/
└── shared/
    └── modules/
        └── common.aps.md

For monorepos, see Monorepo guide →.

Next: Validation rules →