Clay GoodandClaude Opus 4.8
9ae75c86ef
* fix(archive): stop non-TTY confirm prompts from writing ANSI escapes to stdout `openspec archive` asks up to three yes/no questions through @inquirer's `confirm`, which renders by writing ANSI cursor-movement escape sequences — and emits them even when stdout is not a TTY. When archive runs with its output captured to a file or pipe (an agent's background task, CI), those escapes are noise, and in some non-TTY hosts the render loop never settles and repeats `ESC[NNG` moves until the disk fills (reporter hit 19.8 GB). Add `confirmPrompt` in interactive.ts: a real terminal (stdin AND stdout TTY) still gets @inquirer's rich prompt; every other case reads one plain line via node:readline with `terminal:false`, emitting no escapes. Parsing mirrors @inquirer/confirm exactly (prefix match on y/yes and n/no, else the default), and an unreadable stdin rejects with an ExitPromptError-shaped error so the existing #1479 "rerun with --yes" guidance is unchanged. archive's confirmOrBlock now calls confirmPrompt. Closes #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(interactive): cover Windows CRLF and drained-stdin paths; doc note Adds two regression tests surfaced by adversarial review of the #1526 fix: - Windows CRLF piped input (`y\r\n`) parses as a clean yes with no ANSI — the reporter's platform, previously untested (all inputs used `\n`). - A second prompt after stdin was already drained blocks with an ExitPromptError instead of hanging, exercising the readableEnded guard. Also documents in troubleshooting.md that a redirected/agent archive run that pipes an answer no longer writes terminal escape codes into the capture. Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(interactive): align non-interactive classification and handle readline errors Addresses two review findings on the #1526 confirm-prompt fix: - confirmPrompt drops to the plain reader whenever either stream is not a TTY, but isNonInteractivePromptError only checked stdin. A stdin-TTY / stdout-redirected run that hit EOF leaked the raw ExitPromptError instead of the #1479 "rerun with --yes" guidance. Classification now also counts a redirected stdout, matching how the prompt mode is chosen. (isInteractive, used broadly elsewhere, is left untouched.) - readYesNo never listened for the readline/input 'error' event, so a stdin error would hang the promise (and go unhandled). It now settles with the underlying fault, guarded so the promise resolves or rejects exactly once. Tests: TTY-stdin/redirected-stdout EOF is classified non-interactive; an erroring input stream rejects instead of hanging; the archive usable-terminal test now models a full terminal (both streams TTY). Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(archive): gate the change picker on a TTY and tidy the reader Follow-ups from a second review round: - selectChange (the no-argument change picker) called @inquirer's `select` unconditionally. `select` writes ANSI escapes to stdout even when redirected — the same #1526 mechanism the confirm prompts were fixed for — so `openspec archive > log.txt` with no change name still spewed cursor moves into the capture before blocking. Refuse before rendering when either stream is not a TTY, with the same "pass a change name / --yes" guidance the caught ExitPromptError already gives. A new test asserts the picker is never reached in a non-terminal run. - readYesNo now removes its input-stream 'error' listener on every settle path (it lives on the long-lived process.stdin) and closes the readline interface on error too, so nothing accumulates across archive's sequential prompts. - troubleshooting.md now notes the picker also stays clean. Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(changeset): add patch changeset for the archive non-TTY fix (#1526) User-facing patch note for the archive ANSI/disk-fill fix. Also drops an unnecessary optional-chain on the non-nullable readline handle in readYesNo (the listener is only attached after the interface exists). Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The most loved spec framework.
→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises
Tip
New workflow now available! We've rebuilt OpenSpec with a new artifact-guided workflow.
Run
/opsx:propose "your idea"to get started. → Learn more here
Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.
See it in action
You: /opsx:explore
AI: What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI: Let me look at your styling setup...
Cleanest path here: CSS variables + a small theme context,
with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!
You: /opsx:apply
AI: Implementing tasks...
✓ 1.1 Add theme context provider
✓ 1.2 Create toggle component
✓ 2.1 Add CSS variables
✓ 2.2 Wire up localStorage
All tasks complete!
You: /opsx:archive
AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
Specs updated. Ready for the next feature.
What do the specs actually look like?
Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the specs/ folder created above:
## ADDED Requirements
### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.
#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice
Your AI writes these; you review the plan before any code is written.
OpenSpec is built with OpenSpec — browse this repo's live specs and in-flight changes for real examples at scale.
OpenSpec Dashboard
Why teams adopt OpenSpec
Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.
Stores are the answer — planning in a repo of its own. The same openspec/ shape you already know (specs and changes), shared by git push like anything else. One source of truth your whole team and every coding agent can read, across every repo.
- Cross-repo features — one change, one plan, even when the code lands in three repos.
- Shared requirements — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
- Plan before code — capture the plan in the store now; the code repos catch up later.
Stores are in beta. Start with the Stores User Guide.
Quick Start
Requires Node.js 20.19.0 or higher.
Install OpenSpec globally:
npm install -g @fission-ai/openspec@latest
Then navigate to your project directory and initialize:
cd your-project
openspec init
Want your AI to do it? Paste the setup prompt into your coding assistant — it installs the CLI, runs
openspec init, and verifies the result.
Now talk to your AI:
- Not sure what to build yet? Start with
/opsx:explore, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. (Explore guide) - Already know what you want? Go straight to
/opsx:propose <what-you-want-to-build>.
Both are in the default profile. If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.
/opsx:propose is the canonical name; your tool may spell it /opsx-propose (Cursor, GitHub Copilot), @opsx-propose (Amazon Q) or $openspec-propose (Codex). openspec init prints the right form for the tools you picked — see How To Invoke.
Note
Not sure if your tool is supported? View the full list – we support 30+ tools and growing.
Also works with pnpm, yarn, bun, and nix. See installation options.
Docs
Start here: the Documentation Home maps everything. New to OpenSpec? Read Getting Started, then How Commands Work (where you actually type /opsx:propose).
→ Getting Started: first steps
→ Explore First: think it through with /opsx:explore before you commit
→ How Commands Work: where slash commands run vs the CLI
→ Core Concepts at a Glance: the whole mental model, one page
→ Examples & Recipes: real changes, start to finish
→ Workflows: combos and patterns
→ Existing Projects: adopt OpenSpec on a brownfield codebase
→ Editing a Change: update artifacts, go back, reconcile manual edits
→ Commands: slash commands & skills
→ CLI: terminal reference
→ Stores: plan in a separate repo, shared across your team (beta)
→ Supported Tools: tool integrations & install paths
→ Concepts: how it all fits
→ Multi-Language: multi-language support
→ Customization: make it yours
→ FAQ · Troubleshooting · Glossary: quick help
Community schemas
Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how github/spec-kit's community extension catalog handles tool integrations.
→ Browse the catalog in the customization docs.
Why OpenSpec?
AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.
- Agree before you build — human and AI align on specs before code gets written
- Stay organized — each change gets its own folder with proposal, specs, design, and tasks
- Work fluidly — update any artifact anytime, no rigid phase gates
- Use your tools — works with 30+ AI assistants via slash commands
How we compare
vs. Spec Kit (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.
vs. Kiro (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.
vs. nothing — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.
Updating OpenSpec
Upgrade the package
npm install -g @fission-ai/openspec@latest
Refresh agent instructions
Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
openspec update
Usage Notes
Model selection: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.
Context hygiene: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
Contributing
Small fixes — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
Larger changes — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
AI-generated code is welcome — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
Development
- Install dependencies:
pnpm install - Build:
pnpm run build - Test:
pnpm test - Develop CLI locally:
pnpm run devorpnpm run dev:cli - Conventional commits (one-line):
type(scope): subject
Other
Telemetry
OpenSpec collects anonymous usage stats.
We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
Opt-out (any one is enough):
openspec config set telemetry.enabled false(global config; unset means on)export OPENSPEC_TELEMETRY=0orexport DO_NOT_TRACK=1(env overrides config)
Maintainers & Advisors
See MAINTAINERS.md for the list of core maintainers and advisors who help guide the project.
License
MIT