Prolog Agent Toolkit

Version: 0.0.1.dev21
Category: AI Assistant Developer Tools / Prolog Language Tooling
Machine-Readable Context: llms.txt | llms-full.txt | codemeta.json

A reusable AI agent skills, coding standards, and multi-engine (Scryer, SWI, Trealla, Tau) safety execution toolkit for Prolog.

Note

Project Status: Active Development & AI-Driven Origin
This toolkit is fully usable today for sandboxed Prolog execution, project scaffolding, library discovery, and guiding AI assistants. However, it remains under active development.

AI-Driven Development: This entire project—including all source code, Python CLI tools, Prolog modules, test suites, documentation, agent skills (.agents/skills/), autonomous subagents (.agents/agents/), rules, and metadata manifests—was developed by prompting AI agents with human architectural steering, review, and automated verification.

This project is currently hosted in the original Architect's GitHub repository. If there is sufficient interest to build a community of users, it likely will be moved to a GitHub Organization so the project is not dependent on one person reviewing Pull Requests.

If you have ideas, feedback, feature suggestions, or want to contribute, please see CONTRIBUTING.md!

🤖 AI Agent Navigation Quick Start

Entering this repository as an AI agent (Google Antigravity, Claude Code, Cursor, Windsurf, GitHub Copilot, or Emacs AI tools)? Key features: reusable agent skills (.agents/skills/), Prolog purity standards (if_/3, dif/2), library discovery (prolog-agent discover), and multi-engine safety execution.

LLM Machine-Readable Index: Read llms.txt and llms-full.txt

Navigation Blueprint & Top 10 Q&A: Read AGENT_GUIDE.md

Coding & Purity Standards: Inspect AGENTS.md and .agents/skills/

Skills & Capabilities Manifest: Inspect docs/skills_manifest.json & docs/capability_manifest.json

Canonical Examples: See examples/ (agent_skills_dispatch.pl, prolog_mcp_server.pl, neurosymbolic_reasoner.pl)

Library Discovery Protocol: See prolog-library-discovery skill or run prolog-agent discover

Directory & File Map: Inspect AGENT_INDEX.json

Component Ontology: Inspect docs/repository_ontology.json

Terminology & Glossary: Read docs/GLOSSARY.md

Anti-Patterns & Reuse: Read docs/ANTI_PATTERNS.md

Category	Supported Technologies / Systems
AI Assistants & IDEs	Google Antigravity, Claude Code, GitHub Copilot, Cursor, Windsurf, Emacs AI (`aidermacs`, `agent-shell`, `gptel`)
Prolog Engines	Scryer Prolog (Default), SWI-Prolog, Trealla Prolog, Tau Prolog, GNU Prolog, Ciao Prolog
Language Standards	ISO Prolog, Definite Clause Grammars (DCG), `CLP(Z)` Constraints, Reification (`library(reif)`)
Agent Capabilities	Execution Sandboxing, `testing.pl` Unit Testing, `bakage` Manifests, Multi-file Release Versioning

Features

Cross-Platform Safety Wrappers: Runs Prolog engines safely with execution timeouts, low CPU priority, and memory limits across Linux, macOS, BSD, and Windows.
CLI Management Suite: Project bootstrapping, module generator, system switcher, release manager, and skill validator via prolog-agent.
System-Aware Standards: Enforces Scryer, SWI, Trealla, Tau, and portable Prolog conventions automatically.
Autonomous AI Subagents & Skills: Pre-configured subagents and skills for purity auditing, automated refactoring, legacy project migration (prolog-migrate-project), unit test generation, benchmark running, and security scanning.

Prolog Agent Framework — Prolog MCP, Skills, & Agent Architecture

The Prolog Agent Toolkit is an end-to-end foundation for building AI agents, Model Context Protocol (MCP) servers, skill dispatchers, and neurosymbolic reasoning systems in pure ISO Prolog.

Why Build Agents in Prolog?

Homoiconic Skills System: Prolog represents code and data identically. Skills, capabilities, tool definitions, and dispatch rules are expressed directly as pure Prolog terms/facts (skill(Name, Capabilities) in .agents/skills/skills.pl), enabling dynamic capability discovery, inspection, and dispatch via call/N.
Pure Declarative Verification: While LLMs generate probabilistic natural language and code, Prolog provides deterministic ground-truth verification via library(reif) (if_/3, dif/2) and CLP(Z) constraint solvers.
Model Context Protocol (MCP) Tool Servers: Expose Prolog knowledge bases, theorem provers, AST parsers, and constraint models as structured MCP tools callable by Claude, Antigravity, Cursor, and custom agent harnesses.
Sandboxed Execution: Safe execution runners (scryer-safe, swi-safe, trealla-safe, prolog-safe) prevent infinite loops, resource exhaustion, and memory leaks.

Canonical Agent Examples

Explore ready-to-run examples in the examples/ directory:

Agent Skill Dispatcher: Homoiconic skill registration, pure DCG message tokenization, and safe goal dispatching.
Prolog MCP Server: Model Context Protocol (MCP) JSON-RPC tool server pattern with schema validation and structured result terms.
Neurosymbolic Reasoner: Ground-truth verification engine proving LLM claims and solving schedule constraints with library(clpz).
Examples Documentation: Guide to running and extending the examples across Scryer, SWI, and Trealla.

Design Philosophy & IDE Interoperability

Goal: Focus exclusively on what is idiosyncratic to Prolog development.

Does this toolkit conflict with general IDE skills or custom skill collections?
No. prolog-agent-toolkit is strictly complementary. IDEs and general agent skill collections (e.g. Antigravity, Claude Code, Cursor, Copilot plugins) handle broad engineering tasks—Git workflows, web application frameworks, databases, and general system scripts.
Where prolog-agent-toolkit fits:
General LLMs often fail on Prolog because training data skews toward imperative coding patterns and non-logical cuts (!). This toolkit steps in specifically where Prolog requires domain expertise:
- Logical Purity: Pure reified conditionals (if_/3), sound term inequality (dif/2), and pure DCGs.
- Prolog Systems & String Types: Enforcing ISO chars lists vs SWI string objects, and explicit module declarations across Scryer, SWI, Trealla, and Tau Prolog.
- Sandboxed Interpreter Safety: Preventing infinite search loops or system resource starvation via resource-capped safety runners (scryer-safe, swi-safe, trealla-safe, prolog-safe).
- Open Standard .agents/ Interoperability: Built on standard Markdown and JSON frontmatter so general IDE skills and Prolog skills coexist without collision.
AI-Driven Development & Provenance: This entire project—including its Python CLI tools, safety wrappers, Prolog modules, unit tests, documentation, agent skills (.agents/skills/), autonomous subagent definitions (.agents/agents/), schema metadata, and Git hooks—was developed through prompting AI agents (pair programming with AI coding assistants such as Google Antigravity and Claude Code). The human developer steered the system architecture, declarative requirements, prompt design, and empirical test verification.

CLI Reference Summary

Command	Purpose
`prolog-agent init <name> [--system scryer\|swi\|trealla\|tau\|iso]`	Scaffolds a new project with `src/`, `tests/`, manifests (`bakage.toml`/`pack.pl`), and starter module.
`prolog-agent template <name> [--system ...]`	Generates a project template for specified system.
`prolog-agent module <name> [--system ...]`	Scaffolds a single pure Prolog module with Covington doc headers.
`prolog-agent init-script`	Generates shell environment configuration script.
`prolog-agent release [--version X.Y.Z]`	Synchronizes versions across project manifests and creates release tags.
`prolog-agent check-version`	Audits version parity across manifest files (`pyproject.toml`, `bakage.toml`, `pack.pl`, `README.md`).
`prolog-agent install-hooks [--hook-type ...]`	Installs executable Git pre-commit / pre-push hooks to enforce version parity and skill validation.
`prolog-agent list-subagents`	Lists available autonomous subagents in `.agents/agents/`.
`prolog-agent validate-skills`	Validates `.agents/skills` integrity and frontmatter structure.
`scryer-safe [args...]`	Runs Scryer Prolog under safety timeout and memory limits.
`swi-safe [args...]`	Runs SWI-Prolog under safety limits.
`trealla-safe [args...]`	Runs Trealla Prolog under safety limits.
`tau-safe [args...]`	Runs Tau Prolog under safety limits.
`prolog-safe [args...]`	Multi-engine generic safety runner (selected via `PROLOG_ENGINE`).

Installation & Setup

1. Prerequisites

Python Package Manager: uv (recommended for tool isolation and high performance).
Target Prolog Engines: At least one supported Prolog interpreter installed on system PATH:
- Scryer Prolog: scryer-prolog
- SWI-Prolog: swipl
- Trealla Prolog: tpl
- Tau Prolog: tau-prolog or Node.js runtime

2. Install CLI Tools with `uv`

Install prolog-agent-toolkit using uv tool to make prolog-agent, scryer-safe, swi-safe, trealla-safe, tau-safe, and prolog-safe globally available on your system PATH.

Important

You must run the uv tool install command from the root directory of the cloned prolog-agent-toolkit repository:

# Must be executed inside the prolog-agent-toolkit repository root directory:
harry@hogwarts:~/code/prolog-agent-toolkit$ uv tool install . --force
Resolved 2 packages in 3ms
Installed 6 executables: prolog-agent, prolog-safe, scryer-safe, swi-safe, tau-safe, trealla-safe

# Or run directly without permanent installation:
harry@hogwarts:~/code/prolog-agent-toolkit$ uv tool run prolog-agent --help

Verify installation:

scryer-safe --help
prolog-agent --help

3. Integrating Agent Rules & Skills with AI Assistants

To ensure rules and skills never get clobbered or overwritten when updating or working inside target repositories, choose one of the following methods:

Option A: Git Submodule Integration (PRIMARY RECOMMENDED METHOD for Repositories & Teams)

Adding the toolkit as a Git submodule ensures every contributor and AI assistant on any machine gets exact skill parity without breaking local files or requiring global configuration:

# Inside your target Prolog project root:
git submodule add https://github.com/dougransom/prolog-agent-toolkit.git .agents-toolkit

# Configure project .agents/skills.json to inherit toolkit skills:
mkdir -p .agents
cat << 'EOF' > .agents/skills.json
{
  "entries": [
    { "path": "skills" },
    { "path": ".agents-toolkit/.agents/skills" }
  ]
}
EOF

# Link root AGENTS.md to submodule rules:
ln -s .agents-toolkit/.agents/AGENTS.md AGENTS.md

Option B: Symlink into Target Project (Recommended for Personal Local Dev)

Symlinking connects your project root directly to a local copy of prolog-agent-toolkit:

# Inside your target Prolog project root:
ln -s /path/to/prolog-agent-toolkit/.agents .agents
ln -s .agents/AGENTS.md AGENTS.md

Option C: Custom Search Paths via `skills.json` (Recommended for Machine-Wide Setup)

Google Antigravity automatically loads rules and skills from both Global Root (~/.gemini/config) and Workspace Root (.agents).

To load skills globally across all projects on your machine without copying files, create ~/.gemini/config/skills.json:

{
  "entries": [
    { "path": "/path/to/prolog-agent-toolkit/.agents/skills" }
  ]
}

Quickstart: Starting a New Prolog Project

Follow this guide to create and develop a brand new Prolog project with AI assistance:

Step 1: Scaffold the Project

Run prolog-agent init specifying your project name and target Prolog engine (default is scryer):

prolog-agent init my_parser --system scryer
cd my_parser

Step 2: Project Layout Overview

The project is bootstrapped with a clean structure, multi-system adapter support, standard testing framework, package manifests, and AI rules:

my_parser/
├── bakage.toml          # Scryer Prolog manifest
├── pack.pl              # SWI manifest & Scryer fallback
├── package.json         # Tau Prolog / npm manifest (optional)
├── AGENTS.md            # AI assistant rules & system guidelines
├── src/
│   ├── core/            # Portable Prolog core (system-agnostic ISO target)
│   │   └── logic.pl
│   ├── adapters/        # System compatibility shims (scryer, swi, trealla, tau)
│   └── my_parser.pl     # Starter module with Covington doc block & DCG/CLP(Z) stubs
└── tests/
    ├── portable/        # Engine-agnostic unit tests
    └── testing.pl       # Scryer testing.pl unit test harness

Step 3: Run Immediate Smoke Tests

Execute tests safely using the engine's safety runner:

scryer-safe -g "use_module(tests/testing), run_tests, halt."

Step 4: Develop with your AI Assistant

Open the project directory in Google Antigravity, Claude Code, Cursor, Copilot, or Emacs (aidermacs/agent-shell). The AI assistant automatically detects .agents/AGENTS.md and applies Prolog agent guidelines, aiming to produce ISO-compliant code subject to engine capabilities.

Example Starter Prompts:

"Implement a pure DCG parser in src/my_parser.pl to parse JSON tokens using library(charsio) and library(reif)."
"Add unit tests in tests/testing.pl for parse_json/2."

Quickstart: Working with an Existing Prolog Project

Follow this guide (or use the prolog-migrate-project skill) to bring safety sandboxing, standard layouts, and autonomous subagents to an existing Prolog codebase.

Tip

Recommended Git Isolation: When performing major restructuring or removing legacy vendor configs, use a separate Git worktree first (git worktree add -b migrate/prolog-agent-toolkit ../my-repo-migrate main) so your existing codebase remains safe until verified.

Step 1: Adopt Agent Rules into Existing Repository

In your existing project root, link or copy .agents:

cd /path/to/my-existing-prolog-repo

# Link .agents and AGENTS.md
ln -s /path/to/prolog-agent-toolkit/.agents .agents
ln -s .agents/AGENTS.md AGENTS.md

Step 2: Select the Target Engine / System

Set the target engine environment variable for your terminal and safety runners:

# For SWI-Prolog base project:
export PROLOG_ENGINE=swi

# For Scryer Prolog base project:
export PROLOG_ENGINE=scryer

Step 3: Use Autonomous Subagents on Existing Code

Ask your AI assistant to audit, refactor, or test existing modules using the built-in subagents in .agents/agents/:

Code Purity & Covington Style Audit:

"Audit src/legacy_module.pl using prolog-purity-reviewer-agent and report non-logical cuts or defaulty representations."
Imperative to Pure ISO-Target Refactoring:

"Refactor cut_heavy_predicate/3 in src/legacy_module.pl to pure if_/3 and dif/2 using prolog-refactor-agent."
Generate Unit Test Suite:

"Generate a unit test suite for src/parser.pl using prolog-test-generator-agent."
Multi-Engine Portability Check:

"Check if src/utils.pl runs across both Scryer and SWI using prolog-portability-reviewer-agent."

Step 4: Run Tests & CI/CD Integration

Run your existing tests safely under memory and timeout guards:

# For SWI-Prolog test suite:
swi-safe -g "run_tests, halt."

# For custom command under generic runner:
PROLOG_TIMEOUT=15s PROLOG_MEMORY_MAX=200M prolog-safe -g "main, halt."

Developer Workflow Flexibility: Packaged/Tested Projects vs. Lightweight REPL & Scratch Use Cases

prolog-agent-toolkit provides scaffolding for structured, package-based projects with unit test suites (src/, tests/, bakage.toml/pack.pl), but you are not forced to write tests or package manifests.

Why the Toolkit Defaults to Tests & Package Manifests

Automated AI Verification: AI coding assistants (Google Antigravity, Claude Code, Cursor, Copilot) perform best when an automated test runner (testing.pl, plunit) is available to empirically verify that generated logic works cleanly without choice-point leaks or syntax errors.
Reproducible Distribution: Manifest files (bakage.toml, pack.pl, package.json) explicitly record module dependencies so projects can be published, installed, and shared across Prolog package managers.

Workarounds for Lightweight, Non-Packaged, or Test-Free Use Cases

If you do not want a formal package structure or test suite (e.g. playing in the top-level REPL, writing quick logic puzzles, single-file scripts, or classroom learning), use one of these lightweight alternatives:

1. Interactive REPL / Top-Level Queries & Persistent Sessions

Launch interactive top-level REPLs or post successive queries safely to a running Prolog interpreter process without losing state between queries:

prolog-agent query "X = 42."                       # Single query execution against top-level (5s default timeout)
prolog-agent query "test_fact(X)." --file src/main.pl # Query after consulting file
prolog-agent repl                                  # Persistent interactive query session
scryer-safe                                         # Interactive Scryer Prolog top-level REPL (runs indefinitely without idle timeout)
swi-safe                                            # Interactive SWI-Prolog top-level REPL

Software agents can also use Python PrologSession (with PrologSession(engine="scryer") as session: session.query("...")) to post queries to a running top-level interpreter:

Indefinite Idle Sessions: Running scryer-safe or swi-safe at the terminal sitting at ?- never times out while idle, protected by memory caps and low CPU priority.
5s Query Timeout & Suspension: Active queries enforce a default 5-second timeout. If a query does not respond within 5s, the process tree is suspended (SIGSTOP), freezing CPU usage to zero while preserving state in memory.
Fibonacci Continuation Progression: In interactive mode, the user is prompted to extend execution by the next Fibonacci interval (8s, then 13s, 21s, 34s...) or kill the query. Resumption uses SIGCONT.
Non-Interactive Execution: Automated runs (CI/CD, scripts) terminate immediately after the initial timeout to prevent runaway background execution.

2. Standalone Single-File & Scratch Scripting

Create single .pl files anywhere without scaffolding a full directory layout:

# Generate a single standalone module with Covington doc headers:
prolog-agent module scratch

# Run any standalone file safely:
scryer-safe scratch.pl
scryer-safe -g "hello(M), write(M), nl, halt." scratch.pl

3. Stripped / Minimal Repositories

If you scaffold a project using prolog-agent init my_app, you can safely delete the tests/ directory or bakage.toml/pack.pl manifest files if your project does not need automated testing or package distribution. The safety runners (scryer-safe, swi-safe, prolog-safe) execute code independently of any project layout or test harness.

Standard Prolog Folder Architecture & Multi-System Layout

When organizing Prolog software—especially repositories supporting multiple package managers (bakage, pack_install, npm) or multiple systems (Scryer, SWI, Trealla, Tau)—adhere to the following canonical layout:

my_prolog_project/
├── .agents/                        # AI Assistant rules & skill references (symlink or dir)
│   ├── AGENTS.md                   # Project rules & system conventions
│   └── skills/                     # Engine & tool skills
├── src/                            # Source Code Directory
│   ├── core/                       # Portable Prolog Core (system-agnostic ISO target)
│   │   ├── logic.pl                # Pure DCGs, term relations, CLP constraints
│   │   └── types.pl                # Functor data representations
│   ├── adapters/                   # System Shims & Library Normalization
│   │   ├── scryer/compat.pl        # Imports library(charsio), library(reif), library(clpz)
│   │   ├── swi/compat.pl           # Imports library(clpfd), plunit, SWI shims
│   │   ├── trealla/compat.pl       # Trealla compatibility shims & FFI
│   │   └── tau/compat.pl           # Tau DOM & JS interoperability hooks
│   └── my_prolog_project.pl        # Main module entry point
├── tests/                          # Test Suites Directory
│   ├── portable/                   # Engine-Agnostic Goal Assertions
│   │   └── test_core.pl            # Pure goal assertions (must_succeed/1)
│   ├── scryer/                     # Scryer Prolog Test Harness
│   │   └── test_scryer.pl          # Uses library(testing) / testing.pl
│   ├── swi/                        # SWI-Prolog Test Harness
│   │   └── test_swi.pl             # Uses library(plunit)
│   └── js/                         # Tau Prolog JS Integration Tests
│       └── test_tau.test.js        # Jest / Vitest harness
├── bakage.toml                     # Scryer Prolog bakage manifest
├── pack.pl                         # SWI-Prolog pack manifest & Scryer fallback
├── package.json                    # Tau Prolog / npm manifest (optional)
├── AGENTS.md                       # Workspace root AI agent instructions
├── README.md                       # Human-facing project documentation
├── CHANGELOG.md                    # Release history
└── LICENSE                         # Open-source license

Key Architectural Principles

Multi-Manifest Co-existence: Package manifests (bakage.toml, pack.pl, package.json, pyproject.toml) have distinct filenames and co-exist at the repository root without conflict. This allows publishing the project across multiple ecosystems simultaneously.
Core vs. Adapter Decoupling:
- src/core/: Contains portable Prolog logic aiming for ISO compliance (pure DCGs, dif/2, reified if_/3). Free of engine-specific imports or extensions.
- src/adapters/: Contains thin engine-specific compatibility shims that normalize system variations (library(clpz) vs library(clpfd)).
Multi-Runner Test Hierarchy:
- tests/portable/: Goal assertions executable on any conforming Prolog engine.
- tests/scryer/: Scryer unit tests using library(testing).
- tests/swi/: SWI-Prolog unit tests using library(plunit).
- tests/js/: JavaScript integration tests querying Tau Prolog via Node.js test runners.
Optional make packages Target: Projects can define clean Makefile packaging recipes (package_bakage, package_swi, package_npm, package_python) so make packages creates distribution archives (dist/) for every configured package manager.

Safety Sandboxing & Runtime Flags

Control safety thresholds dynamically using environment variables:

# Set custom execution timeout and memory cap
PROLOG_TIMEOUT=10s PROLOG_MEMORY_MAX=128M scryer-safe -g "my_pred, halt."

# Run SWI-Prolog under safe wrapper
swi-safe -g "writeln('SWI Safe Mode'), halt."

# Switch engine dynamically
PROLOG_ENGINE=trealla prolog-safe -g "write('Hello Trealla'), nl, halt."

Onboarding an Additional Prolog System

To add support for a new Prolog engine or system target (such as GNU Prolog, Ciao, ECLiPSe, B-Prolog, Ichiban, or YAP) to the toolkit, use the interactive Engine Onboarding Workflow:

.agents/skills/prolog-engine-onboarding/SKILL.md

Prompt your AI assistant to start the interactive onboarding process:

"Use prolog-engine-onboarding skill to guide me through adding support for GNU Prolog (gprolog) to this toolkit."

Onboarding Steps Summary

The interactive workflow guides you through 6 iterative phases:

Information Gathering: Collects CLI binary names (gprolog, ciao, yap), supported standard features, string representations (chars/codes/string), import syntax, and runner flags.
System Standards & Cheat Sheet Creation: Generates .agents/skills/<engine>-prolog-standards/SKILL.md containing explicit :- use_module(library(...)). headers, exported predicate tables, and system autoload rules.
Safety Runner & CLI Entry Point: Updates runner.py, cli.py, and pyproject.toml to register <engine>-safe.
Project Initializer & Scaffolding: Updates prolog-agent init and prolog-agent template options for --system <engine>.
Metadata & Agent Rules: Updates .agents/AGENTS.md, README.md, codemeta.json, and pyproject.toml.
Automated Verification & Review: Runs unit tests (pytest) and skill validation (prolog-agent validate-skills), asking clarifying questions iteratively until you confirm onboarding is complete.

Programmer Guidelines: Working with AI for Prolog

For full guidelines, see .agents/references/programmer_guidelines.md.

When working with AI coding assistants (Google Antigravity, Claude Code, Cursor, Copilot, Emacs aidermacs/gptel) on Prolog software:

Provide Semantics & AST Shapes, Not Logic Invention: Give the AI module skeletons, AST constructors, and type invariants instead of asking it to invent relations from scratch.
Specify Mode & Determinism Contracts Explicitly: State input/output modes (+/-) and determinism requirements (det, semidet fail cleanly, nondet backtracking).
Use Test-First Prompting: Provide expected test cases (testing.pl, plunit, or test runner) first, then request code satisfying those tests.
Enforce the Declarative Mindset: Explicitly prompt: "Do not use imperative reasoning. Use declarative reasoning based on unification, constraints, and backtracking."
Delegate DCG & Structural Boilerplate: Let AI handle grammar production rules, AST building, and string formatting.
Use AI for Refactoring & Choice-Point Audits: Ask AI to identify choice points, make code tail-recursive, or transform cut-heavy logic into pure forms (dif/2, if_/3).

Customizing & Overriding Code Generation Defaults

If you have specific preferences, coding standards, or reference examples for how you like Prolog code generated that complement or override this toolkit's defaults, you can describe them using 5 standard customization layers:

Workspace Rules (.agents/AGENTS.md or .agents/rules/*.md): Define project-wide coding style rules and canonical code examples. Checked into Git so all team members and AI assistants share the same guidelines.
Custom Project Skills (.agents/skills/<name>/SKILL.md): Create targeted skills containing domain-specific patterns, AST schemas, or sample .pl implementations in an examples/ subfolder.
Global Machine Rules (~/.gemini/config/AGENTS.md or ~/.gemini/config/rules/): Set personal preferences across all local projects without modifying repository files.
Interactive Prompt Steer & AST Specifications: Pass explicit term constructors (e.g. lit(Chars) vs list tuples), mode annotations (+/-), determinism requirements (det/semidet), or test harnesses (testing.pl) directly in your prompt text.
Persistent Learning (/learn): Use the /learn slash command after refining a generated snippet so the assistant persists the new style rules for future interactions.

Example Workspace Rule (`.agents/rules/prolog_style.md`)

# Custom Prolog Code Style Standards

## Rule: Prefer Clean AST Functors over Tagged Lists
Always represent abstract syntax trees with explicit principal functors rather than ad-hoc lists or tuples.

### Preferred Example:
lit(Chars)
seq(Left, Right)
alt(Left, Right)

### Prohibited Example:
[lit, Chars]
[seq, Left, Right]

Precedence Hierarchy

Workspace Rules & Custom Skills (.agents/)   [Highest - Overrides toolkit defaults]
   ↓
Global User Rules (~/.gemini/config/)
   ↓
Toolkit Built-in Standards & Defaults         [Lowest]

Applying this Architectural Pattern to Other Programming Languages

While prolog-agent-toolkit is tailored specifically for multi-engine Prolog software, its underlying 4-layer architectural blueprint can serve as inspiration for developers wanting to build similar AI-agent toolkits for other programming language ecosystems (such as Lisp, Erlang, Elixir, Scheme, Haskell, Python, Rust, or C++):

flowchart TD
    A["1. Resource Sandboxing Layer (<lang>-safe)"] --> B["2. Pre-Code Discovery Layer (<lang>-agent discover)"]
    B --> C["3. Declarative Rules & Skills Layer (.agents/)"]
    C --> D["4. Automated Verification & Diagnostics Layer"]

The 4-Layer Agent Toolkit Blueprint

Resource Sandboxing Layer (<lang>-safe):
- A lightweight execution wrapper around the language runtime (REPL or script runner) enforcing CPU timeouts, RAM caps, and execution priority to protect host environments when AI agents execute untrusted code.
Pre-Code-Generation Discovery Layer (<lang>-agent discover):
- A CLI/API mechanism that queries installed modules, standard libraries, and package manifests before code generation so AI assistants reuse built-in capabilities instead of writing custom code.
Declarative Rules & Skills Layer (.agents/):
- A vendor-neutral .agents/ folder containing root AGENTS.md steering rules, system cheat sheets, and subagent workflow guidelines compatible across any AI coding assistant.
Automated Verification & Diagnostics Layer:
- Automated syntax checkers, linters, and test runners (testing.pl, pytest, cargo check, hlint) that provide immediate empirical feedback to the AI assistant to confirm code correctness.

Release & Versioning Workflow

Canonical Version Source: pyproject.toml is the canonical version source of truth.
Synchronize Releases: Run prolog-agent release [--version X.Y.Z] to synchronize pyproject.toml, bakage.toml, pack.pl, README.md, and CHANGELOG.md.
Git Tagging: Official releases match Git annotated tags (e.g., v0.0.1).

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, testing guidelines, pull request workflows, and the checklist for onboarding new Prolog engines.

Name		Name	Last commit message	Last commit date
.agents		.agents
.github		.github
docs		docs
examples		examples
prolog_agent_toolkit		prolog_agent_toolkit
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
AGENT_GUIDE.md		AGENT_GUIDE.md
AGENT_INDEX.json		AGENT_INDEX.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
codemeta.json		codemeta.json
llms-full.txt		llms-full.txt
llms.txt		llms.txt
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

Prolog Agent Toolkit

🤖 AI Agent Navigation Quick Start

Features

Prolog Agent Framework — Prolog MCP, Skills, & Agent Architecture

Why Build Agents in Prolog?

Canonical Agent Examples

Design Philosophy & IDE Interoperability

CLI Reference Summary

Installation & Setup

1. Prerequisites

2. Install CLI Tools with uv

3. Integrating Agent Rules & Skills with AI Assistants

Option A: Git Submodule Integration (PRIMARY RECOMMENDED METHOD for Repositories & Teams)

Option B: Symlink into Target Project (Recommended for Personal Local Dev)

Option C: Custom Search Paths via skills.json (Recommended for Machine-Wide Setup)

Quickstart: Starting a New Prolog Project

Step 1: Scaffold the Project

Step 2: Project Layout Overview

Step 3: Run Immediate Smoke Tests

Step 4: Develop with your AI Assistant

Quickstart: Working with an Existing Prolog Project

Step 1: Adopt Agent Rules into Existing Repository

Step 2: Select the Target Engine / System

Step 3: Use Autonomous Subagents on Existing Code

Step 4: Run Tests & CI/CD Integration

Developer Workflow Flexibility: Packaged/Tested Projects vs. Lightweight REPL & Scratch Use Cases

Why the Toolkit Defaults to Tests & Package Manifests

Workarounds for Lightweight, Non-Packaged, or Test-Free Use Cases

1. Interactive REPL / Top-Level Queries & Persistent Sessions

2. Standalone Single-File & Scratch Scripting

3. Stripped / Minimal Repositories

Standard Prolog Folder Architecture & Multi-System Layout

Key Architectural Principles

Safety Sandboxing & Runtime Flags

Onboarding an Additional Prolog System

Onboarding Steps Summary

Programmer Guidelines: Working with AI for Prolog

Customizing & Overriding Code Generation Defaults

Example Workspace Rule (.agents/rules/prolog_style.md)

Precedence Hierarchy

Applying this Architectural Pattern to Other Programming Languages

The 4-Layer Agent Toolkit Blueprint

Release & Versioning Workflow

Contributing

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2. Install CLI Tools with `uv`

Option C: Custom Search Paths via `skills.json` (Recommended for Machine-Wide Setup)

Example Workspace Rule (`.agents/rules/prolog_style.md`)