agentic-praxis-grimoire

README

Agentic Praxis Grimoire

What is Agentic Praxis Grimoire?

Agentic Praxis Grimoire (APG) is a provider-neutral toolkit and skill corpus for bounded agent engineering. It gives coding-agent systems reusable, deterministic primitives for selecting task guidance, collecting evidence, resolving curated environments, and inspecting repository structure without dictating an orchestration workflow.

APG includes:

• reusable Go packages for schemas, reports, skill bundles, environment snapshots, and hotspot analysis;
• the apgr command-line interface;
• 39 canonical agent skills that can be selected for one task;
• canonical reporting and evidence formats;
• thin Python and npm compatibility/distribution adapters; and
• repository-maintenance tools used to develop APG itself.

APG is not an autonomous orchestrator. It does not choose a model, reviewer, roadmap, retry policy, or authorization boundary. Orchestrators such as Joint Agentic Command Aegis (JACA) decide when and how to invoke APG.

Why use APG?

APG separates reusable engineering mechanics from provider and workflow policy. That makes the mechanics easier to embed, test, reproduce, and audit.

• Small task context. Select only the relevant skills instead of injecting a global corpus into every agent session.
• Deterministic evidence. Produce canonical Git, diff, and operational records with stable identities.
• Embeddable primitives. Call public Go packages in-process without launching apgr, Python, or a shell.
• Explicit environment inputs. Capture an allowlisted, non-secret environment and resolve it with recorded provenance.
• Honest structural signals. Rank repository hotspots while distinguishing deep metrics, structural metrics, and unavailable capabilities.
• One portable semantic owner. Keep portable behavior in Go while Python and npm remain thin compatibility front doors.

Concrete use cases

Use APG to:

• expose the Markdown and pytest guidance needed for one coding task, and nothing else;
• generate deterministic commit or worktree evidence for a review;
• consume report records directly from a Go service or JACA adapter;
• capture a curated build environment once and resolve it in-process later;
• identify complex or structurally important files before a bounded refactor;
• use the same apgr interface from a source checkout, Go build, Python package, or npm package; and
• retain APG-specific repository checks without moving portable semantics back into Python.

APG does not generate autonomous refactoring plans, analyze Git growth or churn, choose a model, or advance a roadmap.

Quick start

The latest published release is v0.6.0. The source tree currently contains a locally qualified v0.7.0 release candidate that is not yet published to GitHub, PyPI, npm, or Go-module readback.

To try the v0.7 candidate safely from a source checkout, use Go 1.25:

go run ./cmd/apgr --help
go run ./cmd/apgr skills list
go run ./cmd/apgr skills context-report

These commands read the embedded corpus and do not modify a global skill root. To scan the current checkout without executing its source:

go run ./cmd/apgr --repository "$PWD" analyze hotspots \
  --include-path cmd/apgr --format terminal

The scanner requires an absolute physical repository path, stays beneath that root, and does not follow symlinks.

For the published v0.6 Python release:

python -m pip install "agentic-praxis-grimoire==0.6.0"
apgr --version

Do not use a v0.7 PyPI or npm install command yet. Publication belongs to the later release phase.

Install and consumption choices

Go library

The module path is:

github.com/Knowledge-Forge-AI/agentic-praxis-grimoire

Its public root packages are:

• schema — shared version and envelope constants;
• report — canonical Show, Diff, Operational, parsing, and optional publication APIs;
• skills — embedded corpus, deterministic resolution, and isolated materialization;
• envsnap — strict profiles, snapshots, storage, loading, and resolution; and
• hotspot — bounded structural analysis, stable models, and renderers.

JACA-style consumers should import these packages directly. See the Go library reference.

Go CLI

cmd/apgr exposes these principal command families:

apgr build-info
apgr report ...
apgr skills ...
apgr env ...
apgr analyze hotspots ...
apgr response ...

The CLI is an adapter over the same Go owners. Repository-maintenance commands and compatibility routes are documented separately in the CLI reference.

Python

The Python distribution remains agentic-praxis-grimoire, with the apgr console entry point and python -m agentic_praxis_grimoire.

In the v0.7 packaging model, portable commands delegate to a verified bundled Go binary. Python continues to own APG repository and host maintenance where that behavior is intentionally not portable. The v0.7 platform wheels and source distribution are locally qualified candidate artifacts, not live PyPI packages.

npm

The accepted v0.7 candidate architecture defines:

• @knowledge-forge-ai/apgr;
• @knowledge-forge-ai/apgr-darwin-arm64;
• @knowledge-forge-ai/apgr-linux-x64; and
• @knowledge-forge-ai/apgr-linux-arm64.

These packages are not published yet. The JavaScript launcher selects and verifies a same-version platform package, forwards exact arguments with no shell, and owns no APG semantics.

Nix and host integration

Nix, shell composition, and host activation are consumer layers. They may package or activate APG, but they do not own APG runtime semantics. This documentation phase changes no Nix configuration, .flakes state, active installation, or host integration.

See APG v0.7 distribution for the target matrix, artifact architecture, verification, and publication boundary.

Core concepts

Canonical skill corpus

APG has 39 canonical leaves: 14 stable and 25 provisional. Canonical Markdown under skills/ is the maintained body authority; embedded metadata and package resources are verified projections of it.

Explicit, task-scoped selection

The structured resolver uses explicit skill IDs and closed, versioned facts. It selects only exact owners. Composition edges describe relationships among already selected skills; they never create an implicit mandatory profile chain.

Resolved bundles can remain in memory or be materialized beneath a caller-owned, disposable root. APG never injects a bundle into a global skill root. See skill context bundles.

Reproducible context budgets

APG measures descriptions, bodies, fixed prompt overhead, and initial context in bytes. It fails closed on an exceeded bound rather than truncating a description or silently dropping a skill. Provider-specific tokenization and provider limits remain consumer-owned.

Evidence and reporting

Canonical report records carry versioned schemas, stable IDs, deterministic bytes, and caller-owned evidence copies. The Go API supports in-memory use; optional outbox publication adds owner-only paths, bounded locking, recovery, and atomic replacement. See the reporting reference.

Environment snapshots

Environment profiles are strict and allowlisted. Secret-like names are rejected, snapshot storage is owner-only, and canonical JSON records values with validators and provenance. Isolated resolution starts empty; Overlay explicitly adds a caller-owned base. See the environment snapshot guide.

Hotspot analysis

The analyzer reports deep Go metrics and honest structural or unavailable capability levels for other supported surfaces. It does not execute target source, follow symlinks, or inspect Git history. Rankings are deterministic within one report. See the hotspot guide.

Strangler and compatibility architecture

Portable report, skill, environment, hotspot, and response behavior has one Go semantic owner. Python and npm adapters locate, verify, and invoke that owner. APG-specific repository or host maintenance remains Python-owned where the boundary is explicit.

Provider neutrality and safety boundaries

APG has no model or provider selection authority. Normal Go process adapters use exact argument vectors and no shell. Task skills use isolated roots rather than global context injection. Environment snapshots reject secret-like names. Report and response publication use bounded path, mode, locking, and atomicity checks. These are concrete safety properties, not a claim of formal security assurance.

JACA and library integration

APG supplies deterministic engineering primitives and guidance. JACA supplies orchestration: attempts, sequencing, provider selection, retries, authorization, evidence lifecycle, and decisions about what to do next.

The intended dependency points one way:

JACA-owned adapter
    -> APG public Go package

APG never imports JACA or accepts JACA protocol types. A JACA adapter passes a context.Context and structured APG requests, then translates returned APG models and bytes into JACA-owned evidence.

The public module is ready for this integration shape, but real cross-consumer JACA qualification remains future readiness work. This documentation phase does not modify JACA. See the APG–JACA integration boundary.

Documentation

Start with the task-oriented documentation index.

• CLI reference
• Go library reference
• Skill context bundles
• Environment snapshots
• Hotspot analysis
• Distribution and packaging
• APG–JACA integration
• Project model and governance
• Roadmaps and current status
• Development releases and phases

Project status

• Latest published release: v0.6.0
• Development version: v0.7.0 release candidate
• Candidate corpus: 39 canonical / 39 catalog / 39 projections / 39 discoverable
• Maturity: 14 stable / 25 provisional
• Readiness: qualified for APG103 publication
• Publication: pending separately authorized APG103 publication and immutable readback

The exact v0.7 candidate is locally qualified across Go, Python, npm, JACA, selected-only agent discovery, all three target binaries, historical reconstruction, and rollback, but no v0.7 GitHub release, PyPI release, npm release, or Go module readback exists yet. See the v0.7 roadmap, status index, skill catalog, and known language-profile debt.

Contributing and licensing

Read CONTRIBUTING.md before proposing changes. Contributors must follow the project's authority, provenance, testing, and review boundaries, and contribution may require the Contributor License Agreement.

APG is available under GNU GPLv3 or a separately negotiated commercial license. Required third-party notices are recorded in NOTICE.