mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-10-30 07:53:11 +08:00
65a7233f36
* docs(website): add Fumadocs documentation site for Cloudflare Pages Add a self-contained marketing + documentation site under website/, built with Fumadocs (Next.js) and configured as a static export so it deploys directly to Cloudflare Pages with no server runtime. What's included: - A marketing landing page (hero, the two-folder model, the four core ideas, the explore→propose→apply→archive loop, and the "why"). - 13 documentation pages rewritten for clarity and delight: introduction, installation, getting started, how commands work, core concepts, the workflow, explore first, existing projects, editing a change, customization, FAQ, and a reference section (slash commands, CLI, supported tools). - Static client-side search (Orama), per-page Open Graph images, and llms.txt / llms-full.txt routes — fitting for an AI-native tool. - website/README.md with one-table Cloudflare Pages deploy settings (root: website, build: npm run build, output: out). Content is faithful to the docs/ overhaul from #1237, restated in a simpler, friendlier voice. Verified with a clean `next build` (48 static pages, no warnings). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(website): sharpen the sell, add a Stores guide Completes the documentation work begun in #1237 by tightening the Fumadocs site toward the quality bar of the stores user-guide: - Intro now opens problem-first ("the requirements lived only in chat"), adds an honest "How it compares" table (Spec Kit / Kiro / nothing), and frames the tradeoff in a "When the ceremony isn't worth it" callout. - New Stores guide (beta) distilled from docs/stores-beta/user-guide.md: the problem, the annotated shape, a five-minute walkthrough with real command output, a role-based story, the root-resolution order, and an honest-limitations section. Linked from Existing Projects. Verified with a clean `next build` (51 static pages, no warnings). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(website): make the value tangible — landing sections + Examples page Continue the #1237 docs completion with a stronger product story: - Landing page now reads like a real product site: - "Works with the tools you already use" strip (15 named assistants + more) - "What a change actually looks like" — three real artifacts (proposal.md, a spec delta, tasks.md) so the workflow is concrete - "The honest middle" comparison block (Spec Kit / Kiro / no specs) - Robust hero gradient via color-mix instead of v3 theme() syntax - New Examples & Recipes page: seven copy-pasteable, narrated walkthroughs (small feature, bug fix, explore-first, parallel changes, no-behavior refactor with --skip-specs, step-by-step, onboard). Linked from the intro and getting-started. Verified: clean `next build` (54 static pages, no warnings); Tailwind opacity/color-mix utilities confirmed in the generated CSS; all internal links resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(website): add favicon, sitemap, and robots for a complete public site - Branded SVG favicon (app/icon.svg) in the OpenSpec indigo. - Static sitemap.xml covering the home page and every doc, built from the content source and NEXT_PUBLIC_SITE_URL. - robots.txt allowing all and pointing at the sitemap. All three are emitted by the static export. Clean `next build`, 57 pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: lead with stores as "why teams adopt OpenSpec"; complete docs coverage Final pass completing the #1237 documentation work. Reposition stores (beta) as the team adoption story, consistently: - README.md gains a prominent "Why teams adopt OpenSpec" section right after the demo (cross-repo features, shared requirements, plan before code), leading with stores. - Landing page gains a matching "Why teams adopt OpenSpec" section. - Docs intro gains a teams card + callout pointing at stores. - Stores page expanded with full References and Worksets technical examples (the cross-team requirements story, workset create/open). Incorporate the remaining source-doc knowledge so the site is complete: - New pages: Glossary, Troubleshooting, Multi-Language, and an Agents & Automation reference (the machine-readable --json surfaces and workflow primitives that make OpenSpec AI-native). - The Workflow page now covers ff-vs-continue, a three-dimension verify example, and the update-vs-start-fresh decision guide. - Nav restructured with a Help section; reference section gains Agents. Build hardening: `build` now runs `fumadocs-mdx && next build` so the content source is always regenerated. Clean build: 69 static pages, no warnings; all internal links verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(website): fix docs GitHub source links + address review nits - page.tsx: prefix ViewOptionsPopover githubUrl with website/ so the "view/edit source" links resolve to website/content/docs/... instead of 404-ing on every deployed docs page (Alfred blocker). - installation.mdx: note that `yarn global add` is Classic Yarn only and point Yarn Berry users at `yarn dlx` / npm / pnpm. - index.mdx: label the comparison table's first column ("Option"). - (home)/page.tsx: use the shared docsRoute constant for all /docs links instead of hardcoded paths. Verified with `npm run build` in website/ — 69 static pages, and the built getting-started page links to blob/main/website/content/docs/... Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(website): mirror docs/*.md into the site + auto-deploy on a cadence Make the repository's docs/*.md the single source of truth for the docs site instead of maintaining a parallel set of hand-written MDX pages that silently drift. - scripts/sync-docs.mjs mirrors ../docs into content/docs/ on every build: derives title/description, injects Fumadocs frontmatter (+ githubSource), rewrites internal *.md links to /docs routes, and emits meta.json. Pages are written as .md so <placeholders>/{braces} in the docs stay literal and never break the MDX build. - docs.sync.config.mjs is the one manifest deciding which docs publish and their slug/section/icon. content/docs/ is now generated + git-ignored; the curated .mdx pages are removed. The marketing landing page stays hand-authored. - build/dev/types:check run sync:docs first, so the site is always current. - .github/workflows/deploy-docs.yml rebuilds and deploys to Cloudflare Pages via Wrangler on push to docs/**|website/**, daily on a schedule, on demand, and as a build-only check on PRs. Needs CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID secrets and the DOCS_SITE_URL variable. - source.config.ts carries githubSource so "edit this page" opens the real docs/*.md; website/README.md documents the pipeline. Verified: clean build, 23 pages generated, 78 static pages, no warnings; all internal doc links resolve; MDX-hazard docs (cli, customization) build. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(website): fall back to default site URL when NEXT_PUBLIC_SITE_URL is empty The deploy workflow passes NEXT_PUBLIC_SITE_URL from the DOCS_SITE_URL repo variable, which resolves to an empty string when unset. `?? fallback` does not catch '' (only null/undefined), so `metadataBase: new URL('')` crashed `next build` with ERR_INVALID_URL while collecting page data. Use `||` so an empty value also falls back. Verified: `NEXT_PUBLIC_SITE_URL='' npm run build` now generates all 78 static pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: add reviewing, writing-specs, and team-workflow guides Fill the biggest gaps a new user hits, in the plain-language voice of the stores user guide: - reviewing-changes.md: the two-minute human review of an AI-drafted plan before /opsx:apply — what to open, in what order, and the red flags per artifact — plus the /opsx:verify pass after code. - writing-specs.md: what a strong requirement and scenario are made of, choosing ADDED/MODIFIED/REMOVED, and right-sizing a change. - team-workflow.md: how a change maps onto a branch and a pull request, reviewing spec deltas in a PR, when to archive, and parallel changes — framed as convention, since OpenSpec never touches git. Wire them into the docs map (README), the site nav (docs.sync.config.mjs), and light "next steps" cross-links from getting-started, editing-changes, and workflows. Verified: site builds clean, 26 pages, all internal links resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(website): add one-time deploy setup checklist + landing-page note Spell out the three maintainer steps that activate auto-deploy (create the openspec-docs Pages project, add CLOUDFLARE_API_TOKEN/ACCOUNT_ID secrets, merge to main), and note that the pipeline mirrors docs on build regardless. Also flag that openspec.dev is a separate Astro landing page and whether to keep/port this Fumadocs landing page is a maintainer decision. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(website): address review feedback on docs-site PR Maintainer review (TabishB) + Alfred blocker: - deploy-docs.yml: guard the Cloudflare deploy on `github.ref == refs/heads/main`. A `workflow_dispatch` on a feature branch previously passed the guard and, since wrangler hardcodes `--branch=main` (a production deploy), would overwrite the live docs site. Non-main dispatches are now build-only. Also resolves Alfred's deploy-path blocker. - package.json: drop the direct `cnfast` dependency and delete the dead `lib/cn.ts` (nothing imports it; a class-merge helper isn't used). - package.json: declare `zod` (^4.4.3) — it was a phantom dep only resolving via fumadocs-mdx's hoisted copy. Refresh the lockfile. - docs page: omit the on-page <DocsDescription>. The frontmatter description is derived from the first body paragraph, so it rendered the intro twice on every page. Kept in generateMetadata for SEO/OG. - team-workflow.md: `openspec store create` does an initial commit, so scope "never commits" to the user's project and reframe the store clause as "never clones or syncs on its own." - README.md: bump stale "20+ AI assistants" to "30+" to match the site. Verified: npm run types:check + npm run build pass, 26 docs synced, intro paragraph now renders once per page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(website): use pnpm to match the rest of the repo Per maintainer review (TabishB): the root repo is pnpm (ci.yml runs `pnpm install --frozen-lockfile` against a v9 `pnpm-lock.yaml`), but `website/` had introduced npm + a `package-lock.json`. Standardize on one package manager: - Replace website/package-lock.json with website/pnpm-lock.yaml (lockfileVersion 9.0, generated with pnpm v9 to match root). - deploy-docs.yml: add pnpm/action-setup@v4 (version 9, before setup-node, as in ci.yml), switch setup-node to `cache: pnpm` / `cache-dependency-path: website/pnpm-lock.yaml`, and `npm ci` → `pnpm install --frozen-lockfile`, `npm run build` → `pnpm run build`. - package.json scripts + README: `npm run ...` → `pnpm run ...`. website/ stays a standalone package (no pnpm-workspace.yaml), as before. Verified: `pnpm install --frozen-lockfile`, `pnpm run build`, and `pnpm run types:check` all pass — 26 docs synced, 87/87 static pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: temporarily disable docs deploy --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com> Co-authored-by: TabishB <tabishbidiwale@gmail.com>
115 lines
7.1 KiB
Markdown
115 lines
7.1 KiB
Markdown
# OpenSpec Documentation
|
|
|
|
Welcome. This is the home for everything OpenSpec.
|
|
|
|
OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing.
|
|
|
|
If you read nothing else, read these two pages:
|
|
|
|
1. [Getting Started](getting-started.md): install, initialize, and ship your first change.
|
|
2. [How Commands Work](how-commands-work.md): where you actually type `/opsx:propose` (hint: in your AI chat, not the terminal). This trips up almost everyone once.
|
|
|
|
That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion.
|
|
|
|
> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case.
|
|
|
|
## Pick your path
|
|
|
|
**I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby.
|
|
|
|
**I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything.
|
|
|
|
**I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean.
|
|
|
|
**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place.
|
|
|
|
**I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration.
|
|
|
|
**The AI just drafted a plan — now what?** Read it. [Reviewing a Change](reviewing-changes.md) shows the two-minute pass that catches a wrong turn while it's still cheap, and [Writing Good Specs](writing-specs.md) covers what a plan worth approving is made of.
|
|
|
|
**I work on a team.** [OpenSpec on a Team](team-workflow.md) shows how a change maps onto a branch and a pull request, and how teammates review a plan before the code.
|
|
|
|
**I'm coming from the old workflow.** The [Migration Guide](migration-guide.md) explains what changed and why, and promises your existing work is safe.
|
|
|
|
**I want to bend it to my team's process.** [Customization](customization.md) covers project config, custom schemas, and shared context.
|
|
|
|
**Something's broken.** [Troubleshooting](troubleshooting.md) collects the failures people actually hit, with fixes.
|
|
|
|
## The whole map
|
|
|
|
### Start here
|
|
|
|
| Doc | What it gives you |
|
|
|-----|-------------------|
|
|
| [Getting Started](getting-started.md) | Install, initialize, and run your first change end to end |
|
|
| [Explore First](explore.md) | Use `/opsx:explore` to think through an idea before you commit |
|
|
| [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat |
|
|
| [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive |
|
|
| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked |
|
|
|
|
### Use it day to day
|
|
|
|
| Doc | What it gives you |
|
|
|-----|-------------------|
|
|
| [Workflows](workflows.md) | Common patterns and when to reach for each command |
|
|
| [Examples & Recipes](examples.md) | Full walkthroughs of real changes, copy-pasteable |
|
|
| [Writing Good Specs](writing-specs.md) | What a strong requirement and scenario look like, and how to right-size a change |
|
|
| [Reviewing a Change](reviewing-changes.md) | The two-minute pass on a drafted plan before any code is written |
|
|
| [OpenSpec on a Team](team-workflow.md) | How changes fit branches, pull requests, and review |
|
|
| [Using OpenSpec in an Existing Project](existing-projects.md) | Adopting OpenSpec on a large brownfield codebase |
|
|
| [Editing & Iterating on a Change](editing-changes.md) | Update artifacts, go back, reconcile manual edits |
|
|
| [Commands](commands.md) | Reference for every `/opsx:*` slash command |
|
|
| [CLI](cli.md) | Reference for every `openspec` terminal command |
|
|
|
|
### Understand it deeply
|
|
|
|
| Doc | What it gives you |
|
|
|-----|-------------------|
|
|
| [Concepts](concepts.md) | The long-form explanation of specs, changes, artifacts, schemas, and archive |
|
|
| [OPSX Workflow](opsx.md) | Why the workflow is fluid instead of phase-locked, plus an architecture deep dive |
|
|
| [Glossary](glossary.md) | Every term defined in one place |
|
|
|
|
### Make it yours
|
|
|
|
| Doc | What it gives you |
|
|
|-----|-------------------|
|
|
| [Customization](customization.md) | Project config, custom schemas, shared context |
|
|
| [Multi-Language](multi-language.md) | Generate artifacts in languages other than English |
|
|
| [Supported Tools](supported-tools.md) | The 25+ AI tools OpenSpec integrates with, and where files land |
|
|
|
|
### When you need help
|
|
|
|
| Doc | What it gives you |
|
|
|-----|-------------------|
|
|
| [FAQ](faq.md) | Quick answers to the questions people ask most |
|
|
| [Troubleshooting](troubleshooting.md) | Concrete fixes for concrete failures |
|
|
| [Migration Guide](migration-guide.md) | Moving from the legacy workflow to OPSX |
|
|
|
|
### Coordinate across repos (beta)
|
|
|
|
| Doc | What it gives you |
|
|
|-----|-------------------|
|
|
| [Stores: User Guide](stores-beta/user-guide.md) | Plan in its own repo when your work spans repos or teams |
|
|
| [Agent Contract](agent-contract.md) | The machine-readable CLI surfaces agents drive |
|
|
|
|
## The thirty-second version
|
|
|
|
```text
|
|
1. Install npm install -g @fission-ai/openspec@latest
|
|
2. Initialize cd your-project && openspec init
|
|
3. Explore (in your AI chat) /opsx:explore ← optional, but a great habit
|
|
4. Propose (in your AI chat) /opsx:propose add-dark-mode
|
|
5. Build (in your AI chat) /opsx:apply
|
|
6. Archive (in your AI chat) /opsx:archive
|
|
```
|
|
|
|
Steps 1 and 2 happen in your terminal. The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming.
|
|
|
|
## Where else to get help
|
|
|
|
- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) for questions, ideas, and help.
|
|
- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) for bugs and feature requests.
|
|
- **`openspec feedback "your message"`** sends feedback straight from your terminal (it opens a GitHub issue).
|
|
|
|
Found something in these docs that's wrong, stale, or confusing? That's a bug. Open an issue or a PR. Documentation improvements are some of the most valuable contributions you can make.
|