spec-ctx 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "spec-ctx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Deterministic context engine and task workflow for OpenSpec projects.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "specctx": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "skills",
+    "action.yml"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "npm run prepare",
+    "build:bin": "bun build src/cli.ts --compile --outfile build/specctx",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun test",
+    "test:node": "vitest run",
+    "lint": "bash scripts/lint-md.sh",
+    "ctx": "node dist/cli.js",
+    "gen": "node scripts/gen-assets.mjs",
+    "prepublishOnly": "bun run build",
+    "prepare": "node scripts/gen-assets.mjs && tsc -p tsconfig.build.json && node scripts/chmod-bin.mjs",
+    "ci:local": "bash scripts/ci-local.sh"
+  },
+  "dependencies": {
+    "smol-toml": "^1.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonqh/spec-ctx.git"
+  },
+  "homepage": "https://github.com/sonqh/spec-ctx#readme",
+  "keywords": [
+    "openspec",
+    "spec-driven",
+    "ai-agents",
+    "context",
+    "cli"
+  ]
+}

package/schemas/spec-driven-ids/README.md

@@ -0,0 +1,18 @@
+# spec-driven-ids
+
+A fork of the OpenSpec `spec-driven` schema. It adds stable IDs from spec-ctx to every artifact.
+
+- The spec template starts each requirement with `REQ-<CAP>-NNN` and each scenario with `SCN-<CAP>-NNN-<n>`.
+- The instructions tell the agent to get IDs from `specctx id new` and to link IDs with `Refs:` lines.
+- The tasks template cites REQ IDs and puts the `Verify:` command in a code span, so `specctx task done` can run it.
+- `config-fragment.yaml` holds the `rules` and `operations` that `specctx init --schema` adds to `openspec/config.yaml`.
+
+Forked from OpenSpec 1.14.3 with `openspec schema fork spec-driven spec-driven-ids`. CI validates it against that version.
+
+## Install
+
+```bash
+npx spec-ctx init --schema
+```
+
+The command copies this folder to `openspec/schemas/spec-driven-ids/` and sets `schema: spec-driven-ids` in `openspec/config.yaml`.

package/schemas/spec-driven-ids/config-fragment.yaml

@@ -0,0 +1,25 @@
+# spec-ctx fragment for openspec/config.yaml. specctx init --schema adds each top-level key
+# that the project config does not have yet. It never changes a key that exists.
+rules:
+  specs:
+    - Every requirement header starts with its ID, e.g. "### Requirement: REQ-ABC-001 Name". Get the ID from `specctx id new REQ ABC`.
+    - Every scenario header starts with its ID, e.g. "#### Scenario: SCN-ABC-001-1 Name".
+    - A requirement may end with a line "Refs: REQ-ABC-002, ADR-001" to link related IDs.
+    - Requirement text stays under 500 characters. Move detail into scenarios.
+  design:
+    - Each decision is one bullet under "## Decisions". Add new decisions at the end.
+  tasks:
+    - Every task cites at least one REQ ID in square brackets, e.g. "[REQ-ABC-001]".
+    - Every task states its verification as a command in a code span after "Verify:".
+
+operations:
+  apply:
+    guidance:
+      - Start each task with `specctx task start <id>` and read the bundle it prints before you read specs.
+      - Tag code with the REQ ID it implements (a comment `// REQ-ABC-001`). Tag tests with `// Covers: REQ-ABC-001`.
+      - Close each task with `specctx task done <id>`. Never tick a checkbox by hand.
+      - Run `specctx check --strict` after each task group.
+  archive:
+    guidance:
+      - Run `specctx check --strict` and `openspec validate --all --strict`. Both must pass before archive.
+      - Run `openspec validate --all --strict` again after archive and before push.

package/schemas/spec-driven-ids/schema.yaml

@@ -0,0 +1,301 @@
+name: spec-driven-ids
+version: 1
+description: OpenSpec spec-driven workflow with stable IDs from spec-ctx - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      Create the proposal document that establishes WHY this change is needed.
+
+      Sections:
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+      - **Capabilities**: Identify which specs will be created or modified:
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
+      - **Impact**: Affected code, APIs, dependencies, or systems.
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract between
+      proposal and specs phases. Research existing specs before filling this in:
+      run `openspec list --specs` for the project's capability inventory, then
+      `openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
+      look related - that returns a capability's purpose and requirement texts
+      without pulling whole spec files into context. Append `--store "<id>"` to
+      both commands only for a registered standalone store, and keep `--type
+      spec`: a change and a spec sharing a name is otherwise an ambiguous-item
+      error. `openspec list` without `--specs` lists in-flight changes, not
+      specs - it never shows what the project already covers. Reuse an existing
+      capability's exact path instead of introducing a near-duplicate name.
+      The filtered read is only an overview. Before deciding what is already
+      covered or what should change, read each relevant spec in full, including
+      scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
+      Each capability listed here will need a corresponding spec file.
+
+      Every change must either declare at least one capability (new or
+      modified) or explicitly opt out of specs: `openspec validate` rejects a
+      change with zero deltas unless the change's `.openspec.yaml` sets
+      `skip_specs: true`. Use `skip_specs: true` only when no spec-level
+      behavior changes (pure refactor, tooling, docs) - specs describe
+      behavior, so if behavior does not change, no spec should change either.
+      Do not invent a requirement just to satisfy validation.
+
+      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+      implementation details belong in design.md.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: |
+      Create specification files that define WHAT the system should do.
+
+      A spec is a behavior contract, not an implementation plan.
+
+      Good spec content:
+      - Observable behavior users or downstream systems rely on
+      - Inputs, outputs, and error conditions
+      - External constraints (security, privacy, reliability, compatibility)
+      - Scenarios that can be tested or explicitly validated
+
+      Avoid in specs:
+      - Internal class/function names
+      - Library or framework choices
+      - Step-by-step implementation details
+      - Detailed execution plans (those belong in design.md or tasks.md)
+
+      Quick test: if the implementation can change without changing externally
+      visible behavior, it likely does not belong in the spec.
+
+      Create one spec file per capability listed in the proposal's Capabilities section.
+      `<capability-path>` is the spec directory relative to `specs/` (for example,
+      `user-auth` or `identity/user-auth`). Preserve the full path:
+      - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
+      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
+
+      Write the spec files one at a time, so the user sees progress and an
+      interrupted run keeps the files it already wrote:
+      - Before writing anything, compare the capabilities the proposal lists
+        with the `specs/<capability-path>/spec.md` files that already exist,
+        and start with the first capability that has no file. Do not rewrite
+        an existing file unless the user asks you to.
+      - Before each file, say in one line which capability you are writing.
+      - Write each file as soon as you have drafted it. Do not plan every file
+        before writing the first.
+      - Stop when every capability the proposal lists has its file.
+
+      There must be at least one spec file unless the change's `.openspec.yaml`
+      sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
+      rejects a zero-delta change without that marker. If the proposal lists no
+      capabilities and `skip_specs` is not set, revisit the proposal first.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+      - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
+
+      New capabilities only: the delta spec's first section is `## Purpose` -
+      one or two sentences (50+ characters, or `openspec validate --strict`
+      reports it as too brief) describing what the capability is for. Archive
+      copies it into the main spec it creates; without it the new main spec is
+      left with a `TBD ... Update Purpose after archive` placeholder to fill in
+      by hand. Do NOT add `## Purpose` to a delta for an existing capability -
+      that spec already has one and the delta's is ignored. To change an
+      existing capability's Purpose - including a leftover `TBD` placeholder -
+      edit `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
+      directly. `planningHome.root` comes from the `openspec instructions ...
+      --json` response. Always use it rather than a repo-relative path: it
+      resolves to the store whenever the change lives in one - whether that
+      came from `--store`, a project `store:` pointer, or a global default
+      store - and to the current repository otherwise. Do not try to work out
+      which case applies; the field already has.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (the same store-aware root as above)
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+      If adding new concerns without changing existing behavior, use ADDED instead.
+
+      Example (a new capability, so its first section is `## Purpose`):
+      ```
+      # Spec Delta
+
+      ## Purpose
+
+      Lets users take their data out of the product in a portable format.
+
+      ## ADDED Requirements
+
+      ### Requirement: User can export data
+      The system SHALL allow users to export their data in CSV format.
+
+      #### Scenario: Successful export
+      - **WHEN** user clicks "Export" button
+      - **THEN** system downloads a CSV file with all user data
+
+      ## REMOVED Requirements
+
+      ### Requirement: Legacy export
+      **Reason**: Replaced by new export system
+      **Migration**: Use new export endpoint at /api/v2/export
+      ```
+
+
+      Stable IDs (spec-ctx):
+      - Every requirement header starts with an ID: `### Requirement: REQ-<CAP>-NNN <name>`.
+        Get a new ID from `specctx id new REQ <CAP>`. Never count numbers by hand.
+        `<CAP>` is a capability code from `[ids] caps` in `spec-ctx.toml`.
+      - Every scenario header starts with an ID: `#### Scenario: SCN-<CAP>-NNN-<n> <name>`.
+        Get it from `specctx id new SCN <CAP> --for REQ-<CAP>-NNN`.
+      - Under MODIFIED, REMOVED, or RENAMED, keep the existing ID. An ID never changes.
+      - Link related IDs with one line `Refs: ID, ID` after the requirement text.
+      - Replace every placeholder of the template. `specctx check` reports a header with
+        no ID as `missing-id`.
+
+      Specs should be testable - each scenario is a potential test case.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: |
+      Create the design document that explains HOW to implement the change.
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Unknowns that can safely be answered later without
+        changing the specs, the approach, or the task breakdown. Omit if none.
+
+      Open questions are for genuinely deferrable unknowns, not decisions you
+      skipped. If a question would change the specs, the chosen approach, or
+      the task breakdown, resolve it now - ask the user instead of guessing.
+
+      Focus on architecture and approach, not line-by-line implementation.
+      The proposal covers why and what; design covers how. Reference the
+      proposal for motivation and, once written, the specs for requirements -
+      if a section would only restate them, point to them instead.
+
+
+      Stable IDs (spec-ctx):
+      - Each bullet under `## Decisions` is one decision. Its ID is `<change number>/D<n>`
+        by position, so add new decisions at the end and never reorder them.
+      - End a decision with `Refs: ` and the REQ or ADR IDs it serves. Then `specctx bundle`
+        prints the decision with those requirements.
+
+      Good design docs explain the "why" behind technical decisions.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      Create the task list that breaks down the implementation work.
+
+      Before writing tasks, check design.md for Open Questions. If any of them
+      would change what gets built, resolve them with the user first - do not
+      bake an unstated assumption into the task list.
+
+      **IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses
+      checkbox format to track progress. A box holding only `x` counts as done,
+      upper or lower case and with any spacing, so `- [ x]` is done too. Every
+      other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
+      unfinished. A line with no checkbox is not tracked at all.
+
+      Guidelines:
+      - Group related tracked tasks under ## numbered headings
+      - Each tracked task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Tasks should be small enough to complete in one session
+      - Order tasks by dependency (what must be done first?)
+      - Track implementation and verification work that can be completed before
+        archive. If the requested workflow includes archive or work that requires
+        this change to be archived, preserve those steps as plain bullets in an
+        optional `## Workflow follow-up` section at the end of tasks.md. These
+        bullets are reference information outside tracked task progress.
+      - Each task MUST state how to verify completion (a test, command,
+        observable behavior, or delivered artifact). Put the verification in
+        that task's checkbox description. Use a separate verification task only
+        when it checks broader integration or system behavior that spans
+        multiple implementation tasks.
+      - Each task group MUST land the tests and documentation its own work
+        calls for. Do NOT collect testing or documentation into a final group -
+        when a late group first exercises work from an early one, the failures
+        cascade back through every group in between and force rework. A group
+        whose work calls for neither, such as scaffolding or dependency setup,
+        carries neither. A final group is for integration checks only, not for
+        the tests and docs an earlier group owed.
+
+      Example:
+      ```
+      # Tasks
+
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure and verify expected files are present
+      - [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function and verify the export test passes
+      - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
+      - [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
+      ```
+
+      When applicable, append workflow follow-up as plain bullets, for example:
+      ```
+      ## Workflow follow-up
+
+      - Archive the change after the project's review requirements are satisfied.
+      - Verify the archived result.
+      ```
+
+
+      Stable IDs and Verify (spec-ctx):
+      - Every task cites at least one requirement in square brackets: `[REQ-<CAP>-NNN]`.
+      - Every task ends with `Verify:` and the command in a code span, for example
+        ``Verify: `npm test -- tests/export.test.ts` ``. Two spans run joined with `&&`.
+      - Use prose after `Verify:` only when no command can check the work. Then
+        `specctx task done <id> --manual "<note>"` records it.
+      - Close a task only with `specctx task done <id>`. It runs the command, writes
+        evidence under `.ctx/evidence/`, and sets the checkbox.
+
+      Reference specs for what needs to be built, design for how to build it.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [ tasks ]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.

package/schemas/spec-driven-ids/templates/design.md

@@ -0,0 +1,22 @@
+# Design
+
+## Context
+
+<!-- The current state and the constraints that shape the approach. The proposal holds the motivation. -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design gives -->
+
+**Non-Goals:**
+<!-- What stays out of scope -->
+
+## Decisions
+
+<!-- One bullet per decision. The ID of a decision is <change number>/D<n> by position. Add new ones at the end. -->
+- <!-- The decision, the alternative, and why. --> Refs: <!-- REQ-<CAP>-NNN, ADR-NNN -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and the mitigation for each -->

package/schemas/spec-driven-ids/templates/proposal.md

@@ -0,0 +1,34 @@
+# Proposal
+
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Name each capability for a cohesive system
+     behavior that can own related requirements as the system evolves. Do not name
+     implementation tasks or proposal sections. Avoid broad catch-all names. Use
+     kebab-case for path segments you introduce (e.g., user-auth or identity/user-auth)
+     that follow the project's existing spec organization. Each creates
+     specs/<capability-path>/spec.md. -->
+- `<capability-path>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use the exact existing path under openspec/specs/. Leave empty if no requirement
+     changes. A change with no capabilities at all (pure refactor, tooling, docs)
+     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
+     a zero-delta change without that marker. Do not invent a requirement just to
+     satisfy validation. -->
+- `<existing-capability-path>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

package/schemas/spec-driven-ids/templates/spec.md

@@ -0,0 +1,15 @@
+# Spec Delta
+
+## Purpose
+<!-- New capability only. Write one or two sentences of 50 characters or more. Delete this section for an existing capability. -->
+
+## ADDED Requirements
+
+### Requirement: REQ-<CAP>-NNN <!-- requirement name -->
+<!-- Requirement text. Replace REQ-<CAP>-NNN with the output of `specctx id new REQ <CAP>`. -->
+
+Refs: <!-- related IDs such as ADR-001. Delete this line when there are none. -->
+
+#### Scenario: SCN-<CAP>-NNN-1 <!-- scenario name. Get the ID from `specctx id new SCN <CAP> --for REQ-<CAP>-NNN`. -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

package/schemas/spec-driven-ids/templates/tasks.md

@@ -0,0 +1,10 @@
+# Tasks
+
+## 1. <!-- Task group name -->
+
+- [ ] 1.1 <!-- Task description --> [REQ-<CAP>-NNN] Verify: `<!-- command -->`
+- [ ] 1.2 <!-- Task description --> [REQ-<CAP>-NNN] Verify: `<!-- command -->`
+
+## 2. <!-- Task group name -->
+
+- [ ] 2.1 <!-- Task description --> [REQ-<CAP>-NNN] Verify: `<!-- command -->`

package/skills/specctx-bootstrap/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: specctx-bootstrap
+description: Start a session in an OpenSpec project that uses spec-ctx. Use at the start of every session, and on "start", "bootstrap", or "what should I work on". Loads only the spec text that the next task needs.
+---
+
+# specctx-bootstrap
+
+Load the minimum context for one task. Run `specctx` as `npx spec-ctx` when it is not installed.
+
+## Steps
+
+1. Run `specctx status`. It rebuilds a stale index first. Note the active change, the current task, and the count of open questions. The last line `next: <step>` names the next step. Exit 2 with `not an OpenSpec project` means the folder has no `openspec/`. Tell the user to run `npx -y @fission-ai/openspec@latest init` and stop.
+2. Read `.ctx/handoff.md` if it exists. Note `current`, `reopened`, and `open_questions`.
+3. If `status` prints `no active change`, show the open questions to the user. Ask which change to start. Stop here.
+4. Pick the task. Use `current` from the handoff, then the user's message, then the output of `specctx task next`.
+5. Run `specctx task start <task>`. It prints the bundle for the REQ IDs of the task and sets the current task.
+6. Read the bundle. Each block starts with `-- <id> | <file>:<line> | <status> | <reason>`. A `modified` block is the pending text of an active change. Trust it over the main spec.
+7. If the bundle ends with `truncated: N entries omitted: <ids>`, run `specctx bundle <id>` for each ID that the task needs.
+8. Say in one line which task you are on and which IDs you loaded. Then start the work.
+
+## Rules
+
+- Do not open `openspec/specs/` or `openspec/changes/*/specs/` by hand. Use `specctx bundle` or `specctx task start`.
+- Read at most 10,000 characters of spec text before the first code edit.
+- Tag code with `// REQ-ABC-001` and tests with `// Covers: REQ-ABC-001`.
+- Get a new ID from `specctx id new REQ <CAP>`. Never count numbers by hand.
+- Close the task with the `specctx-done` skill.

package/skills/specctx-done/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: specctx-done
+description: Close a task in an OpenSpec project that uses spec-ctx. Runs the Verify command, writes evidence, sets the checkbox, writes the handoff, and shows the metrics. Use when the work of a task is complete, or on "done", "close the task", and "end the session".
+---
+
+# specctx-done
+
+Close the current task with evidence. Run `specctx` as `npx spec-ctx` when it is not installed.
+
+## Steps
+
+1. Run `specctx task done <task>`. It runs the `Verify:` command of the task in the project root.
+2. On exit 0 it writes `.ctx/evidence/<change>/<task>.json` and sets `[x]` on the task line. Nothing else in `tasks.md` changes.
+3. On a failure it prints the last 20 lines of output and exits 1. The task stays open. Fix the cause and run step 1 again.
+4. If the task has prose after `Verify:` and no command, run `specctx task done <task> --manual "<what you checked>"`.
+5. After the last task of a group, run `specctx check --strict`. Fix every finding before the next group.
+6. Run `specctx handoff write`. It writes `.ctx/handoff.md` from the index, the evidence, and the open questions.
+7. Run `specctx stats --change <change>`. Report the five metrics of the change in one line each.
+8. Commit the work together with `.ctx/`. Leave `.ctx/index.json` out of git.
+
+## Rules
+
+- Never tick a checkbox by hand. `check --strict` reports a ticked task with no evidence as `done-without-evidence`.
+- If a spec changed after you closed a task, run `specctx task reopen <task> "<reason>"`.
+- To leave a question for the next session, run `specctx handoff ask "<question>"` before step 6.

package/skills/specctx-next/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: specctx-next
+description: Pick and start the next task in the middle of a session in an OpenSpec project that uses spec-ctx. Use after you close a task, or on "next task" and "what is next".
+---
+
+# specctx-next
+
+Move to the next open task. Run `specctx` as `npx spec-ctx` when it is not installed.
+
+## Steps
+
+1. Run `specctx task next`. It prints the task ID and text, then `reqs:` and `verify:`.
+2. If it prints `no open task. Every task in the active changes is done. Next: archive <change>.`, every task of the active changes has its checkbox set. Run `specctx status`. Its last line is `next: archive <change>`. Tell the user that the change is ready for `specctx check --strict` and archive. Stop here.
+3. Run `specctx task start <task>`. It prints the bundle for the REQ IDs of the task and sets the current task in `.ctx/current.json`.
+4. Read the bundle. Request an omitted ID with `specctx bundle <id>` only when the task needs it.
+5. Run `specctx task verify <task>` once before the work. It runs the `Verify:` command and writes nothing. A failure now shows what the work must fix.
+6. Say in one line which task you are on. Then start the work.
+
+## Rules
+
+- Take the tasks in the order that `specctx task next` gives. Earlier tasks in a group come first.
+- A question that blocks you goes to `specctx handoff ask "<question>"`. Then continue with what you can do.
+- Close the task with the `specctx-done` skill.