Artifact

AgentSpec

File: agent.yaml

A portable, reusable single-agent blueprint. Defines what an agent can do — its resources, profiles, startup behavior, and lifecycle defaults. If you're building an agent, this is the file you write.

Full example

# agent.yaml — portable single-agent blueprint
name: reviewer
version: "1.0.0"

resources:
  skills:
    - code-review        # SKILL.md files
    - security-audit
    - test-coverage
  guidance:
    - docs/conventions.md     # specific file
    - docs/as-built/          # entire folder
    - repo/agents.md
  hooks:
    - on: post_review         # merged into harness config
      run: notify-orchestrator
    - on: pre_commit
      run: lint-check
  subagents:
    - name: detail-checker
      spec: local:agents/detail-checker
  runtime_resources:
    - name: eslint
      type: npm_global

profiles:
  reviewer:
    uses:
      skills: [code-review, security-audit]
      subagents: [detail-checker]
    startup:
      files:
        - path: reviewer-prompt.md
          deliveryHint: guidance_merge
          required: true
          appliesOn: [fresh_start]
  coder:
    uses:
      skills: [code-review, test-coverage]
  qa:
    uses:
      skills: [security-audit, test-coverage]

imports:
  - source: local:agents/base-reviewer
    include: [skills, guidance]

startup:
  files:
    - path: review-prompt.md
      deliveryHint: guidance_merge
      required: true
      appliesOn: [fresh_start, restore]
    - path: repo-context.md
      deliveryHint: guidance_merge
      required: false
      appliesOn: [fresh_start]
  actions:
    - type: send_text
      value: "Begin review of current branch"
      phase: after_ready
      appliesOn: [fresh_start]
      idempotent: false
    - type: send_text
      value: "Resume review from checkpoint"
      phase: after_ready
      appliesOn: [restore]
      idempotent: true

lifecycle:
  execution_mode: autonomous
  restore_policy: resume_if_possible
  compaction_strategy: checkpoint_first

What it contains

resources

The capabilities this agent has access to.

skills—SKILL.md files that teach the agent specific capabilities. Examples: code-review, test-driven-development, git-workflow, security-audit.

guidance—Files or folders loaded into the agent's context. Can be a specific file (docs/as-built/architecture.md) or an entire folder (docs/as-built/). Examples: conventions.md, design.md, soul.md.

hooks—JSON snippets that get merged into the harness config. They add to what's already there. Events: pre_commit, post_review, on_error, on_complete.

subagents—Child agents this agent can spawn within its session. Referenced by local: path to another AgentSpec.

runtime_resources—System dependencies the agent needs. Examples: npm globals, brew packages, CLI tools.

profiles

Named configuration variants that select subsets of declared resources. Profiles filter — they never inject resources not declared in the base spec. You define your own profiles — there are no built-in names. A profile is how one AgentSpec can serve multiple roles.

Example: reviewer—Activates code-review + security-audit skills and the detail-checker subagent. Used when this agent's role is reviewing.

Example: coder—Activates code-review + test-coverage. Same base spec, different role.

Example: qa—Activates security-audit + test-coverage. Same agent blueprint, focused on quality.

imports

Compose resources from other AgentSpecs. Enables reuse without copy-paste.

source—local:agents/base-reviewer or path:../shared/base.yaml

include—Cherry-pick which resource types to import: [skills, guidance, hooks]

startup

Deterministic boot sequence with two parts: files to deliver, then actions to execute.

files—Deliver files to the harness on boot. Each file has a delivery method (merge into guidance, install as skill, or send as text) and controls for when it applies (fresh start, restore, or both).

actions—Commands sent to the harness after files are delivered. Can run after files land or after the harness signals ready. Each action can be scoped to fresh starts only, restores only, or both.

appliesOn—Both files and actions specify when they run: [fresh_start] for first boot, [restore] for recovery, or both. This lets you prime differently on restore vs cold start.

lifecycle

Controls how the agent behaves over time — what happens when it restarts, compacts, or needs recovery.

restore_policy

resume_if_possible — try to resume the session

relaunch_fresh — start over with checkpoint context

checkpoint_only — only restore from checkpoint

Narrowing: profiles can make this stricter, never looser.

compaction_strategy

checkpoint_first — write state before compacting

harness_native — let the harness handle it

pod_continuity — coordinate with pod shared memory

execution_mode

autonomous — run without human interaction

interactive_resident — long-running, human in the loop

What it does NOT contain

• Rig topology — that's a RigSpec. The AgentSpec doesn't know about other agents.
• Final runtime/model/cwd bindings — the AgentSpec can declare defaults, but the rig member makes the final binding. This is how one AgentSpec works across different harness runtimes.
• Secrets or API keys — never checked into a spec.
• Ephemeral runtime state — session IDs, pane refs, timestamps.

Harness Framework vs AgentSpec

This distinction trips people up. A harness framework is a complete, opinionated methodology for agent development — a cohesive system of skills designed to work together, with an orchestration philosophy and a bootstrap step.

An AgentSpec is the format. Harness frameworks are distributed as AgentSpecs, but not every AgentSpec is a framework. A single skill with a hook is an AgentSpec. A framework is an opinionated methodology.

The distinction

Harness asset     = one skill, hook, or guidance file
AgentSpec         = portable blueprint with a manifest
Harness framework = a cohesive, opinionated system
                    (distributed as AgentSpecs)

Examples of frameworks: G-Stack (YC dev lifecycle), GSD, Superpowers (TDD workflow), Agent Focus. All are structurally just AgentSpec folders.