Autograph
dev

Create a package

Build your own project package, step by step. Read the rules first, then skip the steps your package does not need. To adapt the project itself, see Make it yours.

Core packages and project packages

Core packages come with the engine: declared in its West manifest, present in every project, developed by the autograph contributors. A project package, the subject of this page, is declared in the project West manifest and loaded for this project only. See the Glossary.

Rules for package authors

Apply these rules in every package
  • Prefix every package variable with AUGR_PKG_<NAME>_*: the vars: of an included Taskfile leak to the root and its siblings.
  • Defaults live in the env template, never as a ${X:-default} fallback in a usage.
  • One source per parameter: never redefine an env-file name in vars: or env:, it would hide the file value.
  • A global sh: reads context only: values without an env-file line.
  • env: only exports constants computed by the Taskfile (paths, ports, host identity).
  • No dotenv: in an included Taskfile: only the root Taskfile loads env files.

Why, and how a Taskfile reads each kind of parameter: Configuration and state.

1. Create the repository

Create a Git repository with the standard layout:

Package layout
autograph.pkg.mypackage/
  augr.pkg.yml
  README.md
  Taskfile.yaml                        # tasks
  infra/compose.yaml                   # services
  env.template/.env                    # operator settings
  agent/skills/acme-example/SKILL.md   # skills
  docs/                                # reference docs (optional)

autograph.pkg.proxy is a complete service example, autograph.pkg.delivery a skills-only one.

2. Write the manifest

Declare the identity, the engine compatibility, and pointers to the files that exist:

augr.pkg.yml
name: autograph.pkg.mypackage
version: "0.1.0"
description: "My project package"
contract:
  engine_version: ">=0.1.0"

taskfile: Taskfile.yaml
compose: infra/compose.yaml
env_template: env.template/.env

Remove the pointers you do not use; add skills: agent/skills/ for skills. The engine reads only env_template; the other pointers document the layout.

3. Add the Taskfile

Write the tasks with the rules above. For example, a service startup task:

Taskfile.yaml
version: "3"
vars:
  AUGR_PKG_MYPACKAGE_COMPOSE_FILE: "{{.TASKFILE_DIR}}/infra/compose{{.AUGR_CONTAINER_COMPOSE_VARIANT}}.yaml"
  AUGR_PKG_MYPACKAGE_PROJECT: augr-pkg-mypackage

tasks:
  up:
    cmds:
      - $AUGR_CONTAINER_COMPOSE_CMD --project-name {{.AUGR_PKG_MYPACKAGE_PROJECT}} -f "{{.AUGR_PKG_MYPACKAGE_COMPOSE_FILE}}" up -d

Services also get down, ps and logs. An image you own gets build, rebuild and reup, all with the same Compose project name.

4. Add the services

Define the services in infra/compose.yaml and their Dockerfiles under infra/docker/. Pass settings through environment:, and mount state from the service directory of step 6, not from the package checkout.

To support docker-compose v1, add infra/compose.v1.yaml; see Compose runtimes.

5. Declare the operator settings

Commit documented defaults or empty placeholders in env.template/.env, never secrets:

env.template/.env
# Fill this value before running augr:build.
AUGR_PKG_MYPACKAGE_API_KEY=
AUGR_PKG_MYPACKAGE_TIMEOUT=30

task augr:install copies the template to env/<ENV>/env.d/autograph.pkg.mypackage.env without overwriting an existing file: add new variables there by hand. task augr:build aggregates these files into env/.env.project and rejects empty values.

6. Prepare the service state

Keep the data, logs and local configuration of each service under env/<ENV>/services/<service>/, created by a prepare task:

Taskfile.yaml (under tasks)
  prepare:
    preconditions:
      - test -n "$AUGR_ENV_DIR"
      - test -n "$AUGR_ENV"
    cmds:
      - mkdir -p "$AUGR_ENV_DIR/$AUGR_ENV/services/myservice/data" "$AUGR_ENV_DIR/$AUGR_ENV/services/myservice/logs"

Copy default configuration files only when they are absent, as autograph.pkg.proxy does. Mount configuration read-only, data and logs read-write: the state survives container recreation.

task augr:build runs prepare for the core packages only. For a project package, run task augr:pkg:mypackage:prepare once its Taskfile is included (step 8).

7. Contribute agent capabilities

  • Skills: agent/skills/acme-example/SKILL.md. The agent links the skills found at this fixed location in every resolved package.
  • Attitudes: skills named <prefix>-attitude-<name>. The agent loads the attitudes named in its work prompt only.
  • Plugins: agent/plugins/acme-example/index.js, enabled in the agent configuration (no manifest pointer).

The agent links skills and copies plugins at startup: recreate it after adding assets.

8. Register the package

Declare the repository in the project West manifest; the engine manifest lists the core packages only:

deps/manifest/west.yml
manifest:
  self:
    path: manifest
  remotes:
    - name: acme
      url-base: https://github.com/acme
  projects:
    - name: autograph.pkg.mypackage
      remote: acme
      repo-path: autograph.pkg.mypackage.git
      revision: main
      path: modules/autograph.pkg.mypackage
      userdata:
        augr:
          role: package
          kind: project

task augr:install does not resolve project packages yet. Until it does, resolve them with West on the host, from the project root:

terminal
cd deps
west init -l manifest  # first time only, when deps/.west does not exist
west update
cd ..

Then include the package Taskfile in the root Taskfile:

Taskfile.yaml (root, under includes)
  augr:pkg:mypackage:
    taskfile: ./deps/modules/autograph.pkg.mypackage/Taskfile.yaml
    dir: ./deps/modules/autograph.pkg.mypackage
    optional: true

9. Install and check

Run each command separately, so that Task reloads the generated configuration:

terminal
task augr:install
# Fill env/<ENV>/env.d/autograph.pkg.mypackage.env
task augr:build
task augr:pkg:mypackage:prepare
task augr:up
task augr:pkg:mypackage:up
task augr:engine:diagnos

task augr:up starts the core stack only: start your services with their own tasks. A skills-only package needs neither prepare nor up.

10. Support corporate networks

Each image you own needs the proxy build arguments, and the corporate CA if it makes TLS connections: see Corporate proxy and Custom CA certificates.

Learn more

The design behind these steps is in the ADRs on the package contract, lifecycle tasks, image lifecycle, environment aggregation, dependency management and the skill system.