specweave README

The project's README from github.com/anton-abyzov/specweave. As one markdown file: README.md.

SpecWeave

Change agents. Keep the thread.
Plan work as small specs, hand it between Claude, Codex, Grok and any other tool in two words, and close it with evidence.

npm 11 skills MIT Discord


Install

npm install -g specweave        # Node.js 20.12.0+
cd your-project
specweave init .

init writes AGENTS.md (read by Codex, Grok, Cursor, Gemini and Copilot), a two-line CLAUDE.md that imports it, and the skills for Claude Code and Codex. Nothing else runs in the background.

Out of tokens? Say "hand off"

you (in Claude, account 1):   hand off
you (in Codex, or account 2): pick up

That is the whole handoff. "Hand off" runs specweave handoff: it releases your task claims, records why you stopped, and pushes your branch plus a snapshot of your uncommitted edits. "Pick up" runs specweave pickup in any other tool, account, machine or cloud session (a Claude Code Projects thread, a Codex cloud task): it brings that work into the checkout and prints the next task with its acceptance criteria. Nothing to copy, no paths to paste.

Running out mid-task? specweave auto-handoff on, once per machine, makes it automatic: when a session reaches 90% of your plan's 5-hour or weekly limit, it hands off by itself and tells you to say "pick up" elsewhere. Claude Code reads the limit through its status line (your own status line keeps working) and Codex through a Stop hook. Under the threshold it costs no tokens. --at 85 changes the threshold and off undoes every change.

specweave report writes an HTML timeline of who did what on an increment (tools, sessions, handoffs, pickups, test evidence), straight from the ledger.

The loop

# Say or run What happens
1 "pick up" · specweave pickup The open increment, the next task with its acceptance criteria, claims held by others, branch state, notes and project memory, in one read.
2 /sw:increment · specweave create-increment "<title>" One spec.md: Problem, Scope, Acceptance Criteria, Approach and the Tasks.
3 /sw:do · specweave task claim T-01 → task done T-01 --run "<test>" Work a task. done refuses a failing test and stores the evidence in the ledger.
4 specweave verify · /sw:review Runs your test, lint and build; a fresh-context review cites path:line.
5 /sw:done · specweave complete <id> Closes on a green verify. Acceptance criteria are met when their tasks are done; nobody ticks boxes.
6 "hand off" · specweave handoff Stop anywhere; the next tool picks up.

An increment is one folder, .specweave/increments/NNNN-slug/, with one file you read (spec.md) and one the CLI appends to (ledger.jsonl). Increments from 2.x with a tasks.md keep working unchanged.

Works the way Claude Code Projects work

Claude Code Projects SpecWeave
A thread: one session, one branch, one PR One increment
The thread's checklist The ## Tasks of that increment's spec.md, state in ledger.jsonl
Project memory (MEMORY.md + one file per fact) .specweave/memory/, same format, committed, so every tool and account sees it
Threads passing notes specweave note "<text>" on another increment

Project memory in claude.ai stays with one account. .specweave/memory/ travels with the code, so Codex, Grok and a second Claude subscription start from the same decisions.

The eleven skills

The CLI is the product and runs in any tool or in CI. The skills expose it to coding agents: /sw:<name> in Claude Code, sw-<name> in .claude/skills/ (for Projects threads, where plugins do not load) and .agents/skills/ (Codex, Grok).

Skill Use it for
increment Plan the work as one spec.md.
do Claim a task, implement it, close it with evidence.
auto The same loop, unattended, until the tasks run out.
team A worktree per agent, claims arbitrated by the ledger.
review Fresh-context adversarial review; findings cite path:line.
done Verify, review check, specweave complete.
handoff "Hand off" and "pick up".
sync GitHub, Jira and Azure DevOps, only when you run it.
project Shared goals, artifacts and briefs across tools.
brainstorm Framed alternatives, ending in a pick.
jev Closed-set decisions in about 250 ms via Jev.

Upgrade to 3.0

npm i -g specweave@3
specweave update

specweave update rewrites AGENTS.md into the lean form, turns CLAUDE.md into an import of it, keeps your own sections, and backs up the old files under .specweave/backups/. Existing increments need no migration. The 3.0.0 changelog lists what changed and what was removed. To have sessions hand off by themselves near the usage limit, run specweave auto-handoff on once.


Built With SpecWeave

Examples from the maintainer's portfolio. These are usage examples, not controlled productivity measurements.

App Platform What It Does
EasyChamp Web (GCP) Enterprise sports league management. 20+ microservices, ML video analytics. 4 years in production.
SketchMate App Store AI drawing game — multi-model evaluation judges player art semantically.
Lulla App Store Baby sleep app with Apple Watch. ML cry classification (tired/hungry/pain).
Football 2026 App Store + Web World Cup 2026 companion. AI travel planner, live tickets, team stats.
SkillUp Football App Store Coaches monetize training via Stripe. Instagram-like feed, scheduling.
BizZone App Store Student & business events with AI-powered news generation.
EduFeed Web NotebookLM meets Zoom. Upload videos, get quizzes, flashcards, live rooms.
JobWeave Web AI-powered job search. Smart matching, resume optimization.
SpecWeave npm The framework itself. 600+ increments, 538+ releases.
SpecWeave Umbrella GitHub Multi-repo orchestration workspace for all repositories.
vskill npm Package manager for AI skills. Security scanning, 49 platforms.
verified-skill.com Web Skill marketplace & studio. 105K+ verified skills, eval system.

Browse increments on GitHub — full transparency.


How It Compares

Capability Cursor Rules Copilot Instructions Windsurf Cline Vibe Coding SpecWeave
Structured specs (Problem, ACs, Approach) — — — — — Yes
One closure gate you can actually see (verify.json) — — — — — Yes
Autonomous execution (hours, unattended) — — — — — Yes
Multi-agent teams (parallel, contract-first) — — — — — Yes
External sync (GitHub / JIRA / ADO) — — — — — Yes
Append-only ledger (claims, evidence, no lost work) — — — — — Yes
LSP code intelligence (198x faster) — — — — — Yes
Cross-tool handoff (any vendor, any subscription) — — — — — Yes

Cursor tells AI "use Tailwind." SpecWeave tells AI "build a checkout flow against these five acceptance criteria, prove the tests pass, review the diff, then close."


Key Features

Spec-First Planning — Every feature starts as one spec.md: Problem, Scope, ACs, Approach and Tasks.

Evidence, not vibes — specweave task done --run "<test>" refuses a failing command and stores the exit code and output tail in the ledger.

Multi-agent, any vendor — A worktree per agent, claims through ledger.jsonl, one closure. Coordination happens only through committed files.

┌──────────────────┬──────────────────┬──────────────────┐
│  Agent 1 (auth)  │ Agent 2 (payments)│ Agent 3 (catalog)│
│  T-01..T-04      │  T-05..T-08      │  T-09..T-12      │
│  ████████░░ 80%  │  ██████░░░░ 60%  │  ████░░░░░░ 40%  │
└──────────────────┴──────────────────┴──────────────────┘

LSP Code Intelligence — 198x faster than grep, 0 false positives. Semantic references, definitions, and types.

11 skills, one source — the same skills for Claude Code, Codex and Grok; see The eleven skills.

External Sync — specweave sync push|pull|status|setup. GitHub is first-class; Jira and Azure DevOps are opt-in. Nothing calls a tracker unless you run sync.

Enterprise Ready — Compliance audit trails. Brownfield analysis. Multi-repo workspaces.

Dashboard — specweave dashboard shows intents, increments and evidence from local files, with no model calls.


Skills Ecosystem

SpecWeave skills are published and verified at verified-skill.com. The vskill package manager provides:

npx vskill install remotion-best-practices    # Install from registry
npx vskill eval run my-skill                  # Run eval suite

Documentation

spec-weave.com — SpecWeave 3.0 · handoff · commands · skills · configuration

Contributing

Inside this repo dependency install scripts are disabled (.npmrc): run npm ci, then npm run setup (rebuilds the allowlisted native deps), and npm run security:scan before pushing — see SECURITY.md.

Community

Discord · YouTube · GitHub Issues

License

MIT — github.com/anton-abyzov/specweave

specweave (anton-abyzov/specweave)

Searching Database…

166 ·GitHub
Specweave
Что это?SpecWeave — это CLI для рабочего процесса «спецификация прежде всего» при разработке с ИИ: вы описываете функциональность, он генерирует spec.md с проблемой/объёмом/критериями приёмки/задачами, позволяет ИИ-агентам выполнять задачи с подтверждением пройденными тестами и передаёт работу между разными агентами (Claude Code, Codex, Cursor, Copilot, Grok), опционально синхронизируя прогресс с GitHub, Jira или Azure DevOps.
Это CLI-инструмент или фреймворк для кодинга?Это прежде всего npm CLI (бинарник `specweave`) плюс набор из 11 «навыков», которые выставляют его команды как слэш-команды (/sw:) внутри Claude Code, Codex, Cursor и других агентов.
Как завести его в проекте?Выполните `specweave init`: он создаст AGENTS.md, который читают Codex/Grok/Cursor/Gemini/Copilot, двухстрочный CLAUDE.md, импортирующий его, и установит навыки для Claude Code и Codex.
С какими агентами для кодинга он реально работает?Он сделан для работы в Claude Code, Codex, Grok, Cursor, Copilot, Windsurf, Cline и Gemini, а сопутствующий менеджер пакетов vskill может развертывать навыки в общей сложности на 49 платформах агентов.
Что будет, если у меня кончатся токены посреди задачи?Команда 'hand off' (или `specweave handoff`) освобождает ваши заявки на задачи и отправляет снапшот незакоммиченных правок; `specweave auto-handoff on` может делать это автоматически, как только сессия достигнет 90% от 5-часового или недельного лимита вашего плана, что определяется по строке состояния Claude Code или Stop-хуку Codex.
Для кого это создано?Для разработчиков и команд, использующих несколько ИИ-агентов для кодинга и нуждающихся в общем проверяемом плане работ, который переживает смену инструментов, аккаунтов или машин, включая многагентные/параллельные команды.
Он работает на любой ОС или только внутри конкретных редакторов?Это CLI на Node.js/npm, поэтому он кроссплатформенный — Windows, macOS и Linux, — и интегрируется с тем агентом/редактором для кодинга, которым вы уже пользуетесь.
Отправляет ли дашборд или синхронизация мои данные куда-то?Локальный дашборд читает только локальные файлы и не делает обращений к моделям, а внешняя синхронизация с GitHub/Jira/Azure DevOps происходит лишь когда вы явно выполняете команду синхронизации.
Чем SpecWeave отличается от простого использования Cursor rules или инструкций Copilot?Эти инструменты лишь подмешивают указания по стилю вроде 'use Tailwind'; SpecWeave структурирует работу как спецификации с явными критериями приёмки, запускает видимый шлюз завершения (verify.json), поддерживает автономную многочасовую работу, многагентные команды, внешнюю синхронизацию и append-only журнал доказательств — чего обычные файлы правил не дают.
Что такое «increment» в SpecWeave?Increment — это одна папка (.specweave/increments/NNNN-slug/) с единственным spec.md, содержащим Problem, Scope, Acceptance Criteria, Approach и Tasks, плюс ledger.jsonl, в который CLI дописывает записи по ходу работы.
Для чего нужны 11 навыков?Они оборачивают команды CLI (increment, do, auto, team, review, done, handoff, sync, project, brainstorm, jev) в слэш-команды внутри Claude Code, Codex и других агентов, охватывая планирование, выполнение задач, ревью, передачу работы и внешнюю синхронизацию.
Что такое vskill?vskill — сопутствующий менеджер пакетов SpecWeave для ИИ-навыков: он занимается проверкой безопасности (52 шаблона атак, закрепление SHA-256), устанавливает навыки на 49 платформ агентов и поддерживает оценку и бенчмаркинг навыков через свой Skill Studio.
What are similar projects?openrig, operator-memory, agent-router, emdash, cc-wf-studio, marketingskills, 1code, pstack
Which topics is it in?jira, spec-driven-development, ai-coding-agent, coding-agents, github, workflow-automation, orchestration, cli-tool, skills, testing, multi-agent, documentation
Creator
anton-abyzov
Size
629.4 MB
Stars
166
Updated
CommitOct 20Releasev3.1.4Oct 20
Age
11mo
Commits · 90 Days