Autograph
dev

Basic tools and practices

The day-to-day developer experience with autograph: task commands, agent sessions, restart cycles, and debugging.

Session lifecycle

Steps 1 to 4 are first-time setup (see Get started). Day-to-day work starts at step 5.

Session lifecycle: setup, install, configure, build, then daily: engine up, app start, agent, stop

Task namespaces

All commands go through Task. A single root Taskfile.yaml includes everything. Namespaces group commands by concern.

admin:*

First-time project setup: init submodules, create env directory, snapshot/restore runtime state.

augr:*

Engine lifecycle: resolve packages, aggregate env, build images, start/stop containers.

augr:engine:*

Engine: check prerequisites, resolve the core packages with West, report the ecosystem state.

augr:pkg:agent:*

Dev agent: launch chat sessions, open shell, stream logs, sync telemetry to Phoenix.

augr:pkg:metalab:*

Metalab agent: same as dev agent but works on autograph itself instead of your project.

augr:pkg:proxy:*

Stack proxy: prepare or reset its configuration, rebuild it, check its status, stream its logs.

app:*

Application lifecycle (project-specific). In the seed: start/stop dev servers, run tests, quality checks.

security-audit:*

Validate all security constraints: non-root agent, network isolation, capabilities, resource limits.

git:*

Extract a branch diff or uncommitted changes for code review, into the dev exchange zone.

Applying your changes

Different changes require different commands to take effect. Use the lightest one that covers your case. See Architecture for how the layers compose.

What changedWhat to do
Env variable added or changedtask augr:build && task augr:reup
Agent Dockerfile changedtask augr:pkg:agent:rebuild
App source codeNothing, dev server watches
App Dockerfile changedtask app:rebuild
App dependencies (package.json)task app:reinstall
Compose config changedtask augr:reup
Package updated upstreamtask augr:update && task augr:reup
Engine updated upstreamtask augr:upgrade && task augr:build && task augr:reup

Agent sessions

The agent container runs as a persistent daemon started by task augr:up. You attach to it with task augr:pkg:agent:chat to launch an interactive OpenCode session.

Attitudes (permanent)

Injected into every session via the work prompt. They define how the agent thinks. Not optional.

Egoless augmentationKnowledge vigilance: detect gaps, capitalize on corrections
Alignment empathyDetect divergences, express disagreement constructively

Skills (on demand)

Protocol documents loaded when a task matches their domain. Linked from the packages into /augr/agent/skills/ at container startup. Project-local skills in workspace/agent/skills/ are not loaded automatically yet.

augr-delivery-trackingFilesystem-based delivery and ticket execution
augr-code-qualityCode quality guidance, test formalism, review workflow
augr-code-reviewSystematic code review checklist and standards
augr-git-conventionsCommit messages, branching conventions
augr-documentation-writingStructured documentation creation
augr-cowritingCollaborative markdown editing conventions
augr-canvasStructured exploration in *.canvas.md files
augr-infrastructure-developmentDocker, Compose, env configuration
augr-knowledge-curationKnowledge artifacts, ADRs, decision trees

Debugging

Logs

terminal
task augr:logs              # All engine containers
task augr:pkg:agent:logs   # Agent container only
task app:logs              # Application containers

Container status

terminal
task augr:ps               # Engine containers
task app:ps                # App containers

Agent shell

Open a shell inside the agent container for manual inspection:

terminal
task augr:pkg:agent:shell

System diagnostics

The engine includes a comprehensive observation tool that reports the state of every entity in the ecosystem: source entity states (aligned, branched, dirty, diverged), agent health, config freshness, and exchange zone status.

terminal
task augr:engine:diagnos

Security validation

terminal
task security-audit:validate

Checks all security constraints: non-root agent, no Docker socket, network isolation, capabilities dropped, resource limits, mount options.

Observability

Agent sessions emit OpenTelemetry spans to Phoenix, running in the engine compose. Token consumption, response latency, and model usage are visible in the Phoenix dashboard.

terminal
# Push current session data to Phoenix
task augr:pkg:agent:sync