@blockdance-lab/blockspec

Language / 语言: English · 中文

BlockSpec — A spec-driven AI workflow tool for the Block team, based on OpenSpec.

Install BlockSpec from npm

npm install -g @blockdance-lab/blockspec   # global CLI (command: blockspec)
npm install @blockdance-lab/blockspec      # add as a project dependency

Run blockspec init in your repo, then use the same /opsx:… slash commands as upstream OpenSpec. The init summary now highlights both Fast Lane entries:

Fast lane for small changes: /opsx:do "your request"
Terminal helper: blockspec quick "your request"
Start your first change: /opsx:propose "your idea"

The rest of this README still documents the OpenSpec-style workflow and CLI unless noted here.

TDD workflow (tdd schema)

Start a change with /opsx:tdd "<name>" (or blockspec new change "<name>" --schema tdd). Artifact order: proposal → specs → test-plan → design → tasks, then /opsx:apply. The tdd schema adds a test-plan phase before design so verification strategy is explicit.

Preferring human / visual work over automated tests

BlockSpec does not force everything through unit tests. The pipeline is controlled by how you (or the AI) write three layers:

• Specs (specs/**/spec.md) — For behavior you cannot express as a single deterministic assertion (visual polish, motion, device-specific behavior), put <!-- manual-verify --> immediately after the scenario heading. That marks the scenario as not a default auto-test target.

• test-plan.md — Each scenario becomes a verification item. Classify as auto-test only when you will actually write and maintain an automated test with Setup / Action / Assert. Use visual when “looks right” is the pass condition (browser, Storybook, screenshots). Use manual when a human must follow steps on a device or environment. When in doubt and you do not want automation, bias toward visual or manual instead of auto-test.

• tasks.md — Task labels drive apply behavior. [RED] / [GREEN] / [REFACTOR] mean strict test-first discipline for that slice of work. [UI] is for styling and layout without an automated assertion. [VERIFY] is an explicit human checkpoint (describe what to check). To run a change mostly by human review, tell the model clearly—for example: “Put all scenarios under manual-verify where needed; make test-plan mostly visual/manual; use [UI] and [VERIFY] tasks and avoid [RED]/[GREEN] except for core logic.” Only [RED]/[GREEN] tasks require failing tests before implementation; [UI] and [VERIFY] do not.

Default workflow (lighter)

/opsx:propose "<name>" — proposal → specs → design → tasks (no required test-plan). Same slash command works under OpenSpec or after blockspec init.

Fast Lane quick mode

Use /opsx:do "<small request>" when the change is low-risk and you want the assistant to create a minimal record and implement immediately. It creates quick.md and tasks.md by default, does not require proposal review, and does not run tests unless you add --verify or the assistant decides a check is necessary.

Terminal helper:

blockspec quick "update pricing CTA copy"          # create quick.md/tasks.md, then hand off to /opsx:do
blockspec quick "update pricing CTA copy" --verify # ask the agent to run one lightweight relevant check
blockspec quick "fix typo" --no-record             # no change directory, direct handoff

Quick mode sits beside the proposal/apply flow; it does not replace it. It should escalate to /opsx:propose for auth, payments, database migrations, permissions, public APIs, broad refactors, unclear requirements, or anything that needs formal review. Recorded quick changes can still be archived; if they have no specs/ delta files, archive keeps them as history without updating main specs.

→ More on slash workflows: docs/opsx.md

The most loved spec framework.

Our philosophy:

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.

Teams

Using OpenSpec in a team? Email here for access to our Slack channel.

See it in action

Fast Lane (quick): minimal record → implement → summary

You: /opsx:do "rename pricing CTA to Start free trial"
AI:  Created openspec/changes/quick-20260428-pricing-cta/
     ✓ quick.md — request, mode, summary placeholders
     ✓ tasks.md — 3-5 lightweight implementation tasks
     ✓ Updated pricing CTA copy
     No tests run by default quick mode.

You: /opsx:archive quick-20260428-pricing-cta
AI:  Archived as a history-only quick record. No main specs updated.

TDD workflow (tdd): proposal → specs → test-plan → design → tasks

You: /opsx:tdd add-payment-validation
AI:  Created openspec/changes/add-payment-validation/
     ✓ proposal.md  — why we're doing this, what's changing
     ✓ specs/       — GIVEN/WHEN/THEN scenarios, manual-verify markers
     ✓ test-plan.md — auto-test / visual / manual classification
     ✓ design.md    — technical approach + test strategy
     ✓ tasks.md     — [RED]/[GREEN]/[REFACTOR]/[UI]/[VERIFY] labeled tasks
     Ready for test-driven implementation!

You: /opsx:apply
AI:  [RED]    Write failing test: validateCard returns error on invalid number
     [GREEN]  Implement validateCard
     [RED]    Write failing test: validateCard accepts Visa/Mastercard
     [GREEN]  Handle card type check
     [REFACTOR] Extract card type constants
     [UI]     Style error message component  ← visual inspection
     [VERIFY] Manual: test on real device   ← manual checkpoint
     All tasks complete!

Default workflow (spec-driven): proposal → specs → design → tasks

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.

OpenSpec Dashboard

Quick Start

Requires Node.js 20.19.0 or higher.

Install BlockSpec globally:

npm install -g @blockdance-lab/blockspec@latest

Then navigate to your project directory and initialize:

cd your-project
blockspec init

After init, use /opsx:do <small-request> for Fast Lane implementation, or prepare the same path from the terminal with blockspec quick "<small-request>". Use /opsx:tdd <what-you-want-to-build> for test-driven development, or /opsx:propose <what-you-want-to-build> for the default planned workflow.

If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:sync, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.

[!NOTE] Not sure if your tool is supported? View the full list – we support 25+ tools and growing.

Also works with pnpm, yarn, bun, and nix. See installation options.

Docs

→ Getting Started: first steps
→ Workflows: combos and patterns
→ Commands: slash commands & skills
→ CLI: terminal reference
→ Supported Tools: tool integrations & install paths
→ Concepts: how it all fits
→ Multi-Language: multi-language support
→ Customization: make it yours

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 20+ AI assistants via slash commands
• Choose your discipline — tdd for test-first engineering (test-plan + task labels), spec-driven for lightweight iteration

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 Opus 4.5 and GPT 5.2 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 dev or pnpm 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: export OPENSPEC_TELEMETRY=0 or export DO_NOT_TRACK=1

Maintainers & Advisors

See MAINTAINERS.md for the list of core maintainers and advisors who help guide the project.

License

MIT