mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-10-02 05:24:34 +08:00
Tabish Bidiwale
f1b521dffa
* docs: rebuild docs site from docs-lab
Replace the docs site's source tree with docs-lab, a page-by-page rebuild
of the OpenSpec docs (40 pages: Start / Guides / Customize / Multi-repo /
Reference / Help).
- Point website/docs.sync.config.mjs at ../docs-lab and restructure the
sidebar into nested groups; sync script gains nested meta.json emission,
leading-quote descriptions, idempotent writes, and diagram asset copying
- Remove the marketing landing page; / now redirects to /docs
(meta-refresh page + Cloudflare _redirects)
- Add remark plugins (faq, file-steps, gfm-alert) and the FileSteps
component backing the new page formats
- Add install.md at the repo root, curled by docs-lab/start/installation.md
as an agent-executable install prompt
- Add the docs authoring skills (.agents/skills/{write,draft,verify}-
openspec-docs); docs-lab/README.md links into write-openspec-docs
The old docs/ tree is now unused by the site and left for a follow-up.
Claude-Session: https://claude.ai/code/session_01BMMLYNJQPKXx1QHpnDn4ho
* docs: hold back unwritten pages, add worksets, drop diagram drafts
- website: comment out Overview, Guides, Architecture, Help, Legacy in
docs.sync.config.mjs until those pages are written; temporary
/docs -> /docs/installation redirect (Cloudflare _redirects + static
export meta-refresh fallback in page.tsx)
- docs-lab: new multi-repo/worksets.md page, published under Multi-repo
- docs-lab: content revisions across start/, customize/, reference/,
help/, multi-repo/; add review notes (Notes.md)
- remove docs-lab/diagrams option-* drafts and their website copies
- write-openspec-docs skill: add spoken-flow sentence rule
* docs: address review on PR #1649
- sync-docs: read the existing output directly instead of exists-then-read
(CodeQL TOCTOU alert)
- hold back the headings-only Environment variables and Stores reference
pages until written; links to them fall back to their GitHub source
- sources.md: cutover keeps docs/ in place and points at public/_redirects
- setup.md: label the workflow tree as the default set plus two optional ones
* docs: two review nits (spoken-flow rule, XDG_DATA_HOME note)
2.0 KiB
2.0 KiB
Overview
Your options for customizing OpenSpec.
OpenSpec supports multiple customization options. This page shows what each one changes and when to use it.
What you can customize
| Option | What it changes | Use it when |
|---|---|---|
| Profiles | Which workflows are installed, and whether as skills, commands, or both | You want additional workflows and working patterns, or to remove workflows you don't need |
| Project configuration | The instructions injected into every workflow run: context, rules, and operation guidance (config.yaml) |
You want changes planned your way, like tasks always including Playwright tests |
| Schemas | What OpenSpec produces: the artifacts, their order, and their templates | Changes should produce different planning files, sections, or formats |
Not sure which to use?
Config and schemas are two levels of customization. Pick by how hands-on you want to get:
- Start with project configuration: it's lighter, and for most projects it's enough. You keep the standard artifacts and add your own context and rules on top.
- Fork a schema when adding isn't enough: config only adds on top of the core workflow. It can add a rule like "tasks always include tests," but it can't drop the design doc or rename a file. That's schema territory. Forking gives you your own copy to edit.
"Fork" here means the openspec schema fork command, not forking a git repo. Schemas has the details.
flowchart LR
a["The workflows should know my stack and conventions"] --> config
b["One artifact needs an extra rule, like tasks always including tests"] --> config
c["Different artifacts, file names, or document structure"] --> schema
d["The built-in instructions say things my team does differently"] --> schema
config["Project configuration<br/>(config.yaml)"]
schema["Fork a schema<br/>(openspec schema fork)"]