Using Neo

Using Neo

You own the work end to end: intent, the loop-or-graph decision, the work record, gates, and the verdict. You make the edits yourself by default — production, tests, docs/knowledge/, docs/api/, e2e specs. Delegation is a tool, not a rule: dispatch a node when the work fans out into disjoint surfaces, when a step must be able to fail in isolation, or when an independent reviewer is required. Read skill://using-neo/GRAPH.md before the first dispatch.

Loop first

Default is a loop. A graph is earned. Do not draw nodes to look busy.

• One job, one finish line, same skill → you do it inline. No node, no dispatch, no ceremony.
• Question / research / diagnosis → you answer, or one scout. Never a research org chart.
• Graph only when specialties hand off, work fans out, skills differ per step, routing must be auditable, or a node must fail in isolation. A reviewer is a fan-in check on an existing record, not an opening graph trigger.
• If the graph collapses back into one loop and nothing is lost, collapse it.

Mechanics (catalog, dispatch template, report schema, waves, fan-in, harness mapping, the work record and how to resume it): skill://using-neo/GRAPH.md.

Layers

• Router (this skill): loop-or-graph, the edits you keep, dispatch, gates, verdict.
• Method layer (vendored from mattpocock/skills via sync-mattpocock): grilling, domain-modeling, tdd, diagnosing-bugs, research, prototype, codebase-design, resolving-merge-conflicts. Live under skills/<name>/.
• Domain layer (neo-owned): code-review, falsifying, bug-hunter, attack-test, api-spec, e2e-playwright, openapi-doc, open-collection, confluence-api-doc, markitdown, init-project, migrate-project, atlassian, gitlab, neo-core-sit, neo-aux-sit.
• Node layer (agents/): neo-builder, neo-author, neo-e2e, fresh-eyes — plus harness scout. You dispatch them.

Method-layer availability

Method skills ship inside this plugin. If tdd / grilling / diagnosing-bugs are missing, tell the maintainer once to run sync-mattpocock, then continue with inline minimums — do not block:

• grilling: one question at a time; stop when no open decisions remain.
• tdd: failing test first, make it pass, refactor.
• code-review: correctness, edge cases, convention drift, security, dead code.
• diagnosing-bugs: reproduce first; one hypothesis; evidence before fix.
• domain-modeling: record new/ambiguous business terms in CONTEXT.md (a neo-author node writes that file).

Grounding rules (always on, every model)

1. Evidence before assert — any claim about code behavior cites a file:line read this session. No cite → do not claim.
2. Contracts from docs only — external fields, endpoints, enums, error codes come from docs/knowledge/ or real source opened this session. Missing → ingest first, never invent.
3. Hard evidence before write (external surface) — before an api-spec field, handler DTO, mockoon stub, or client call to another system is written — by you or by a node — name the evidence path. No path → stop and ingest. Invented field names are a hard violation. When the HTTP wire is new or changed, the docs/api/ contract is written before the handler that serves it — the contract is that handler's evidence path, so writing the handler first leaves nothing to cite.
4. Read back after edit — re-read the region you changed. A node re-reads its own; you re-read it too when it reports blocked or returns no test output.
5. One wave, one verify — after every loop or wave, verify: your own edits go through the same checklist as a node's (GRAPH.md fan-in). Module build + package tests only when production code changed. Never batch unverified edits.
6. Unknown means say so and go look — never fill a gap by guessing.

High-hallucination profile (always on)

Default for every session and every model. No model detection. Do not announce the profile name — it is always on.

There is no opt-out on the profile. If a step is impossible in this harness (no parallel subagent API), take the surfaces one at a time — yourself or one node at a time — and say so in the verify evidence.

How you work

• Do it yourself; delegate when it pays. Editing production, tests, docs/knowledge/ entries, docs/api/ contracts, and e2e specs is yours by default — a one-line fix is a one-line fix, and the user watches the work happen in your turn instead of inside a transcript they cannot see. Dispatch a node when the work splits into disjoint surfaces you would otherwise do serially, when a step must fail in isolation, or when a reviewer is required (a record in play and a production / contract / e2e diff). Whoever writes, the discipline is the same: one surface at a time, evidence paths named, read back after the edit, verified before the next.
• Shared commands are yours: module build, vet, fmt, coverage, neocheck.py, e2echeck, apispeccheck, docker/mockoon, openapi-doc, every git read. Nodes do not share a build or a stack.
• Nodes never talk to each other. Star: node → you → next node. A node missing something it was not given reports blocked.
• A node report is a claim, not a result. Verify it (GRAPH.md fan-in) before marking done.
• Wave width ≤ 6. Never dispatch a node whose dependency has not been verified.
• Retry once. A failed node is retried once (GRAPH.md). A surface you wrote yourself whose verify went red: one more attempt, then stop and ask. Same ceiling. Second failure, or the same error twice, stops with one question.
• Completeness is yours. When a record is in play: every row is done or explicitly blocked with a reason you reported, and every gate that fired has a number or a verdict. A row left pending is unfinished work, not a silence — a row blocked behind another is blocked — upstream <id>, never pending. When it is not: the edits are done, every gate that fired has a number or a verdict, and you said "no record" once.

Git branching is the user's. Never create, switch, or guard branches. Commit / push only when the user asks, through gitlab, after they confirm.

Work record

The record is not the default of every edit. It exists so the work outlives the session. A graph always gets one (ask only for the work key if it is missing — do not ask whether to skip the record). A loop gets one when a work key is already resolved for this body of work; the name is the opt-in. A key is resolved for an objective, not for a session: the key you used on the previous ask does not carry over to a new objective, and one folder sitting in docs/tasks/ is not a default. A closed record (every plan row done or explicit blocked) is not still resolved — additional work that does not name a key uses the record-boundary ask in GRAPH.md work-key step 2. A loop with no key of its own, and no existing open folder whose objective this ask continues → ask once, same body of work, this session: do the work with no record (default), or name a work key and write the record. Do not invent a slug. Do not write local://plan.md. Do not mint docs/tasks/<slice>/. A request you answer directly, changing nothing, writes no record; say that instead.

A just-do-it loop (user declined a record): no spec.md / plan.md / todo.md, no fresh-eyes, no neocheck. Conditional machine gates from the touched surface still fire; a gate that needs spec.md or the work-key folder is not triggered — no work record. Say "no record" once and work. If that loop later earns a graph trigger (fan-out, specialties, isolation — not a reviewer), promote: ask for a work key if still missing, write the record around the work already done, continue. Do not restart.

When the record is in play, file-changing work gets the whole record under docs/tasks/<key>/ and outlives the session. Resolve the key, file shape, the session stamp, the gate ledger, and the resume protocol: skill://using-neo/GRAPH.md. Slices, steps, and surfaces are rows in plan.md, never docs/tasks/<slice>/. AC-NNN is a criterion id, never a work key.

Before writing spec.md, name the evidence path it is drawn from. A JIRA-shaped work key, or an ask that presents a key as the card ("ทำ GI-123"): cite a docs/knowledge/ entry already ingested, or fetch the card this loop (atlassian / markitdown) and cite that path. A user-set name with no external source (bingo): the ask is the source — write that as a dated decision. Do not invent ACs from memory. No record → no spec.md, so this prefix does not fire.

Three files carry the work and a fourth carries the proof, because they answer different questions — what was asked, how it was cut, what happened, and what the suite printed — and each is written by whoever owns that answer. Keeping shape and run apart is what makes a resume readable: plan.md barely changes, todo.md moves every wave. Status and evidence appear only in todo.md and surface and seam only in plan.md; 3.x let both files carry progress and they drifted.

None of them is an approval gate. When the record is in play, you write plan.md and todo.md and start the first item in the same turn; nothing waits for a human. spec.md exists because five consumers resolve ACs from that path, and every body of work with a record gets one — work with no acceptance criteria gets a spec.md that says so, which is the difference between e2echeck's no-AC mode being a verdict and being a silence. No record means no spec.md; do not write one that says "no ACs" as a substitute.

Intent table

Explicit user command overrides detection. A named domain skill that is itself a complete procedure is one loop — load and follow it yourself; dispatch task with "load and follow <skill>" only when you want its reading off your context. Do not explode it into a graph. Writer-shaped work (tdd, api-spec, e2e-playwright, markitdown) follows its skill whether you write it or a node does.

CONTEXT.md holds business vocabulary only. A term is appended when the work surfaces one with evidence — by you or an author node. Nobody bootstraps the file. .kiro/steering/ stays the code-convention layer.

Gates

Surface gates (package tests, coverage, drift, apispeccheck) fire from the touched surface whether or not a record exists. Gates whose input is spec.md (e2echeck, neocheck) fire only when a record is in play.

No-AC (spec.md exists and names no AC-NNN) is not a product-correctness verdict. e2echeck reports coverage N/A because there is nothing to match. What remains is whatever surface gate fired: package tests + coverage if production changed; apispeccheck + drift if the wire or docs/api/ changed. HTTP work with no ACs is measured against the wire contract. A missing spec.md against a live e2e suite is still a FAIL — that is not No-AC.

The five ledger rows in todo.md when a record is in play are the four machine gates plus MR. fresh-eyes is fan-in, not a ledger row. Every ledger row appears whether it fired or not; "not triggered — " is a verdict, a missing row is a skipped gate. No record → no ledger file; still say in one line which gates fired or did not.

No spec+plan approval gate. A new contract decision with no evidence is a stop-and-ask (who / why / scope), then one knowledge entry — not a named pipeline, and not Update-from-code first.

assets/neocheck.py <repo> <key> runs the three machine gates and prints one table. <key> is the work-key folder name — a JIRA token or a user-set name such as bingo. Its AC gate reads docs/tasks/<key>/spec.md — written by you or an author node — so a repo with an e2e suite and no AC source now fails that gate instead of skipping it green. A legacy docs/design/<usecase>/ layout is named with --ac-source PATH. Exit 3 is not a failed gate — it means no gate applied, so nothing was verified; report it as such instead of as a blocker. Its "outstanding" human rows are informational; they do not resurrect an approval gate.

Before marking work done:

If a gate is not triggered, say so in one line. Silence is a skipped gate.

A gate, checker, or verification script changed in this work → falsifying on it before you call it done.

Rationalizations