node-spec
/node-spec
Plan node spec for node-loop - what a plan node is, its fence, sizing rules and smells. Use when writing, sizing, implementing or reviewing a `nodes/NN-slug.md` plan node.
- Author
- exit-node ↗
- Repository
- node-loop ↗
- Licence
- MIT
- Last repository change
- 04.11.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Plan node spec for node-loop - what a plan node is, its fence, sizing rules and smells. Use when writing, sizing, implementing or reviewing a `nodes/NN-slug.md` plan node.
Original author description
Plan node spec for node-loop - what a plan node is, its fence, sizing rules and smells. Use when writing, sizing, implementing or reviewing a `nodes/NN-slug.md` plan node.
How it works
- What a plan node is
- Terms
- Fence syntax
- Sizing rules
- Acceptance
- Smells
SKILL.md preview
---
name: node-spec
description: Plan node spec for node-loop - what a plan node is, its fence, sizing rules and smells. Use when writing, sizing, implementing or reviewing a `nodes/NN-slug.md` plan node.
---
# Plan node spec
File format: [`template.md`](template.md) in this skill directory.
## What a plan node is
A plan node is the smallest change one fresh agent can implement and one reviewer can pass or fail from the diff alone.
"Fresh" means the agent starts with only `brief.md`, its plan node file, and the `contracts.md` sections of its dependencies.
Write every plan node so that context is enough.
Always say "plan node" or `nodes/NN-slug.md`, never bare "node", so nobody reads it as Node.js.
## Terms
- **fence**: the paths a plan node owns (`## Fence`) plus its `## Out of scope` list. The implementer changes only fenced paths; `scripts/check-result` lists every changed path outside it and catches any write that reached the main checkout.
- **creep**: a change the plan node did not ask for, inside or outside the fence. Ideas that occur along the way go to `parking.md`.
- **shrink**: a stub, a TODO, a weakened or skipped test, or an unmet acceptance item.
- **kickback**: a failed review, fence check, leak check or cherry-pick; a new, fresh implementer continues the plan node from the previous `.patch`.
- **wave**: the set of plan nodes whose dependencies have all merged; they run in parallel.
## Fence syntax
One `- ` list item per path under `## Fence`; the first token is the path, anything after it is a note.
- `path/exact.ts` matches that file.
- `src/auth/` (trailing slash) matches everything below the directory.
- `src/**/*.test.ts` is a bash pattern where `*` also matches `/`.
Fence new files too: a file the plan node creates needs its path in the fence.
Generated files the change produces (lockfiles, snapshots, migrations) belong in the fence of the plan node that produces them.
## Sizing rules
1. **Tracer bullet first.** Prefer a thin vertical slice through every layer that works end to end over a horizontal layer that works only once later plan nodes land.
2. **Contract first.** When several parallel plan nodes consume the same new types, schema or interface, put that contract in its own plan node in an earlier wave; its `Exposes:` line is what the others build against.
3. **One fresh context.** The implementer can hold the plan node, the brief, the dependency contracts and every fenced file at once.
4. **One-pass diff.** The reviewer can judge the diff in one read; the rough bar is under ~400 changed lines, excluding generated code.
5. **Ends green.** After the plan node merges alone, the build and the existing tests pass; every acceptance command passes.
6. **Disjoint fences per wave.** No path matches the fences of two plan nodes in the same wave, so their branches cherry-pick onto the run branch without conflict.
## Acceptance
Each `## Acceptance` item is one checkable statement plus the exact command that proves it, as in the template.
The reviewer runs those commands; an item without a command is judged by reading the diff, so reserve that for statements a diff answers directly ("no new public export in `src/index.ts`").
Commands run from the root of the implementer's own checkout, so write them repo-relative (`python3 -m unittest test_todo.py`, never `cd /abs/path && ...`).
Fence paths are repo-relative too; no absolute path appears anywhere in a plan node.
## Smells
A plan node with any of these smells gets split, merged or rewritten before the planner yields:
- An acceptance item needs "and" more than twice: it is several plan nodes.
- Its fence overlaps a plan node in the same wave: move the shared path into an earlier contract plan node or serialise the two.
- An acceptance item cannot be checked ("works well", "is clean", "handles errors properly"): rewrite it as an observable outcome with a command.
- It only makes sense together with another plan node (neither can merge alone and stay green): merge them, or cut a contract plan node both depend on.
- Its `Consumes:` names an interface no dependency `Exposes:`: add the dependency or the missing contract plan node.
- An acceptance command or path is absolute or starts with `cd`: rewrite it relative to the repo root, since the implementer runs in its own checkout.
Files in this package (2)
- SKILL.md 4 KB
- template.md 2 KB
Versions
The database has no other skills named node-spec.
Database snapshot: 13.11.2026 · package version c8d62f386cba (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100plan
Turn a finalized spec into a step-by-step implementation plan at .ai/plans/{YYYY-MM-DD}-{slug}.md, where every task has exact file paths, exact commands, and a verification with expected output. Use when asked to "plan the implementation", "create a plan", or after a spec's open… - 100plan-format
Use when writing, revising or repairing an implementation plan file (<name>-plan.md). - 100tasks
Use to break a designed feature into atomic, ≤1-day tasks with a dependency graph, a per-task Definition of Done, and a machine-readable tasks.json that the implement engine consumes. Triggers on "task breakdown for {slug}", "break down tasks for {slug}", "tasks for {slug}",… - 90sdlc-specify
Create or update a feature specification (what and why, no implementation) in specs/NNN-slug/spec.md. Use for T3 features, when the user says 'spec this' or 'write a spec', or when requirements for existing behaviour change. - 90work-node
Carries out one task or phase while keeping its node in the RoadRaven desktop app current. Claims or creates a node, sets it in progress, checkpoints progress into the node's notes, stays inside the files the brief names, proves a fix with a failing test first, runs the… - 100blender-syntax-nodes
Use when building node trees via Python -- Geometry Nodes, Shader Nodes, or Compositor Nodes. Prevents the breaking change of using node.inputs/outputs by index instead of NodeTreeInterface (4.0+) for node group I/O. Covers node creation, linking, group management, and the…