Naming conventions, file naming rules, and canonical file templates for AASDD specs.

Naming

Thing	Convention	Example
Ability names	PascalCase verb phrase	ParsePrompt, SnapshotWorkspace
Ability folders	kebab-case	parse-prompt/, snapshot-workspace/
Type names	PascalCase noun	WorkspaceSnapshot, ChangeSet
Concept folders	kebab-case domain	workspace/, planning/
Scenario folders	kebab-case description	happy-path/, max-retries-exhausted/
Decision names	PascalCase noun phrase	DocumentTransport, InteractionChannel
Decision folders	kebab-case description	document-transport/, interaction-channel/
State names	PascalCase adjective or participle	Idle, Analyzing, Failed, Complete

Type names are canonical across spec and implementation — adapt only the casing to the language convention (WorkspaceSnapshot → workspace_snapshot in snake_case).

File Naming

Location	Artifact
Specification overview	spec.md
Ability spec (at any depth)	ability.md
Concept domain	concept.md
Scenario	scenario.md
State machine	state-machine.md
Decision	decision.md

Spec artifacts use a fixed <type>.md filename — the directory name carries identity, the filename carries the type. All spec artifact files start at H2.

Formatting Rules

• One blank line between every section (heading, paragraph, table, list, blockquote, code block)
• No trailing blank lines at end of file
• No consecutive blank lines
• Tables use | --- | separator rows (no : alignment markers)
• All identifiers in table cells (input names, output names, property names, state names, failure names) are wrapped in backticks
• The Ability column in state tables uses backticks for ability names; — (em dash) marks states with no mapped ability

File Templates

spec.md

## {SpecName}

**AASDD:** v{N}
**Version:** {X}.{Y}.{Z}

{One sentence describing what this spec covers.}

### Invariants

- {Cross-cutting invariant that applies to the spec as a whole}

Optional sections (in order when present):

### Failure Modes

| Failure         | Condition                    | Effect         |
| --------------- | ---------------------------- | -------------- |
| `{FailureName}` | {When this condition occurs} | {What happens} |

ability.md

Required sections in this order. Optional sections omitted entirely when not applicable.

## {AbilityName}

{One sentence stating what this ability does.}

### Inputs

| Name           | Type                                                 | Description   |
| -------------- | ---------------------------------------------------- | ------------- |
| `{input_name}` | [{TypeName}]({relative/path/to/concept.md#typename}) | {Description} |

### Outputs

| Name            | Type                                                 | Description   |
| --------------- | ---------------------------------------------------- | ------------- |
| `{output_name}` | [{TypeName}]({relative/path/to/concept.md#typename}) | {Description} |

### Invariants

- {Invariant statement}

### Failure Modes

| Failure         | Condition                    | Effect         |
| --------------- | ---------------------------- | -------------- |
| `{FailureName}` | {When this condition occurs} | {What happens} |

Optional sections (in order when present):

### Idempotency

{Brief statement of idempotency behavior.}

After all required and recognized optional sections, any number of custom ### sections may follow. Custom sections have no fixed template — their names and content are author-defined. This applies to all spec file types (spec.md, ability.md, concept.md, scenario.md, state-machine.md, decision.md).

Type references

• Scalar types (text, number, boolean, timestamp) — plain text, not linked
• Same-spec types — [TypeName](relative/path/to/concept.md#typename)
• Structural modifiers — prefix: list of TypeName, optional TypeName, map of KeyType to ValueType; apply to any type including cross-spec types
• Types from another spec — plain text with a description noting external definition; no linking

concept.md

## {DomainName} domain

{One-sentence description of what types this domain contains.}

### {TypeName}

{One-sentence or short-paragraph description of what this type represents.}

#### Properties

| Name              | Type                      | Description   |
| ----------------- | ------------------------- | ------------- |
| `{property_name}` | [{TypeName}](#{typename}) | {Description} |
| `{property_name}` | text                      | {Description} |

Enum types (see METHODOLOGY.md) omit #### Properties and use a Value/Meaning table instead:

### {EnumTypeName}

{One-sentence description.}

| Value         | Meaning                 |
| ------------- | ----------------------- |
| `{ValueName}` | {What this value means} |

Type column conventions: scalar types are plain text, same-file references use [TypeName](#typename), same-spec references use [TypeName](../domain/concept.md#typename).

scenario.md

## {ScenarioName}

{One sentence describing what makes this scenario distinct.}

> `{State1}` → `{State2}` → `{State3}`

- {Notable behavior or outcome}

Divergences use — (em dash):

> `{State1}` → `{State2}` — {ConditionName} → `{State3}`

Optional ### Example section (in order when present):

### Example

{Concrete real-world instance of this scenario, written as prose.}

state-machine.md

A state-machine.md appears at the spec root, alongside spec.md, coordinating the top-level lifecycle. A spec may define at most one state machine.

Sections appear in this exact order. Optional sections omitted entirely when not applicable.

## State Machine

{One sentence describing what this machine orchestrates.}

```mermaid
stateDiagram-v2
    [*] --> {State1}
    {State1} --> {State2}: {trigger}
    {State2} --> [*]
```

### Orchestrator

{One-paragraph description of who owns transition logic and what the orchestrator does.}

#### Orchestrator-Managed State

| Name              | Type                                                   | Description   |
| ----------------- | ------------------------------------------------------ | ------------- |
| `{variable_name}` | [{TypeName}]({relative/path/to/concept.md#{typename}}) | {Description} |

### States

| State         | Ability         | Description                         |
| ------------- | --------------- | ----------------------------------- |
| `{StateName}` | `{AbilityName}` | {Description}                       |
| `{StateName}` | —               | {Description of control flow state} |

### Transitions

| From          | To          | Trigger             | Data Passed Forward |
| ------------- | ----------- | ------------------- | ------------------- |
| `{FromState}` | `{ToState}` | {Trigger condition} | {Data description}  |

### Transition Rules

- {Cross-cutting constraint}

### Exceptional Flows

#### {FlowName}

{Prose describing recovery behavior or non-standard lifecycle events.}

The diagram is required. Use any diagram syntax that renders in your environment; the template uses Mermaid as a common default. #### Orchestrator-Managed State is present only when the orchestrator maintains state across the lifecycle. ### Exceptional Flows is optional.

decisions/{decision}/decision.md

A technology decision for one open choice the spec leaves to the implementer. Each decision file covers exactly one choice: the transport for an input that crosses a system boundary, the storage mechanism for persistent state, the model or service powering a capability. The three sections — Context (why a decision is needed), Requirement (what the implementation must provide), and Decision (the chosen approach) — are all required.

## {DecisionName}

### Context

{What spec concept this relates to and why a technology decision is needed.}

### Requirement

{What capability the implementation must provide to satisfy the spec.}

### Decision

{The chosen approach and brief reasoning.}