docs(openspec): seed OpenSpec with current-state capability specs#77
Merged
johannesjo merged 2 commits intomainfrom Apr 20, 2026
Merged
docs(openspec): seed OpenSpec with current-state capability specs#77johannesjo merged 2 commits intomainfrom
johannesjo merged 2 commits intomainfrom
Conversation
Introduce OpenSpec by scaffolding `openspec/` via the canonical `openspec init` layout and documenting two already-shipped capabilities as living specs (not in-flight change proposals): - openspec/config.yaml — schema + project context (stack, layout, conventions) consumed by the OpenSpec CLI and agent skills. - openspec/specs/remote-access/spec.md — HTTP+WebSocket server, token auth, agent list broadcasting, streaming, ring-buffer scrollback, mobile SPA. - openspec/specs/steps-tracking/spec.md — opt-in prompt injection, `.claude/steps.json` watcher with debounce, IPC contract, panel rendering, git exclude for linked worktrees. Specs use the canonical Requirement/Scenario (WHEN/THEN) format and pass `openspec validate --strict`. `openspec/changes/` is intentionally empty — reserved for genuinely new proposals. Editor integrations under `.claude/` are regenerated locally via `npx @fission-ai/openspec@latest init --tools claude` since `.claude/` is gitignored.
Review findings folded in:
- Fix 3 factual discrepancies in steps-tracking:
* `awaiting_review` pause is a prompt-contract the injected instruction
asks the agent to follow, not a system-enforced behavior. Fold it into
the prompt-injection scenario and drop the standalone scenario.
* Timestamps without a timezone are tolerated by the renderer for
display; the app itself already emits UTC-suffixed timestamps. Reword
accordingly.
* Remove the "auto-scroll on new step" scenario — not implemented.
- Strip library / internal-API identifiers from normative text in
remote-access so the spec stays durable when implementation details
change: `http.createServer`, `ws WebSocketServer`, `crypto.randomBytes`,
`crypto.timingSafeEqual`, `verifyClient`, `maxPayload`, and the exact
`Cache-Control` string. Observable contract (0.0.0.0, 4001, 429, 401,
byte/timeout budgets) is retained.
- Tighten the desktop UI counter scenario (was vague "connection churn").
- Trim both Purpose sections to WHY only; HOW belongs in requirements.
- Reword the steps-file "append-only" requirement as an app guarantee
rather than an agent obligation (the app can't enforce agent behavior
at runtime).
- Trim `openspec/config.yaml` context to avoid duplicating `CLAUDE.md`.
Add a third spec-authoring rule (describe observable behavior, not
library names).
- Add a `## Specs` section to `CLAUDE.md` pointing agents at
`openspec/specs/` and the `/opsx:propose` flow.
`openspec validate --all --strict` still passes (2/2).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduce OpenSpec by scaffolding
openspec/via the canonicalopenspec initlayout and documenting two already-shipped capabilities asliving specs (not in-flight change proposals):
conventions) consumed by the OpenSpec CLI and agent skills.
agent list broadcasting, streaming, ring-buffer scrollback, mobile SPA.
.claude/steps.jsonwatcher with debounce, IPC contract, panel rendering,git exclude for linked worktrees.
Specs use the canonical Requirement/Scenario (WHEN/THEN) format and pass
openspec validate --strict.openspec/changes/is intentionally empty —reserved for genuinely new proposals. Editor integrations under
.claude/are regenerated locally via
npx @fission-ai/openspec@latest init --tools claudesince.claude/is gitignored.