| name | add-dag-node |
| description | Scaffold a new DAG node in afi-reactor, wire it into the pipeline, and ensure all types and validators are imported from afi-core while obeying AFI Orchestrator Doctrine and the AFI Droid Charter.
|
Skill: add-dag-node (afi-reactor)
Purpose
Use this skill when you need to add a new DAG node to the AFI Reactor
pipeline, wire it into the existing graph, and keep everything aligned with:
- AFI Droid Charter
- AFI Droid Playbook
- afi-reactor/AGENTS.md
- AFI Orchestrator Doctrine (the "10 Commandments")
- Canonical types and validators from
afi-core
This skill is primarily used by dag-builder-droid and any future reactor droids
that work on the DAG.
Preconditions
Before changing anything, you MUST:
-
Read:
afi-reactor/AGENTS.md- AFI Orchestrator Doctrine file referenced there
- AFI Droid Charter
- AFI Droid Playbook
-
Confirm:
- The requested node belongs in afi-reactor (orchestration), not in
afi-core (validators / runtime logic) or afi-config (governance).
- The change does not require editing smart contracts, Eliza configs, or
deployment/infra repos.
If any requirement is unclear or appears to violate Doctrine or AGENTS.md,
STOP and ask for human clarification instead of trying to be clever.
Inputs Expected
The caller should provide, in natural language or structured form:
- Node name (e.g.
NewsSentimentEnricher, GreeksScorer)
- Node purpose:
- What this node does in one or two sentences
- Lifecycle stage:
- One of:
Raw, Enriched, Analyzed, Scored
- Inputs:
- What data it expects, and from which upstream node(s) or stage(s)
- Outputs:
- What it emits and which downstream nodes or stage(s) should consume it
- Canonical types / validators:
- Which types / schemas / validators exist in
afi-core that should be used,
if known
If any of this information is missing, ask clarifying questions or produce a
minimal, clearly-labeled stub that's safe to evolve later.
Step-by-Step Instructions
When this skill is invoked, follow this sequence:
1. Restate the requested change
In your own words, summarize:
- The node's purpose
- Its lifecycle stage
- Its upstream and downstream relationships
This summary should be short and precise, so humans can quickly confirm the
intent.
2. Locate the DAG structures
Identify the current DAG layout and relevant files, typically including:
- DAG engine and orchestration code (e.g.
src/core/dag-engine.ts or similar)
- DAG graph or codex (e.g.
config/dag.codex.json or similar config files)
- Any codex/metadata that describes nodes and stages (e.g.
codex/*.json)
- Any existing node patterns in
src/dags/ (or equivalent)
Do not modify these yet; just understand how the DAG is currently modeled.
3. Create the node scaffold
Create a new node file under the appropriate folder, for example:
src/dags/<stage>/<nodeName>.ts
orsrc/dags/<nodeName>.ts
Follow any existing naming and folder conventions in afi-reactor.
In the new file:
- Import canonical types / schemas / validators from
afi-core where needed.
- Never re-define schemas or validators that already exist in
afi-core.
- Export a clearly named function such as:
runNode, execute, or the project's established pattern.
- Keep implementation minimal:
- If the logic is not well-specified, stub the body with
TODO comments and
clearly throw or return a safe placeholder.
- Do not implement complex business logic unless explicitly requested.
All comments should be clear, referencing:
- The node's purpose
- Its lifecycle stage
- Any assumptions or TODOs
4. Wire the node into the DAG graph
Update the DAG graph / codex / configuration files so this new node is part of
the pipeline:
- Register the node with:
- Unique identifier / key
- Stage (Raw / Enriched / Analyzed / Scored)
- Input/output relationships (upstream/downstream nodes)
- Ensure the wiring respects:
- No forbidden cycles (unless explicitly allowed by the Doctrine)
- The existing pipeline architecture and naming conventions
- If there is a central registry for node metadata, add a minimal entry using
the existing pattern.
If wiring rules are ambiguous or require architectural changes, STOP and mark
this as a human decision point.
5. Add minimal tests or runners (optional but recommended)
Where patterns already exist (e.g. in ops/runner/ or test/):
- Add a small integration test or runner stub that:
- Constructs a minimal signal or input
- Passes it through the new node
- Asserts basic shape/flow (not business outcomes)
- Do not introduce new test frameworks or heavy dependencies.
If no test patterns exist yet, leave a clearly marked TODO and surface this
in your summary.
6. Validate and build
Run at least:
npm run build in afi-reactor
If relevant quick tests exist and are safe to run:
npm test (or the closest equivalent)
Do not mark the skill as "successful" if the build fails. Instead, stop, gather
error output, and surface it with minimal, clear commentary.
Hard Boundaries
When using this skill, you MUST NOT:
- Create or modify validators or schemas in
afi-reactor.
- Those belong in
afi-core or afi-config.
- Duplicate or move canonical logic from
afi-core into afi-reactor.
- Modify any other repos (
afi-token, afi-config, afi-ops, afi-infra, etc.).
- Introduce new external services, queues, or transports.
- Perform large, sweeping refactors of the DAG architecture without explicit
human approval.
- Change tokenomics, emissions, or smart contracts.
If a request forces you towards any of the above, STOP and escalate.
Output / Summary Format
At the end of a successful add-dag-node operation, produce a short summary
that includes:
- Node name and stage
- Files created
- Files modified (graph/config/metadata)
- Any new tests or runners added
- Any TODOs or open questions that must be resolved by a human
Aim for something a human maintainer can read in under a minute to understand
exactly what changed and why.
Example Usage Patterns
You should use this skill for requests like:
- "Add a new Raw-stage node that normalizes exchange metadata before enrichment."
- "Insert a News Sentiment Enricher node between the Enriched and Analyzed stages."
- "Wire an existing afi-core validator into a Scored-stage node that computes
a composite score."
You should NOT use this skill for:
- Changing how PoI/PoInsight are defined at the validator/agent level.
- Modifying Eliza agents, character specs, or AFI gateway behavior.
- Editing or deploying smart contracts.
