import{_ as s,o as e,c as i,a2 as a}from"./chunks/framework.CJEbdX1t.js";const k=JSON.parse('{"title":"OpenSpec Framework","description":"","frontmatter":{},"headers":[],"relativePath":"concepts/openspec.md","filePath":"concepts/openspec.md"}'),n={name:"concepts/openspec.md"};function r(d,t,o,l,h,c){return e(),i("div",null,[...t[0]||(t[0]=[a(`<h1 id="openspec-framework" tabindex="-1">OpenSpec Framework <a class="header-anchor" href="#openspec-framework" aria-label="Permalink to &quot;OpenSpec Framework&quot;">​</a></h1><p>Specwright adopts an <a href="https://github.com/Fission-AI/OpenSpec" target="_blank" rel="noreferrer">OpenSpec</a>-inspired structured artifact model. Specs are not freeform wiki pages — they&#39;re structured programs that the platform can parse, track, and verify.</p><h2 id="artifact-types" tabindex="-1">Artifact Types <a class="header-anchor" href="#artifact-types" aria-label="Permalink to &quot;Artifact Types&quot;">​</a></h2><p>Each feature or change can be expressed through complementary artifacts:</p><table tabindex="0"><thead><tr><th>Artifact</th><th>Purpose</th><th>File Pattern</th></tr></thead><tbody><tr><td><strong>Proposal</strong></td><td>Why this change is needed, scope, impact</td><td><code>docs/specs/&lt;name&gt;.md</code> (frontmatter + problem section)</td></tr><tr><td><strong>Spec Sections</strong></td><td>What the system must do (requirements + acceptance criteria)</td><td>Numbered sections within spec files</td></tr><tr><td><strong>Design</strong></td><td>How to implement it (architecture, trade-offs, migration)</td><td><code>docs/decisions/*.md</code>, <code>docs/architecture.md</code></td></tr><tr><td><strong>Tasks</strong></td><td>Implementation checklist with live ticket links</td><td>Acceptance criteria (<code>- [ ]</code>) + synced Jira/Linear/GitHub tickets</td></tr></tbody></table><h2 id="spec-file-structure" tabindex="-1">Spec File Structure <a class="header-anchor" href="#spec-file-structure" aria-label="Permalink to &quot;Spec File Structure&quot;">​</a></h2><p>A spec file is a markdown document with YAML frontmatter and numbered sections:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">title</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Feature Name&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">status</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">draft</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">owner</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">your-name</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">team</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">team-name</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">ticket_project</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">PROJ</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">created</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2026-02-01</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">updated</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2026-02-26</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">tags</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">feature</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">mvp</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># Feature Name</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Brief overview of this feature.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 1. Background</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Why this feature exists and what problem it solves.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 2. Requirements</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:system:2 status:todo --&gt;</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:jira:PROJ-100 --&gt;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### Acceptance Criteria</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Criterion one</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Criterion two</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline;">x</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] Criterion three</span></span></code></pre></div><h2 id="frontmatter" tabindex="-1">Frontmatter <a class="header-anchor" href="#frontmatter" aria-label="Permalink to &quot;Frontmatter&quot;">​</a></h2><p>The YAML frontmatter is the spec&#39;s metadata. Specwright uses these fields for tracking, routing, and display:</p><table tabindex="0"><thead><tr><th>Field</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>title</code></td><td>Yes</td><td>Human-readable feature name</td></tr><tr><td><code>status</code></td><td>Yes</td><td>Overall spec status (<code>draft</code>, <code>todo</code>, <code>in_progress</code>, <code>done</code>, <code>blocked</code>, <code>deprecated</code>)</td></tr><tr><td><code>owner</code></td><td>No</td><td>Person responsible for the spec</td></tr><tr><td><code>team</code></td><td>No</td><td>Team that owns this feature</td></tr><tr><td><code>ticket_project</code></td><td>No</td><td>Jira project key, Linear team, or GitHub repo for ticket creation</td></tr><tr><td><code>created</code></td><td>No</td><td>Date the spec was first written</td></tr><tr><td><code>updated</code></td><td>No</td><td>Date of last modification</td></tr><tr><td><code>tags</code></td><td>No</td><td>List of tags for filtering and routing</td></tr></tbody></table><h2 id="section-numbering" tabindex="-1">Section Numbering <a class="header-anchor" href="#section-numbering" aria-label="Permalink to &quot;Section Numbering&quot;">​</a></h2><p>Sections use numbered headings (h2 for top-level, h3+ for subsections). This gives each section a stable identifier for ticket linking and status tracking:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 2. Stripe Migration          ← Section 2</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### 2.1 API Integration         ← Section 2.1</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### 2.2 Webhook Handler         ← Section 2.2</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 3. Idempotency Layer         ← Section 3</span></span></code></pre></div><h2 id="acceptance-criteria" tabindex="-1">Acceptance Criteria <a class="header-anchor" href="#acceptance-criteria" aria-label="Permalink to &quot;Acceptance Criteria&quot;">​</a></h2><p>Each section can have acceptance criteria expressed as markdown checklists:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### Acceptance Criteria</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Email sent on new comment mentioning the user</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline;">x</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] Webhook signature verification on all incoming events</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Rate limit: max 10 emails per user per hour</span></span></code></pre></div><p>Checked items (<code>[x]</code>) represent completed/verified criteria. The agent evaluates these against code in PRs to determine <a href="/docs/concepts/coverage.html">realization status</a>.</p><h2 id="all-markdown-knowledge-base" tabindex="-1">All-Markdown Knowledge Base <a class="header-anchor" href="#all-markdown-knowledge-base" aria-label="Permalink to &quot;All-Markdown Knowledge Base&quot;">​</a></h2><p>Specwright indexes <strong>every markdown file</strong> in the repository, not just specs. All docs become part of the platform&#39;s knowledge and feed into agent analysis.</p><table tabindex="0"><thead><tr><th>Doc Type</th><th>Examples</th><th>How the Agent Uses It</th></tr></thead><tbody><tr><td><strong>Specs</strong></td><td><code>docs/specs/*.md</code></td><td>Primary intent — tracks sections, AC, tickets, realization</td></tr><tr><td><strong>ADRs</strong></td><td><code>docs/decisions/*.md</code></td><td>Context for &quot;why was it built this way?&quot; queries</td></tr><tr><td><strong>Architecture docs</strong></td><td><code>docs/architecture.md</code></td><td>System context for cross-cutting PR analysis</td></tr><tr><td><strong>READMEs</strong></td><td><code>README.md</code>, <code>docs/*.md</code></td><td>Onboarding context, API docs, usage guides</td></tr><tr><td><strong>Changelogs</strong></td><td><code>CHANGELOG.md</code></td><td>Release history for staleness detection</td></tr><tr><td><strong>Runbooks</strong></td><td><code>docs/runbooks/*.md</code></td><td>Operational context the agent can surface</td></tr><tr><td><strong>Contributing guides</strong></td><td><code>CONTRIBUTING.md</code></td><td>Process docs the agent keeps current</td></tr></tbody></table><p>Configure which files are indexed via <code>specs.doc_paths</code> in <a href="/docs/getting-started/configuration.html">SPECWRIGHT.yaml</a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><strong>Guide</strong>: <a href="/docs/guides/writing-specs.html">Writing Specs</a> — practical guide to authoring effective specs</li><li><strong>Reference</strong>: <a href="/docs/reference/spec-format.html">Spec Format</a> — formal syntax for frontmatter, sections, ACs, and comments</li><li><strong>Reference</strong>: <a href="/docs/reference/config.html">SPECWRIGHT.yaml</a> — full configuration schema</li><li><strong>Concept</strong>: <a href="/docs/concepts/living-specs.html">Living Specs</a> — how specs stay in sync with code through agents</li><li><strong>Concept</strong>: <a href="/docs/concepts/delta-tracking.html">Delta Tracking</a> — how status comments and ticket links work</li></ul>`,24)])])}const g=s(n,[["render",r]]);export{k as __pageData,g as default};
