Execute

Execute every actionable Reactant annotation in one document, one tag at a time, in source order. The host agent is the parser: read and interpret the document directly. Do not call or rely on a programmatic tag scanner, parser, AST, or dispatch classifier.

Entry and Dispatch Boundary

Reactant has three direct entry skills: execute, execute-one, and skill-generator. The first two are document routers. skill-generator is a direct project-authoring utility, has no inline tag form, and is never dispatched by a router. All remaining Reactant skills are tag-only workers. Invoke a worker only after this router has selected its exact actionable annotation from the target document. Never invoke a worker because ordinary chat, authored prose, or another skill merely resembles its capability.

Usage

/execute <file>

Resolve a relative file path against the current working directory.

Annotation Interpretation

Reactant annotations normally look like <@skill-name> or <@skill-name: prompt>. Natural-language prompts may wrap across lines. Use the whole document, its structure, and surrounding prose to decide whether an apparent tag is an actionable instruction.

• <@comment: ...> is human-readable data: preserve it and never dispatch it.
• A paired <@chat-model name="..."> ... </@chat-model> block is model-response data. Treat its payload as opaque conversation content even if it contains apparent tags.
• A chat-user already followed by its chat-model response is answered and remains as chat history; do not dispatch it again.
• Tags shown as documentation, quoted examples, or code samples are normally literal examples, not instructions. A leading backslash may explicitly mark an example, but examples do not require an escape character. Use context.
• execute, execute-one, and skill-generator are entry skills, not inline operations. Preserve and report an apparent annotation using any of those names; never dispatch it.
• Leave ambiguous or malformed-looking text unchanged and report it instead of guessing. Leave unknown skill tags unchanged and warn the user.

Skill Discovery

For the selected annotation, find the matching Agent Skill in this order:

1. <project-root>/.reactant/skills/<name>/SKILL.md.
2. Skill roots listed in <project-root>/.reactant/config.json, in order.
3. The bundled Reactant skills available in the current host/install.

Project-local skills may shadow ordinary bundled skills. They may not shadow the reserved names execute, execute-one, skill-generator, chat-user, resolve, chat-model, or comment. If discovery is ambiguous, do not dispatch; report the collision. Adding a valid project-local skill requires no registry edit.

Workflow

1. Read the entire current file.
2. Interpret the document and select the first actionable Reactant annotation in source order using the rules above. If none remains, report the summary and stop.
3. Discover and read the matching SKILL.md. This exact router selection is the only authorization to activate that tag-only worker. Follow its protocol for this one annotation only. Use an isolated subagent if the host provides one and doing so is appropriate; otherwise perform the protocol directly.
4. Give the selected skill the absolute document path, project root, exact raw annotation, interpreted skill name and prompt, surrounding authored block, relevant scope modifiers, ordered chat chain when applicable, context references, and full-file access for broader context.
5. Accept the skill result as produced. Do not add a second model pass, grade, fact-check, automatically retry, or semantically verify it.
6. If the skill succeeds, re-read and reinterpret the entire current file, then repeat from step 2. Earlier work may move, add, answer, or remove later annotations.
7. If the skill fails or a needed capability is unavailable, leave its tag in place, stop immediately, and do not execute later tags.
8. Report a brief summary of executed tags, any failure, unknown tags, and skipped comments/chat history/literal examples.

Rules

• Always choose the next instruction from a fresh reading of the current file; never batch or reorder annotations.
• Preserve unrelated annotations, comments, chat-model blocks, answered chat turns, and literal examples byte-for-byte unless the selected skill is explicitly defined to consume that exact content.
• If several actionable annotations share a block, the first skill may edit the authored prose but must leave later annotations available for the next pass.
• One dispatched failure stops this run.
• Never re-dispatch an annotation that a completed dispatch left unchanged: if a worker reports success but the document is unchanged and the same annotation is still actionable (a no-op), stop and report it instead of selecting the same annotation again. This rule applies with and without transactional history.
• The router itself does not edit .reactant/; only a selected skill that is explicitly responsible for project-local skills, or the transaction kernel, may do so.

Transactional History

A project may record authoring history. Before the first dispatch, look for .reactant/config.json at or above the document's directory. If it exists and contains a "repository_id" field, history is enabled and EVERY dispatch must be wrapped in a kernel transaction as described below. If the file is absent or has no repository_id, dispatch exactly as described above, editing the real file directly — no history is recorded.

The kernel ships with the optional reactant Python developer package. When history is enabled but python3 -m reactant version fails, do not dispatch: report that this project has history enabled but the kernel is unavailable, and let the user either install the package or decide to proceed without history by saying so explicitly.

Wrap each selected annotation like this:

1. Open the transaction, passing your selection as JSON on stdin:

   python3 -m reactant tx-begin --project "<project-root>" --json-file - <<'EOF'
   {"invocation": "execute",
    "document": "<target document path>",
    "tag": {"raw": "<annotation text copied exactly from the document>",
            "name": "<interpreted skill name>",
            "prompt": "<interpreted prompt, or omit>"},
    "skill": {"name": "<skill name>", "path": "<selected skill directory>"},
    "agent": {"host": "<host product name>", "model_name": "<exact model id, or omit>"},
    "context_inputs": ["<double-backtick input paths, if any>"],
    "observed_annotations": [{"kind": "comment", "name": "comment",
                              "raw": "<@comment: copied exactly>"}]}
   EOF
   

   tag.raw must be an exact copy of the selected annotation text. If that exact text occurs more than once in the document, add "char_start": <0-based character offset> so the range is unambiguous. observed_annotations is optional but valuable: report the annotation-layer content you noticed while interpreting the document — <@comment: ...> tags and other non-executable data — copied exactly, so provenance can exclude those words from authored text. The same more-than-once rule applies (char_start per entry). Relative context_inputs paths resolve from the document's directory. The kernel only verifies mechanically that each range matches your raw text; selecting and interpreting annotations remains your judgment. If tx-begin reports an error (for example another transaction is still open), resolve it as the message directs before dispatching.

2. The reply contains staged_project_root and staged_document_path. Give the worker skill the STAGED document path and STAGED project root instead of the real ones. During the transaction, neither you nor the worker may modify the real project — a real-project change is detected at commit and fails the transaction.

3. When the worker completes successfully:

   python3 -m reactant tx-commit <transaction-id> --project "<project-root>"
   

   If the worker added new annotation-layer content — for example the <@chat-model> response block appended by chat-user — report it in the commit so provenance can exclude it from authored prose: pass --json-file - with {"produced_annotations": [{"kind": "chat-model", "name": "chat-model", "raw": "<inserted block text copied exactly>", "path": "<file it is in>"}]}. The path is relative to the staged project root and must name a file this transaction changed. If the exact raw text occurs more than once in that file, add "char_start" for the entry, as with the tag.

4. When the worker fails or a needed capability is unavailable:

   python3 -m reactant tx-fail <transaction-id> --project "<project-root>" --error "<short summary>"
   

   Then stop this run as usual; the unresolved tag remains in the real file.

5. Act on the commit reply's "status" — there are three outcomes, not two:

   • "success": the staged result is installed in the real project and recorded. Re-read the REAL file and continue with the next annotation.
   • "no-op": the worker completed but produced NO staged change, so the selected annotation is still present and would be re-selected on the next pass. Stop this run immediately: report that the worker made no change, leave the tag in place, and do not retry it in this invocation. Never loop on a no-op.
   • "failed" (for example, the real project changed while the transaction was open): stop and show the user the error summary.

Open transactions are serialized: never begin a second transaction before the first is committed or failed.