Elyntic Agent

Elyntic is a multi-agent system built on Pi. It provides an orchestrator, worker agents, skills, and extensions.

Quick Start

# 1. Install the Elyntic command (Node.js 22.19+)
npm install -g @cgh567/agent

# 2. Clone this repo
git clone https://github.com/elyntic-agi/elyntic-agent.git ~/elyntic-agent

# 3. Bind the CLI to this checkout, then run setup
export ELYNTIC_DIR="$HOME/elyntic-agent"
cd ~/elyntic-agent && bash setup.sh

# 4. Set an API key if using Anthropic
export ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE

# 5. Start Elyntic
elyntic

Keep ELYNTIC_DIR set when launching from a new shell; the global command otherwise uses its installed package copy. The installer currently creates a ~/helios-agent compatibility symlink because its settings and scripts still use that path. This is not a second checkout.

What You Get

Elyntic (Orchestrator)

Elyntic splits complex tasks across parallel subagents. It never writes code directly — it delegates to specialized agents.

Minion (Workers)

Minion agents implement tasks using TDD with 11 pre-completion gates. Each worker receives a single task and grinds until it's done.

Agent Roles

| Agent | Role | |-------|------| | scout | Fast codebase recon | | planner | Task graph creation | | worker | TDD implementation | | reviewer | Adversarial code review | | judge | Cycle evaluation | | sub-planner | Recursive subsystem planning | | debug-worker | Runtime bug diagnosis | | researcher | Web research | | context-builder | Requirements analysis |

Each role's supported models are declared in its file under agents.

Dispatch Engines

1. subagent() — Single tasks, parallel batches, chain pipelines
2. coordinate() — Structured TASK-XX specs with parallel workers + review
3. orchestrate.sh — Shell-based planner→worker→judge cycle loop

Skills

• engineering — TDD workflow, pre-completion gates, design heuristics
• elyntic-orchestrator — Multi-cycle planner→worker→judge orchestration
• elyntic-prime — Delegation enforcement protocol
• elyntic-health — System health diagnostics
• focus — Development context awareness
• agent-pr-guardrails — Prevent agents from merging PRs
• skill-graph — Memgraph knowledge graph integration

Extensions

The package and extension paths are declared in settings.json. Setup loads those packages and the local extensions directory.

Usage

# Elyntic orchestrates (delegates to workers)
export ELYNTIC_DIR="$HOME/elyntic-agent"
elyntic "Build a REST API with JWT auth"

The optional cycle runner requires a separate pi CLI (npm install -g @cgh567/cli), Python with PyYAML, and a timeout command on its verification path. Check those prerequisites before using it.

Inside an Elyntic session, use its agent tools (these are not shell commands):

// Direct agent dispatch
subagent({ agent: "worker", task: "Add rate limiting to /api/login" })

// Parallel workers
subagent({ tasks: [
  { agent: "worker", task: "Task 1: Add bcrypt" },
  { agent: "worker", task: "Task 2: Create login endpoint" }
]})

// Execute an existing structured plan
coordinate({ plan: "specs/auth.md" })

Structure

~/elyntic-agent/
├── agents/                  # Agent definitions
│   ├── worker.md            # Minion worker (TDD + 11 gates)
│   ├── planner.md           # Elyntic planner (hypothesis-driven)
│   ├── judge.md             # Cycle evaluator (semi-formal verification)
│   ├── elyntic-system.md    # Elyntic system-agent definition
│   ├── coordination/        # Variants for coordinate() engine
│   └── crew/                # Variants for pi-messenger Crew
├── docs/                    # Documentation index and references
│   ├── README.md            # Docs index
│   └── guide/               # Agent-readable installation and setup guides
│       └── installation.md  # Step-by-step installation guide
├── prompts/                 # Templates (post-mortem, adversarial-review)
├── skills/                  # Skills loaded on demand
├── extensions/              # Local extension hooks
├── scripts/                 # Utility scripts
├── .planning/               # GSD lifecycle artifacts (gitignored transient data)
│   ├── PLAN.md              # Goal-backward plan (discuss → plan)
│   ├── CONTEXT.md           # Discuss-phase findings
│   ├── VERIFICATION.md      # Verifier output
│   └── debug/               # Transient debug sessions (active/ is gitignored)
├── AGENTS.md                # Agent-readable project context (per-directory)
├── settings.json            # Pi config + extension manifest
└── setup.sh                 # Installer

GSD Lifecycle

Every non-trivial task follows the GSD (Get Shit Done) execution standard:

discuss → plan → execute → verify

1. Discuss — Elyntic identifies gray areas, asks clarifying questions, and produces CONTEXT.md
2. Plan — Planner (Wheeler) creates a goal-backward PLAN.md with wave-based task decomposition
3. Execute — Workers (Dyson) implement using TDD: RED → GREEN → refactor, with pipe verification
4. Verify — Verifier (Hans) checks invariants, data flows, and acceptance criteria, producing VERIFICATION.md

Artifacts live in .planning/ at the repo root. Transient debug sessions (.planning/debug/active/) are gitignored.

Agent-Readable Installation Guide

The file docs/guide/installation.md is a structured, machine-readable guide written for AI agents (Elyntic, workers) to consume during setup tasks. It covers:

• Prerequisites and environment setup
• Dependency installation order
• Extension registration
• Health checks and smoke tests

Human users can read it too — it mirrors setup.sh but with rationale and troubleshooting context.

Desktop app

This repository supplies the agent runtime. The desktop app is developed separately.

Paper References

Agent improvements based on "Agentic Code Reasoning" (Anthropic 2026):

• Vacuous Test Guard (cpp_3)
• Name Resolution Audit (django-13670)
• Indirection Check (Mockito_8)
• Confident Wrong Answer warning (py_5)
• Gates 11-12 in pre-completion checklist