Agentic Praxis Grimoire (APG) is a modular engineering operating model for coding agents. It curates practices that improve planning, implementation, testing, debugging, review, delivery, and coordination without turning one source methodology into a universal workflow.
Public APG v0.4.0 contains twenty-eight skills, projection and reporting components, source-specific release and user-lifecycle validation, governance, and licensing terms. Fourteen catalog rows are stable and fourteen remain provisional; release inclusion does not change maturity. v0.4.0 appends one intentionally squashed release commit and an annotated tag to the preserved v0.1.0 through v0.3.0 history. Its canonical public checkout supplies the maintainer’s separately managed user-global Codex integration. Private development history remains distinct.
APG0 through APG8 are the closed v0.1 development epic, with each historical terminal outcome preserved, including APG3’s blocked result. The epic established the project, bootstrap maturity model, six skills, repository discovery, dogfooding, project-local projection and rollback, and RepoMap managed adoption. The maintainer subsequently decommissioned Superpowers, and a bounded fresh RepoMap smoke passed after decommission. APG9 closes that epic, reconciles current state, and accepts the APG10 through APG14 v0.2 roadmap in ADR 0006.
APG10 accepts that closeout, resolves the experimental guideline source’s provenance and reuse boundary, and records its final dispositions in ADR 0007. Frozen scenarios found current assumption, alternative, traceability, and speculative-scope behavior adequate. They demonstrated one narrow gap for locally owned code or test artifacts made unnecessary by the authorized change, which received one independently reviewed implementation-discipline correction. No seventh skill or maturity change was introduced.
APG11 accepts ADR 0008, establishes the skill authoring and maintenance guide, adds a dependency-free read-only mechanical skill-library checker, and closes the former candidate-theme queue through the legacy roadmap ledger. It changes no skill leaf or maturity state. APG11A’s accepted lexical correction then closes required-key shadowing and fenced-code false negatives without changing that architecture.
APG12 accepts ADR 0009, adds an exact non-private public surface policy, and supplies separate dependency-free commands for reproducible local public candidates and state-owned user-scope skill links. Its executable regression detects the public v0.1.0 omitted-wrapper class. Disposable candidate and user lifecycle dogfood leave the public repository and active integration unchanged. APG12A subsequently corrects public-lineage and read-only validation defects without reopening that architecture.
APG13 accepts ADR 0010
after individual historical inventories, frozen current applications, complete
regression, and fresh non-author reviews. All six current catalog entries are
stable; every canonical leaf remains byte-identical to the APG12A baseline.
APG14 corrects two APG9 evidence labels without changing those dispositions,
publishes the exact non-private v0.2.0 projection, and fast-forwards the active
public-backed source without changing its integration ownership shape. Public
v0.1.0 remains historical and unchanged. Stability and publication do not
establish clean comparative superiority, production warranty, universal
applicability, or automatic invocation. Superpowers remains retired. The
maintainer subsequently completed the requested full Codex restart and
fresh-session discovery smoke and reported that it passed.
APG15’s capability-oriented, synthesis-first v0.3 architecture is accepted in ADR 0011. APG16 adds one provisional public workflow router for ambiguous selection, routing audit, and capability-health diagnosis. It routes to one smallest sufficient stable process leaf or none; it is not a session bootstrap, mandatory chain, action authority, or procedure owner. The maintainer’s later fresh-session observation closes its duplicate-name discovery request.
APG17 accepts
ADR 0013
and adds one provisional synthesizing-repository-guidance leaf. It classifies
mixed guidance into bounded owners, rights, privacy, migration, and rollback
dispositions before any rewrite. It does not author the resulting artifact,
mirror private sources, migrate root guidance, remove private skills, or grant
implementation authority. APG18 accepts
ADR 0012,
adds the normative language-profile contract and one provisional
python-language-profile, and preserves the six-skill public v0.2 lifecycle.
APG19 accepts separate shell-language and test-harness ownership, adds
provisional Bash, Bats, and Zsh profiles, and defers ZUnit on current
source/runtime evidence.
APG19A accepts that substantive result and adopts semantic phase identity, independent ADR and exit sequences, semantic durable references, and precommit record finalization in ADR 0015. Its focused audit corrects Bats test counting for the runner-supported comment function form without changing thresholds, maturity, catalog shape, the six-skill v0.2 lifecycle, or the APG23/APG24 smoke deferral.
APG20 truthfully defers independent Go and Ruby profile candidates after fresh
review identifies material semantic, measurement, source-license, and dogfood
defects beyond its correction allowance. APG20A accepts that defect ledger,
corrects the report-lock race exposed by APG20’s retry, and retains corrected
Go and Ruby profiles as provisional development skills. APG21 accepts separate
Nix, PostgreSQL, and SQLite ownership under
ADR 0016
and retains PostgreSQL and SQLite as provisional profiles. Nix is
deferred-material-defect after its corrected candidate exposes a second
behavior-bearing contradiction. APG21A corrects that retained defect ledger,
retains Nix provisionally, and applies one bounded PostgreSQL false-escalation
correction. Private development now contains nineteen skills and projections:
six stable process skills and thirteen provisional v0.3 skills before APG23. The router map
contains eighteen routable non-router entries. No generic SQL owner,
root or private cutover, or v0.3 release is implemented.
APG22 records 35/35 matched read-only router, retained-profile, and guidance- synthesis dogfood cases across APG, RepoMap, and public-safe synthetic boundaries. It finds no behavior-bearing APG defect and proposes no APG root reduction. The guidance-migration proposal keeps target-specific and private guidance with its current owner and requires distribution, shadow, discovery, override, rollback, and target acceptance before any later cutover. The v0.3 release-scope ledger records APG22A’s retained approved-roadmap manager-assignment owner and APG22B’s exact ZUnit v0.8.2 with Zsh 5.9.2 profile. The unsupported 5.3.1 pair and every unverified range remain excluded. No cutover, decommission, public release, active-integration change, or application smoke occurs.
APG22C subsequently corrects the ZUnit harness’s selected user-startup evidence. Matched positive, negative, and in-runner controls retain the exact 5.9.2 support boundary and the 5.3.1 unsupported result without changing a skill, maturity row, catalog shape, public v0.2, or active integration.
APG23 completes the required fresh-session discovery and explicit-use smoke, records independent maturity and release-inclusion decisions for all thirteen v0.3 skills, and accepts all thirteen for v0.3. Eight rows are promoted to stable and five remain provisional, producing fourteen stable and five provisional development rows. Public v0.2, schemas, managed defaults, and the active integration remain unchanged. APG24 is the only remaining v0.3 phase and separately owns candidate construction and publication.
APG24 accepts ADR 0019, publishes all nineteen skills as v0.3.0, expands new project defaults and source-specific user transitions while retaining schema version 1, and fast-forwards the active public-backed source without changing its aggregate link ownership. Public v0.2.0 remains unchanged. The personal same-name router remains installed for a source-qualified fresh-session shadow; no root/private cutover, router decommission, or successor phase is authorized.
APG24A records the maintainer-reported successful public-v0.3 fresh-session shadow and the later personal-router decommission performed under separate human authority. Focused verification confirms unchanged public and active v0.3.0 state, nineteen aggregate skills, preserved personal transition targets, and an exact private restoration source. v0.3 is terminal; APG24A changes only documentation and publication-excluded evidence.
APG25 accepts structured project defaults, testing and coverage policy, a Python-first reporting architecture, ChatGPT-manager topology, and the v0.4 roadmap through ADRs 0020-0022. One bounded correction makes approved-roadmap assignments consume repository defaults and state deviations rather than repeat ordinary procedure. No skill is added, tool is converted, test is migrated, ChatGPT leaf is moved, personal skill is changed, or release is begun.
APG26 adds provisional pytest-test-profile and
converting-bash-scripts-to-python private-development capabilities after
current-source calibration, sixty frozen scenario families, failing-first
focused tests, read-only report-tool dogfood, and fresh review. Development is
now 21 canonical skills, 21 catalog rows, 21 relative projections, 14 stable
rows, 7 provisional rows, and 20 routable non-router capabilities. Public and
active v0.3.0 remain unchanged at nineteen skills; no report tool is converted,
no git-diff-report is implemented, and no test is migrated.
APG26A records that APG26’s formal-phase commit contains only its subject and
corrects forward without rewriting APG26. The dependency-free Python
apg-check-phase-commit-message command rejects that regression and validates
the required phase subject plus ordered Scope, Result, Verification, and
Not run sections before and after new APG formal-phase commits. No skill,
maturity, release, active integration, report executable, or report format
changes in APG26A.
APG27 accepts the design in
ADR 0023
and produces a partial, uncommitted standard-library libexec/agent_report
candidate. The Python
git-show-report preserves version-2 bytes on the characterized POSIX
platform, git-diff-report adds deterministic drift-checked uncommitted state
evidence through a private index, and append-operational-report enforces exact
same-report Git show/diff association. The phase stops partial before commit
because the development release checker does not retain immutable v0.3.0
policy as a historical surface and the Python profile retains a Red branch
signal. GitPython is not selected, the pytest migration remains deferred, and
the published and active v0.3.0 objects remain unchanged.
APG27A preserves that partial result, freezes immutable v0.3.0 policy independently from the current development inventory, decomposes the Red path- safety owner without changing diagnostics, and adopts the corrected report core. Focused parity, safety, association, historical-release, and independent review gates pass. APG27A does not begin the pytest migration or change public or active v0.3.0.
APG28A subsequently adopts the corrected pytest migration after preserving APG28’s Partial result, and APG29 aligns the affected process owners with the adopted structured-project and test defaults.
APG30 implements ADR 0022’s first actor-qualified namespace. The new
provisional chatgpt-manager-workflow subrouter and the unchanged
composing-approved-roadmap-assignments leaf are canonical under
skills/chatgpt/, while both retain flat .agents/skills/<name> discovery
links. Development is 22/22/22 with fourteen stable and eight provisional
rows. The general map has nineteen ordinary non-ChatGPT leaves plus the
subrouter; the ChatGPT-local map has the one manager leaf. Public and active
v0.3.0 remain immutable at 19/19/19. Application discovery and every personal
skill transition remain behind APG31’s mandatory restart gate.
APG31 passes that fresh-session topology gate and independently shadows three personal hygiene capabilities against current APG and repository owners. The personal docs-only capability is decommissioned after replacement, restoration, and non-author review. Git-history scope reduction and RepoMap phase-hygiene decommissioning remain deferred because their current private routing boundaries cannot be corrected within APG31 authority. Development remains 22/22/22, router maps remain exact, and public and active v0.3.0 remain unchanged. A fresh-session post-transition discovery smoke is still required.
APG31A records that later smoke as passed while preserving APG31’s historical
Partial result. It completes the two deferred dispositions:
git-history-hygiene is scope-reduced after generalized behavior returns to
APG and repository owners, and repomap-phase-hygiene is decommissioned after
generalized behavior returns to current RepoMap owners. APG development and
public/active v0.3.0 remain unchanged.
APG32 retains the provisional minitest-test-profile after current Minitest,
Ruby, and extracted mock calibration; thirty-six frozen trigger, non-trigger,
semantic, structural, and stop families; a failing-first mirrored contract; and
fresh non-author review. One bounded correction makes fixture alternatives and
Minitest-specific boundary effects explicit while preserving existing general,
Ruby, and repository owners. Development becomes 23/23/23 with fourteen stable
and nine provisional rows. The general map has twenty-one edges; the
ChatGPT-local map remains one edge. Public and active v0.3.0 remain immutable
at 19/19/19. No dependency, framework selection, readiness, smoke, release,
publication, or successor phase is included.
APG33 retains the provisional dockerfile-profile after current Dockerfile
frontend, BuildKit, Docker documentation, and OCI image-configuration
calibration; forty frozen trigger, non-trigger, semantic, structural, and stop
families; a failing-first mirrored contract; and fresh non-author review. The
profile owns Dockerfile-specific parser, stage, instruction, context, copy,
mount, cache, user, metadata, and platform judgment while preserving image,
dependency, runtime, release, and live-operation authority. Development becomes
24/24/24 with fourteen stable and ten provisional rows. The general map has
twenty-two edges; the ChatGPT-local map remains one edge. Public and active
v0.3.0 remain immutable at 19/19/19. No Docker build, container, daemon,
registry, readiness, smoke, release, or publication action is included.
APG34 retains the provisional vagrantfile-profile after current Vagrant
source and documentation, configuration-load, Ruby-compatibility, box,
provider, plugin, network, synced-folder, provisioner, trigger, and state
calibration; forty frozen trigger, non-trigger, semantic, structural, and stop
families; a failing-first mirrored contract; one bounded source-semantics and
machine-measurement correction; and fresh non-author review. The profile owns
Vagrantfile-specific configuration judgment while preserving provider, box,
plugin, host, network, filesystem, command, lifecycle, release, and
live-operation authority. Development becomes 25/25/25 with fourteen stable
and eleven provisional rows. The general map has twenty-three edges; the
ChatGPT-local map remains one edge. Public and active v0.3.0 remain immutable
at 19/19/19. No Vagrantfile evaluation, box or plugin mutation, provider
contact, machine lifecycle, readiness, smoke, release, or publication action
is included.
APG38 retains provisional go-test-profile and go-cmp-test-profile after
independent current-source review, 66 public-safe
scenario families, categorical corpus calibration, isolated Go 1.25.10
compatibility probes, and fresh corrected-state review. ADR 0026 accepts two
directly triggerable Go component owners without a stack owner.
matryer-is-test-profile and nix-test-profile are deferred and absent after
new post-correction attribution/false-escalation and FreeBSD sandbox-default
defects. Development becomes 27/27/27 with fourteen stable and thirteen
provisional rows. The general map has twenty-five edges; the
ChatGPT-local map remains one edge. Public and active v0.3.0 remain immutable
at 19/19/19. No Nix execution, target-repository test, readiness, smoke,
release, publication, deployment, or successor phase is included.
APG40 independently integrates the APG39 replacements. nix-test-profile
passes exact Nix 2.35.1 and pinned Nixpkgs/NixOS 26.05 source review, forty
corrected public-safe scenarios, source-only structural calibration, one
coherent correction cycle, and fresh non-author review, then begins
provisional. matryer-is-test-profile is deferred-material-defect after
corrected-state review finds its equality mechanism still inaccurate. ADR
0027 is Rejected; ADR 0026 remains Accepted and controlling; no
go-testing-stack exists. Development becomes 28/28/28 with fourteen stable
and fourteen provisional rows, twenty-six general-map entries, one
ChatGPT-local entry, and twenty-seven checked route edges. Public and active
v0.3.0 remain immutable at 19/19/19.
APG41 closes the v0.4 development surface with all fourteen provisional rows
retained and unpromoted. Cross-profile dogfood preserves direct owner
selection and no mandatory chain; one bounded correction makes the Minitest,
Dockerfile, and Vagrantfile removal descriptions candidate-independent. Two
disposable exact v0.4.0 candidates and isolated lifecycle smoke pass on the
current host. The terminal result is
ready-for-publication-with-provisional-limitations; it publishes and deploys
nothing, and it authorizes no successor phase. Public and active v0.3.0 remain
19/19/19.
The human maintainer retains ultimate project, roadmap, publication, license, and destructive-action authority. ChatGPT manages planning and review only within a human-authorized task, phase, or preapproved roadmap envelope. Top-level Codex executes bounded ChatGPT assignments and manages internal Codex workers. Evidence and recommendations do not expand any actor’s authority. The manager-worker protocol defines the complete chain and stop boundaries.
APG is for maintainers who design agent workflows, agents that implement or review those workflows, and contributors evaluating whether a practice improves correctness, safety, maintainability, or delivery outcomes at an acceptable cost.
AGENTS.md contains the small set of repository-wide rules that
should apply to nearly all work.docs/project-model.md defines artifact ownership,
evidence domains, and the candidate-to-adoption lifecycle.docs/skill-authoring-and-maintenance.md
owns the APG skill-specific authoring, correction, support, maturity,
deprecation, and removal procedure.docs/provenance.md defines public and
publication-excluded provenance responsibilities.docs/manager-worker-protocol.md defines
external authority, top-level management, internal delegation, evidence, and
final reporting.docs/structured-project-phase-defaults.md
defines formal and non-phase commit, status, ADR, docs-only, scoped-test, and
manager-assignment compression defaults.docs/testing-and-coverage-policy.md
defines scoped tests, coverage remediation, mock boundaries, and the adopted
APG pytest architecture.docs/agent-reporting-architecture.md
defines the Python-first Git-show, Git-diff, and operational-report
ownership and format boundaries.docs/chatgpt-manager-skill-topology.md
defines implemented nested ChatGPT canonical owners, flat discovery,
subrouting, and personal transition gates.docs/adr/ records durable architecture decisions under
an independent four-digit sequence.docs/status/ records truthful phase exits under an
independent five-digit sequence.skills/ contains and indexes twenty-eight canonical
skills: fourteen stable rows and fourteen provisional manager-assignment,
language, database, test-profile, or conversion rows..agents/skills/ is the checked-in Codex repository
discovery projection; its twenty-eight relative symbolic links contain no
independent skill content.docs/bootstrap-v0.1.md defines maturity,
provisional evidence, rollback, dogfooding, and decommission gates.docs/superpowers-transition.md maps
materially relevant Superpowers workflows to APG, native Codex, project
policy, deferral, or rejection.docs/project-skill-projection.md
documents opt-in cross-repository installation, adoption, verification, and
rollback.docs/public-release-process.md documents
exact projection, deterministic candidate construction, validation, and the
v0.2.0 and v0.3.0 publication records.docs/user-scoped-skill-integration.md
documents direct public-sourced user links, state, lifecycle, restart, and
migration boundaries.docs/superpowers-decommission-runbook.md
preserves the human-owned decommission and rollback sequence after the
completed operation without authorizing restoration.docs/evaluations/ records the
public-safe APG4 scenario and review summary; the APG3 blocked record remains
preserved separately, and the
APG10 evaluation
records the experimental-source dispositions.docs/roadmap.md records the closed v0.1 and v0.2
sequences, the completed v0.3 sequence, APG25’s v0.4 foundation, APG26’s
initial enabling capabilities, and APG26A’s formal-commit correction. The
detailed v0.4 roadmap owns the dependency-ordered
future slices without allocating phase IDs.docs/legacy-roadmap-closure.md gives every
former candidate or deferred theme a terminal owner or condition.bin/ and libexec/ contain deterministic reporting tools, the
dependency-free project-local and user-scoped projection commands, the
read-only skill-library, record-identity, and formal-phase commit-message
checkers, and the local-only public candidate builder/checker with
non-executable helpers.src/test/unit/python/agentic-praxis-grimoire/ and
src/test/int/python/agentic-praxis-grimoire/ mirror production owners for
isolated unit tests and real-boundary integration tests. Test filenames use
.unit.test.py or .int.test.py suffixes.The repository separates tests by level and implementation language:
src/test/unit/<language>/
src/test/int/<language>/
APG28A adopts the corrected pytest migration. The repository interfaces are:
bin/apg-test unit
bin/apg-test integration
bin/apg-test unit-integration
Each command defaults to eight xdist workers. The strict source and mirror
inventory is recorded in testing/apg-test-inventory.json; exact integer
statement and branch counts enforce 80/80 component and 85/85 union gates.
Run-scoped manifests account for xdist workers, collection, terminal results,
and required Python-child coverage. Both report-tool Bats files remain.
Validate the current canonical skill library and checked-in Codex projection without mutation:
bin/apg-check-skill-library [--root <path>] [--format text|json]
bin/apg-check-record-identity [--root <path>] [--format text|json] \
[--expect-available <phase>] [--expect-allocated <phase>]
bin/apg-check-phase-commit-message --phase <PHASE-ID> \
(--message-file <path> | --commit <revision>) [--format text|json]
These commands validate only their adopted mechanical APG subsets. They do not prove semantic quality, imperative mood, authority, privacy, provenance, client discovery, maturity, release completeness, record truth, or stable behavior.
The adopted Python reporting interfaces are:
bin/git-show-report <phase-id> <commit> <status-doc> <result> <final-gate>
bin/git-diff-report <phase-id> <result> <final-gate> [--status-doc <path>]
bin/append-operational-report <phase-id> <absolute-body-path> <result> <final-gate> [options]
On Windows invoke the entry point through an interpreter, for example
python bin/git-diff-report --help. Report replacement fails closed there
until native sharing, reparse, and replacement safety is characterized. A Git
record must exist before its associated operational append. Standalone
operational records are accepted only when the canonical phase report contains
no Git show or diff record.
A candidate practice moves through a bounded lifecycle:
Copied or adapted expression requires confirmed reuse rights and any required notice. Synthesized or inspired practices still retain useful provenance. Source inclusion, frequency, ownership, or apparent authority is not itself an adoption decision.
The project model owns this general lifecycle. The skill authoring and maintenance guide owns its proportional application to skill changes.
The canonical public identity is agentic-praxis-grimoire. Public v0.1.0 was
published as a filtered projection with one intentionally squashed commit and
historically omitted the documented bin/apg-project-skills wrapper. ADR 0009
replaces manual selection with an exact projection of every tracked path except
private/, plus critical-owner checks that detect deletion from source.
Public v0.2.0, v0.3.0, and v0.4.0 each append one deterministic squashed
release commit and annotated tag while preserving the preceding public release
as sole parent. v0.4.0 publishes twenty-eight skill owners with fourteen stable
and fourteen provisional rows, then advances the aggregate-owned active source
by exact fast-forward. Future publication remains a separately authorized
human decision.
Agentic Praxis Grimoire is licensed under the GNU Affero General Public License v3.0 or later. See LICENSE.
Commercial licenses are available for proprietary terms, including closed-source embedding, private service deployments, OEM use, support, warranty, indemnity, and custom commercial terms. See COMMERCIAL-LICENSE.md.
Contributions are accepted under the terms in CONTRIBUTING.md and CLA.md.
Agents should read AGENTS.md, then the focused owner for the task.
Maintainers evaluating source-derived policy should begin with the
project model, provenance policy,
and the ADR index.
Delegated work should follow the
manager-worker protocol. The completed v0.1
epic, post-release APG-TEST0 foundation, and completed APG10 through APG14 v0.2
sequence are described in the roadmap. No successor roadmap
epic begins automatically.