Give AI the right context. Define clear authority. Verify every change.

The name comes from the Javanese idea of pakem: a trusted rule, pattern, or reference point. Pakemin is an open-source AI Engineering Governance Framework for making AI-facing project knowledge explicit and dependable without tying it to one vendor.

Why Pakemin Exists

AI coding agents are becoming part of everyday software work, but each tool tends to bring its own instruction format. A project can quickly end up maintaining AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, GitHub Copilot instructions, and other vendor-specific files that all try to describe the same codebase.

That duplication creates drift. One file says how tests should run, another has outdated architecture notes, and a third contains rules that nobody remembers to update. The project slowly loses a single source of truth for the knowledge agents need.

Pakemin solves this with three connected pillars: Right Context in a project-owned .ai/ core, Clear Authority through scoped and restrictive rules, and Verifiable Changes through deterministic evidence. Vendor adapters stay thin: they point agents to the portable core instead of becoming separate instruction systems.

This also means switching agents does not mean starting from zero. Project knowledge lives in .ai/ instead of any vendor's files or chat history, so a new tool follows its thin adapter to the same portable core. .ai/memory/ records active work with owner and status, so a different agent — or a teammate — can pick up where the last one left off. Continuity comes from version-controlled project state, not from a particular agent account or captured sessions.

The goal is not to wrap LLMs or choose a winning agent. The goal is to make project knowledge portable, reviewable, and stable as teams move between AI coding tools.

Purpose

AI coding tools use different project instruction formats, including AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, GitHub Copilot instructions, and other tool-specific files. When each format becomes its own source of truth, project knowledge is duplicated and eventually diverges.

Pakemin treats project knowledge as project-owned. The portable core describes context, memory, rules, workflows, skills, templates, and overrides in a vendor-independent form. Thin vendor adapters can then point agents toward that shared source or translate it for tools with narrower loading behavior.

Quick Start

Install from npm:

npm install -g pakemin
pakemin --help

Run Pakemin from a checkout:

git clone [email protected]:frachman/pakemin.git
cd pakemin
node ./bin/pakemin.js --help
node . --help

Use it in another project:

cd /path/to/your-project
pakemin init
pakemin adapters generate
pakemin validate --adapters

Run pakemin adapters generate after pakemin init so AI coding tools can discover the shared .ai/README.md portable core through their own instruction files.

For local development, you can link the command:

cd /path/to/pakemin
npm link
cd /path/to/your-project
pakemin init
pakemin adapters generate
pakemin validate --adapters

What It Creates

pakemin init creates a project-owned portable core:

.ai
├── README.md
├── context/
│   ├── project.md
│   ├── architecture.md
│   ├── stack.md
│   └── roles.md
├── memory/
│   ├── active.md
│   └── known-issues.md
├── rules/
│   ├── engineering.md
│   └── ai-agents.md
├── workflows/
│   ├── feature.md
│   ├── bugfix.md
│   └── review.md
├── skills/
├── templates/
│   ├── requirement.md
│   ├── adr.md
│   ├── milestone.md
│   └── task.md
└── overrides/

pakemin adapters generate creates the default thin adapter:

• AGENTS.md

Optional compatibility adapters can be generated explicitly:

• CLAUDE.md
• GEMINI.md
• .cursor/rules/pakemin.md
• .github/copilot-instructions.md

Language Presets

Default init is language-neutral. If Pakemin detects common project files, it reports the detected stack and suggests an explicit preset.

pakemin init --preset=go
pakemin init --preset=java
pakemin init --preset=node
pakemin init --preset=python
pakemin init --preset=rust
pakemin init --preset=dotnet
pakemin init --preset=ruby
pakemin init --preset=auto
pakemin init --preset=auto,rust

Use --preset=auto,<id> to combine detected stacks with explicit presets.

Presets write small starter documents into .ai/context and .ai/rules. They do not install dependencies, modify source code, or run build tools.

CLI Commands

pakemin init [path] [--force] [--dry-run] [--preset=go]
pakemin validate [path] [--links-only] [--adapters]
pakemin check [path] [--baseline=<rev>] [--target=<rev>] [--working-tree]
pakemin adapters list [path]
pakemin adapters generate [path] [--force] [--dry-run] [--only=agents,claude]
pakemin doctor [path]

pakemin check verifies a Git change set against repository governance and prints a deterministic report. It requires an explicit baseline and an explicit target or working-tree mode, and it does not claim task-authority compliance.

Verify Changes

v0.2.0 adds repository-level verification. Define governance in a project-owned .ai/pakemin.yaml:

formatVersion: "0"
scopes:
  - id: repository
    paths: ["**"]
rules:
  - id: repository.source-change-requires-tests
    type: changed-path-requires-changed-path
    scope: repository
    when:
      changedPaths:
        include: ["src/**"]
    require:
      changedPaths:
        include: ["test/**"]

Then verify a Git change set against it:

pakemin check --baseline=<revision> --target=<revision>

check exits 0 for pass, 1 for fail, and 2 for requires-review, and prints a deterministic JSON report on stdout. Configuration and runtime failures exit 3 and 4 with a diagnostic envelope on stderr. The command requires an explicit baseline and exactly one explicit target form, never infers a comparison, and keeps verificationMode: "repository". See the CLI reference and Governance Schema v0.

Goals

• Keep project knowledge independent from any one AI vendor.
• Store project context, decisions, rules, and workflows in version-controlled files.
• Preserve work continuity across agents, sessions, and teammates through project-owned memory.
• Support gradual adoption in existing repositories.
• Keep the system readable and editable by humans.
• Provide a foundation for future CLI tooling and adapters.

Non-Goals

Pakemin is not an LLM wrapper, chat application, prompt marketplace, hosted memory database, MCP replacement, plugin marketplace, or autonomous development platform.

Those areas may be explored later, but they are outside the current documentation milestone.

Support

If Pakemin helps your project, give it a star, share it, or open an issue or PR.

Bug reports, adapter improvements, documentation fixes, and language preset feedback are especially welcome during the public preview stage.

See CONTRIBUTING.md for how to set up a local checkout and open a pull request.

Repository Guide

• Documentation overview
• Getting started
• First-Time User Tutorial
• Architecture
• Reference
• CLI reference
• Development
• Architecture decision records
• Examples

Current Status

Current stable: v0.2.0.

The stable release includes a dependency-free CLI, project-owned .ai scaffolding, thin adapter support, validation, language presets, governance verification through pakemin check, and a reference repository. Task-aware verification remains deferred until a task-envelope contract exists.

Schemas, plugin architecture, shared framework distribution, hosted services, and release automation are intentionally deferred.

Verification

Run the core checks from a checkout:

npm test
npm run validate
node ./bin/pakemin.js validate examples/saas-reference-repository --adapters