Back to Openspec

Concepts

docs-lab/guides/concepts.md

1.11.01.3 KB
Original Source

Concepts

What the two artifacts are, and how a change describes a diff against current specs.

<!-- Skeleton: headings only. Narrowed in review round 3 (dedup pass). The quickstart's archive file-steps absorbed the loop mechanics this page once planned to own, so the loop section is gone: the quickstart is the loop's only teacher, and core-vs-optional moved to customize/profiles.md. The fixed-vs-shapeable section was cut entirely (customize/overview.md dropped that framing in review, 2026-08-14: it opens straight on the options and never says what can't be changed). What remains is the one explanation this page owns: the artifacts. Specs absorbs "What a spec is"; Changes owns the delta concept: one worked delta block (ADDED/MODIFIED/REMOVED, from docs/concepts.md's core) showing a change as a diff against current specs; the file-format rules live in reference/schemas/spec-driven/index.md (Delta specs section). Disk paths appear inline with the concept that owns them (specs/ under Specs, changes/ under Changes), never as a layout section. Close with link lines: quickstart for the loop, customize/overview for the customization options. When to archive relative to a branch or PR stays in guides/teams.md. -->

Specs: the system as built

Changes: a folder of deltas