Key terms used in the Autograph project. A shared reference to avoid ambiguity in communication between operator, agent, and documentation.
The central component of autograph. A minimal orchestrator that:
augr.contract.yml)augr:engine:prep, augr:engine:reset, augr:engine:diagnos)The engine is integrated into a project via a Git submodule (engine/).
A modular extension that adds capabilities to an autograph project. A package provides a combination of: Docker services, Taskfile tasks, agent skills/attitudes, documentation.
There are two kinds of packages, distinguished by the West manifest that declares them:
| Kind | Declared in | Resolved into | Present in | Developed by |
|---|---|---|---|---|
| Core package | Engine manifest (engine/deps/manifest/west.yml) |
engine/deps/modules/ |
Every project | The autograph contributors |
| Project package | Project manifest (deps/manifest/west.yml) |
deps/modules/ |
The project that declares it | The project team or a third party |
A package declared in the engine's West manifest (kind: core). Managed by the engine and developed by the autograph contributors. Always present in any autograph project. Provides the foundational "augmented dev" experience.
Examples: autograph.pkg.agent, autograph.pkg.delivery, autograph.pkg.metalab, autograph.pkg.proxy
A package declared in the project's root West manifest (kind: project), loaded on demand for this project only. Optional, adds capabilities specific to the project, a domain or a stack. Developed by the project team or by a third party. Older documents and the ADRs call it a third-party package.
task augr:install does not resolve project packages yet: resolve them with West on the host.
Examples (future): autograph.pkg.python, autograph.pkg.node, autograph.pkg.api-mock
A Git repository derived from the template, customized for a concrete use case. It owns its code, secrets, and project packages. This is what the operator uses daily for development.
The 3-layer model defines the access levels of the agent container to project files:
Read-Write zone. Contains source code, documentation, delivery, proposals. This is the agent's working space.
Path in container: /workspace
Read-Only zone. Contains the engine, resolved packages, Taskfiles, .git. The agent can read for context but cannot modify.
Path in container: /hostspace/
Not mounted zone. Contains secrets (env/), Docker socket, host network. The agent has no access whatsoever.
The L1 zone of an instantiated project. The workspace/ directory at the project root, mounted RW in the agent container. Contains: src/, docs/, delivery/, agent/, exchange.dev.tmp/, infra/, env.template/.
Asynchronous communication zones between agent and operator. Each agent mode has its own exchange directory:
workspace/exchange.dev.tmp/ - dev-agent exchange zone (inside workspace L1). Used for proposing L2 changes (exchange.dev.tmp/proposed/), code review diffs, and canvas exploration files.exchange.lab.tmp/ - metalab exchange zone (at project root). Used by the metalab agent to propose changes to L2 files (Taskfiles, README, project workspace files).Both follow the mirror path convention: proposed changes replicate the host-relative path structure so it is unambiguous which file is being replaced. The operator reviews and applies via cp.
Machine-readable YAML file at the engine root. Defines: contract version, engine capabilities, expected variables, lifecycle tasks. Packages declare their compatibility against this version.
Read-only report of the ecosystem state (task augr:engine:diagnos): host prerequisites, Git state of the project, the engine and the packages, contract, agent health, network isolation, Docker networks, service directories, generated configuration, exchange zones. It also runs when the stack is down.
Git-based dependency management backend, developed by the Zephyr project (RTOS). autograph uses it to resolve packages. West reads a manifest (west.yml) that declares Git repos and clones/updates them into a modules/ directory.
Specificity: runs in a dedicated Docker container (Python + west + git).
Official tool: West (Zephyr project)
One of three activity profiles available within an autographed project. A project alternates between modes depending on what the operator is doing.
The finished product runs standalone. Autograph scaffolding is stripped away - no agent container, no dev tools, no framework overhead. Analogous to a production build in classical development.
Active development of the product. Autograph is present as a read-only construction tool (pinned version). The agent works on the project, not on autograph. Dev tooling (Phoenix, eval) available via Docker profiles.
Working on autograph itself, using the project as context. An inversion of dev mode: the agent's workspace (L1 mutable) contains autograph sources with full git history, while the project is frozen context (L2 frozen). Changes are tested against the current project before being contributed upstream via the forge workflow.
Requires the optional package autograph.pkg.metalab. Dev and metalab agents run simultaneously in fully isolated containers.
See also: Shadow, Forge.
The action of concluding metalab work into a contribution to autograph. Forge is to metalab mode what "build" is to dev mode: the transition from working state to delivered artifact. Where build produces dev -> prod for the project, forge produces metalab -> prod for autograph itself. The term evokes the fabrication of the tool.
Concretely, the forge workflow is: the metalab agent produces changes in autograph sources (L1), the operator reviews them, creates branches (metalab/<slug>), commits in dependency order (packages first, engine second, seed root last), pushes upstream, and opens PRs.
For v0, forge is purely a documented operator workflow - there is no task augr:forge automation. The operator follows explicit git commands described in forge-workflow.md.
See: autograph.pkg.metalab/docs/forge-workflow.md.
The instantiable boilerplate repository. Clone it, configure it, and you have a functional autographed project. Formerly called "template".
Repository: autograph.seed
A project that uses autograph as its development framework. Created by instancing the seed. Owns its own code, delivery, and configuration while consuming autograph as a frozen dependency.
The development philosophy behind autograph: the framework observes real usage (from all autographed projects) and evolves in response. Each project is both a consumer of autograph and a potential source of improvements. The metalab mode formalizes this feedback loop.
An on-demand competency that the agent loads for a specific task. Defined as a SKILL.md file in a named directory. A skill is activated explicitly - it is not auto-loaded. It captures reusable know-how (conventions, workflows, decision frameworks) that the agent applies when the situation calls for it.
Naming: augr-* (core packages), <vendor>-* (project packages), unprefixed (project-local). See ADR: skill-system.
A permanent behavioral posture that shapes the agent's conduct across all tasks. Unlike a skill (on-demand, task-specific), an attitude is always active and defines vigilance patterns: what to watch for, when to alert, how to self-correct.
Naming: augr-attitude-* prefix. Examples: alignment-empathy (detect divergences with operator intent), egoless-augmentation (detect knowledge gaps, capitalize corrections).
A structured exploration document (*.canvas.md) used for brainstorming, problem decomposition, and decision preparation. Unlike persistent documentation, which captures settled knowledge, a canvas is a working surface for thinking: it holds options, open questions, and in-progress reasoning before they converge into a decision or a deliverable. Canvas files live in the agent's exchange zone (exchange.dev.tmp/).
See skill: augr-canvas.