Phased guide for agents

01Overview

The guide divides the work on a site into five phases, numbered from 0 to 4. Phase 0 explains the Nucleo model. Phases 1 to 4 take the site from tokens and sections to the dynamic parts.

On every call the guide reads the state of the site and the saved documents. From these it calculates the current phase and the list of things to do.

The guide is read-only: it saves no state and does not remember previous calls.

You query it with the ability nucleo/guide, with wp nucleo guide (or wp nucleo ability run guide) and with the command nucleo guide of the local CLI.

The instructions of the MCP server ask the agent to call nucleo-guide before writing.

Every rule has a code (R1.2). Some errors and some quality reports show the same code in the guide field.

02Reading the guide

nucleo/guide

What it does: returns the requested phase, or the calculated current phase. The response contains the site state, the rules of the phase, the things to do, the exit conditions and the next command.

How to use it: via MCP with the tool nucleo-guide. Via REST with GET /wp-json/wp-abilities/v1/abilities/nucleo/guide/run. Example input: {"phase": 2, "design": "home.html"}.

Parameters:

Response fields:

Permissions: current_user_can('edit_posts'). OAuth scope nucleo:read.

Edition: Free

Known limits:

• The ability is annotated readonly, idempotent and not destructive. The write rate limit does not apply.
• The texts of rules, things to do and exit are in English in the code, translatable with the nucleo domain.
• If the Nucleo cache is empty but the data exists, the first entry of todo asks to run cache-rebuild.
• If reading the documents stops at the limit, the last entry of todo says how many documents it read out of how many.

wp nucleo ability run guide

What it does: runs nucleo/guide from WP-CLI and prints the JSON response.

How to use it: wp nucleo ability run guide --input='{"phase":1}' --user=<id|login>. The nucleo/ prefix of the name is optional.

Parameters: --input, JSON object with the same fields of the ability. Default {}.

Permissions: as nucleo/guide. Edition: Free

Known limits: an --input that is not a JSON object returns invalid_json. The wp nucleo guide command is generated for the ability: see the next section.

wp nucleo guide

What it does: runs nucleo/guide with the command generated for every ability (nucleo/guide becomes wp nucleo guide) and prints the JSON response.

How to use it: wp nucleo guide --input='{"phase":1}' --user=<id|login>.

Parameters: --input, JSON object with the same fields of the ability.

Permissions: as nucleo/guide. Edition: Free

Known limits: the command is generated for the nucleo/* abilities: a dash in the name becomes a space (nucleo/doc-patch becomes wp nucleo doc patch). Commands starting with status, export, import, sync, docs, mcp or ability are not generated, so existing ones are not overwritten.

nucleo guide

What it does: calls nucleo/guide from the local computer and prints the response as text.

How to use it: nucleo guide [0-4] [--design PATH]. Example: nucleo guide 2.

Parameters:

Lines printed, in order: Phase <n>: <title>, State: …, Checks: … (when present), Distinct: with one line per node (when present), Coverage: <read> of <total> documents read (with (truncated) when reading stopped), Basics:, To do:, Rules: (with tools: under each rule), Exit:, Next: …. Empty sections do not appear. Next does not appear when next is null.

Permissions: as nucleo/guide, with the CLI credentials.

Edition: Free

Known limits: the State line shows only tokens, sections, layouts, menus, types and documents. Checks, Distinct and Coverage have their own lines; Distinct appears only if there are distinct nodes. If the site responds with an error, the CLI shows the server message as an error.

MCP server instructions

What it does: the MCP server sends the agent a fixed text at start-up. The text asks to call nucleo-guide before writing and to follow the phases in order.

How to use it: automatic, INSTRUCTIONS field of the server response.

Parameters: None

Permissions: those of the MCP connection.

Edition: Free

Known limits: it is a hint. All tools remain visible in every phase.

03Phase calculation

Current phase

What it does: without phase, the guide checks phases 1 to 4 in order. It returns the first one not met. If all are met, it returns 4.

How to use it: call nucleo/guide without phase.

Parameters: None

Permissions: as nucleo/guide.

Edition: Free

Known limits:

• Phase 0 is never chosen automatically. It is read only with phase: 0.
• The verified conditions are these. The exit conditions are only text.

• pathLinks, mixedSections and forms generate things to do but do not block the exit from the phase.
• With an empty model, phase 3 checks only handLists.
• A single layout with the entire_site condition applies to all types.

Site state

What it does: collects the state on every call, with a few aggregate queries. It writes nothing to the database.

How to use it: state field of the response.

Parameters: state fields:

Permissions: as nucleo/guide.

Edition: Free

Known limits:

• Reading stops at 1000 documents. It reads layouts and sections first, then the most recently modified documents.
• The posts trash, auto-draft and inherit are excluded. Drafts count.
• The application of header, footer and single to the whole site comes from the layout map in the store. If the cache is empty, the guide sees these conditions as not met.
• A draft without a slug appears with its ID in the references (page:14#r).

Document checks

What it does: goes through the tree of each document read and counts the signals of the rules. For each counter it keeps up to 3 example positions, in the form <ref>#<node id>.

How to use it: state.checks field. The examples appear in the entries of todo.

Parameters: counters:

Permissions: as nucleo/guide.

Edition: Free

Known limits:

• Structure of a block for repeated: type and some settings. level counts for nc/heading, section for nc/section-ref, postType for nc/query and nc/collection, layout and tag for the other blocks. A setting that is absent counts as the default of the block manifest.
• Binds to a field of the current content also count, with source post, nucleo, item, acf, metabox, jetengine or woo. Texts, images, links and style do not count.
• nc/section-ref and lists weigh 0. A container of only references is not a repetition.
• The blocks inside nc/query, nc/collection and the hand lists do not count in repeated.
• A block is reported if at least one copy is not inside a block already repeated. The group lists all the copies.
• The to-do explains at most 3 groups and shows at most 4 copies per group.
• For mixedSections, a nc/section-ref counts as a section if the root of the section is nc/section. If the section is not among the documents read, the reference does not count.

Distinct block on purpose

What it does: a node with "guide": {"distinct": "<reason>"} does not count as a repetition. The blocks inside it still count. The guide lists the node and the reason in state.distinct.

How to use it: add the guide key to the node in the document. Example: "guide": {"distinct": "home opening, deliberately different"}.

Parameters:

Permissions: those of writing the document.

Edition: Free

Known limits: a distinct node makes its containers different too. state.distinct shows at most 3 nodes; state.checks.distinct counts all of them.

04Phases

Phase 0: template structure

What it does: explains the Nucleo model. Title in the code: Template structure.

How to use it: nucleo/guide with phase: 0. In the other phases the same rules appear in short form in basics.

Parameters: rules:

Permissions: as nucleo/guide.

Edition: Free

Known limits: enter this phase only on explicit request. The exit is text only: knowing the two worlds, the document model, the token syntax and the two channels. No verified condition. todo is always empty.

Phase 1: tokens and components

What it does: brings the design into tokens and reusable sections. Title in the code: Tokens and components.

How to use it: current phase when the condition of phase 1 is not met, or phase: 1.

Parameters: rules:

Things to do generated:

• no saved token: run nucleo tokens suggest <design.html>, then tokens-set;
• tokenLiterals > 0: replace the values with the tokens;
• repeated > 0: create sections, with the explanation of the groups and the doc-patch operations (remove, then insert of a nc/section-ref with the same id);
• mixedSections > 0: move the other blocks into a section of their own.

Permissions: as nucleo/guide.

Edition: Free

Known limits: the exit is text only: every repeated element has a section; no value matches a token. R1.3 has no check in the code. R1.4 cites nucleo/kit-list, which is Pro: without a license the ability is not registered.

Phase 2: global parts

What it does: moves header, footer and navigation into the layouts. Title in the code: Global parts.

How to use it: current phase when phase 1 is met and phase 2 is not, or phase: 2.

Parameters: rules:

Things to do generated: missing header or footer layout; layout present but without the entire_site condition; no menu; globalParts > 0; pathLinks > 0.

Permissions: as nucleo/guide.

Edition: Free

Known limits: the exit is text only: header, footer and menu apply to the whole site; no page repeats the global parts. pathLinks does not block the exit. R2.5 has no check in the code.

Phase 3: real content

What it does: turns the repeated elements into content with type, fields and a single layout. Title in the code: Real content.

How to use it: current phase when phases 1 and 2 are met and phase 3 is not, or phase: 3.

Parameters: rules:

Things to do generated: handLists > 0; for every type without a single layout; for every type without published items.

Permissions: as nucleo/guide.

Edition: Free

Known limits: the exit is text only: every list of the design reads real content; every item has its own page. The code does not check that a nc/query or nc/collection list exists for every type.

Phase 4: dynamic parts

What it does: replaces the fake controls with native blocks or components. Title in the code: Dynamic parts.

How to use it: current phase when phases 1 to 3 are met, or phase: 4. It is also the phase returned when all phases are met.

Parameters: rules:

Things to do generated: inertButtons > 0; a test submission for every form, with the number of forms.

Permissions: as nucleo/guide.

Edition: Free

Known limits: the exit is text only: no fake control; every form tested with a test submission. The code checks only inertButtons. The test submission cannot be verified: the entry stays in todo as long as forms exist. next is null.

05Rule codes in errors

Link to errors and reports

What it does: adds the code of the guide rule in the guide field of some quality reports and some errors. The rule field remains the id of the quality rule.

How to use it: automatic, in the responses of save, validation, quality and import.

Parameters:

Permissions: those of the operation that produces the error.

Edition: Free

Known limits: the other rules have no link. The quality rules are described in the quality engine.