Quick Start¶
Create a Project¶
This creates a ossature.toml config and a specs/ directory. The config looks like:
[project]
name = "myproject"
version = "0.0.1"
spec_dir = "specs"
[output]
dir = "output"
language = "python"
[llm]
model = "anthropic:claude-sonnet-4-6"
The default model is anthropic:claude-sonnet-4-6. If you're using a different provider, update the model field to match, for example openai:gpt-5.2 or ollama:devstral-latest. The API key you export must match the provider in your model string (e.g., OPENAI_API_KEY for openai:…). See Configuration for all options.
Write a Spec¶
Create a spec file:
This creates specs/my-feature.smd. Open it and describe what you want to build. Here's what a minimal spec looks like:
---
id: MY_FEATURE
status: draft
priority: high
depends: []
---
# My Feature
## Overview
A short description of what this module does.
## Goals
- The main thing this feature should achieve
## Non-Goals
- Something this feature deliberately leaves out
## Requirements
### Some Requirement
What the feature should do.
**Accepts:** the input it takes, with types
**Returns:** what it produces on success
## Constraints
- Any rule the implementation should follow
## Examples
### Basic Usage
**Input:**
```json
{ "field": "value" }
```
**Output:**
```json
{ "result": "success" }
```
## Acceptance Criteria
- The main use case works as described
Every section here is required, and ossature validate reports any that are missing or empty. Each requirement needs an Accepts: and a Returns: line, with an optional Errors: list. The file that ossature new my-feature generates already has all of these sections, so editing it is the quickest path.
You can also create architecture files (.amd) that describe the internal structure, components, data models, and interfaces. If you skip them, the LLM infers the architecture during audit. But if you know what shape your system should take, writing one upfront gives the LLM less room to improvise.
An AMD file links back to its spec via spec in its frontmatter and breaks the system down into concrete pieces. Here's a template:
---
spec: MY_FEATURE
status: draft
---
# Architecture: My Feature
## Overview
How the system is structured at a high level. Which modules exist,
what role each one plays, how they connect.
## Components
### Component Name
@path: src/myproject/component.py
What this component does and what it's responsible for.
**Interface:**
```python
def do_something(input: str) -> Result: ...
```
**Contracts:**
- do_something raises ValueError on empty input
- The returned Result is a new object, input data is never mutated
**Depends on:** None
## Data Models
### Some Model
```json
{
"id": 1,
"name": "example"
}
```
## Flow
```
Entry point
├── action_a -> component.do_something()
└── action_b -> other_component.handle()
```
## Dependencies
- some-library 2.x: what it's used for
The Components section is where most of the detail goes. Each component gets a @path (where it will live in your project), a description, an interface showing its public API, a list of behavioral contracts the implementation must uphold (or **Contracts:** None when the signature already covers the behavior), and a list of other components it depends on. You can define as many components as you need.
Validate¶
Check that your specs are well-formed:
This parses everything and checks for structural issues. No LLM calls.
Audit¶
Send your specs to the LLM for review. This catches ambiguity, gaps, and feasibility issues, then generates a build plan:
The plan gets written to .ossature/plan.toml. You should read it before building. You can reorder tasks, add notes, or skip things you don't want.
Build¶
When the plan looks right:
By default the build pauses on failures and lets you retry, skip, or quit. You can also run ossature build --auto to run without pausing, or ossature build --step to pause after every task for approval.
If Something Fails¶
Use ossature retry to re-run just the failed tasks:
Or redo everything from a specific task onwards:
Check the current state at any point:
Next Steps¶
- Workflow Guide - Full walkthrough from init to build with a real example
- SMD Format - Learn the spec format
- AMD Format - Define architecture explicitly
- Configuration - Customize your project
- Commands - All available commands