harn-agent

name	harn-agent
short	Autonomous Harn agent workflows and safe task execution.
description	Use for autonomous Harn agent work, task decomposition, capability boundaries, and host interaction patterns.
when_to_use	Use when designing autonomous agent sessions, delegated workers, approval boundaries, or host capability usage.

Harn agent

Use this skill when designing autonomous Harn sessions, delegated workers, task decomposition, or approval-aware host interactions.

Pair it with [[harn-orchestration]] for workflow design and [[harn-diagnostics]] for repair/autonomy decisions.

Start here

• Use docs/llm/harn-quickref.md for agent_loop.
• Use the same quickref for tool formats, model options, and prompt templates.
• Use [[harn-tracing]] when transcripts, replay, or receipts matter.
• Agent session runtime code is mainly under crates/harn-vm/src/agent_sessions*.
• Bridge behavior lives near crates/harn-vm/src/bridge.rs.
• ACP behavior crosses VM and CLI integration tests.
• Keep autonomous behavior inspectable.
• Keep worktree-backed execution preferred for background edits.

Agent loop design

• Give each loop a concrete task.
• Give each loop an explicit stop condition.
• Give each loop a narrow tool surface.
• Carry a session id when transcript continuity matters.
• Persist useful transcript deltas.
• Persist recovery advice when failure can be resumed.
• Persist mutation-session metadata when edits happen.
• Keep handoff artifacts structured.
• For a structured terminal answer, set the agent's canonical output contract. It is applied only at finalization; ordinary tool turns stay unconstrained. Read run.output and run.output_valid.
• Avoid prose-only protocols for downstream automation.
• Bound retries and tool-call loops.

Capability boundaries

• Shell access should be explicit.
• Filesystem mutation should be explicit.
• Network access should be explicit.
• MCP access should be explicit.
• Host calls should be explicit.
• Secrets should stay in host-managed capability stores.
• Approval UX belongs to hosts.
• Concrete file mutation belongs to hosts.
• Undo and redo semantics belong to hosts.
• Harn should record what happened and why.

Autonomy and repair

• Use harn check before applying broad edits.
• Use harn lint before merging user-facing Harn code.
• Use harn fix --plan to inspect available repairs.
• Use harn fix --apply only within the permitted safety ceiling.
• Format-only repairs are safer than semantic rewrites.
• Capability-affecting repairs should escalate.
• Cross-file repairs should usually be reviewed.
• When a diagnostic code is known, use the code, not message scraping.
• If a tool result is ambiguous, ask for a smaller next step.
• Do not continue autonomous mutation after a trust-boundary violation.

Delegation patterns

• Split independent read-only investigation from implementation.
• Give delegated workers a clear file ownership boundary.
• Tell workers they are not alone in the codebase.
• Avoid overlapping write sets.
• Ask explorers specific codebase questions.
• Ask workers to edit files directly only inside their scope.
• Keep integration decisions in the coordinating session.
• Review worker diffs before publishing.
• Rerun the narrow tests that cover integrated changes.
• Use [[harn-testing]] to pick the verification level.

Common gotchas

• Do not assume ambient cwd state is safe for autonomous edits.
• Do not hide generated files in source changes.
• Do not widen capabilities to make a test pass.
• Do not conflate user approval with tool availability.
• Do not let compaction lose session intent.
• Do not let retry loops mask real diagnostics.
• Do not trust stale provider state.
• Do not record private prompt content in public summaries.
• Do not drop user or other-agent work when rebasing.
• Do not commit temporary logging.

Verify

• Agent session changes: targeted cargo test -p harn-vm agent.
• Bridge or ACP behavior: cargo test -p harn-cli --test acp_server_cli when feasible.
• Orchestration behavior: cargo test -p harn-vm orchestration.
• Repair/autonomy behavior: targeted harn fix tests.
• Transcript changes: targeted replay or record tests.
• Harn workflow examples: cargo run --quiet --bin harn -- check <path>.
• Conformance changes: cargo run --quiet --bin harn -- test conformance --filter <name>.
• Flake guard for tests: make lint-test-patterns.
• Broad shared behavior: make test.
• Release-facing changes: run the release gate requested by the repo docs.