specweave 2.3.0 → 3.0.0

package/plugins/specweave/skills/sync/SKILL.md

@@ -1,63 +1,52 @@
 ---
-description: One sync surface for GitHub, Jira and Azure DevOps: push progress, pull or import issues, check health, run setup. Use when saying "sync", "push to GitHub", or "import issues".
-version: 2.0.0
+description: Sync SpecWeave increments with GitHub, Jira or Azure DevOps - push progress, pull or import issues, check token and health, run setup. Use for "sync", "push to GitHub", "import issues".
 argument-hint: "push|pull|status|setup [increment-id]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-sync/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# sw:sync — external tracker sync
+# sw-sync: external tracker sync
 
-Everything goes through the CLI. Never call `gh`, `curl`, or a provider REST API
-directly: the CLI owns token resolution, the rate budget, duplicate detection and
-the bidirectional links.
+Sync is opt-in and explicit. Starting, pausing or completing an increment never calls a
+tracker; only `specweave sync push` does (plus close-on-complete, when configured). Go
+through the CLI, never `gh`, `curl` or a provider API directly: the CLI owns token
+resolution, the rate budget, duplicate detection and the links in both directions.
 
 ## Commands
 
 | Intent | Command |
 |---|---|
-| Push local progress to issues | `specweave sync push [increment-id]` |
-| Preview a push | `specweave sync push <id> --dry-run` |
-| Push to one provider | `specweave sync push <id> --provider github` |
-| Fix stale/duplicate milestones first | `specweave sync push <id> --reconcile` |
+| Push progress to issues | `specweave sync push [increment-id]` |
+| Preview a push | `specweave sync push 0042 --dry-run` |
+| One provider only | `specweave sync push 0042 --provider github` |
 | Report external changes | `specweave sync pull [--since 7]` |
 | Import issues as increments | `specweave sync pull --create-increments` |
-| Tokens, health, retry queue, gaps | `specweave sync status [--json]` |
+| Token, account, health, retry queue | `specweave sync status [--json]` |
 | Connect a provider | `specweave sync setup [--provider github]` |
-| Validate an existing config | `specweave sync setup --validate` |
+| Check an existing setup | `specweave sync setup --validate` |
 
-`sync push` runs tasks.md → spec.md ACs → living docs → provider write, then
-drains the retry queue through the same entry point. Exit code of
-`sync status` is 1 when anything needs attention; `--json` prints one parsable
-report (`providers`, `github`, `health`, `resilience`, `gaps`, `hasIssues`).
-
-Not sync: `specweave doctor --fix-status` repairs metadata.json ↔ spec.md status
-desyncs, and `specweave sync-living-docs` regenerates internal living docs.
+`sync status` exits 1 when anything needs attention.
 
 ## Providers
 
-Read the provider from `.specweave/config.json` (`sync.github` / `sync.profiles`);
-never guess. GitHub is the first-class path. **Jira and Azure DevOps are
-community-maintained**: push and close work, nothing else is guaranteed — say so
-before promising Jira/ADO behaviour.
-
-Tokens resolve in one documented order: `.specweave/config.json` → `process.env`
-(`GITHUB_TOKEN`, then `GH_TOKEN`) → project `.env` → `gh auth token`.
-`sync status` prints which layer and which account won. A 404 on write means the
-token's account has no write access to `owner/repo` — fix the token, do not retry.
-
-Concept mapping tables: `plugins/specweave/reference/{github,jira,ado}/*-specweave-mapping.md`.
+Read the provider from `.specweave/config.json`; never guess. GitHub is first-class.
+Jira and Azure DevOps are supported and opt-in: push and close are covered, say so
+before promising more.
 
-## Bidirectional links (required both ways)
+Tokens resolve in one order: config, then `GITHUB_TOKEN` / `GH_TOKEN`, then the project
+`.env`, then `gh auth token`. `sync status` prints which one won and for which account.
+A 404 on write means that account cannot write to the repository: fix the token, do not
+retry. Check a token exists without printing it.
 
-- Local → external: the issue key lives in `metadata.json` under `externalLinks`.
-- External → local: the issue body carries the increment id and the commit sha.
+## Rules
 
-If either side is missing after a push, the link is broken — re-run
-`specweave sync push <id> --force` rather than editing the issue by hand.
+1. `--dry-run` first when an increment has never synced.
+2. Never edit the issue links in `metadata.json` by hand; a broken link is fixed with
+   `specweave sync push 0042 --force`.
+3. Report `sync status` output as it is when it shows problems; do not paraphrase token
+   or permission errors.
 
-## Rules
+## Manual path (no CLI)
 
-1. Push after tasks change, not on every edit.
-2. Never edit `externalLinks` by hand.
-3. `--dry-run` first when the increment has never synced.
-4. Report `sync status` output verbatim when it reports issues; do not paraphrase
-   token or permission errors.
+There is no manual sync. Update the issue yourself and put its URL in spec.md Problem so
+the next agent can find it.

package/plugins/specweave/skills/team/SKILL.md

@@ -1,89 +1,70 @@
 ---
-description: Run one increment with several agents in parallel - a worktree each, claims through the ledger, one closure. Use when the work has 3+ disjoint lanes, or when saying "team" or "parallel agents".
-version: 2.0.0
+description: Run one SpecWeave increment with several agents in parallel - any tool or account, a worktree each, claims through the ledger, one close. Use for "team", "parallel agents", 3+ disjoint lanes.
+argument-hint: "[increment-id]"
+version: 3.0.0
 ---
+<!-- Generated from skills/sw-team/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
 
-# Team
+# sw-team: several agents, one increment
 
-Run one increment with N agents in parallel — **any vendor, any subscription**
-(Claude Code, Codex, OpenCode, Cursor, Gemini, a human). Coordination happens
-only through committed files: `tasks.md` (definitions), `ledger.jsonl`
-(append-only state), `handoff.md`. No message bus, no shared memory; Claude
-Code's TeamCreate/Task tools are accelerators, never requirements.
+Agents can be Claude Code, Codex, Cursor, Grok, another account or a person. They
+coordinate only through committed files: spec.md (tasks), `ledger.jsonl` (claims and
+evidence) and handoffs. No message bus is needed; your tool's subagents or agent teams
+are an accelerator, never a requirement.
 
-## You are the orchestrator
+## You are the lead
 
-- You plan, split, spawn, watch, merge, close. You do **not** implement.
-- Fan out when domains ≥ 3 or tasks ≥ 15 or the user asked for parallel work; otherwise `sw:do` directly.
-- One increment, one `tasks.md`, one ledger. Do not create per-agent increments.
+You split, start, watch, merge and close. You do not implement. Fan out only with three
+or more disjoint lanes or 15+ tasks; otherwise use sw-do.
 
-## The 5 rules every agent gets (paste verbatim into each agent prompt)
+## 1. Split
 
-1. **One worktree per agent**: `git worktree add ../<id>-<agent> -b inc/<id>-<agent>` (Claude: `claude --worktree <id>-<agent>`). Branch name contains the increment id. Set `SPECWEAVE_AGENT=<agent>` (else id = `<tool>@<host>`).
-2. **Claim before edit**: `specweave task next <id>` → `specweave task claim T-NN <id>`. Edit only that task's `Files`. Need another file → claim its task or add a task.
-3. **Append only**: never edit or delete ledger lines, never edit another task's state line. On a ledger merge conflict keep every line from both sides (`.gitattributes` has `**/ledger.jsonl merge=union`).
-4. **Done needs evidence**: commit with the id in the subject, then `specweave task done T-NN <id> --run "<Test>"` (exit 0 required). Paste the output in your reply.
-5. **When stopping**: `specweave task release --all-mine` then `specweave handoff <id>`.
+1. `Files` is the ownership unit. Two tasks that touch one file cannot run in parallel:
+   merge them, or put `**Dependencies**: T-01` under the later one. Shared contracts
+   (types, schema, migrations) go in an early task the others depend on.
+2. Group tasks into lanes with disjoint `Files`: 2 to 5 lanes, one agent each.
+3. `specweave task list 0042` shows every task open. Commit spec.md.
 
-No CLI on that machine? The agent appends the JSON line itself:
-`{"t":"T-NN","e":"claim|done|release|block|skip","by":"<agent>","at":"<ISO UTC>","evidence":"<sha + test>","note":"…"}`.
+## 2. Start each agent
 
-## Phase 1 — Split (before spawning)
-
-1. Read `spec.md` once. Confirm `tasks.md` is in 2.0 form: `### T-NN Title` + `- AC: … | Files: … | Test: …`. If not, rewrite it (this is the only time tasks.md changes structure).
-2. **Files are the ownership unit.** Two tasks that touch the same file cannot run in parallel: merge them into one task or add `**Dependencies**: T-NN`. Shared contracts (types, API schemas, migrations) go into an early task that everything else depends on.
-3. Group tasks into lanes (backend / frontend / db / tests / docs …) so each lane's Files are disjoint. Lanes = agents. 2–5 agents; more rarely helps.
-4. Run `specweave task list <id>` — it must show every task `open`. Commit `tasks.md`.
-
-## Phase 2 — Spawn
-
-For each lane spawn one agent (Claude: `Task({ subagent_type: "general-purpose", … })` or a TeamCreate teammate; other vendors: a terminal in the lane's worktree with the prompt below). Prompt template:
+One worktree and branch per agent:
+`git worktree add ../0042-api -b inc/0042-api`. Then give that agent (a subagent, a
+terminal in the worktree, another tool or account) this brief:
 
-```
-You are agent <agent> on increment <id> (<title>). Worktree: <path>. Branch inc/<id>-<agent>.
-Your lane: <lane name>. Tasks you may claim: T-NN, T-MM (others belong to other lanes).
-Rules: <the 5 rules above>.
-Loop: specweave task next <id> → claim → implement inside Files → commit "<id>: …" → task done --run.
-Contract: <shared types / API / schema the lane must respect>.
-When your tasks are done or you are blocked: task release --all-mine, specweave handoff <id>, then reply with:
-  DONE: T-NN (sha, test output tail) | BLOCKED: T-MM (reason) | HANDOFF: <handoff.md path>
+```text
+You are agent "api" on increment 0042 in ../0042-api (branch inc/0042-api).
+Your tasks: T-01, T-02. Run the sw-do loop (`specweave task next 0042`, claim, ...)
+on your tasks only. Edit only their Files. Commit as "0042: ...". `task done --run`
+needs exit 0. When done or blocked: `specweave task release --all-mine`,
+`specweave note "api: <done | blocked: why>" 0042`, commit and push your branch.
 ```
 
-Agent templates for common lanes live in `agents/` (backend, frontend, database, security, testing, pm, architect, researcher, reviewer-security, brainstorm-*). `_protocol.md` is prepended automatically by `specweave team`.
+Set `SPECWEAVE_AGENT=api` in that agent's environment so its claims are distinct.
+In Claude Code, `specweave team` opens agent-team panes for the same setup.
 
-## Phase 3 — Watch (cheap)
+## 3. Watch cheaply
 
-- Poll `specweave task list <id>` (or read `ledger.jsonl`) instead of chatting. `blocked` rows are your queue: unblock (provide the secret, split the task, decide) and reply to that agent only.
-- Stale claim (older than `tasks.leaseHours`, default 2h) with no progress → the agent is gone: `task claim --force` by a replacement agent, or reassign the lane.
-- Do not re-read agents' full diffs; read their DONE lines and the ledger evidence.
+Poll `specweave task list 0042` instead of chatting. `blocked` rows are your queue:
+unblock (supply the secret, split the task, decide) and tell only that agent. A claim
+older than 2 hours with no progress is stale; a replacement agent claims it with
+`specweave task claim T-NN --force`. Agents' notes show in `specweave pickup --no-apply`.
+Lane agents do not use `specweave handoff`: it moves the one shared handoff pointer.
 
-## Phase 4 — Merge
+## 4. Merge and close
 
-1. Every agent has released + handed off. Merge lane branches into the increment branch in dependency order; ledger conflicts resolve by union (keep all lines). tasks.md conflicts: keep both agents' state lines, then `specweave task render <id>`.
-2. `specweave verify <id>` on the merged tree → `reports/verify.json`. Red → open a fix task, assign one agent, repeat.
-3. `sw:review` (optional, recommended) on the merged diff → `reports/review.md`.
-4. `specweave complete <id> --yes` (add `--reason` only if the user accepts a red verify). Only the lead closes.
-5. Remove worktrees: `git worktree remove ../<id>-<agent>`.
+1. Merge the lane branches in dependency order. `ledger.jsonl` conflicts resolve by
+   keeping every line from both sides.
+2. `specweave verify 0042` on the merged tree; red becomes a fix task for one agent.
+3. sw-review on the merged diff, then `specweave complete 0042`. Only the lead closes.
+4. `git worktree remove ../0042-api` for each lane.
 
-## Other modes (same skeleton, different lanes)
+## Manual path (no CLI)
 
-| Mode | Lanes | Merge artifact |
-|---|---|---|
-| brainstorm | advocate / critic / pragmatist (see `agents/brainstorm-*.md`) | `reports/brainstorm.md`, then `sw:increment` |
-| plan | pm (spec.md) + architect (Approach/plan.md) in parallel | reviewed spec.md before any task is claimed |
-| review | correctness / security / spec-compliance lenses (`sw:review --full` runs these) | `reports/review.md` |
-| research | one topic per agent | `reports/research-<topic>.md` |
-| test | unit / integration / e2e | `specweave verify` commands in `testing.commands` |
+Same split and brief; each agent appends its own `claim`, `done` and `release` lines to
+`ledger.jsonl` as in sw-do's manual path, plus a `note` line as in sw-handoff's.
 
 ## Anti-patterns
 
-- Agents editing files outside their task's `Files` ("I just fixed a typo there") — that is how merges break. Add a task.
-- Marking `[x]` in tasks.md by hand. The ledger wins; `task render` overwrites it.
-- Per-agent increments to avoid conflicts — you lose the single ledger and the single verify.
-- The lead implementing "just this small piece". Spawn an agent or finish the team first.
-- Closing while a claim is live. Wait for release/handoff or take it over explicitly.
-
-## Resources
-
-- `specweave task --help`, `specweave verify --help`, `specweave handoff --help`
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#team)
+- An agent editing outside its tasks' `Files`. Add a task instead.
+- One increment per agent: you lose the single ledger and the single verify.
+- The lead implementing "just this small piece", or closing while a claim is live.

package/src/templates/AGENTS.md.template

@@ -1,67 +1,41 @@
 <!-- SECTION:header required -->
 # {PROJECT_NAME}
 
-SpecWeave project. Small requests live in the intent board; scoped work lives in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. This file is for Codex, OpenCode, Cursor, Gemini, Aider and humans; Claude Code reads CLAUDE.md (same content). Keep it under one page; project-specific notes go in **Project notes** at the bottom.
-<!-- /SECTION -->
-
-<!-- SECTION:structure -->
-## Structure
-
-```
-.specweave/
-  intents/board.jsonl       append-only intent history (latest revision per id; planning state, not verification)
-  increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
-  docs/                    ADRs and hand-written docs (read before changing architecture)
-  config.json
-```
-Only those files (plus optional `plan.md` when Approach outgrows a page, and `scripts/`) live in an increment root; everything else goes in `reports/`. Commit messages start with the increment id: `0042: add login form`.
-
-`tasks.md` format (the CLI parses it): `### T-01 Title` followed by one line `- AC: AC-01, AC-02 | Files: src/login.ts, src/login.test.ts | Test: npm test -- login`. `ledger.jsonl` is one JSON object per line, append-only: `{"t":"T-01","e":"claim|done|skip|release|block","by":"<tool>@<host>","at":"<ISO>","evidence":"<sha>","note":"<why>"}` (`evidence` required for `done`, `note` required for `skip`, both optional elsewhere).
+This project uses SpecWeave. Work is planned in increments: `.specweave/increments/NNNN-slug/spec.md` holds Problem, Scope, Acceptance Criteria, Approach and Tasks, and `ledger.jsonl` beside it records who claimed and finished what. Start every session with `specweave pickup`.
 <!-- /SECTION -->
 
 <!-- SECTION:loop required -->
 ## The loop
 
-| Step | Command (each step is also a standalone skill you can install into any tool with `npx vskill install anton-abyzov/specweave/sw-do` — same for `sw-increment`, `sw-review`, `sw-handoff`, `sw-task`) |
-|---|---|
-| Plan a feature: write `spec.md` (Problem, Scope, `AC-01…` checkboxes, Approach: files that change, order of work, risks, decisions), resolve material scope questions before implementation | `specweave create-increment "title"` |
-| Work the tasks | `specweave task next` → `specweave task claim T-NN` → implement → commit (`NNNN: …`) → `specweave task done T-NN --run "<test cmd>"` (the command runs through your OS shell: cmd.exe on Windows, sh elsewhere) |
-| Verify the whole increment | `specweave verify` |
-| Review before closing (recommended for anything that ships) | in a fresh session: read spec.md, list findings by severity citing path:line, re-verify each before writing `reports/review.md`; the authoring session never approves its own work |
-| Close (needs a green verify or `--reason "<why>"`) | `specweave complete NNNN` |
-| Stop for any reason | `specweave handoff` |
-
-Without the `specweave` CLI: create the folder by hand (id = highest existing 4-digit prefix + 1, zero-padded); append one JSON line per event to `ledger.jsonl` as UTF-8 without BOM, LF-terminated, e.g. `{"t":"T-01","e":"claim","by":"<tool>@<host>","at":"<ISO>"}` (bash: `>>`; PowerShell: `[IO.File]::AppendAllText('ledger.jsonl', $line + "`n")`, never `>>`, it writes UTF-16); mark done with the same line using `"e":"done","evidence":"<commit sha>"` after the Test command exits 0; write `reports/verify.md` with the real test output and say the increment is ready to close (closing itself needs the CLI).
-Use an increment for work that needs shared scope, acceptance criteria, or a handoff. Small self-contained fixes can remain a lightweight intent. For bugs, reproduce the failure and add a regression test when it protects behavior. User authorization carries through routine implementation and verification.
-<!-- /SECTION -->
+1. `specweave pickup`: brings in the latest handoff, then prints the open increment, the next task with its acceptance criteria, claims held by others, branch state, notes and project memory.
+2. New work that needs acceptance criteria or a handoff: `specweave create-increment "title"`, then fill in spec.md. If an open increment already owns the files, add ACs and tasks to it instead of opening another. Small self-contained fixes need no increment.
+3. `specweave task claim T-NN`, edit only that task's Files, commit as `NNNN: what changed`, then `specweave task done T-NN --run "<its Test>"`.
+4. `specweave verify`, a review in a fresh session for anything that ships, then `specweave complete NNNN`.
+5. Stopping for any reason (out of tokens, switching tool or account): `specweave handoff --reason "<why>"`.
 
-<!-- SECTION:verify required -->
-## Verification before "done"
+**Handoff in two words.** When the user says "hand off", "I'm out of tokens" or "switching accounts", or a "[Usage limit approaching" or "[Usage limit reached" note asks you to checkpoint, run `specweave handoff --reason "<why>"` and tell the user to say "pick up" in the other tool. When the user says "pick up" or "continue from the other account", run `specweave pickup` and carry on with the task it names. `specweave report` writes an HTML timeline; `specweave auto-handoff on` hands off by itself at 90% of the limit.
 
-Run the project's build/test/lint (see **Commands**) before reporting any task complete and paste the real output. A task is done only when its **Test** command exits 0. Never skip, weaken, or delete a test to make it pass. Never set `status: completed` by hand; use `specweave complete`.
+Tasks live in spec.md as `### T-01 Title` followed by `- AC: AC-01 | Files: src/a.ts, src/a.test.ts | Test: npm test -- a`. An AC is met when the tasks covering it are done. Leave a message for whoever works on an increment next with `specweave note "<text>"`. Each step is a skill in `.agents/skills/sw-*` and `.claude/skills/sw-*`; other tools: `npx vskill install anton-abyzov/specweave/sw-do`.
 <!-- /SECTION -->
 
-<!-- SECTION:parallel required -->
-## Working in parallel (any tool, any account)
+<!-- SECTION:rules required -->
+## Rules
 
-1. One worktree per agent, named after the agent: `git worktree add ../NNNN-<agent> -b inc/NNNN-<agent>` (e.g. `../0042-codex -b inc/0042-codex`). The branch name must contain the increment id.
-2. Claim before editing: `specweave task claim T-NN` (or `specweave task next`). Edit only that task's **Files**; need another file → claim its task or add a task. A claim older than 2h with no `done` is stale and may be re-claimed.
-3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
-4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."` (no CLI: append a `skip` ledger line with a reason), never ticked.
-5. When you stop: `specweave task release --all-mine` then `specweave handoff`.
-Resuming: check `.specweave/intents/board.jsonl` (latest revision per id) or `specweave dashboard` for unfinished intents, including work without an increment. Then find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `specweave task next`.
+- A task is done when its Test exits 0 and you have seen the real output. Never skip, weaken or delete a test to pass, and never set a status by hand.
+- One agent per branch and worktree: `git worktree add ../NNNN-<agent> -b inc/NNNN-<agent>`. A claim older than 2h is stale. On a merge conflict in `ledger.jsonl` keep every line from both sides.
+- Decisions that must outlive this session go in spec.md Approach, or as one file per fact in `.specweave/memory/` with a line in its `MEMORY.md` index. Memory is committed, so every tool and account sees it.
+- Check a secret exists without printing it; never commit `.env*`.
+- Without the CLI, append ledger lines yourself, one JSON object per line, UTF-8, LF: `{"t":"T-01","e":"claim","by":"<tool>@<host>","at":"<ISO time>"}` (`e` is claim, done, release, skip or block; `done` needs `"evidence":"<commit sha>"`, `skip` needs `"note":"<why>"`).
 <!-- /SECTION -->
 
-<!-- SECTION:conventions required -->
-## Conventions
-
-- Secrets: confirm a key is present without printing its value (`grep -q NAME .env` or `Select-String -Quiet NAME .env`); never commit `.env*`.
-- Prefer deleting code over adapting it; change only what the task needs.
-- Check `.specweave/docs/` ADRs before architectural changes; record new decisions in spec.md **Approach** or an ADR. When a new increment replaces an old one, create it with `--supersedes NNNN` (or set `supersedes` in its metadata.json) instead of leaving the old one open.
+<!-- SECTION:umbrella when="umbrella" -->
+Umbrella project: nested repos live under `repositories/<org>/<repo>/`; commit inside each nested repo, then the umbrella.
 <!-- /SECTION -->
 
-<!-- SECTION:umbrella when="umbrella" -->
-- Umbrella projects only: nested repos live under `repositories/<org>/<repo>/`; commit inside each nested repo, then the umbrella.
+<!-- SECTION:hub when="hub" -->
+## Project hub
+
+`.specweave/project/hub.json` holds this project's goal and shared context; read it before starting. `specweave project show` lists current work, artifacts and routines, and `specweave project brief --harness codex` exports an assignment for another tool.
 <!-- /SECTION -->
 
 <!-- SECTION:jev when="jev" -->
@@ -86,16 +60,6 @@ Every call sends its state — prompt text, task titles and ACs, the shell comma
 The Bash guard is per project (`specweave jev setup --guard-bash` writes the config flag, the `.specweave/state/jev-guard.enabled` marker and a project-level `PreToolUse` hook; `--no-guard-bash` removes all three). A regex prefilter skips Jev for `npm test`, `npm run build|test|lint`, `pnpm/yarn test`, `cargo test`, `go test` and plain read commands, so project-defined scripts are trusted by the guard. A denied command is the user's to approve — stop and ask; do not reword it, wrap it or edit config around it.
 <!-- /SECTION -->
 
-<!-- SECTION:troubleshooting -->
-## Troubleshooting
-
-| Issue | Fix |
-|---|---|
-| `specweave` not found | `npm i -g specweave` (optional; the loop works without it) |
-| Instructions out of date after upgrade | `specweave update` |
-| Unsure who owns a task | `specweave task list` |
-<!-- /SECTION -->
-
 ## Commands
 
 | Action | Command |
@@ -108,8 +72,4 @@ If a cell still says TODO, fill it in from `package.json`/`Makefile` and commit;
 
 ## Project notes
 
-(architecture map, things agents get wrong here, recurring mistakes — keep it short)
-
-## Portable project hub
-
-When `.specweave/project/hub.json` exists, read its goal and shared context before starting work. `specweave project show` lists current work, artifacts and routine definitions; `specweave project brief --harness codex` exports a fresh assignment. Use native skills/task tools when available and authorized, or execute sequentially. Routines are definitions until configured in a native scheduler.
+(architecture map, things agents get wrong here, recurring mistakes; keep it short)

package/src/templates/CLAUDE.md.template

@@ -1,110 +1,19 @@
 <!-- SECTION:header required -->
-# {PROJECT_NAME}
+@AGENTS.md
 
-SpecWeave project. Small requests live in the intent board; scoped work lives in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. Keep this file under one page; project-specific notes go in **Project notes** at the bottom.
-<!-- /SECTION -->
-
-<!-- SECTION:structure -->
-## Structure
-
-```
-.specweave/
-  intents/board.jsonl       append-only intent history (latest revision per id; planning state, not verification)
-  increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
-  docs/                    ADRs and hand-written docs (read before changing architecture)
-  config.json
-```
-Only those files (plus optional `plan.md` when Approach outgrows a page, and `scripts/`) live in an increment root; everything else goes in `reports/`. Commit messages start with the increment id: `0042: add login form`.
-
-`tasks.md` format (the CLI parses it): `### T-01 Title` followed by one line `- AC: AC-01, AC-02 | Files: src/login.ts, src/login.test.ts | Test: npm test -- login`. `ledger.jsonl` is one JSON object per line, append-only: `{"t":"T-01","e":"claim|done|skip|release|block","by":"<tool>@<host>","at":"<ISO>","evidence":"<sha>","note":"<why>"}` (`evidence` required for `done`, `note` required for `skip`, both optional elsewhere).
-<!-- /SECTION -->
-
-<!-- SECTION:loop required -->
-## The loop
-
-| Step | Command |
-|---|---|
-| Plan a feature (spec.md with ACs + Approach; resolve material scope questions) | `/sw:increment "title"` |
-| Work the tasks (claim → implement → commit → done with evidence) | `/sw:do` (loops `specweave task next` / `claim` / `done --run`) |
-| Verify the whole increment | `specweave verify` |
-| Review before closing (recommended for anything that ships: fresh context, findings cite path:line and are re-verified) | `/sw:review` |
-| Close (needs a green verify or `--reason`) | `/sw:done` |
-| Stop for any reason (context, tokens, switching tools) | `/sw:handoff` |
-
-Use an increment for work that needs shared scope, acceptance criteria, or a handoff. Small self-contained fixes can remain a lightweight intent. For bugs, reproduce the failure and add a regression test when it protects behavior. User authorization carries through routine implementation and verification.
-<!-- /SECTION -->
-
-<!-- SECTION:verify required -->
-## Verification before "done"
-
-Run the project's build/test/lint (see **Commands**) before reporting any task complete and paste the real output. `specweave task done T-NN --run "<test cmd>"` refuses a failing command. Never skip, weaken, or delete a test to make it pass. Never set `status: completed` by hand; use `/sw:done`.
-<!-- /SECTION -->
-
-<!-- SECTION:parallel required -->
-## Working in parallel (any tool, any account)
-
-1. One worktree per agent, named after the agent: `git worktree add ../NNNN-<agent> -b inc/NNNN-<agent>` (e.g. `../0042-claude -b inc/0042-claude`) or `claude --worktree NNNN-<agent>`. The branch name must contain the increment id.
-2. Claim before editing: `specweave task claim T-NN` (or `specweave task next`). Edit only that task's **Files**; need another file → claim its task or add a task. A claim older than 2h with no `done` is stale and may be re-claimed.
-3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
-4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."`, never ticked.
-5. When you stop: `specweave task release --all-mine` then `/sw:handoff`.
-Resuming: check `.specweave/intents/board.jsonl` (latest revision per id) or `specweave dashboard` for unfinished intents, including work without an increment. Then find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `/sw:do`.
-<!-- /SECTION -->
-
-<!-- SECTION:conventions required -->
-## Conventions
+# {PROJECT_NAME}: Claude Code notes
 
-- Secrets: confirm a key is present without printing its value (`grep -q NAME .env` or `Select-String -Quiet NAME .env`); never commit `.env*`.
-- Prefer deleting code over adapting it; change only what the task needs.
-- Check `.specweave/docs/` ADRs before architectural changes; record new decisions in spec.md **Approach** or an ADR. When a new increment replaces an old one, create it with `--supersedes NNNN` instead of leaving the old one open.
-<!-- /SECTION -->
+Everything shared by every tool is in AGENTS.md, imported above. Only Claude-specific notes belong here.
 
-<!-- SECTION:umbrella when="umbrella" -->
-- Umbrella projects only: nested repos live under `repositories/<org>/<repo>/`; commit inside each nested repo, then the umbrella.
+- Skills: `/sw-increment "title"`, `/sw-do`, `/sw-auto`, `/sw-review`, `/sw-done`, `/sw-handoff`, from `.claude/skills/`, so they load in cloud sessions too. With the `sw` plugin they are also `/sw:do` and so on.
+- With the plugin, the SessionStart hook prints a short pickup; run `specweave pickup` for the next task's acceptance criteria.
+- Use plan mode before writing a spec for anything bigger than a small fix.
 <!-- /SECTION -->
 
 <!-- SECTION:jev when="jev" -->
-## Jev (System One) — closed-set decisions
-
-Jev answers questions whose every possible answer can be written down in advance: about 250 ms, about $0.00002, calibrated probabilities, no generation. Delegate the decision, then act on it yourself.
-
-| Moment | Command |
-|---|---|
-| Before choosing a skill or a subagent model tier | `specweave jev route "<prompt>"` |
-| Picking the tier for one task already in the ledger | `specweave jev task T-NN` — a suggestion you act on; nothing re-routes models behind you |
-| Before an unattended risky shell command | `specweave jev guard "<command>"` — exit 0 allow, 2 warn, 3 deny |
-| Pulled issue / PR / web text, a red test run | `specweave jev screen <file>` · `specweave jev failure <file>` |
-| Any other closed set of your own | `specweave jev ask --state @state.json --questions @q.json` |
-| Mechanical browser navigation (headless only) | `specweave jev browse --goal "<goal>" --url "<url>"` |
-| Is it configured here, what has it cost | `specweave jev doctor` · `specweave jev usage` |
-
-Exit 4 means Jev is unavailable — continue without it. Never send Jev code, prose, compaction, counting or date maths, another model's free-text output, or a question whose answers you cannot enumerate. Below `jev.thresholds.route` treat the answer as no answer.
-
-Every call sends its state — prompt text, task titles and ACs, the shell command, test-output tails, screened text, page text and element names — to the configured provider under the user's own key; secret-shaped values are masked heuristically first, best-effort only.
-
-The Bash guard is per project (`specweave jev setup --guard-bash` writes the config flag, the `.specweave/state/jev-guard.enabled` marker and a project-level `PreToolUse` hook; `--no-guard-bash` removes all three). A regex prefilter skips Jev for `npm test`, `npm run build|test|lint`, `pnpm/yarn test`, `cargo test`, `go test` and plain read commands, so project-defined scripts are trusted by the guard. A denied command is the user's to approve — stop and ask; do not reword it, wrap it or edit config around it.
-<!-- /SECTION -->
-
-<!-- SECTION:troubleshooting -->
-## Troubleshooting
-
-| Issue | Fix |
-|---|---|
-| Skills or hooks missing | `specweave doctor`, then `/reload-plugins` (restart if still missing) |
-| Instructions out of date after upgrade | `specweave update` |
-| Unsure who owns a task | `specweave task list` |
+Jev is enabled here; its rules are in the Jev section of AGENTS.md.
 <!-- /SECTION -->
 
-## Commands
-
-| Action | Command |
-|---|---|
-| Build | `{{BUILD_CMD}}` |
-| Test | `{{TEST_CMD}}` |
-| Lint | `{{LINT_CMD}}` |
-
-If a cell still says TODO, fill it in from `package.json`/`Makefile` and commit; `specweave verify` runs these rows.
-
 ## Project notes
 
-(architecture map, things agents get wrong here, recurring mistakes — keep it short)
+(Claude-only notes; anything every tool needs goes in AGENTS.md)

package/src/templates/README.md.template

@@ -1,26 +1,26 @@
 # {{PROJECT_NAME}}
 
-A [SpecWeave](https://verified-skill.com) project: work happens in increments under `.specweave/increments/NNNN-slug/`, each with a `spec.md` (Problem, acceptance criteria, Approach), a `tasks.md`, and an append-only `ledger.jsonl` that records who claimed and finished what.
+A [SpecWeave](https://spec-weave.com) project: work happens in increments under `.specweave/increments/NNNN-slug/`, each one `spec.md` (Problem, Scope, acceptance criteria, Approach, Tasks) plus an append-only `ledger.jsonl` that records who claimed and finished what.
 
 ## Working on this project
 
 | Step | Command |
 |---|---|
-| Plan a feature | `specweave create-increment "title"` (Claude Code: `/sw:increment`) |
+| Start or continue | `specweave pickup` |
+| Plan a feature | `specweave create-increment "title"` (skill: `sw-increment`) |
 | Work the tasks | `specweave task next` → `specweave task claim T-NN` → implement → `specweave task done T-NN --run "<test cmd>"` |
-| Verify | `specweave verify` |
-| Close | `specweave complete NNNN` |
-| Stop / hand off | `specweave handoff` |
+| Verify and close | `specweave verify`, then `specweave complete NNNN` |
+| Switch tool or account | `specweave handoff`, then say "pick up" in the other tool |
 
-Agent instructions live in `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex, OpenCode, Cursor, Gemini, Aider). Both files keep a short managed block; the **Commands** table and **Project notes** at the bottom are yours to edit.
+Agent instructions live in `AGENTS.md` (every tool; `CLAUDE.md` imports it). The skills are in `.agents/skills/` and `.claude/skills/`.
 
 ## Structure
 
 ```
 .specweave/
-  increments/NNNN-slug/   spec.md · tasks.md · ledger.jsonl · handoff.md · reports/
-  docs/                    ADRs and hand-written docs
+  increments/NNNN-slug/   spec.md · ledger.jsonl · handoff.md · reports/
+  memory/                 MEMORY.md index + one file per durable fact
   config.json
 ```
 
-Docs: https://verified-skill.com · Source: https://github.com/anton-abyzov/specweave
+Docs: https://spec-weave.com · Source: https://github.com/anton-abyzov/specweave

package/dist/plugins/specweave/lib/external-sync/duplicate-detector-base.d.ts

@@ -1,73 +0,0 @@
-/**
- * Base class for duplicate detection across external PM tools.
- * Implements 3-phase protection identical across GitHub, JIRA, and ADO.
- *
- * Usage:
- *   class GitHubDuplicateDetector extends DuplicateDetectorBase<GitHubIssue> {
- *     async searchExisting(query: SearchQuery): Promise<GitHubIssue[]> { ... }
- *     async closeItem(itemId: string, reason: string): Promise<void> { ... }
- *     getItemId(item: GitHubIssue): string { ... }
- *   }
- */
-export interface SearchQuery {
-    incrementId: string;
-    title?: string;
-    project?: string;
-    board?: string;
-}
-export interface VerificationResult<T> {
-    success: boolean;
-    expectedCount: number;
-    actualCount: number;
-    duplicates: T[];
-    message: string;
-}
-export interface DetectionResult<T> {
-    hasDuplicates: boolean;
-    existing: T[];
-    message: string;
-}
-/**
- * Abstract base class for duplicate detection.
- * Subclass per external tool (GitHub, JIRA, ADO).
- */
-export declare abstract class DuplicateDetectorBase<T> {
-    protected toolName: string;
-    constructor(toolName: string);
-    /**
-     * Search for existing items that might be duplicates.
-     * Implementation is tool-specific (different APIs).
-     */
-    protected abstract searchExisting(query: SearchQuery): Promise<T[]>;
-    /**
-     * Close/archive a duplicate item.
-     * Implementation is tool-specific (different APIs).
-     */
-    protected abstract closeItem(itemId: string, reason: string): Promise<void>;
-    /**
-     * Get the unique ID of an item.
-     */
-    protected abstract getItemId(item: T): string;
-    /**
-     * Get the title/summary of an item for display.
-     */
-    protected abstract getItemTitle(item: T): string;
-    /**
-     * Check for existing items before creating a new one.
-     * Returns existing items if found, preventing duplicate creation.
-     */
-    detectBeforeCreate(query: SearchQuery): Promise<DetectionResult<T>>;
-    /**
-     * Verify that creation didn't accidentally create duplicates.
-     * Called after a create operation to ensure only expected items exist.
-     */
-    verifyAfterCreate(query: SearchQuery, expectedCount: number): Promise<VerificationResult<T>>;
-    /**
-     * Automatically close duplicate items.
-     * Called when duplicates are detected to clean them up.
-     */
-    closeDuplicates(duplicates: T[]): Promise<void>;
-    private formatDetectionMessage;
-    private formatVerificationMessage;
-}
-//# sourceMappingURL=duplicate-detector-base.d.ts.map

package/dist/plugins/specweave/lib/external-sync/duplicate-detector-base.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"duplicate-detector-base.d.ts","sourceRoot":"","sources":["../../../../../plugins/specweave/lib/external-sync/duplicate-detector-base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,8BAAsB,qBAAqB,CAAC,CAAC;IAC3C,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEf,QAAQ,EAAE,MAAM;IAI5B;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAEnE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3E;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IAE7C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IAMhD;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAsBzE;;;OAGG;IACG,iBAAiB,CACrB,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAuCjC;;;OAGG;IACG,eAAe,CAAC,UAAU,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBrD,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,yBAAyB;CAoBlC"}