AchillesAgentLib Documentation
AchillesAgentLib can be integrated into a Node.js application to add skill discovery, direct skill execution, reusable model-driven conversations, plan-based orchestration, and deterministic local project memory.
System overview
An application integrates AchillesAgentLib by creating MainAgent at a workspace root. MainAgent discovers supported skill descriptors, registers each one with its specialized subsystem, and exposes the enabled top-level tools to a reusable LoopAgentSession. Every model call passes through LLMAgent. Orchestration skills may select a SOPAgenticSession for a plan-first workflow.
flowchart TB M[MainAgent: catalog, routing, reusable prompt session] M --> S[Agentic sessions: Loop or SOP] M --> X[Skill subsystems and built-in skill folders] S --> L[LLMAgent and provider configuration] S --> X classDef runtime fill:#f5f1ff,stroke:#6657b8,color:#2d246b; class M,S,L,X runtime;
The flow begins in MainAgent, which maintains the skill catalog and owns the reusable prompt session. General prompts continue through a Loop session, while orchestration workflows may use a SOP session. The active agentic session sends model requests through LLMAgent; when the model-driven flow needs a tool, the session invokes the enabled skill through its owning subsystem. A direct executeSkill() call follows the shorter MainAgent-to-subsystem path and does not enter an agentic session.
Documentation paths
Start with MainAgent for the end-to-end request path, then use Agentic Sessions and LLMAgent for execution details. Architecture and Subsystems introduces descriptor families. The Built-in Skills menu reaches the eight portable code skills distributed under skills/. Utilities covers BacklogManager, MarkdownDataStore, and evaluation support.
The Wiki is the canonical terminology source. The design specifications are authoritative for behavior and constraints and are available through Specifications.
Source, style, and tests
Public exports begin at index.mjs. Runtime classes live with their subsystem or utility, while portable skill examples and executable code remain inside each skill folder. Coding style, source layout, file-size rules, and modular test organization are defined by DS004-coding-style. Deterministic component tests live below tests/ and run with node --test <test-file>; npm test runs the complete configured suite.
Documentation Map
The columns mirror the primary header menus in the same order. Every entry below a heading is the corresponding submenu destination and includes a short description of that page.
| Overview | Runtime | Skill Families | Built-in Skills | Utilities | Reference |
|---|---|---|---|---|---|
Home Introduces the library, its runtime architecture, and the documentation entry points. | LLMAgent Explains model configuration, provider calls, and session creation. | Orchestration Introduces allowlisted workflows implemented through orchestration skills. | bash Documents bounded Bash command execution and timeout handling. | Backlog Manager Describes the file-backed backlog API and task lifecycle. | Wiki Provides canonical definitions for project terminology. |
MainAgent Covers skill discovery, catalog routing, prompt sessions, and direct execution. | Agentic Sessions Introduces the shared execution contract for Loop and SOP sessions. | Code Explains stable JavaScript-backed skills and their execution boundary. | edit Documents exact text replacement inside workspace files. | MarkdownDataStore Introduces structured, file-backed Markdown record storage. | Specifications Opens the authoritative design-contract matrix. |
Architecture and Subsystems Maps descriptor families to their specialized runtime subsystems. | Loop Sessions Explains iterative model and tool execution with reusable context. | Dynamic Code Covers request-local direct answers and temporary generated JavaScript. | glob Documents file discovery by glob pattern and modification time. | Evals Suite Describes evaluation coverage and the repository's validation surface. | |
SOP Sessions Explains plan-first execution, dependencies, validation, and replanning. | DBTable Introduces schema-driven table skills, generation, runtime, and tests. | grep Documents regular-expression search across workspace files. | |||
Agentic Knowledge Units Explains deterministic local project memory and context assembly. | Ploinky Explains how o-skills expose Ploinky agents from agent-card metadata. | mirror-code-generator Documents source generation from skill-local specifications. | |||
read Documents numbered text reads and base64 binary reads. | |||||
webfetch Documents URL retrieval and HTML-to-text conversion. | |||||
write Documents creating or overwriting a workspace file. |
Recommended reading flow
Begin with Overview to understand the public entry point and subsystem boundaries. Continue through Runtime for execution behavior, then choose the relevant Skill Families or Built-in Skills page. Use Utilities when those APIs are in scope, consult Wiki for canonical terminology, and open Specifications for authoritative contracts.