Create a project pack

Define a pack in a Python package installed alongside your company CLI. Keep this package outside the agent repository so the deployed agent does not acquire authoring-only dependencies.

Generate a starter pack

Create a Python pack and an editable compile manifest together:

harnest pack init acme --output ./acme-pack

Omit --output to use ./acme-pack. The name must begin with a lowercase letter and contain only lowercase letters, digits, or hyphens, with a maximum of 63 characters. harnest is reserved. The destination must not already exist; the command never overwrites an existing team pack.

acme-pack/
  pack.py
  harnest-compile.yaml
  team-guide.md

Generated file	What to customize
`pack.py`	Pack identity, initialization, migrations, and the company’s CLI.
`harnest-compile.yaml`	Optional dependency groups selected for compilation.
`team-guide.md`	Team documentation copied unchanged to `docs/team-guide.md` in each new agent.

The generated manifest starts with:

version: 1
extras: []

Run the Python file with the Harnest SDK installed in your authoring Python environment and the Harnest CLI on PATH:

python ./acme-pack/pack.py init ./sales --minimal
harnest compile ./sales --format executable --output ./dist/sales-agent

To start from your team’s existing agent template, use:

python ./acme-pack/pack.py init ./sales --template acme-sales

The template is prepared first, then the pack initializer runs against its files. See template initialization for checksum pins and option compatibility. On Windows, use an output name ending in .exe. Set HARNEST_CLI to your Harnest executable path if it is not on PATH. The initializer copies the manifest and team guide into new agents. Team documentation is excluded from compilation. Use agent templates for model-facing instructions and skills. Adding an extra requires the corresponding [project.optional-dependencies] entry in the generated agent’s pyproject.toml. The compile manifest controls dependency selection only; it does not package arbitrary project files. Edit these files before creating agents. To update existing agents, increment schema_version, add a migration, and run python ./acme-pack/pack.py upgrade ./sales --apply. Initializers do not run again during upgrade. You can later move this starter into your team’s Python package and expose main through a company CLI console entry point. Include both template files beside pack.py in the installed package. Harnest compiles agents; the pack remains authoring code.

Start with a typed definition

This first release accepts a team name and writes it to the company’s owner field. The migration example later renames that field to team.

pack.py

from enum import Enum
from pydantic import BaseModel, Field
from harnest.authoring import ChangePlan, ProjectContext, ProjectPack

class Environment(str, Enum):
    DEVELOPMENT = "development"
    PRODUCTION = "production"

class Options(BaseModel):
    team: str = Field(min_length=1, description="Team responsible for this agent")
    environment: Environment = Environment.DEVELOPMENT

class Settings(BaseModel):
    owner: str = Field(min_length=1)
    environment: Environment

pack = ProjectPack(
    name="acme",
    schema_version=1,
    options=Options,
    config_file="acme-agent.yaml",
    config_model=Settings,
)

@pack.initialize
def initialize(context: ProjectContext) -> ChangePlan:
    return ChangePlan(
        context.yaml.set(
            "acme-agent.yaml", key=("owner",), value=context.options.team,
        ),
        context.yaml.set(
            "acme-agent.yaml",
            key=("environment",),
            value=context.options.environment.value,
        ),
    )

Options validates caller inputs; Settings validates the resulting company configuration, including during upgrades without new inputs.

Pack properties

See ProjectPack configuration for required properties, validation, and defaults. Track schema_version separately from the package release version. Keep company properties in a separate file such as acme-agent.yaml. Use existing Harnest fields when changing Harnest configuration; arbitrary company fields do not extend Harnest’s configuration schema.

Package templates

A pack that generates a company workflow could have this structure:

acme_agent_pack/
  __init__.py
  pack.py
  cli.py
  templates/
    ci.yml

Pass templates=Path(__file__).parent / "templates" to ProjectPack, and include the files in your package’s build configuration. Templates are read as data; Harnest does not import or execute them.

Declare compilation dependencies

Use ordinary pack operations to maintain optional dependency selections:

@pack.initialize
def initialize(context: ProjectContext) -> ChangePlan:
    """Select the team's optional integration dependencies for compilation."""
    return ChangePlan(
        context.yaml.set("harnest-compile.yaml", key=("version",), value=1),
        context.yaml.set("harnest-compile.yaml", key=("extras",), value=["crm"]),
    )

Declare the matching [project.optional-dependencies].crm group in the agent’s pyproject.toml, for example through the team’s agent template. Package versions remain in Python metadata. The compile manifest does not accept resources. Change existing agents through versioned pack migrations and coordinate ownership of shared fields. Compilation reads the resulting files without importing or shipping the authoring pack. See compilation selections and reports for dependency selection, compiled content, and shared-runtime behavior.

Choose what runs

Pass installed pack objects explicitly to ProjectCLI or ProjectPlanner. Harnest does not discover packs from package names in a project file.

Pack callbacks are trusted Python, not sandboxed code. Keep them deterministic and free of filesystem or network side effects. A preview can execute callbacks multiple times without applying any changes.

Continue with the @pack.initialize reference or build your company CLI.

Overview

Get started

Harnest Studio

Guides

API reference

Create a project pack

Generate a starter pack

Start with a typed definition

Pack properties

Package templates

Declare compilation dependencies

Choose what runs

​Generate a starter pack

​Start with a typed definition

​Pack properties

​Package templates

​Declare compilation dependencies

​Choose what runs

Generate a starter pack

Start with a typed definition

Pack properties

Package templates

Declare compilation dependencies

Choose what runs