add-dag-node

name	add-dag-node
description	> Use when this capability is needed.

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-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.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.