{"owner":"Fission-AI","repo":"OpenSpec","hasSkills":true,"totalSkillsCount":22,"totalTokensCount":51882,"categories":["anthropic-skill","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/draft-openspec-docs/SKILL.md",".agents/skills/release-openspec/SKILL.md",".agents/skills/release-openspec/agents/openai.yaml",".agents/skills/release-openspec/references/release-notes.md",".agents/skills/verify-openspec-docs/SKILL.md",".agents/skills/write-openspec-docs/SKILL.md",".agents/skills/write-openspec-docs/full-process.md",".agents/skills/write-openspec-docs/writing.md","skills/README.md","skills/openspec-apply-change/SKILL.md","skills/openspec-archive-change/SKILL.md","skills/openspec-bulk-archive-change/SKILL.md","skills/openspec-continue-change/SKILL.md","skills/openspec-explore/SKILL.md","skills/openspec-ff-change/SKILL.md","skills/openspec-new-change/SKILL.md","skills/openspec-onboard/SKILL.md","skills/openspec-propose/SKILL.md","skills/openspec-sync-specs/SKILL.md","skills/openspec-update-change/SKILL.md","skills/openspec-verify-change/SKILL.md","test/AGENTS.md"],"skills":{".agents/skills/draft-openspec-docs/SKILL.md":"---\nname: draft-openspec-docs\ndescription: Collaborative page-drafting mode for the OpenSpec docs. Builds a scratch plan inside the target page (purpose, structure, numbered draft steps), iterates on it with the user, then drafts one section per approved step and cleans up after itself. Use when a page needs a from-scratch rewrite or a new page is being shaped with the user in the loop.\nargument-hint: target page\n---\n\n# Draft OpenSpec docs (scratch-plan workflow)\n\nYou are shaping a docs page with the user in the loop. The page is planned and reviewed inside the page itself, then drafted one section at a time. Load `write-openspec-docs` (the style authority) and `no-ai-slop` before drafting anything.\n\n## 1. Set up the scratch section\n\nStrip the page to its title and `>` goal line, then add a working section below them:\n\n```md\n## Scratch: page plan (delete before publish)\n\n### Purpose\n\n### Structure\n```\n\n- **Purpose**: 3-5 dot points. Who the reader is and what they come to look up, what the page covers, what it links out to. Check `docs-lab/README.md` (the page's goal line) and `docs-lab/message-map.md` (the questions routed here) before writing it.\n- **Structure**: a numbered list of the page's sections, one line each naming the section and the shape of its content (table, fence, tree, bullets).\n- Say what the page will do, never what it won't. Plain words and short bullets; the user reads this in their editor.\n\n## 2. Iterate until the plan is approved\n\n- Plan edits are cheap; page edits aren't. Reshape the plan as many times as the user asks before drafting.\n- Record every decision in the plan itself, not only in chat. Add a `### Notes` list for follow-ups that belong to other pages and product observations found along the way.\n- The user may edit the file directly between turns; their edits are decisions, not drift to revert.\n- Surface one open call at a time, with a recommendation.\n\n## 3. Add the draft plan, then draft step by step\n\nOnce the structure holds, add a `### Draft plan` below the notes: one step per page section, each with an ID and a readable title (`**D1. Goal line and intro**`), ending with a consolidation step (cross-page updates) and a cleanup step. Then:\n\n- Wait for the user to call a step ID. Draft exactly that step, into the page above the scratch block.\n- Verify each fact against source before writing it; a cheap grep beats trust. Reference content shows the raw contract (templates, instructions, config) verbatim in fences, linked to the file on GitHub, rather than paraphrasing it.\n- Keep sibling sections on a repeatable sub-structure so the page scans as one system.\n- Mark the step `(done)` in the plan, report what landed, and name the next step.\n\n## 4. Consolidation and cleanup\n\n- **Consolidation**: update everything that points at the page. The README goal line (verbatim match with the page's `>` line), the message map, the sync config (`website/docs.sync.config.mjs`), and any cross-links found by grepping the tree. Run `node website/scripts/sync-docs.mjs` to validate.\n- **Cleanup**: delete the scratch block, run the retrievability and glance tests from `write-openspec-docs` at desktop and narrow widths, and flip the page's message-map row to Answered if its prose landed.\n",".agents/skills/release-openspec/SKILL.md":"---\nname: release-openspec\ndescription: >-\n Use this skill when releasing OpenSpec: audit merged work and changeset\n coverage, decide whether a catch-up changeset PR is needed, prepare or resume\n the Changesets Version Packages PR, cut a beta or stable release, verify\n publishing, and polish GitHub release notes. Also use when asked whether an\n open release PR is complete, what the next release step is, or to continue a\n release paused for human approval.\n---\n\n# Release OpenSpec\n\nRun the OpenSpec release workflow as a resumable state machine. Inspect live GitHub state on every invocation and take only the next safe action. Do not assume an earlier invocation completed.\n\n## Principles\n\n- Treat `Fission-AI/OpenSpec` and `origin/main` as the release source of truth.\n- Default to a read-only audit when the user asks for status, readiness, or advice.\n- Treat a request to release, prepare a release, continue, or resume as authorization to perform the applicable release actions.\n- Preserve the user's checkout. Never discard unrelated changes or switch their current branch just to prepare a changeset.\n- Use a temporary worktree from current `origin/main` for release-authored commits when the checkout is dirty or not on `main`.\n- Never approve your own PR. Human review is a deliberate gate.\n- Treat merge-queue entry as an intermediate state, not a merge. Advance only after GitHub reports `mergedAt` and the commit is present on `main`.\n- Never create the automated Version Packages PR manually. The Changesets action owns it.\n- Never push an empty commit merely to retrigger CI. Diagnose the failed or missing run first.\n- Report URLs, the state reached, and the exact human action needed whenever pausing.\n\n## Know the two PR types\n\nKeep these distinct in output and decisions:\n\n- **Changeset PR**: A normal human-authored PR that adds one or more `.changeset/*.md` files. Prefer adding a changeset to the feature/fix PR; create a catch-up changeset PR only for already-merged work that should be included.\n- **Version Packages PR**: The automated `changeset-release/main` PR titled `chore(release): version packages`. Merging or adding changesets to `main` updates this same PR. Merging it publishes the stable release.\n\nAn open Version Packages PR does not prohibit a catch-up changeset PR. It means a catch-up PR is useful only when the audit finds missing release-worthy work. Once that PR merges, wait for the existing Version Packages PR to update.\n\n## Start with a release audit\n\n1. Verify the repository and tools:\n - Resolve the GitHub repository with `gh repo view --json nameWithOwner,url`.\n - Require authenticated `gh`, `git`, and `pnpm` before write actions.\n - Stop before release mutations if the canonical repository is not `Fission-AI/OpenSpec`.\n2. Refresh without modifying the worktree:\n\n ```bash\n git fetch origin main\n ```\n\n Do not fetch every tag indiscriminately. This repository may contain a conflicting historical local tag, which can make `git fetch --tags` fail even though `origin/main` fetched successfully.\n\n3. Find the latest stable GitHub release. Exclude drafts and prereleases; do not use `git describe`, because a beta tag may be newer than the stable baseline.\n\n ```bash\n gh release list --repo Fission-AI/OpenSpec \\\n --exclude-drafts --exclude-pre-releases --limit 100 \\\n --json tagName,publishedAt \\\n --jq 'max_by(.publishedAt) | {tagName, publishedAt}'\n ```\n\n Ensure that exact stable tag resolves locally before using it as a `git log` boundary. Fetch only that tag if it is missing. If a same-named local tag disagrees with the canonical remote, report the mismatch and use a separately resolved canonical commit; never force-rewrite the user's tag as part of an audit.\n\n4. Find open release-related PRs:\n\n ```bash\n gh pr list --repo Fission-AI/OpenSpec --state open \\\n --head changeset-release/main \\\n --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup\n ```\n\n Identify the Version Packages PR by `headRefName == \"changeset-release/main\"`, not title alone. Separately list likely changeset PRs and inspect their files; require positive additions to `.changeset/*.md`. Do not mistake the Version Packages PR's changeset deletions for authored changesets, and do not rely on titles because a feature/fix PR may add release tracking.\n5. Read the live release policy in `.changeset/README.md`, pending `.changeset/*.md` files on `origin/main`, and the Version Packages PR body/files when it exists.\n6. List first-parent commits since the latest stable tag:\n\n ```bash\n git log --first-parent --date=short \\\n --pretty=format:'%h%x09%ad%x09%s' ..origin/main\n ```\n\n7. Map release-worthy merged PRs to existing changesets. Use PR files and changeset history; do not infer coverage from similar wording alone.\n8. Classify the audit as:\n - `missing-tracking`: user-facing work intended for this release lacks a changeset;\n - `awaiting-changeset-review`: a suitable changeset PR already exists;\n - `awaiting-merge-queue`: an approved changeset or Version Packages PR is queued but has not landed on `main`;\n - `awaiting-version-update`: required changesets are on `main`, but the Version Packages PR has not incorporated them;\n - `awaiting-version-review`: the Version Packages PR is current but lacks approval;\n - `ready-to-publish`: the Version Packages PR is current, approved, and green;\n - `publishing`: the Version Packages PR merged but artifacts are incomplete;\n - `needs-finalization`: npm, tag, and GitHub Release exist but notes are still raw;\n - `complete`: package, tag, GitHub Release, and polished notes agree.\n\nPresent a compact audit with the stable baseline, proposed version, covered changes, possible omissions, intentionally skipped internal/docs work, open PRs, and next action.\n\n## Decide changeset coverage\n\nFollow `.changeset/README.md` rather than assuming every merged PR needs a changeset.\n\nInclude work selected for release tracking, especially:\n\n- new user-facing features or commands;\n- notable fixes or hotfixes;\n- breaking changes or deprecations;\n- user-visible performance improvements.\n\nNormally skip documentation-only work, tests, CI/tooling, and internal refactors. Flag ambiguous user-visible changes instead of silently excluding them. Ask the user only when the ambiguity materially changes release scope or the semantic version; otherwise use best judgment and let PR review be the approval gate.\n\n## Create or continue a changeset PR\n\nDo this only for `missing-tracking`.\n\n1. If an open changeset PR already covers the missing work, reuse it. Inspect its `headRefName`, head repository, and `maintainerCanModify`; fetch that exact head branch from its owning repository into a temporary worktree, make the update there, and push back to the same PR head. Stop if the branch is not writable. Do not create a duplicate PR or replacement branch.\n2. Read `.changeset/README.md` immediately before authoring.\n3. Only when no suitable PR exists, create a short `changeset-` branch from current `origin/main`. Use a temporary worktree so the operator's checkout remains untouched.\n4. Prefer one changeset per coherent release unit. A single catch-up changeset may summarize several small items selected for the same release.\n5. Use the exact package name `\"@fission-ai/openspec\"`, the highest required semantic bump, only relevant headings, and user-focused descriptions.\n6. Validate before pushing:\n\n ```bash\n pnpm exec changeset status\n ```\n\n7. Commit, push, and open a PR whose body lists the covered merged PRs and explains why the catch-up is needed.\n8. Stop after returning the PR URL and request human approval. Do not approve it yourself.\n\nOn a later invocation, if the PR is approved and checks are green, merge or enqueue it only when the user asked to continue or complete the release. If GitHub uses a merge queue, inspect `mergeQueueEntry`, queue checks, and `mergedAt`; remain in `awaiting-merge-queue` until the PR actually lands on `main`. Then wait for the Changesets action on `main` to update the existing Version Packages PR. Poll with concise progress updates; do not push an empty commit or another branch update, because that can dismiss approval and restart the queue.\n\n## Validate the Version Packages PR\n\nBefore calling it ready:\n\n1. Confirm it targets `main` from `changeset-release/main` and is generated by the expected automation.\n2. Enumerate every pending `.changeset/*.md` file on current `main`, excluding `.changeset/README.md`. Verify the PR consumes every one and contains the corresponding changelog content. If any pending changeset should be deferred, stop: remove or revise it through a separately reviewed change and wait for automation to regenerate the Version Packages PR before continuing.\n3. Fetch `baseRefOid` and `headRefOid` with `gh pr view`, require `baseRefOid` to equal current `origin/main`, and create clean detached temporary worktrees for both revisions. If the head object is missing locally, fetch the immutable `pull//head` ref first. Never validate from the operator's current worktree.\n4. In the base worktree, run `pnpm exec changeset status --output changeset-status.json` and read the expected package/version from that file. Install locked dependencies in the temporary worktree first if the Changesets CLI is unavailable.\n5. Compare the base status and complete pending-changeset set against the head worktree: `package.json`, `CHANGELOG.md`, removed changeset files, PR body, and proposed version must all agree. This is a base-to-head comparison because the head has already consumed the changesets and cannot calculate the pending release itself.\n6. Remove the temporary worktrees after validation, then inspect all required checks and review state with `gh pr view` / `gh pr checks`.\n\nIf current but unapproved, return the URL and pause for human approval. If approved and green, merge or enqueue only when the user asked to release or continue. With merge queue enabled, do not treat approval, auto-merge enablement, or queue entry as the stable publish trigger; wait for `mergedAt` and confirmation that the merge reached `main`.\n\n## Verify stable publishing\n\nAfter the Version Packages PR merges:\n\n1. Find the release workflow run for the merge commit and wait for completion.\n2. Verify all three artifacts independently:\n - `npm view @fission-ai/openspec@ version`\n - remote tag `v` points at the expected commit;\n - `gh release view v` exists and is not a prerelease.\n - The release's assets include the 8 `openspec-*` standalone archives (`.tar.gz`, `.zip` on Windows) and `SHA256SUMS`, attached by the Binaries workflow (`binaries.yml`) about 10 minutes after the release is published. Until `SHA256SUMS` is there, the install scripts keep installing the previous release, so users are never left without one.\n3. If only some artifacts exist, report partial state and resume verification before retrying any publish action. Never republish a version already on npm. Missing binaries never need an npm action: re-run `binaries.yml` with `workflow_dispatch` and the release tag to attach them.\n4. Once all artifacts exist, read [references/release-notes.md](references/release-notes.md), polish the GitHub Release, and verify the saved title/body.\n\n## Cut a beta\n\nOnly enter this path when the user explicitly asks for a beta or prerelease.\n\n1. Run the same audit and confirm pending changesets produce a next stable version.\n2. Explain that beta publishing does not consume changesets or replace the stable Version Packages PR.\n3. Trigger the existing `release-prepare.yml` workflow on `main`; do not calculate or set the beta version locally.\n4. Verify the workflow-selected version, npm `beta` dist-tag, remote tag, and prerelease GitHub Release.\n5. Do not merge the stable Version Packages PR as part of a beta request.\n\n## Handle failures\n\n- For failed CI, inspect the failing check and logs before proposing a rerun or code change.\n- For a stale Version Packages PR, first confirm a successful `push` run of `release-prepare.yml` occurred after the latest changeset reached `main`.\n- For branch divergence, let the Changesets action update its branch. Do not force-push `changeset-release/main`.\n- For a queued PR, inspect merge-group checks and queue state. Do not re-enqueue, update the branch, or rerun unrelated checks while it is progressing normally.\n- For a version that already exists on npm, stop and reconcile the tag/GitHub Release rather than incrementing or republishing implicitly.\n- For missing GitHub permissions or required review, report the exact gate and URL; preserve the detected state so the next invocation can resume by inspection.\n\n## Completion report\n\nReport:\n\n- released version and stable/beta channel;\n- changeset PR and Version Packages PR URLs, when applicable;\n- release workflow result;\n- npm package, tag, and GitHub Release verification;\n- release-notes finalization status;\n- any intentionally deferred changes.\n",".agents/skills/release-openspec/agents/openai.yaml":"interface:\n display_name: \"Release OpenSpec\"\n short_description: \"Audit, prepare, publish, and finalize releases\"\n default_prompt: \"Use $release-openspec to audit the current release state and take the next safe release step.\"\n",".agents/skills/release-openspec/references/release-notes.md":"# GitHub release notes\n\nRead this file only after the npm package, tag, and GitHub Release exist, or when the user explicitly asks to preview or polish release notes.\n\n## Gather source material\n\n1. Bind the release values once and fetch the current release. Replace the example values, but keep every expansion quoted:\n\n ```bash\n tag=\"vX.Y.Z\"\n previous_tag=\"vA.B.C\"\n gh release view \"$tag\" --repo Fission-AI/OpenSpec \\\n --json body,name,isPrerelease,url\n ```\n\n2. For a stable release, find the preceding stable release by excluding drafts and prereleases. For a beta, compare against the preceding tag in the same beta series when one exists; otherwise compare against the latest stable release.\n3. Fetch GitHub-generated notes to recover first-time contributor attribution and the full changelog link:\n\n ```bash\n gh api repos/Fission-AI/OpenSpec/releases/generate-notes \\\n -f \"tag_name=$tag\" -f \"previous_tag_name=$previous_tag\" -q '.body'\n ```\n\n4. Cross-check the final content against the released `CHANGELOG.md` section and the merged Version Packages PR. Never invent an item from commit titles alone.\n\n## Title\n\nUse:\n\n```text\n - \n```\n\nLead with the most notable user-facing addition. For two similarly important additions, comma-separate them. For a fix-only release, name the primary fixed area.\n\n## Body\n\nUse only the sections that contain content:\n\n```markdown\n## What's New in \n\n\n\n### New\n\n- **Feature** - What users can now do and when it helps.\n\n### Improved\n\n- **Area** - What became easier, safer, faster, or more consistent.\n\n### Fixed\n\n- **Area** - What now behaves correctly.\n\n## New Contributors\n\n* @username made their first contribution in #PR\n\n**Full Changelog**: \n```\n\n## Voice and cleanup\n\n- Write for developers using OpenSpec with AI coding assistants.\n- Be direct and practical; avoid marketing language.\n- Lead with user capability or impact, not implementation.\n- Keep each item to one or two sentences.\n- Remove commit hashes, changeset wrappers, raw semantic-bump headings, and inline `Thanks @user` boilerplate.\n- Omit internal CI, test, and refactor details unless users experience the result.\n- Keep contribution credit in `New Contributors`, not inside feature bullets.\n- Preserve GitHub's first-contribution wording and PR link.\n- Exclude core maintainer `@TabishB` from `New Contributors`. If no external first-time contributors remain, omit that section.\n- Always retain the full changelog compare link.\n\n## Apply and verify\n\nCreate a temporary file, write the body to it with the available file-editing tool, bind the final title, then update:\n\n```bash\nnotes_file=\"$(mktemp)\"\ntitle=\"$tag - Release Theme\"\n# Write the polished Markdown body to \"$notes_file\" before continuing.\ngh release edit \"$tag\" --repo Fission-AI/OpenSpec \\\n --title \"$title\" --notes-file \"$notes_file\"\n```\n\nWhen the user asked only for a preview or audit, show the proposed title/body without editing. When the user asked to run, continue, or complete the release, apply the polished notes without an extra confirmation pause, then fetch the release again and verify the saved title/body.\n",".agents/skills/verify-openspec-docs/SKILL.md":"---\nname: verify-openspec-docs\ndescription: Fact-checks OpenSpec user documentation with a fresh-context subagent that re-runs commands and checks claims against source. Manually triggered; not part of the drafting loop. Use when the user asks to verify, fact-check, or accuracy-check a docs page, section, or set of changed claims.\nargument-hint: page or section\n---\n\n# Verify OpenSpec docs\n\nCheck finished docs prose against reality. The point of a fresh context is that the reviewer hasn't watched the prose get written, so it can't be talked into the author's assumptions.\n\nThis skill runs only when the user asks for it. Drafting is owned by `write-openspec-docs`; don't invoke this from inside a drafting session unless the user requests a verification pass.\n\n## Scope the run\n\n1. Confirm the target: a page, one `##` section, or a list of changed claims. If invoked without a target, ask.\n2. Read the README at the root of the docs tree the target lives in; its invariants and page map are part of what gets checked.\n3. One subagent per unit (one `##` section, or the stated claim list). A full page is several subagents, run in parallel.\n\n## Spawn the reviewer\n\nGeneral-purpose subagent. Subagents don't inherit skills, so the prompt hands the reviewer everything by path. Fill every placeholder, make every path absolute, and send:\n\n```\nYou are reviewing one unit of OpenSpec's user documentation before it reaches the docs owner. Be the two hardest readers it will meet: a skeptical developer reading it cold, and a fact-checker with the repo open.\n\nRepo root: . Use absolute paths with every tool.\n\nRead first:\n1. /README.md: the page map and standing invariants.\n2. /.agents/skills/write-openspec-docs/writing.md: the house writing rules.\n3. : review only \" | these changed claims: >; read the rest of the page for context.\n\nThen check, in this order:\n\n1. Facts. Every command, flag, path, config key, output block, default, and behavior claim. Re-run the terminal commands shown: read-only commands anywhere, anything that mutates state in a scratch directory or not at all. Commands for the AI chat surface (like /opsx:propose) can't run in a shell; verify their names and behavior against the skill sources this repo ships. Check names against src/ and the CLI's own --help. An output block must match what the command actually prints.\n2. Examples. Any example spec or change must pass `openspec validate`. Run it when the example exists on disk.\n3. Structure. Flag anything that re-explains a topic whose canonical home is another page, or breaks a rule the docs tree's README states.\n4. Job fit. Does the unit serve the page's stated job (the one-line statement under the title, if present)? Does the arriving reader get what they came for quickly?\n5. Trust and slop. Flag: hype or comfort adjectives (easy, simple, powerful, seamless), claims with no shown evidence, vague generalization where a specific fact belongs, binary contrasts (\"not X, it's Y\"), colon reveals, importance puffery, summary endings, em dashes, bullet lists that should be prose, and three parallel punchy sentences in a row.\n\nReport findings only, most severe first. For each: quote the line, say what is wrong, and give the fix in one line. For every fact you verified, say how (the command you ran, or the file and line you checked). List any claim you could not verify and why. Do not rewrite the unit. If the unit is clean, say so and list exactly what you verified.\n```\n\n## Handle the report\n\n- Default is report, not rewrite: show the user the findings ranked most severe first, each with the quoted line and one-line fix, plus what was verified and how, and any claim the reviewer couldn't verify.\n- Apply fixes only when the user asked for a verify-and-fix run or approves the findings. A verifier can also be wrong: rejections go in the report with your reason, so the user can overrule you.\n- If an applied fix changed a factual claim, verify again, scoped to the changed claims. Typo and wording fixes don't need a second pass.\n- Two passes without converging means stop and take it to the user. Don't polish in a loop.\n",".agents/skills/write-openspec-docs/SKILL.md":"---\nname: write-openspec-docs\ndescription: Switches into OpenSpec docs-writing mode; loads the house style guide and drafts or revises pages in its voice (action-first, no preamble, scannable). Use when writing or editing pages in the OpenSpec docs tree.\nargument-hint: page or section\n---\n\n# Write OpenSpec docs\n\nYou are now writing OpenSpec's user docs. Read [writing.md](writing.md); it is the style authority for everything drafted here. The short version, in effect immediately:\n\n- A page is a retrieval surface, not an essay. Structure decides whether the reader finds the answer; prose only decides how it reads. Open every section with the answer, never a running story.\n- Choose the page type before the outline. Guides follow the reader's task; reference mirrors the product's structure and uses exact field, command, and file names as scan anchors. Reference needs complete coverage without compressing several facts into one sentence, cell, or paragraph.\n- Draft the shortest version that answers; expanding a spare page is cheap, cutting a bloated one is a rewrite. Plain words, the fewest of them: an idea that fits in one line takes one line. Depth most readers skip goes behind a link, and the payload (commands, real output, failures and fixes) stays whole.\n- Dumb sentences, smart structure. Write the obvious sentence (actor, verb, object, stating the literal event); never compress extra facts in or take an angle. No hype adjectives, no preamble, no em dashes.\n- One job per slot: one fact per sentence, list intros only announce the list, one reader question or lookup target per section. A related fact gets its own slot, never a ride in someone else's.\n- Ground items in what the reader can verify: path or folder first, concept as the gloss, real output shown honestly.\n- No house template. Inventories open with a list naming every item, then expand each in its own unit after the list, never inline. Sequences take numbered steps (numbers mean order; inventories take bullets). Single ideas and reasoning stay in short prose.\n- Every load-bearing fact sits on a scan anchor: code fence, numbered bold lead-in, `**Term**: fact` bullet, table, file tree. Never only mid-paragraph.\n- Before finishing, run two backstop tests. Retrievability: can each question or exact product name be found by scanning alone? The glance: inspect the rendered page as shapes; does it look finishable, or like work? Check table-heavy changes at desktop and narrow widths. A failure means a slot got written without being earned; fix it now, don't leave it for review.\n\n## Ground rules\n\n- Load the `no-ai-slop` skill before drafting; it owns the generic slop patterns, while [writing.md](writing.md) owns what OpenSpec's docs specifically look and sound like.\n- Read the target page in full before editing it.\n- Real facts only: flags, paths, and output as they exist in source. If a claim can't be checked cheaply, still write it, but name it as unchecked when you show the work; never bridge a gap with a plausible-sounding sentence.\n- A fact lives on one page; everywhere else links to it. The docs tree's README owns the page map and structural invariants; check it before restructuring or adding pages.\n- For reference pages, inventory the contract from source before drafting prose. Follow the reference process in [writing.md](writing.md#reference-pages).\n- When unsure how something should scan or sound, match the exemplars: `docs-lab/start/setup.md` for section shape and inventories, `docs-lab/start/installation.md` (Uninstalling) for multi-step tasks.\n\n## When done\n\nShow the user what changed and name any unchecked claims.\n\nIf the user asks for the deep, evidence-first drafting session (run every command, one section per sitting, formal checkpoints), follow [full-process.md](full-process.md).\n",".agents/skills/write-openspec-docs/full-process.md":"# Full drafting process (opt-in)\n\nThe evidence-first, checkpointed way to draft a page. Use this only when the user asks for the deep process; the default mode is SKILL.md alone.\n\n## Orient (every session, before any writing)\n\n1. Read the README at the root of the docs tree you're writing in. Where it states invariants or a page map, it wins over this skill.\n2. Read the target page top to bottom, plus anything its comments cite.\n3. Read the sibling pages this page links to or overlaps with, enough to know what must stay a link rather than become an explanation.\n4. Write down the page's job in one line: who arrives, trying to do what, and what they leave able to do. If the page carries a job statement (docs-lab pages use a `>` blockquote under the title), test against it. If the unit you're about to write doesn't serve that job, stop and raise it instead of drafting around it.\n\n## Work in small units\n\n- The default unit is one `##` section. A page is several sittings, not one.\n- For revisions to existing prose, the unit is the requested change, however many headings it touches.\n- Draft the next unit only after the user has reviewed the current one. When the user asks for fixes, fix only that; don't smuggle in the next unit.\n\n## Evidence before prose\n\nBefore drafting a unit, know where its claims come from.\n\n- Run the terminal commands the unit will show when they're cheap: read-only commands anywhere, anything that mutates state in a scratch directory or not at all. Paste real output; trim it, never retouch it.\n- Check names against source: flags, paths, config keys, and defaults come from `src/` and the CLI's own help, not from older docs. When docs and source disagree, source wins; note the conflict for the user.\n- Never bridge a gap with a plausible-sounding sentence. A claim you couldn't check gets flagged at the checkpoint, not silently shipped. Don't let one expensive check stall the draft.\n\n## Strip the slop\n\nInvoke the `no-ai-slop` skill on the drafted unit and apply its edit pass. Docs prose gets no exemption: the patterns it names read as machine-written to exactly the audience these docs must win over.\n\n## Does it do the job?\n\nReread the unit cold, as the reader the job line names, arriving with their actual problem. Answer three questions:\n\n1. Can they act? Every step is runnable as written, and nothing depends on knowledge the page hasn't given or linked.\n2. Do they know it worked? Where success could be in doubt, the unit shows something visible: output, a file, what the agent does next. Where the outcome is obvious, no success line is owed.\n3. What can they do now that they couldn't before? If the honest answer is \"they read some context\", the unit is explaining instead of solving; cut it back to what serves the job or raise it with the user.\n\nA unit that fails here gets fixed before the checkpoint, not annotated.\n\n## Checkpoint\n\nEnd the unit by showing the user:\n\n- the file path and the unit written;\n- the page's job in one line, and what this unit lets the reader do toward it;\n- which claims you checked and how (commands run, files read);\n- any claim still unchecked.\n\nThen stop. The next unit starts when the user says so.\n",".agents/skills/write-openspec-docs/writing.md":"# OpenSpec docs: the style guide\n\nStructure, voice, tone, and language for OpenSpec's user docs. This file is the primary style authority for the docs tree. The tree's own README owns structure (the page map and which page teaches what); when this file and that README disagree, the README wins. `no-ai-slop` owns the generic slop patterns; this file owns what OpenSpec's docs specifically look and sound like.\n\n## Six principles\n\nEvery rule below applies one of these; when rules collide, the principles decide.\n\n- **A page is a retrieval surface, not an essay.** The reader arrives mid-task with a question, scans for the answer, and leaves. Structure decides whether they find it; prose only decides how it reads. Structure wins.\n- **The shortest version that answers is the right length, drafted that way from the start.** Expanding a spare page is cheap; cutting a bloated one is a rewrite. Plain words, and the fewest of them: an idea that fits in one line takes one line.\n- **Dumb sentences, smart structure.** Write the obvious sentence: actor, verb, object, stating the literal event (\"Running init creates two things in your project\"). Never the version that compresses facts in or takes an angle (\"Everything init creates is meant to be committed\"). If a sentence needs unpacking, it failed.\n- **One job per slot.** A sentence carries one fact (one carrying three hides two). A list intro only announces its list. A section owns one reader question or lookup target. Related facts get their own slot, never a ride in someone else's.\n- **Ground everything in what the reader can verify.** Name things by path, file, or real output: what the reader could match against `ls`. The concept is the gloss, never the name.\n- **No house template.** Shape follows content: inventories get overview-then-expand, sequences get numbered steps, a single idea gets short paragraphs, and reasoning lives in prose. The universal check is the retrievability test, not bullet count.\n\n## The retrievability test\n\nName the questions or exact product terms a reader would bring to the section (\"does init touch `.gitignore`?\", \"how do I add a tool later?\", `generates`). Each answer or term must be findable by scanning, heading to anchor to fact, without reading paragraphs. If finding a fact means reading sentences, restructure; prose that passes needs no bullets, and no amount of bullets saves a section that fails.\n\n## The shortest draft\n\nBrevity happens at drafting time, not review. A page that needs heavy cutting in review gets rewritten, and a rewrite costs more than writing it spare the first time. Start from the shortest version that answers and expand only where a real reader question goes unanswered.\n\nEvery slot is earned before it's written:\n\n- **The unit**: it answers a reader question or documents a lookup target, or it doesn't go in. Tight prose on the wrong scope is still the wrong scope.\n- **The sentence**: would any reader come back for it? If not, it spends attention without buying anything; don't write it.\n- **The depth**: an edge case or rationale most readers skip goes behind a link to its canonical page, not inline. The docs keep the depth; this page doesn't charge every reader for it.\n- **The payload**: the command, the real output, the failure and its fix stay whole. Spare means no wind-up and no commentary, never fewer facts.\n\nThe glance test is the backstop, not the method. Scroll the rendered page and read it as shapes: short units, air between anchors, no screen-filling block of anything. A page that looks like work loses its reader before the first sentence; if yours does, something above got in without earning its slot. For table or layout changes, check both desktop and narrow widths; the Markdown source can't show cramped columns, poor wrapping, or horizontal scrolling.\n\n## Shape of a section\n\n- **Answer first**: open with the command, the inventory, or the fact in one line. Context and rationale come after, never first.\n- **Inventory, then expand**: when a section covers several things (what init installs, what an uninstall leaves behind), open with a list naming every item in one line each, then expand each in its own unit after the list (a subsection or bold lead-in).\n- **The overview only names**: a count (\"two things:\") is not an inventory, and expansion never happens inline in the list; the reader sees the whole footprint, then the detail.\n- **Place first, meaning second**: name each on-disk item by its path or folder (\"an `openspec/` folder at the repo root\"), never by concept alone (\"the planning folder\"). The concept gloss can wait for the item's expansion. When a location varies (per tool, per OS), anchor it with a real folder or two (\"`.agents/`, `.claude/`\") and link the full list.\n- **Core before nuance**: inside every unit, the answer, then what to expect, then edge cases last. A reader who stops early still leaves with the core.\n- **One unit per target**: task pages separate different reader questions. Reference pages separate different product elements when readers look them up independently. Two facts with different targets get separate units, even when one elegant sentence could join them.\n\n## Scan anchors\n\nEvery load-bearing fact sits on an anchor: something the eye lands on without reading. A fact a reader might come back for never lives only in the middle of a paragraph. The anchors these docs use:\n\n- Code fences, for commands and real output.\n- Numbered steps with bold lead-ins (`**1. Remove the package.**`) for multi-step tasks.\n- `**Term**: fact` bullets for options, properties, and locations.\n- Tables, when several items share the same attributes (mostly reference pages).\n- File trees with inline annotations for layouts.\n\nA full screen of content with no anchor is a wall, even when every sentence in it is true.\n\n## Choosing the shape\n\nNo house template: facts go on anchors (enumerable content defaults to a list or table); explanation, reasoning, and judgment go in prose. The content picks the form:\n\n- **Sequences**: numbered steps, one bounded action each. Numbers mean order of execution; an inventory of things takes bullets, never numbers. Restate any value a step needs rather than pointing back three steps.\n- **Options, properties, locations**: `**Term**: fact` bullets.\n- **Items sharing the same attributes**: a table.\n- **A single idea** (why a store is worth it, what sync treats as drift): a couple of short paragraphs; that is the right shape.\n- **Connected reasoning**: a paragraph. Shredding a thought into fragments makes it harder to read, not easier; a bullet list of full explanatory sentences is a paragraph in costume, so write the paragraph.\n\nAcross every form:\n\n- Cap lists at about five items. Longer than that, split by priority: common path first, edge cases into their own list or a linked page.\n- Keep items parallel: same internal order (name, fact, catch, link), same grammatical shape. Repetition across items is what makes scanning work; never vary structure between items for the sake of the prose.\n- Uniformity is right when the content is uniform (a reference table, an install matrix). When every section on a varied page resolves to the same pattern, some of those lists are disguised paragraphs.\n\n## Prose budget\n\nParagraphs are glue between anchors, not containers for facts.\n\n- One to three lines. Three is the ceiling; a glue line between two anchors is often enough.\n- The list intro has exactly one job: say what the list is (\"Running init creates two things in your project:\"). Never spend that slot on a different fact, however related; it gets its own line after the list.\n- Parentheses and semicolon riders are for true asides only (a version caveat, a pointer). If a reader might return for the fact, it gets its own anchor.\n- A section that is mostly paragraphs is misshaped, unless the page is genuinely conceptual (Concepts, explanations of the model). Even there, front-load each paragraph and leave air between them.\n\n## Sentences\n\n- Short sentences, active voice. Default subject is \"you\" or the tool by name.\n- No preamble. The first sentence of any unit states the thing itself, never wind-up (\"Before we get into...\", \"It's worth understanding that...\").\n- No em dashes anywhere in these docs. Use a colon, a comma, parentheses, or two sentences.\n- Write the sentence you would say out loud. A draft that splices clauses with semicolons or colon-stacked fragments (\"different documents: fewer of them, different names, different structure\") gets rewritten as the spoken version (\"when you want these to be different documents, whether that means fewer of them, different names, or a different structure\"). Colons still introduce lists, fences, and labels. They don't splice prose.\n- Contractions are fine (\"you're set\", \"doesn't come along\"). These docs talk, they don't proclaim.\n- Inside narrative paragraphs, vary sentence length so the prose doesn't read staccato. Paragraphs only; list items stay parallel even when the cadence repeats.\n\n## Voice\n\nThe narrator is a colleague who has run every command on the page, hit the failure modes personally, and is telling you what they know. Not a marketer, not a tutorial host, not a manual.\n\n- Calm and specific. The reader wants the fact, the command, and the catch, in that order.\n- Confidence comes from precision, not emphasis. Never \"very\", \"extremely\", \"critical\", bold-for-importance, or exclamation marks.\n- Plain judgment is welcome. The docs may tell the reader what to do and what to skip: \"The `openspec/` folder: pause first.\"\n- Address the reader as \"you\". OpenSpec, the CLI, and init do things. \"We\" appears only for project decisions (\"we say skills\"), never as a tour guide.\n- Dry beats chirpy. No cheerleading, no apologizing, no drama around failures. A failure is a fact with a fix.\n\n## Structure and tone by page type\n\nSame voice everywhere; structure and temperature shift:\n\n- **Start pages**: numbered steps and short units, nothing assumed, every step ends in something visible. Warmest the docs get, which is still plain.\n- **Guides**: peer to peer, skip re-orientation. The judgment calls are the reason guides exist; put them on anchors so they scan.\n- **Reference**: mirror the product, use its exact names as anchors, and cover the contract without compressing it. Tables and fragments are common, but scan speed decides the shape. No motivation or persuasion; the reader is here to look something up and leave.\n- **Troubleshooting**: symptom, cause, fix, in that order, one unit per symptom. Name the error the reader sees. Never \"you may notice\" or \"sometimes it can happen that\".\n\nGuides and Customize pages share one skeleton: a one-line what, a link to the Quickstart (never a recap), the 80% path, then Advanced. The exception is the concepts page, which is an explanation, not a task guide; its shape follows its concerns.\n\n## Reference pages\n\nReference describes the product for a reader who is already working with it. The outline follows the machinery: file, block, field; command group, command, option; object, property, value. Use the product's exact names as headings when readers will search for those names. Reader-question headings belong to task pages unless the question itself is the established lookup term.\n\nCover the full contract without packing several facts into one sentence, cell, or paragraph.\n\n### Draft the contract first\n\nBefore writing prose:\n\n1. Inventory the product elements from source.\n2. Arrange them in the same hierarchy as the product.\n3. Write the smallest complete contract for each element.\n4. Expand only the elements whose behavior needs more room.\n5. Add examples that illustrate one rule at a time.\n6. Audit defaults, constraints, failures, ignored input, and validation gaps.\n\nFor each field, option, command, or file, record the identity facts that apply:\n\n- Exact name and syntax\n- Type or accepted values\n- Required state and default\n- Scope, location, or base path\n\nThen record the behavior facts that apply:\n\n- Behavior and side effects\n- Constraints\n- Failure and ignored-input behavior\n- What validation catches and misses\n\nDon't create empty sections or table columns for facts that don't apply.\n\n### Inventory, then expand\n\nOpen with a complete table or list. Expand an item below the inventory only when its behavior can't fit cleanly in the overview. Put the expansion under the item's exact name so the table of contents works as an index.\n\nFor field and option references, `Field | Contract` is the safe table shape when definitions need sentences. Add more columns only when every cell is short and comparable. If columns split one coherent definition into fragments or wrap badly at a narrow width, use fewer columns or move the detail below the inventory.\n\n### Examples and edge cases\n\nAn example illustrates one mapping, rule, or result. It doesn't become a sequence the reader follows or a narrative about completing a task. A complete example may follow the contract when seeing the elements together helps lookup.\n\nPut the concrete default path or value in the primary slot. Put environment variables and uncommon overrides afterward.\n\nState the observable consequence of a limit. If OpenSpec ignores a misspelled field, say that validation passes and the field has no effect. If a value falls back, name the value OpenSpec uses.\n\n## Two surfaces\n\nOpenSpec spans the terminal and the AI chat, and readers mix them up. Label every snippet:\n\n```\nIn your terminal:\n openspec init\n\nIn your AI chat:\n /opsx:propose add-rate-limit\n```\n\nWhere the reader could doubt it worked (a fresh install, a first run, a command with no output of its own), end with the concrete success signal: the line the command prints, the file that now exists, what the agent says next. Where the outcome is obvious, stop; an unneeded success line is noise.\n\n## Authoring mechanics\n\nPages are plain markdown; GitHub and the site both render them. JSX components (``, ``, `
`) don't render; never use them.\n\n- **Install commands**: write the global npm command once, in a fence whose language is `npm`; the site renders it as npm/pnpm/yarn/bun tabs with a copy button per tab (`remarkNpm` in `website/source.config.ts`, which also persists the reader's choice across blocks). On GitHub the fence degrades to the plain npm command.\n- **Callouts**: GitHub-style blockquote alerts (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`); GitHub styles them natively and the site renders them as callouts (`remarkGfmAlert` in `website/lib/remark-gfm-alert.ts`). Never place one directly under the page title: the sync lifts the leading blockquote into the page description.\n\n## What earns a developer's trust\n\n- Show the real command and its real output, trimmed honestly. A retouched output is a lie the reader catches on their first run.\n- No hype and no comfort adjectives: easy, simple, just, powerful, seamless, robust. Three lines that show the thing beat any adjective about it.\n- State limits plainly. A named limitation builds more trust than praise: \"Your assistant does need to be able to run shell commands; a few IDE integrations can't.\"\n- Don't generalize. Where you're tempted to write what OpenSpec \"helps\" with, write what actually happens: which file appears, what the diff shows, what the agent does next.\n- Don't define what you can show. An unfamiliar term whose instances explain themselves (the workflow list: propose, explore, apply...) is introduced by showing the instances with one-phrase glosses; the abstraction can wait.\n- Exact names: flags, paths, config keys, and versions as they exist in source, linked to their canonical page on first use.\n\n## Naming and terms\n\n- One term per concept, the glossary's term if the tree has one; today that means \"skills\", never \"slash commands\".\n- No invented taxonomy. Product terms (spec, change, delta, profile, store) name real things; use them freely. Any other organizing word in a heading or goal (\"layers\", \"levers\", \"pillars\") must pass one test: would a reader use it to ask their own question? If not, write the reader's question or the plain enumeration (\"What you can customize\", never \"The three layers\").\n- Examples invoke workflows by skill: the ask that triggers it (\"ask your agent to propose a change\") or the skill's name (`openspec-propose`), which is the same in every tool. A command spelling (`/opsx:propose`) appears only as a labeled per-tool example, never as the generic instruction; commands are headed for deprecation and their spellings vary per tool.\n- Prefer the shared `.agents/` folder in file-path examples; a tool-specific folder (`.claude/`) appears only when the example is about that tool.\n- Headings lead with a verb when the section is something the reader does (\"Initialize your project\"). Found content takes a plain noun phrase (\"Install methods\"). Never a vague verb (\"Understand it\") and never a pun.\n- If the page carries a one-line job statement under the title (docs-lab uses a `>` blockquote the site lifts into the page description), keep it plain, concrete, and true of the finished page.\n\n## One canonical home\n\nA fact lives on exactly one page; everywhere else links to it. A second copy is a future contradiction. The tree's README says which page owns what; when in doubt, link.\n\n## Exemplars\n\nWhen unsure how something should scan or sound, match these:\n\n- `docs-lab/start/setup.md`: section shape, inventory-then-expand, enumerable facts on bullets.\n- `docs-lab/start/installation.md`, the Uninstalling section: multi-step tasks with bold numbered lead-ins.\n","skills/README.md":"# OpenSpec skills for skills.sh\n\nInstall the OpenSpec workflow skills into any [skills.sh](https://skills.sh)-compatible agent:\n\n```bash\nnpx skills add Fission-AI/OpenSpec\n```\n\nEach `openspec-*/SKILL.md` here is the same skill `openspec init` writes into a\nproject. The skills drive the `openspec` CLI, so for the full setup (CLI +\n`openspec/` project scaffolding + slash commands) run:\n\n```bash\nnpx openspec@latest init\n```\n\n> These files are generated from the skill templates — do not edit by hand. Run\n> `pnpm build && pnpm generate:skills` after changing a template;\n> `skillssh-parity.test.ts` fails if they drift.\n","skills/openspec-apply-change/SKILL.md":"---\nname: openspec-apply-change\ndescription: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says \"openspec apply\", \"opsx apply\", or \"openspec implement\".\nallowed-tools: Bash(openspec:*)\nlicense: MIT\ncompatibility: Requires openspec CLI.\nmetadata:\n author: openspec\n version: \"1.0\"\n---\n\nImplement tasks from an OpenSpec change.\n\n**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store ` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store ` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change \"\" --json --store \"\"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.\n\n**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store ` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `\"root\": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.\n\nOne `\"root\": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.\n\nOtherwise, with no root, what happens next depends on how this workflow was reached:\n\n- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.\n- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store `), or continue without OpenSpec for this request. Wait for their answer.\n\nIn both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.\n\n**Input**: Optionally specify a change name (e.g., `/openspec-apply-change add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.\n\n**Steps**\n\n1. **Select the change**\n\n If a name is provided, use it. Otherwise:\n - Infer from conversation context if the user mentioned a change\n - Auto-select if only one active change exists\n - If ambiguous, run `openspec list --json` to get available changes and ask the user to select one\n\n Always announce: \"Using change: \" and how to override (e.g., `/openspec-apply-change `).\n\n2. **Check status to understand the schema**\n ```bash\n openspec status --change \"\" --json\n ```\n Parse the JSON to understand:\n - `schemaName`: The workflow being used (e.g., \"spec-driven\")\n - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints\n - Which artifact contains the tasks (typically \"tasks\" for spec-driven, check status for others)\n\n3. **Get apply instructions**\n\n ```bash\n openspec instructions apply --change \"\" --json\n ```\n\n This returns:\n - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)\n - Progress (total, complete, remaining)\n - Task list with status, source path, and source line\n - Dynamic instruction based on current state\n - Optional `context`: current required project instruction input from the selected root\n - Optional `operationGuidance`: current advisory guidance for apply\n - `missingArtifacts` (when present): required artifact ids with no output\n\n **Handle states:**\n - If `state: \"blocked\"`: show the message and pause implementation.\n - If `missingArtifacts` is non-empty: suggest using `/openspec-continue-change` to create them.\n - Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked.\n - If `state: \"all_done\"`: report that all tracked tasks are complete and suggest review or verification as appropriate before archiving\n - Otherwise: proceed to implementation\n\n Treat `context` as a required prompt-level input. Read and consider it, and\n apply relevant project facts, conventions, and constraints while implementing.\n Treat `operationGuidance` as optional additive advice. Read and consider every\n entry, and follow entries that are applicable and compatible with the built-in\n workflow.\n\n Keep both fields separate from CLI-returned state, missing artifacts, tasks,\n progress, `contextFiles`, and the built-in `instruction`. They are not\n evidence of task completion, do not replace the built-in instruction, and do\n not permit bypassing a blocked state. If context conflicts with the built-in\n instruction, an explicit user choice, or a CLI-controlled value, report the\n conflict and preserve the controlling value. If guidance is inapplicable or\n conflicts with those controlling inputs, do not follow it and explain why.\n These are prompt-level behavior contracts, not enforceable checks.\n\n4. **Read context files**\n\n Read every file path listed under `contextFiles` from the apply instructions output.\n The files depend on the schema being used:\n - **spec-driven**: proposal, specs, design, tasks\n - Other schemas: follow the contextFiles from CLI output\n\n Do not copy `context` or `operationGuidance` verbatim into implementation\n files or planning artifacts unless the user separately asks for that content.\n\n5. **Show current progress**\n\n Display:\n - Schema being used\n - Progress: \"N/M tasks complete\"\n - Remaining tasks overview\n - Dynamic instruction from CLI\n\n6. **Implement tasks (loop until done or blocked)**\n\n For each pending task:\n - Show which task is being worked on\n - Make the code changes required\n - Keep changes minimal and focused\n - Before editing, confirm the checkbox at the returned `sourcePath` and `line` still matches the task description; if it does not, rerun the apply instructions and use the refreshed location\n - Mark the task complete at its returned `sourcePath` and `line`: `- [ ]` → `- [x]`\n - Rerun the apply instructions and confirm that task is now done and progress changed\n - Continue to next task\n\n **Pause if:**\n - Task is unclear → ask for clarification\n - Implementation reveals a design issue → suggest updating artifacts\n - A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently\n - Error or blocker encountered → report and wait for guidance\n - User interrupts\n\n7. **On completion or pause, show status**\n\n Display:\n - Tasks completed this session\n - Overall progress: \"N/M tasks complete\"\n - If all done: report that tracked tasks are complete and suggest review or verification as appropriate before archiving\n - If paused: explain why and wait for guidance\n\n**Output During Implementation**\n\n```\n## Implementing: (schema: )\n\nWorking on task 3/7: \n[...implementation happening...]\n✓ Task complete\n\nWorking on task 4/7: \n[...implementation happening...]\n✓ Task complete\n```\n\n**Output On Completion**\n\n```\n## Implementation Complete\n\n**Change:** \n**Schema:** \n**Progress:** 7/7 tasks complete ✓\n\n### Completed This Session\n- [x] Task 1\n- [x] Task 2\n...\n\nAll tracked tasks are complete. Review or verify the change as appropriate\nbefore archiving. You can archive this change with `/openspec-archive-change`.\n```\n\n**Output On Pause (Issue Encountered)**\n\n```\n## Implementation Paused\n\n**Change:** \n**Schema:** \n**Progress:** 4/7 tasks complete\n\n### Issue Encountered\n\n\n**Options:**\n1.