weave · diff
git:20260916.635b2af to git:20260916.72d9168
159 added, 26 removed. Audit A to A.
---
name: weave
- description: Use for any coding task that benefits from connecting agents, project context, terminal output, git, tests, and prior decisions into one adaptive workflow. Turns a free-form request into a verifiable task (Goal/Constraints/Required/Validation), classifies it as simple or complex, and runs the matching flow. Reads and writes .weave/state.md so Codex and Claude Code can hand work back and forth. Also use when the user says "weave", "use weave", or asks to continue work tracked in .weave/.
+ description: Use for any coding task that benefits from a request contract, a short pre-edit plan, working memory across a session, and a fidelity check before declaring done - connecting agents, project context, terminal output, tests, git, and prior decisions into one adaptive workflow. Turns a free-form request into a verifiable contract (Goal/Constraints/Required/Not requested/Completion criteria), classifies it as simple or complex, and runs the matching flow. Reads and writes .weave/state.md so Codex and Claude Code can hand work back and forth. Also use when the user says "weave", "use weave", or asks to continue work tracked in .weave/.
---
# Weave
Weave is not another coding agent. Weave is a lightweight layer that connects
coding agents, project context, terminal tools, git, tests, and prior
decisions into one adaptive workflow.
Tagline: **Different tools. One workflow.**
Principle: **Preserve signal. Remove noise. Keep work connected.**
+ Git is one possible source of context (status, diff, log, blame) — never
+ the center of this skill. Everything below applies the same way whether
+ or not the current directory is a git repository.
+
+ The cycle Weave drives is:
+
+ ```
+ UNDERSTAND -> PLAN -> READ WHAT'S NEEDED -> DECIDE -> IMPLEMENT THE MINIMUM -> VALIDATE
+ ```
+
Follow the steps below in order. Do not skip step 1 or 2 — they are what
keep a "complex" task from turning into unnecessary multi-agent ceremony,
- and what keep a "simple" task from being under-specified.
+ what keep a "simple" task from being under-specified, and what stop
+ activity (files opened, searches run, code written) from being mistaken
+ for progress toward the actual request.
- ## 1. Frame the task
+ ## 1. Request contract
- Rewrite the user's request as four short fields before touching any file.
+ Rewrite the user's request as explicit fields before touching any file.
If the user already gave enough detail, this takes one paragraph, not a
- document.
+ document. This contract is what the Fidelity check (section 6) compares
+ the finished work against — write it before you have a reason to defend
+ a particular approach, not after.
- **Goal**: the verifiable outcome (what should be observably true when done).
- **Constraints**: technical, security, and scope limits (languages, files
that must not change, backwards-compatibility, performance, licensing).
- **Required**: the changes actually needed — nothing speculative.
- - **Validation**: the concrete check that proves it's done (a test, a
- command, a manual repro step).
+ - **Not requested**: adjacent things the request does *not* ask for —
+ say them explicitly so a later change doesn't drift into them because
+ they were merely "nearby."
+ - **Completion criteria**: the concrete check that proves it's done (a
+ test, a command, a manual repro step) — this is the Validation step,
+ named for what it actually verifies.
+ - **Blocking questions**: only what genuinely cannot be decided without
+ the user, because the answer would materially change the result. An
+ ambiguity that doesn't change the outcome gets a stated, reasonable
+ assumption instead of a question — don't invent a requirement either
+ way; write down what you assumed and why.
If `.weave/state.md` already exists for this task, read it first (see
- section 6) — another agent (Codex or Claude Code) may have already framed
- the task, selected context, or left a pending blocker. Continue from there
- instead of re-deriving it.
+ section 7) — another agent (Codex or Claude Code) may have already framed
+ the task, built working memory, or left a pending blocker. Continue from
+ there instead of re-deriving it; update the contract only if new evidence
+ actually changes it.
## 2. Classify: simple or complex
Ask: does this touch one concern in a small, well-understood surface, or
does it span multiple files/modules, require a design decision, or carry a
real risk of side effects?
**Simple** — a single-file or single-concern change, a well-scoped bug fix,
a small refactor, adding a test. Flow:
```
Context → Implementation → Verification
```
Do not invoke Planner, Reviewer, Security, or multiple agents for this.
- Do the work directly.
+ Do the work directly. Keep the request contract as the one paragraph
+ section 1 describes and hold it in your own reasoning — do not create
+ `.weave/state.md` for a simple task just to externalize that paragraph.
+ Only write the file if the task turns out to need a handoff to another
+ agent, grows past "simple" mid-task, or the user asked for it tracked.
+ A `.weave/state.md` that adds a read, a directory, and a write without
+ changing what gets built is the process getting in its own way.
**Complex** — spans multiple files/modules, changes a public interface,
touches shared state, or the right approach isn't obvious yet. Flow:
```
Context → Plan → Build → Review → Tests
```
These are functions performed in sequence, not personas. Don't invent
extended backstories or names for them — "Plan" is a short written plan,
"Review" is a pass over the diff, "Tests" is running/writing validation.
+ Write the plan in `.weave/state.md` before the first edit. It holds only:
+ the cause or hypothesis being investigated, the parts it affects, the
+ minimal execution sequence, and the final validation. New evidence can
+ change the plan — update it in place when that happens. It should not be
+ rebuilt from scratch each time you learn something; if you're rewriting
+ the whole plan repeatedly instead of adjusting one part of it, that's a
+ sign the investigation, not the plan, needs another pass.
+
Add a **Security** pass only when the task has a real security surface:
authentication, authorization, credentials/secrets, private data, executing
commands, handling untrusted input, or adding a dependency/external call.
Otherwise skip it — don't add it by default.
### Subagents
Use the platform's native subagent/task-delegation feature only when all
three hold: the platform actually offers it in this session, the phases are
genuinely independent, and splitting them reduces work or improves
verification (e.g. Review running against the diff while Tests run
separately). Otherwise run every phase yourself in the current agent —
that is the default, not the fallback.
- Use the host's task or agent tool when it is available in the current
session. Otherwise run every phase sequentially in the current agent.
## 3. Context Engine v0
- Never dump the whole repository into context. Build a short, justified
- context set using tools you already have:
+ Never dump the whole repository into context. Start from the request's
+ actual entry points (the file/function the user named, the error's
+ location, the command that fails) and follow real dependencies outward —
+ expand to another file only when a concrete caller, import, or reference
+ leads there. A full-repo scan is not a default starting move.
+ Build a short, justified context set using tools you already have:
+
- Project instructions: `AGENTS.md`, `CLAUDE.md`, or equivalent files that
apply to the touched paths.
- - `git status` and `git diff` (run through Weave's own filtering when the
- hook is active — see section 4) for what's already in flight.
- Files the user directly named.
- Targeted search with `rg`/`grep` for the symbol, error string, or
behavior in question — not a full-repo scan.
- Direct callers of any function you're about to change (`rg` for the
function name).
- Tests that already cover the touched code.
- Config needed to understand the runtime flow (e.g. the one env var or
config key that changes behavior).
+ - `git status`/`git diff` (run through Weave's own filtering when the
+ hook is active — see section 4) *only* when the task needs to know
+ what's already in flight — it's a source of context, not a required
+ step, and everything above works the same with no `.git` present at all.
- For every file you pull in, record one line:
+ Every search and every read answers one concrete question. Before
+ repeating a read or a search, check: did this content change? is there a
+ genuinely new question? was the prior read incomplete for what you need
+ now? If none of those hold, reuse what you already found instead of
+ re-deriving it — see Working memory below. This is a reminder, not a
+ lock: a read that's actually needed (the file changed, a new question
+ came up) always proceeds normally.
+ For every file you pull in, record one line in `.weave/state.md`'s
+ Working memory:
+
```
- file: <path>
reason: <why this file, specifically>
relation: <how it relates to Goal/Required>
```
- This list is what goes into `.weave/state.md`. If a file doesn't earn a
- reason, don't include it.
+ If a file doesn't earn a reason, don't include it.
- Do not build embeddings, a vector index, a custom AST, a context database,
- or a full-repo crawler. `rg`, `git`, and reading the named files is the
- whole engine for v0.
+ ### Working memory
+ `.weave/state.md`'s Working memory section (see section 7) is where
+ findings live during the task, so they don't have to be rediscovered:
+
+ - files read, and why each one earned a read
+ - facts confirmed (not restated from a guess — actually verified)
+ - decisions taken, and what made them the right call
+ - hypotheses considered and discarded, and why
+ - commands run and their relevant result (not full logs)
+ - the next concrete action
+
+ Update it as you go, not as a wrap-up at the end — it's only useful if
+ it's current when the next read-or-reread decision comes up.
+
+ When Weave's own reread-detection hook is active in Claude Code
+ (`hooks/preread.js`, matching the `Read`/`Grep`/`Glob` tools), a repeated
+ read or search on content that hasn't changed surfaces a short reminder
+ automatically. Treat that reminder as confirmation to pull the answer
+ from Working memory instead of re-deriving it, not as a request to argue
+ past it — and if it fires on a read you know is legitimately new
+ information, that's fine, it never blocks the read.
+
+ Do not build embeddings, a vector index, a custom AST, a context
+ database, or a full-repo crawler. `rg`, targeted reads, and the working
+ memory above are the whole engine for v0.
+
## 4. Terminal Intelligence
Weave has its own terminal-output reduction engine (`core/`, `cli/weave.js`,
`hooks/`) and no external runtime dependency. A `PreToolUse` hook rewrites
eligible Bash calls through `weave exec`. The original command runs unchanged
inside a capturing Bash process. Background commands and commands longer than
4,000 characters are not wrapped.
Current profiles cover Git status/diff/log and common Git actions, searches,
tests, builds, linters, package managers, directory listings, Docker,
Kubernetes, Terraform, and logs. File-reading commands and explicit JSON
output are always verbatim. Unknown small output is also left untouched.
The same engine can be invoked directly:
```
node "<plugin-root>/cli/weave.js" doctor # static sanity check of the installation (files, config, permissions) - not an end-to-end lifecycle test
node "<plugin-root>/cli/weave.js" mode [name] # show or set off/lite/full/ultra
node "<plugin-root>/cli/weave.js" gain # bytes received vs presented, this project's recorded runs
node "<plugin-root>/cli/weave.js" recall <id> # full original output for a run that was filtered or failed
```
When a reduced report would actually be smaller than the original output,
the `weave exec` result — whether you triggered it directly or the hook
did — is reported in this shape (otherwise Weave passes the original
stdout/stderr through verbatim, with no envelope):
```
Command: <exact command run>
Exit: <exit code>
Summary: <what happened, one or two lines>
Failures: <errors/failures with file:line, or "none">
Omitted: <lines cut for length, or "nothing omitted">
Recovery: <"weave recall <id>", or "nothing to recover" if nothing was omitted>
```
Never report success when the exit code is non-zero. Failed commands keep
their complete captured stdout and stderr. If a command couldn't run at all (blocked
by the host's own permission system, tool missing, etc.), say so plainly —
don't infer or fabricate a result.
Each captured stream is limited to 20 MB. Interactive and TTY-sensitive
programs should be run outside the wrapper.
If Weave's own tooling isn't available for some reason (hook not
installed, running outside a Weave-managed project), fall back to the
target tool's native quiet/short flags (`--oneline`, `--short`, `-q`) —
never install anything silently to work around it.
## 5. Minimalism policy (mandatory baseline)
The active mode is persisted per project in `.weave/mode`. Switch it with
`/weave off`, `/weave lite`, `/weave full`, or `/weave ultra`. `full` is the
default. Lifecycle hooks inject only the selected policy instead of repeating
the whole skill on every prompt.
These ten rules are the `full` baseline:
1. Understand the request and trace the flow it actually affects before editing.
2. Examine callers and integrations before fixing a bug — patch the shared cause, not just the symptom the report named.
3. Ask whether the functionality needs to exist at all before adding it.
4. Reuse what already exists in the repo instead of writing it again.
5. Prefer the standard library and native platform features over a new library.
6. Produce the smallest correct diff — no unrequested abstractions, no speculative flexibility.
7. Run a verification proportional to the risk — a one-line fix needs a quick check; a security- or data-affecting change needs a real one.
8. Never fabricate success when a command couldn't be run — report the blocker plainly (see section 4).
9. Trigger an extra review pass for anything touching security, auth, credentials, money, personal data, or data-loss risk — never simplify those away to shrink a diff.
10. Record only compact, useful context in `.weave/state.md` — not full logs, not speculation, not secrets.
+ Before writing any new code, check in order — stop at the first "yes":
+
+ 1. Does this actually need to exist? (a real requirement, not a guess at future need)
+ 2. Does the project already have something equivalent?
+ 3. Does the standard library solve it?
+ 4. Does the platform solve it natively?
+ 5. Does an already-installed dependency solve it?
+ 6. Can the fix land at the shared point every caller already goes
+ through, instead of at each call site?
+ 7. Could code be removed here instead of added?
+
+ Do not create: an abstraction with a single implementation; configuration
+ for a value that never varies; a generic system for one concrete case;
+ files "for later"; a wrapper that only renames a call; documentation that
+ promises behavior that isn't implemented yet; or a test that repeats
+ existing coverage without exercising a genuinely different risk.
+
Use the independent `weave-review`, `weave-audit`, `weave-debt`,
`weave-gain`, and `weave-help` skills when their narrower operation is asked
for. They report without silently changing code.
- ## 6. Shared state: `.weave/state.md`
+ ## 6. Fidelity check
- Create `.weave/` only when this skill actually runs in a project — never
- speculatively. Use a single file, `.weave/state.md`, so either agent can
- read the other's work:
+ Before declaring the task done, answer these against the Request
+ contract from section 1 — in `.weave/state.md`'s Fidelity check section,
+ not just silently in your head:
+ 1. Did I deliver what was actually asked?
+ 2. Did I change anything that wasn't required?
+ 3. Does the change address the cause, not just a symptom?
+ 4. Is there an equally correct, smaller change I passed over?
+ 5. Am I calling activity — files opened, commands run, lines written —
+ a result, when the Completion criteria aren't actually met?
+ 6. Does every claim I'm about to make have real evidence behind it (a
+ command's actual output, a test that actually ran) rather than an
+ assumption that it would work?
+
+ A technically valid change that solves a different problem than the one
+ in the Request contract is not done. Go back to section 1 and reconcile
+ the gap before reporting completion — don't report success and let the
+ mismatch surface later.
+
+ ## 7. Shared state: `.weave/state.md`
+
+ Create `.weave/` only when the task actually calls for it (see section
+ 2 — most simple tasks don't) — never speculatively, and never as a
+ default action for every request this skill handles. Use a single file,
+ `.weave/state.md`, so either agent can read the other's work:
+
```markdown
# Weave state
## Task
<one-line description>
## Goal
...
## Constraints
...
- ## Context selected
+ ## Not requested
+ <adjacent things explicitly out of scope, or "none noted">
+
+ ## Completion criteria
+ ...
+
+ ## Blocking questions
+ <only questions that would materially change the result, or "none">
+
+ ## Working memory
- file: ...
reason: ...
relation: ...
+ Confirmed facts: ...
+ Decisions: ...
+ Discarded hypotheses: ...
+ Commands run: ...
+ Next action: ...
+
## Plan
<only for complex tasks>
## Changes made
...
## Review
<findings from the Review pass, if complex>
## Verification
Command: ...
Exit: ...
Summary: ...
Failures: ...
+
+ ## Fidelity check
+ <answers to section 6's questions, or "not yet run">
## Open / blocked
<anything unresolved, or "none">
```
Rules:
- If the file exists, read it before starting — don't overwrite context
another agent (Codex or Claude Code) left behind. Update the relevant
sections instead of replacing the whole file.
- Never write secrets, tokens, credentials, full log dumps, or personal
data into this file — it's meant to be readable and, in most projects,
committable.
- Whether `.weave/state.md` is committed or gitignored is a per-project
choice — see the README for the tradeoff. Don't decide this silently;
if the project has no existing convention, ask or leave it untracked by
default and say so.