Declare project changes

Return a ChangePlan from your initializer or migration. It holds ordered operations; constructing it does not write files.

from harnest.authoring import ChangePlan, ProjectContext, WritePolicy

def add_defaults(context: ProjectContext) -> ChangePlan:
    return ChangePlan(
        context.yaml.set("acme-agent.yaml", key=("region",), value="eu-west"),
        context.files.write_text("company-notes.md", "Contact the platform team.\n"),
    )

Register a function like this with the appropriate pack decorator. Return ChangePlan() when a hook has no work to propose.

File operations

Use ProjectContext.files to read staged files or propose writes, copies, templates, and deletion. The file operation reference explains the result of each operation. Paths must be canonical project-relative paths. Absolute paths, traversal, source symlinks, and reserved state paths such as .git/, .harnest/, and harnest-packs.lock are rejected. File/directory conversions require manual migration.

YAML operations

Use ProjectContext.yaml to read configuration and propose field edits while retaining unrelated values. Use tuples for key paths. ("deployment", "region") identifies a nested field; ("deployment.region",) identifies a literal key containing a dot. A rename cannot move a field into itself or its descendants. A scalar parent is a conflict, not an object to replace implicitly.

YAML documents must be mappings with unique keys and a single document. Edits preserve unrelated values but normalise formatting and do not preserve comments.

Write policies

Use the enum values from harnest.authoring, rather than strings:

Policy	Absent file or field	Existing file or field
`WritePolicy.IF_MISSING`	Create it and record the pack’s ownership baseline.	Preserve it without adopting unowned content.
`WritePolicy.MANAGED`	Create it and record ownership.	Replace it only if it matches the pack’s recorded baseline.

IF_MISSING is the default for file writes, verbatim copies, templates, and YAML sets. MANAGED is appropriate when a later pack release updates a generated workflow or an unchanged default.

from harnest.authoring import ChangePlan, ProjectContext, WritePolicy

def update_workflow(context: ProjectContext) -> ChangePlan:
    return ChangePlan(
        context.files.from_template(
            ".github/workflows/agent.yml",
            template="ci.yml",
            policy=WritePolicy.MANAGED,
        ),
    )

Local edits block managed replacement. YAML renames instead carry the user’s current value forward.

Add team documentation to the project

Teams can copy Markdown guides, API references, runbooks, PDFs, images, and other files into generated projects. Use from_file to preserve the original bytes without decoding text or substituting dollar expressions. Set templates on your ProjectPack to the directory containing the packaged assets:

@pack.initialize
def initialize(context: ProjectContext) -> ChangePlan:
    """Give teammates reference material in each generated project."""
    return ChangePlan(
        context.files.from_file("docs/runbook.md", source="runbook.md"),
        context.files.from_file("docs/handbook.pdf", source="handbook.pdf"),
    )

source is relative to the pack’s templates directory; path is relative to the generated agent. Sources must be regular files inside the template directory and included in the distributed package. Each operation copies one file for teammates; these documents are excluded from compilation. Use agent templates for model-facing instructions and skills. Use policy=WritePolicy.MANAGED in a migration to update an unchanged pack-owned document. Local edits block replacement.

Templates

Set templates=Path(__file__).parent / "templates" when defining your pack. Without values, template content is copied literally, including dollar signs. Supplying values enables Python string.Template substitutions:

team-notes.txt

Agent: $agent
Team: $team

from harnest.authoring import ChangePlan, ProjectContext

def add_team_notes(context: ProjectContext) -> ChangePlan:
    return ChangePlan(
        context.files.from_template(
            "team-notes.txt",
            template="team-notes.txt",
            values={"agent": context.name, "team": context.options.team},
        ),
    )

Provide every referenced variable and use $$ for a literal dollar sign when substitution is enabled. Missing templates or substitutions fail the hook and block application.

Combine packs

Different packs can own separate fields in the same YAML file. Ownership of a whole file overlaps all fields inside it; ownership of a parent key overlaps its descendants. Conflicting proposals block the combined plan even if their values are identical. Core Harnest migrations run first. A core rewrite of a pack-owned file also requires review because the planner does not assume that the two migrations are compatible. See resolve blockers.

Overview

Get started

Harnest Studio

Guides

API reference

Declare project changes

File operations

YAML operations

Write policies

Add team documentation to the project

Templates

Combine packs

​File operations

​YAML operations

​Write policies

​Add team documentation to the project

​Templates

​Combine packs

File operations

YAML operations

Write policies

Add team documentation to the project

Templates

Combine packs