Skip to content
Skills Library
Management & product · Planning

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.

Repository
node-loop ↗
Licence
MIT
Last repository change
04.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.

Licence

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

  1. What a plan node is
  2. Terms
  3. Fence syntax
  4. Sizing rules
  5. Acceptance
  6. Smells
Original SKILL.md headings · 59 lines, 694 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.