2 Commits

Include renames

Author	SHA1	Message	Date
Clay GoodandClaude Opus 5	b928165276	docs(explore): stop claiming explore never writes files (#1838) ... * docs(explore): stop claiming explore never writes files Sixteen lines across both documentation trees told users that `/opsx:explore` creates no artifacts and writes no files, full stop. That has been false since explore shipped (#467): its capture branch writes the planning artifacts the user asked for, and can edit an existing change's artifacts. #1503 later made it scaffold with `openspec new change` first, closing #668 and #720. The claim appeared in two shapes. Six lines denied the capability outright ("Explore creates no artifacts and writes no code"). Ten more said the same thing as a timing claim ("before any artifact exists"), which reads as ordinary pitch copy and is what escaped the first pass. Every site now carries one guarantee, worded the same way: explore never writes code, and writes nothing else unless you ask, or say yes when it offers. Four sites described only the user-initiated trigger, which left the offer path - the one a reader actually hits - looking like it did not exist. docs/explore.md and docs/commands.md also gain a positive description of capture where the denial used to sit, including what scaffolding creates beyond the artifacts you named, and how capture differs from handing off to propose (propose writes the set your schema requires; capture writes only what you named). Closes #1833 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(docs): keep the retired explore wording retired A flat list of the phrasings that actually carried the claim, swept over the eleven pages that pitch explore. Fails on main with all sixteen offenders; clean on this branch. Modeled on test/vocabulary-sweep.test.ts, and deliberately a list rather than a grammar. An earlier draft built the grammar - section splitting, code-fence tracking, a conditional-marker exemption so "creates no artifacts unless you ask" would pass - and measured against realistic prose it was imprecise in both directions while returning the same verdict on the real input. The list has no exemption logic to get wrong, and any maintainer can extend it. Phrasings that are only wrong in the absolute ("writes nothing", "creates nothing") are left to review, since the conditional form of each is the wording the failure message recommends. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(docs): pin the explore capture contract, not the word The guide check matched any "capture", so "explore automatically captures every artifact" passed. Both explore.md and commands.md now must name the user trigger, `openspec new change`, and the named-artifacts scope, with no capture line claiming it happens unprompted, and keep "never writes code". Also scope the explore.md guarantee to the setup files a new change needs, and make the commands.md offer name the change and its scope, which the template asks for on main and after #1832. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(docs): accept negated unprompted-capture wording, catch non-capture verbs The unprompted check matched "automatically" on any capture line, so the correct "Explore does not automatically capture artifacts" failed, while "Explore automatically writes planning artifacts" was never scanned because it lacks the word capture. Check each clause of lines naming explore or capture for an unprompted write verb with no preceding negation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-09-16 15:45:53 +00:00
4 people	bb1f18c483	docs: comprehensive overhaul — discoverability, explore-first, and closing recurring doc-request issues (#1237) ... * docs: comprehensive documentation overhaul (home, mental model, command location, FAQ, glossary, troubleshooting, recipes) Addresses #1228 (docs are fragmented and hard to discover). Additive, docs-only. The single sharpest gap from the issue thread was that nobody explains where slash commands run, hence the new "How Commands Work" page. New docs: - docs/README.md documentation home / index that maps every doc - docs/how-commands-work.md where /opsx:* (chat) vs openspec (terminal) run; "interactive mode" answered - docs/overview.md core concepts at a glance, one page - docs/faq.md consolidated common questions - docs/glossary.md every term in one place - docs/troubleshooting.md concrete fixes for concrete failures - docs/examples.md real changes start to finish (recipes) Small additive edits: - docs/getting-started.md "where do I type this?" callout + first-five-minutes + richer Next Steps - README.md Docs list points at the new home and key new pages Voice: warm, plain, bottom-line-up-front; no em-dashes in prose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: make /opsx:explore front and center, plus general polish Per maintainer feedback (Tabish): "the docs in general need some work, alongside making the explore option a lot more front and center." explore ships in the default core profile but every doc led with propose and treated explore as a footnote for "unclear requirements." This reframes the canonical loop as explore -> propose -> apply -> archive and gives explore real prominence. - docs/explore.md (new): dedicated "Explore First" guide. When to use it, what it does/doesn't, a full transcript, handoff to propose, tradeoffs. - getting-started.md: explore added to the flow and first-five-minutes, with a featured callout and Next Steps entry. - overview.md: explore featured in the loop and next-links. - docs/README.md: explore in the opening, pick-your-path, 30-second version, and the doc map. - how-commands-work.md: explore leads the command list with a "good rhythm" note and an optional step in the clean-first-run example. - workflows.md: new first-class "Start by exploring" pattern in the default section (was buried under expanded mode); quick-reference row strengthened. - commands.md / faq.md / glossary.md: explore featured as the place to start. - examples.md: top callout pointing at the explore recipe. - README.md: explore opens the "See it in action" demo and Quick Start, and is added to the Docs list. Docs-only and additive. No em-dashes in prose; links verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: close recurring gaps (existing projects, editing changes, uninstall, context limits) + sync tool list Sweep of open issues and discussions surfaced several questions good docs should answer but didn't. This adds the missing guides and fixes a stale list. New guides: - docs/existing-projects.md: adopting OpenSpec on a large brownfield codebase without documenting everything up front (addresses #510, #1100, #176). Delta-first framing, first-change walkthrough, onboard, importing existing requirements docs, domain organization, monorepo/workspace pointers. - docs/editing-changes.md: how to edit any artifact, update a proposal/spec after starting, go back after implementing, and reconcile manual code edits (addresses #684, #976, #355, #1188, #169, #1206). Enhancements: - installation.md: Updating + Uninstalling sections (addresses #308). - faq.md: new entries for existing codebases, editing artifacts, going back, reconciling manual edits, context limits / long sessions, and uninstalling (addresses #257 among others). - cli.md: --tools list now includes `vibe` and matches AI_TOOLS in src/core/config.ts, with a note pointing at the source (fixes #1213). - Wired the new guides into the docs home, getting-started, and the README. Docs-only and additive. No em-dashes in prose; links and section anchors verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: reconcile coordinate-across-repos docs with the stores model The merge with main pulled in the stores rename (#1190), which retired the workspaces/initiatives/context-store vocabulary and deleted docs/workspaces-beta/. This updates the three docs still describing the old model so they match the new stores model, fixing the vocabulary-sweep test and dead links: - glossary.md: Workspace/Link/Context store/Initiative -> Store/Reference/ Working context/Workset; link to stores-beta/user-guide.md - README.md: replace deleted workspaces-beta/* links with the Stores User Guide and Agent Contract - existing-projects.md: reframe the multi-repo section as stores; drop the dead concepts.md#coordination-workspaces anchor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: TabishB <tabishbidiwale@gmail.com> Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>	2026-06-24 06:52:59 +00:00