Airic

Airic is a document-defined, trainable agent built on Pi Coding Agent.

It turns a methodology into a project-owned operating model: procedures, standards, tool policies, decision boundaries, precedents, and reflection lenses. Reflection can then improve that model through ordinary, reviewable file edits.

Airic is one Pi package with two delivery modes backed by the same application behavior:

Mode	Host	UI
Pi extension	An existing Pi installation	Pi TUI
airic acp	Zed or another ACP client	The client's native ACP UI

Pi remains an external host dependency in both modes. Airic does not bundle or privately own a Pi runtime. The ACP adapter starts the installed compatible Pi in RPC mode and loads the same Airic extension used in the Pi TUI.

Install and run

Install Pi and Airic once, globally:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent airic-agent

Both Pi TUI and ACP use this one Airic installation. Do not also run pi install for Airic: it creates a second extension copy, which causes duplicate tool-name conflicts when ACP starts.

If you previously installed Airic with pi install, run pi list and remove the listed Airic source with pi remove <source> before using the command above.

Pi TUI

From the project you want to train, find npm's global package directory:

npm root -g

Then start Pi with Airic's extension file, replacing <npm-global-root> with the printed path:

pi --extension <npm-global-root>/airic-agent/dist/extension.js

Pi still loads your usual Pi extensions, skills, and configuration. In the TUI, run /airic init to initialize a project, or /airic to see all Airic commands.

Installation alone does not alter Pi's behavior. Initialization copies Airic's editable Core and Packsmith packs from the installed package into the project's .airic/ directory and creates a fixed .airic/project/ scope for project-owned operating knowledge. These are ordinary editable and versionable file sets.

The Pi TUI is a first-class Airic delivery. /airic commands, tool calls, session state, mode changes, reflection, and methodology review use Pi's native terminal UI. ACP clients may present the same behavior with richer native selectors or forms; capability semantics remain shared even when presentation differs.

Run through ACP

After the global installation above, ACP clients launch the adapter included in the same Airic package:

airic acp

Configure an ACP client with command airic and argument acp.

The Pi TUI and ACP modes share Pi's normal configuration, credentials, packages, extensions, skills, prompts, and project trust decisions. A capability added to Pi is therefore available to Airic when it is compatible with the active TUI or RPC presentation mode.

The loop

methodology → doc-pack → real work → reflection → direct edit → Git review → better next task

Airic's operating model is deliberately project-local in v0.1 and remains visible in .airic/. A durable runtime or client constraint may instead be placed in a scope-matched context file such as AGENTS.md when that client discovers and loads it at session startup. Pi sessions remain Pi sessions, and ordinary project files are never behavior-patch targets.

Commands

Command	What it does
/airic	List the dedicated Airic commands.
/airic init	Copy the editable Core and Packsmith packs and create the project operating-model scope.
/airic status	Show packs, effective artifacts, and active artifacts.
/airic mode [mode-id]	Show or select the session's Airic mode.
/airic onboard <paths...>	Use Packsmith to turn methodology sources into a local doc-pack.
/airic reflect [lens-id]	List reflection lenses or start reflection over the current Pi conversation branch.
/airic pack list	List project packs and their available, installed, or enabled state.
/airic pack install <pack-id>	Install and enable an official pack from the Airic release.
/airic pack enable <pack-id>	Enable an already-installed project pack.
/airic pack disable <pack-id>	Disable a pack without deleting its local files.

Agents can enter the same flow through airic_reflect. Calling the tool without lens_id is read-only and returns every selectable lens linked to the Core reflection procedure across enabled packs. Calling it again with one of those ids activates the doc-defined procedure and lens. The tool is a cross-mode entry point; the procedure remains the owner of the reflection method.

Doc-packs

Each enabled pack is stored under .airic/packs/<pack-id>/:

manifest.yaml
types/*.md
artifacts/
├── modes/*.md
├── roles/*.md
├── procedures/*.md
├── standards/*.md
├── tool-policies/*.md
├── decision-boundaries/*.md
├── precedents/*.md
└── reflection-lenses/*.md

The type directories are a placement convention rather than part of artifact identity: IDs, types, and links remain declared in frontmatter. The loader continues to read nested and legacy flat artifact paths so existing project models remain valid.

Types declare one generic loading mechanism: activation, linked, retrieval, tool-bound, or authoring. Activation-loaded artifacts additionally declare activation: resident or activation: on-demand; other types enter context through artifact links, retrieval, an active tool, or an authoring operation.

Artifacts may declare typed links. Required links enter the same context closure, selectable links expose a named choice slot, discoverable links add a local candidate, and reference links preserve navigation without loading content. A reverse target-active trigger lets an extension pack contribute its own artifact—such as a reflection lens—to a procedure owned by another pack.

Before each agent run, the application layer assembles the effective context and records the loaded artifacts, reasons, pack versions, and active procedures in the session trace. Procedures remain ordinary session activation state and must be explicitly deactivated when their flow exits; Airic does not create a separate task or procedure-run entity.

Modes are single-select. Core's resident Airic mode is the general partner for developing ideas, turning intent into verified progress, navigating available Airic capabilities, and helping the user recognize useful learning boundaries. Selecting an on-demand specialist mode replaces it until that mode is exited or another on-demand mode is selected. Specialist modes remain focused on their target work; reflection is available to all modes through the explicit airic_reflect tool rather than through an inherited reflection standard. The current mode and active procedures are included in Airic status.

The copied airic-core pack defines the initial vocabulary: mode, procedure, standard, tool-policy, decision-boundary, precedent, and reflection-lens. The copied airic-packsmith pack supplies the methodology-onboarding flow. Packs can add their own types without requiring an Airic runtime release.

Initialization includes airic-core and airic-packsmith. Use /airic pack list to see the optional official packs, then /airic pack install <pack-id> to copy and enable one in the project. The repository also publishes these optional official packs:

Pack	Initial responsibility
airic-founder	Apply the source-bounded Founder Playbook across Idea, MVP, Launch, and Scale work.
airic-developer	Plan, implement, locally verify, and reflect on software from explicit, human-approved product intent.
airic-writing	Support collaborative writing while preserving argument integrity.

Project operating model

.airic/project/ is the fixed, always-on home for operating knowledge owned by the current project. It uses the same manifest and typed-artifact contracts as a doc-pack, uses the reserved project.* ID namespace, and may reuse the types defined by airic-core. Project procedures, standards, roles, tool policies, decision boundaries, precedents, reflection lenses, and modes are stored in the corresponding subdirectories under .airic/project/artifacts/.

The project scope loads after configured base packs and is recorded as scope: project in context provenance. Loading order does not silently grant override authority: inheritance, narrowing, and supersession must remain explicit in the governing artifact contracts. Project artifacts may reuse and link base artifacts, but distributable base packs may not depend on project-owned types or artifacts.

The physical boundary also prepares Airic for a future organization scope managed or synchronized through Airic Server: distributable base packs, team-owned organization guidance, and repository-owned project guidance can then retain distinct ownership and synchronization rules. Organization synchronization and cross-scope conflict resolution are not implemented in this release.

airic-founder provides four on-demand founder modes for Idea, MVP, Launch, and Scale work. The modes change the current session posture without declaring that the company has entered a stage. Venture stage, hypotheses, experiments, evidence, and decisions remain in user-owned venture records outside .airic/. Its procedures validate opportunities, conduct customer discovery, design venture experiments, run MVP learning cycles, coordinate repeatable operations and scale systems, and assess stage transitions. Build, pivot, stop, launch, scale, material venture interpretation, and stage decisions remain founder-owned.

The Founder pack intentionally excludes generic Business Model and Domain-Driven Design methods. Its pack-root README publishes its source, supported capabilities, non-goals, known methodology gaps, human authority, and extension policy. Artifact types still describe artifacts inside a doc-pack, while standards may govern external user files.

airic-developer depends on the Founder pack only for stage-aware tradeoffs. It requires explicit, human-approved product intent and stops when consequential behavior is unresolved; it does not inherit a generic Business Model or DDD method. It also incorporates CMP as a development method: non-trivial changes are planned by routing the required modification context before coding, then reflected on afterward for missing paths, boundary shortcuts, and unowned capabilities. What-level architecture decisions remain explicitly human-owned.

Governance

Reflection starts from the current conversation already present in the agent context. A lens must be selected from the Core procedure's selectable links; reverse target-active links allow any enabled pack to contribute additional lenses without changing Core. Reflection uses airic_trace only when relevant history was compacted or is absent, or when exact branch-entry evidence is needed. Attribution identifies the responsible behavior surface but does not select the edit destination. Before writing, the agent applies Core's Durable instruction placement standard: every durable instruction must have an explicit behavior owner, authoritative scope and source, fitting representation, discovery route, and full-body loading route. Project-specific operating guidance remains under .airic/project/; an installed third-party pack is not edited as though it were its authoritative source. A runtime constraint that must enter every affected session may instead use the narrowest AGENTS.md or equivalent context file that the client actually discovers and loads. Rule size alone never makes AGENTS.md the right owner, and a client-only rule must not leak through a repository context file into unaffected clients. A missing owner, representation, discovery path, or loading capability produces placement-blocked rather than an inert or mis-scoped instruction. The agent then explains the attribution, placement decision, and intended governed-file change in the conversation and edits it when authorized. The user reviews the result with the ordinary Git diff or an explicit external handoff. Airic never targets ordinary project files for a behavior-model change.

Every pack in this repository's .airic/packs/ directory is an official Airic pack and is packaged directly with Airic. .airic/project/ belongs only to this repository and is excluded from release assets. Initialization copies the editable default packs, airic-core and airic-packsmith; it does not copy the other official packs into a new project, and instead creates a fresh empty project scope. config.yaml records the source, package version, and SHA-256 of the release's official packs; Airic does not retain a project-local .upstream mirror. For clients that hide dot-directories, .airic may be a symbolic link to a directory inside the project (for example, Airic/); symbolic links inside the operating-model tree and root links to locations outside the project remain invalid.

Development

npm install
npm run build
npm test
npm run pack:check

For local Pi testing, load the compiled extension with:

pi -e ./packages/airic/dist/extension.js

Release

The release workflow publishes only packages/airic when a v* tag is pushed. The tag must exactly match the package version, for example v0.2.0 for airic-agent@0.2.0. Prerelease versions such as v0.2.0-beta.1 are published under the npm next tag.

Configure release.yml as the trusted publisher for the airic-agent package on npmjs.com before the first automated release. The workflow uses GitHub OIDC and does not require a long-lived NPM_TOKEN.

Develop Airic in Zed

This repository includes .pi/settings.json, which loads the compiled packages/airic/dist/extension.js for local development. Run npm run build after changing either delivery mode. Pi project resources run only after the repository is trusted. Start Pi once in this directory, run /trust, then restart the agent process.

Build Airic, then point Zed at Airic's own ACP adapter:

{
  "agent_servers": {
    "airic-local": {
      "type": "custom",
      "command": "node",
      "args": ["/absolute/path/to/airic/packages/airic/dist/cli.js", "acp"]
    }
  }
}

After publishing, the equivalent package-backed entry is:

{
  "agent_servers": {
    "airic": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "airic", "acp"]
    }
  }
}

Open the repository in Zed and start an airic-local external-agent thread. Zed's mode selector is populated from the enabled Airic mode artifacts and remains single-select. Its model selector is populated from Pi's available models, and its reasoning-effort selector is populated from the selected model's Pi registry metadata. Changing the model refreshes the available reasoning-effort values. Airic advertises the portable /airic command, whose no-argument help lists init, status, mode, onboard, and reflect; use the same syntax in the Pi TUI and ACP clients.

When reflection changes the behavior model, Airic explains the attribution and intended effect in the conversation, then edits the relevant .airic files directly. Review those changes with Zed's Git integration or the repository's ordinary Git diff before continuing work.

When a procedure starts or completes, Airic ACP emits a visible status message and also records activeMode and activeProcedures in ACP session metadata. To discuss a passage, select it in a Markdown buffer and run agent: add selection to thread; embedded editor context is enabled by default.

Airic ACP starts a Pi RPC process per Zed session. ACP session IDs are the corresponding persistent Pi session IDs, so Zed can load a thread with its current-branch conversation history or resume it without replaying messages after the adapter restarts. Airic reconstructs the active mode and procedures from the Pi session. Start a new Zed agent thread after changing packages/airic/src/extension.ts or packages/airic/src/acp/. Use dev: open acp logs when the adapter starts without showing Airic tools.

Limits in v0.1

• No global operating model or remote doc-pack registry.
• No vector retrieval or autonomous reflection.
• Tool policies guide the model; use Pi or a dedicated extension for hard sandboxing and permission enforcement.

License

MIT