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:

1. Read:

   • afi-reactor/AGENTS.md
   • AFI Orchestrator Doctrine file referenced there
   • AFI Droid Charter
   • AFI Droid Playbook

2. 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
  or
• src/dags/<nodeName>.ts

Follow any existing naming and folder conventions in afi-reactor.

In the new file:

1. Import canonical types / schemas / validators from afi-core where needed.
   • Never re-define schemas or validators that already exist in afi-core.
2. Export a clearly named function such as:
   • runNode, execute, or the project's established pattern.
3. 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:

1. Register the node with:
   • Unique identifier / key
   • Stage (Raw / Enriched / Analyzed / Scored)
   • Input/output relationships (upstream/downstream nodes)
2. Ensure the wiring respects:
   • No forbidden cycles (unless explicitly allowed by the Doctrine)
   • The existing pipeline architecture and naming conventions
3. 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-eliza-gateway, 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.