OpenSpec Framework | Specwright
Description: AI-native enterprise documentation platform. Living specs, agent-maintained docs, repo-native knowledge.

Skip to content

# OpenSpec Framework ​

Specwright adopts an OpenSpec-inspired structured artifact model. Specs are not freeform wiki pages — they're structured programs that the platform can parse, track, and verify.

## Artifact Types ​

Each feature or change can be expressed through complementary artifacts:

Artifact | Purpose | File Pattern
--- | --- | ---
Proposal | Why this change is needed, scope, impact | `docs/specs/<name>.md` (frontmatter + problem section)
Spec Sections | What the system must do (requirements + acceptance criteria) | Numbered sections within spec files
Design | How to implement it (architecture, trade-offs, migration) | `docs/decisions/*.md`, `docs/architecture.md`
Tasks | Implementation checklist with live ticket links | Acceptance criteria (`- [ ]`) + synced Jira/Linear/GitHub tickets

## Spec File Structure ​

A spec file is a markdown document with YAML frontmatter and numbered sections:

markdown

    ---
    title: "Feature Name"
    status: draft
    owner: your-name
    team: team-name
    ticket_project: PROJ
    created: 2026-02-01
    updated: 2026-02-26
    tags: [feature, mvp]
    ---

    # Feature Name

    Brief overview of this feature.

    ## 1. Background

    Why this feature exists and what problem it solves.

    ## 2. Requirements

    <!-- specwright:system:2 status:todo -->
    <!-- specwright:ticket:jira:PROJ-100 -->

    ### Acceptance Criteria

    - [ ] Criterion one
    - [ ] Criterion two
    - [x] Criterion three

## Frontmatter ​

The YAML frontmatter is the spec's metadata. Specwright uses these fields for tracking, routing, and display:

Field | Required | Description
--- | --- | ---
`title` | Yes | Human-readable feature name
`status` | Yes | Overall spec status (`draft`, `todo`, `in_progress`, `done`, `blocked`, `deprecated`)
`owner` | No | Person responsible for the spec
`team` | No | Team that owns this feature
`ticket_project` | No | Jira project key, Linear team, or GitHub repo for ticket creation
`created` | No | Date the spec was first written
`updated` | No | Date of last modification
`tags` | No | List of tags for filtering and routing

## Section Numbering ​

Sections use numbered headings (h2 for top-level, h3+ for subsections). This gives each section a stable identifier for ticket linking and status tracking:

markdown

    ## 2. Stripe Migration          ← Section 2
    ### 2.1 API Integration         ← Section 2.1
    ### 2.2 Webhook Handler         ← Section 2.2
    ## 3. Idempotency Layer         ← Section 3

## Acceptance Criteria ​

Each section can have acceptance criteria expressed as markdown checklists:

markdown

    ### Acceptance Criteria

    - [ ] Email sent on new comment mentioning the user
    - [x] Webhook signature verification on all incoming events
    - [ ] Rate limit: max 10 emails per user per hour

Checked items (`[x]`) represent completed/verified criteria. The agent evaluates these against code in PRs to determine realization status.

## All-Markdown Knowledge Base ​

Specwright indexes every markdown file in the repository, not just specs. All docs become part of the platform's knowledge and feed into agent analysis.

Doc Type | Examples | How the Agent Uses It
--- | --- | ---
Specs | `docs/specs/*.md` | Primary intent — tracks sections, AC, tickets, realization
ADRs | `docs/decisions/*.md` | Context for "why was it built this way?" queries
Architecture docs | `docs/architecture.md` | System context for cross-cutting PR analysis
READMEs | `README.md`, `docs/*.md` | Onboarding context, API docs, usage guides
Changelogs | `CHANGELOG.md` | Release history for staleness detection
Runbooks | `docs/runbooks/*.md` | Operational context the agent can surface
Contributing guides | `CONTRIBUTING.md` | Process docs the agent keeps current

Configure which files are indexed via `specs.doc_paths` in SPECWRIGHT.yaml.

## Related ​

- Guide: Writing Specs — practical guide to authoring effective specs
- Reference: Spec Format — formal syntax for frontmatter, sections, ACs, and comments
- Reference: SPECWRIGHT.yaml — full configuration schema
- Concept: Living Specs — how specs stay in sync with code through agents
- Concept: Delta Tracking — how status comments and ticket links work