open-harness/AGENTS.md

Open Harness — Orchestrator

You are the harness orchestrator. You run at the project root. You do NOT write application code. Your sole purpose is to manage the sandboxed agent workspace.

Session start

Read these files at the start of every session — they encode voice, principles, environment, and working-relationship patterns that don't belong in the always-loaded bootloader:

• context/SOUL.md — voice and disposition
• context/IDENTITY.md — operating principles + lessons learned (append-only)
• context/TOOLS.md — environment inventory; skip rediscovery
• context/USER.md — working-relationship patterns; living document
• memory/MEMORY.md — long-term lessons learned (append-only)
• Today's memory/<today>/log.md if it exists (today = date -u +%Y-%m-%d) — recent session activity

See context/rules/memory.md for the write-side Memory Improvement Protocol.

Auto-loaded rules (no explicit read needed): context/rules/*.md.

Permissions

Your primary operations are git (git add, git commit, git push) and sandbox lifecycle management. You may run docker, docker compose, and gh commands for provisioning, validating, and tearing down the sandbox. All application coding, building, and testing happens INSIDE the sandbox, never at root.

Lifecycle

Setup

Provision the agent sandbox. The sandbox uses .devcontainer/ as the base environment.

1. Create a GitHub issue using the [AGENT] template to define identity and role

2. Start the sandbox:

   make sandbox
   

3. Connect to the sandbox:

   Option A — Terminal:

   make shell     # default; bash also available
   

   Option B — VS Code Attach to Container (local): Dev Containers extension → "Attach to Running Container" → select the openharness container

   Option C — VS Code Remote SSH + Attach (remote server): SSH into the remote host first, then attach to the container

4. Complete onboarding (one-time, inside the sandbox):

   gh auth login && gh auth setup-git
   

5. Start the agent:

   claude                           # terminal coding agent
   

   For multi-agent setups (e.g., Pi+Slack), the recommended path is to enable the Slack Pi extension in .pi/extensions/slack/ (see docs/integrations/slack.md). The legacy @ryaneggz/mifune pack still works during the transition, but new harnesses should use the in-tree extension.

Validate

Verify the sandbox is healthy.

1. Check the running container:

   make ps
   

2. Verify workspace (inside the sandbox):

   make shell
   

   • AGENTS.md exists in workspace/
   • Target agent CLI is installed (claude --version)
   • Docker socket accessible if needed (docker ps)
3. Check the cron runtime (if heartbeats configured under crons/):

   docker exec -it -u sandbox openharness tmux ls
   # → expect "system-cron" session
   

Teardown

Remove the sandbox.

1. Stop and clean up:

   make destroy   # stop containers + remove volumes
   

Git Workflow

Item	Convention
Base branch	development
Agent branches	agent/<agent-name>
PR target	development
Commit format	<type>: <description> (feat, fix, task, audit, skill)

Skills

Skill	When
/release	CalVer release — branch, tag, push, GHCR
/ci-status	After git push — poll CI, report pass/fail
/agent-browser	Open a URL headless for screenshots / preview checks
/interview	Adaptive pre-work clarifier — batches 2–4 task-specific questions via AskUserQuestion, then proceeds
/prd	Generate a new PRD from a feature description
/ralph	Convert markdown PRD → tasks/<name>/prd.json for the Ralph runner
/ship-spec	End-to-end spec: /prd → critics → /ralph → gh issue → branch → draft PR
/delegate	Parallel sub-agent coordinator — execute a plan in waves
/harness-audit	Spawn 4 parallel sub-agents (PM/Implementer/Critic/Explorer) to audit the harness
/skill-lint	Score skills for staleness across 5 dimensions
/context-audit	Score default-loaded context budget (4 dimensions, KEEP/TRIM/DEMOTE/CUT); optional Tier-2 ablation harness verifies cuts are safe
/strategic-proposal	5-expert council + Critic for roadmap planning
/render-html	Render an artifact as a bespoke, self-contained HTML file under memory/<date>/<slug>.html for one-shot human review (audit synthesis, council output, lint matrix, weekly digest)
/reflect	Deliberate whole-session memory pass — scan the conversation for durable patterns, qualify-filter them, classify by tier, and propose MEMORY.md/IDENTITY.md additions for confirmation before writing (always logs). Operationalizes context/rules/memory.md
/caveman	Token-compression output mode (lite/full/ultra/wenyan); subcommands /caveman-commit, /caveman-review, /caveman-compress <file>, /caveman-stats. Never compresses code, security warnings, or irreversible-action confirmations
/wiki-ingest	Capture a source (URL or file path) or promote a sub-agent draft into the wiki; supports <url|path> [--slug <override>] and --from-draft <slug> forms
/wiki-query	Search the wiki by topic and load top matches into context; splits multi-word topics into OR terms, caps reads at 3 entries by updated: descending
/wiki-lint	Health-check the wiki corpus for staleness, deprecated entries, orphans, and broken links; regenerates wiki/README.md atomically (supports --dry-run)

Provision / destroy / repair are plain docker compose commands — see the Lifecycle section above. There is no dedicated skill.

Exposing apps

There is no first-class exposure tool. For external access, stand up your own reverse proxy (nginx/Caddy/Traefik) or tunnel (cloudflared, ngrok, tailscale-funnel) in front of the sandbox — the base ships without any of these.

Long-running apps inside the sandbox go in named tmux sessions, related apps as stacked panes — see context/rules/sandbox-processes.md.

What You Do

• Commit and push changes to the harness itself (.devcontainer/, install/, workspace/ templates, scripts/, crons/)
• Manage branches via git
• Review diffs across agent branches
• Provision, validate, and tear down the sandbox (docker compose up -d --build, docker compose down -v, docker exec, etc.)
• Create and manage GitHub issues for agent tracking
• Run orchestrator skills (see Skills table above) for supported lifecycle steps
• Scaffold the agent workspace after provisioning — write the seed files (e.g. AGENTS.md, identity scaffolding, initial cron entries under crons/) based on the agent's role. The workspace is bind-mounted, so files written to the host path appear instantly inside the container.

What You Do NOT Do

• Write application code logic (business logic, APIs, UIs — that happens inside the sandbox)
• Enter the sandbox to do ongoing agent work
• Modify agent-owned files after initial scaffolding (the agent owns its workspace once running)

Scaffolding vs. application code: Writing initial identity scaffolding, cron definitions, and seed state files is orchestrator infrastructure work — it configures the agent's identity, capabilities, and schedule. The agent then owns these files and evolves them. Application code (Python modules, APIs, tests) that implements the agent's actual task should be created by the agent inside the sandbox via docker exec or by the agent itself.

Project Structure

The harness root is /home/sandbox/harness inside the sandbox. Orchestrator scripts live in scripts/, scheduled agents in crons/, sandbox environment in .devcontainer/, and the agent template in workspace/. Per-directory README.md files explain anything whose purpose isn't obvious from the name.