AgenticSystemCore

Agentic System Core

A specification for publishing machine-discoverable knowledge bundles — the Agentic Knowledge Web.

What this repository holds is the specification itself — numbered normative rules, three JSON Schemas, an OWL 2 RL ontology and a suite of conformance test vectors — together with the reference engine that implements it, its command line agsc, and the nine independent checkers of AGSC-09-90 — seven validators and two generators — that anyone can run against any distribution of the format (the repository also holds the maintainer's own tools, which do not ship).

Status

Released. This tree states specification 1.0.0. spec/00-overview.md is authoritative, and it is the file to read rather than this line. The packages — agentic-system-core and its short alias agsc-cli on npm, and agentic-system-core on PyPI — carry version 1.0.1 (see "Versions" below) and are published from the package tag; the name-reservation placeholders that preceded them shipped no runtime and are marked deprecated on npm and yanked on PyPI. Install with npm install agentic-system-core, or pip install agentic-system-core (the Python checkers and reading API; the other verbs still run on the Node engine). The reference engine claims Level 3 (its claim).

Versions. Two numbers, stated apart. The *specification version* (spec_version, declared in spec/00-overview.md) names the rules, schemas, vocabulary and conformance vectors; a Bundle declares it in agsc.config.json. The *package version* (package.json, agentic-system-core and agsc-cli on npm, agentic-system-core on PyPI) names the implementation; it moves alone for a patch that changes no rule and no emitted byte — a dependency fix, a defect in a check — and a package-only release carries the package tag v and no specification tag. agsc --version prints the package version; the conformance claim names both ("agentic-system-core 1.0.1 conforms to AgenticSystemCore 1.0.0, Level 3"); the change log says for every release whether the specification moved.

The specification's own site is AgenticSystemCore.com.

In three sentences

A Bundle is a folder of Markdown files with a small block of typed fields at the top of each; the specification says how that folder becomes a knowledge node — a static website plus a graph, a search index, text files for agents and a discovery document — with the same bytes from any implementation. People and agents read a node through ordinary web addresses, change it only by proposals that a person ratifies, and compose its items into a starting harness — files an architect or an agent runtime starts from. Nodes find and cite each other with no server in between.

What is different about it

To the author's knowledge, no other system combines discovery through already-registered web mechanisms with an integrity digest on every artefact link of its discovery document, a typed graph with a published ontology, machine artefacts whose bytes are fixed by expected-byte conformance vectors, governance in which every change — human or agent — arrives as a proposal carrying its provenance and a person ratifies it (directly, or by a standing rule a person recorded in the node's configuration), and composition of the same files into a starting harness, with no server required at any point.

This is a claim about the specification's text and its vectors, not a performance claim. Other systems have some of these properties; the dated comparison is in docs/RELATED-WORK.md.

Beside that combination, and each available elsewhere on its own: six modes of use (docs/plain/modes.md); seven tools on every item page and on `/compose/` for a browser's own agent, identical to the local tool server (AGSC-09-16); eight plugin kinds with a forward-compatibility promise (docs/PLUGINS.md, AGSC-00-24); a content version stamped on every surface (AGSC-04-25); and federation walked by the client, never by a node (AGSC-11-06).

What it is best for

For agents

• Memory for one agent. agsc mcp in a Bundle gives an assistant seven tools to search, read, follow links and cite items by address; nothing leaves the machine (Mode 1, use case L1).
• Shared memory for many agents. Every agent reads the same published files and writes only by proposals a person ratifies (Mode 1, docs/CONNECTORS.md).
• A source of skills. Each cluster becomes one skill pack holding its published items — the procedures are the part an agent follows — with a lockfile of their digests, installable into agent tool folders; skills from other repositories come in as procedures (Mode 3, use case L4).
• A starting harness. A selection of items becomes a harness — seven kinds of file an architect or a runtime can start from; it is not a running system, and no rendering for a particular runtime ships at 1.0 (Mode 4, use case M5).
• A live board for a team of agents. Agents claim and finish tasks on shared boards until they are done; decisions stay with people (Mode 5, use case M1).
• Knowledge across nodes. A client reads several nodes' graph dumps and joins them locally, every foreign result marked with its origin; at 1.0 the walk is a library function of the engine, not a command (Mode 1, use case D4).

For people

• A wiki that corrects itself. Markdown in, a checked and linked site out, with every change reviewed (Mode 0, use case L5).
• A project's living specifications. Decisions, specifications, tasks and gates as one governed memory, and steering files that keep a coding agent on course (Mode 2, use case L3).
• A library of patterns. Concepts with sources and provenance, readable without JavaScript, composable into a starting architecture (Mode 4, docs/USE-CASES.md).
• A team board. A board from GitHub, GitLab, Jira, Trello, Linear, Asana, Notion, Obsidian, Todo.txt or plain Markdown becomes a live board and goes back again (Mode 5, use case M7).

Quick start

From a clone of this repository (Node 22.13 or later):

npm ci                                   # the exact pinned libraries

npm test # the whole suite, offline REPO=$PWD; cp -r tests/fixtures/minimal /tmp/agsc-try && cd /tmp/agsc-try SOURCE_DATE_EPOCH=1767225600 node "$REPO/bin/agsc.js" ci # lint, build twice, compare, verify: "ci: pass"

On a folder of your own Markdown notes (Node 22.13 or later, git, a POSIX shell):

npm install agentic-system-core                          # in a working folder

export PATH="$PWD/node_modules/.bin:$PATH" # puts agsc on the PATH cd my-notes && agsc init # each note gets a header and moves to content/concepts/ mkdir -p .well-known && printf 'Contact: mailto:you@example.org\n' > .well-known/security.txt git init -q && git add -A && git commit -q -m 'my notes' # the build takes its instant from this commit agsc ci # ci: pass (warnings are advice, errors stop) agsc build # the site, the graph and the agent files in www/

Without the security contact ci stops with AGSC-E901; without a commit (or SOURCE_DATE_EPOCH) it stops with AGSC-E204. The Mode 0 guide walks through this with the lines each command prints, and five more guides do the same for the other modes. To connect an assistant, read docs/USING-WITH-ASSISTANTS.md. To teach a coding agent the engine itself, install the agent skill in [skills/agentic-system-core/](https://github.com/andreibesleaga/agentic-system-core/blob/main/sk