From 82d24da11c183ef52c397e2fd02ba7b1a7170d04 Mon Sep 17 00:00:00 2001 From: ryaneggz Date: Sun, 29 Mar 2026 16:29:04 -0600 Subject: [PATCH] feat: add root CLAUDE.md/AGENTS.md and rename worktrees to .worktrees Add root-level orchestrator instructions that define the harness's sole purpose: managing sandboxed agents via .worktrees/. Includes setup, validate, and teardown lifecycle documentation. - AGENTS.md: root orchestrator instructions (git-only permissions, lifecycle) - CLAUDE.md: symlink to AGENTS.md (matches workspace/ convention) - Rename worktrees/ to .worktrees/ (dot-prefixed hidden directory) - Update Makefile, .gitignore, and remaining issue templates - Remove agent, audit, skill, and task issue templates (intentional) Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/ISSUE_TEMPLATE/agent.md | 57 ------------- .github/ISSUE_TEMPLATE/audit.md | 58 -------------- .github/ISSUE_TEMPLATE/bug.md | 4 +- .github/ISSUE_TEMPLATE/feature.md | 4 +- .github/ISSUE_TEMPLATE/skill.md | 124 ----------------------------- .github/ISSUE_TEMPLATE/task.md | 52 ------------ .gitignore | 4 +- {worktrees => .worktrees}/.gitkeep | 0 AGENTS.md | 98 +++++++++++++++++++++++ CLAUDE.md | 1 + Makefile | 2 +- 11 files changed, 106 insertions(+), 298 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/agent.md delete mode 100644 .github/ISSUE_TEMPLATE/audit.md delete mode 100644 .github/ISSUE_TEMPLATE/skill.md delete mode 100644 .github/ISSUE_TEMPLATE/task.md rename {worktrees => .worktrees}/.gitkeep (100%) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.github/ISSUE_TEMPLATE/agent.md b/.github/ISSUE_TEMPLATE/agent.md deleted file mode 100644 index f68c594..0000000 --- a/.github/ISSUE_TEMPLATE/agent.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -name: Agent -about: Provision a new agent workspace -title: "[AGENT] " -labels: agent -assignees: "" ---- - -## Identity - -- **Name**: -- **Role**: - -## Context - - - ---- - -## Workspace Setup - -> An agent is a persistent, isolated workspace with its own branch, memory, and context. Agents are long-lived — they accumulate knowledge and work on multiple issues across their lifetime. - -### Metadata - -> **IMPORTANT**: The very first step should _ALWAYS_ be validating this metadata section to maintain a **CLEAN** development workflow. - -```yml -agent: "" -branch: "agent/" -worktree_path: "worktrees/" -``` - -### 1. Provision the agent - -```bash -make NAME= quickstart -``` - -This will: -- Create a git worktree at `worktrees/` on branch `agent/`, branched from `development` -- Build the Docker image from the worktree's context -- Start the container with the worktree's workspace mounted -- Run the setup script - -### 2. Enter the sandbox - -```bash -make NAME= shell -claude -``` - -### 3. Verify - -- [ ] Container is running (`make list`) -- [ ] Agent can access workspace (`ls ~/workspace`) -- [ ] SOUL.md and MEMORY.md are present diff --git a/.github/ISSUE_TEMPLATE/audit.md b/.github/ISSUE_TEMPLATE/audit.md deleted file mode 100644 index b4eefc2..0000000 --- a/.github/ISSUE_TEMPLATE/audit.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: Audit -about: Review or audit existing code, config, or processes -title: "[AUDIT] " -labels: audit -assignees: "" ---- - -## Scope - - - -## Objective - - - -## Checklist - -- [ ] -- [ ] -- [ ] - ---- - -## Agent Assignment - -### Metadata - -> **IMPORTANT**: The very first step should _ALWAYS_ be validating this metadata section to maintain a **CLEAN** development workflow. - -```yml -agent: "" -branch: "agent/" -worktree_path: "worktrees/" -pull_request: "FROM agent/ TO development" -``` - -### Workflow - -```bash -# Enter the assigned agent's sandbox -make NAME= shell -claude - -# If the audit produces fixes — PR from agent branch to development -cd worktrees/ -git add -A && git commit -m "audit(): " -git push -u origin agent/ -gh pr create --base development --title "audit(): " --body "Closes #" -``` - ---- - -## Deliverables - -- [ ] Findings documented in the PR description or a report file -- [ ] Fixes applied (if applicable) -- [ ] PR targets `development` branch (if changes were made) diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md index 31d3fa5..b176c25 100644 --- a/.github/ISSUE_TEMPLATE/bug.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -41,7 +41,7 @@ assignees: "" ```yml agent: "" branch: "agent/" -worktree_path: "worktrees/" +worktree_path: ".worktrees/" pull_request: "FROM agent/ TO development" ``` @@ -53,7 +53,7 @@ make NAME= shell claude # When complete — PR from agent branch to development -cd worktrees/ +cd .worktrees/ git add -A && git commit -m "fix(): " git push -u origin agent/ gh pr create --base development --title "fix(): " --body "Closes #" diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md index 6f124d3..eff8a27 100644 --- a/.github/ISSUE_TEMPLATE/feature.md +++ b/.github/ISSUE_TEMPLATE/feature.md @@ -29,7 +29,7 @@ assignees: "" ```yml agent: "" branch: "agent/" -worktree_path: "worktrees/" +worktree_path: ".worktrees/" pull_request: "FROM agent/ TO development" ``` @@ -41,7 +41,7 @@ make NAME= shell claude # When complete — PR from agent branch to development -cd worktrees/ +cd .worktrees/ git add -A && git commit -m "feat(): " git push -u origin agent/ gh pr create --base development --title "feat(): " --body "Closes #" diff --git a/.github/ISSUE_TEMPLATE/skill.md b/.github/ISSUE_TEMPLATE/skill.md deleted file mode 100644 index 46c33cf..0000000 --- a/.github/ISSUE_TEMPLATE/skill.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -name: Skill -about: Create a new Claude Code skill -title: "[SKILL] " -labels: skill -assignees: "" ---- - -## Skill Definition - -- **Name**: -- **Description**: -- **Degrees of Freedom**: - -## Purpose - - - -## Examples - -### Example 1 - -**User**: -**Assistant**: - -### Example 2 - -**User**: -**Assistant**: - ---- - -## Skill Structure - -> Skills are modular instruction packages — NOT agents, NOT slash commands. They live at `.claude/skills//` and follow progressive disclosure: metadata is always loaded, SKILL.md loads when triggered, resources load on demand. - -``` -/ -├── SKILL.md # Required: frontmatter + instructions -├── scripts/ # Optional: executable code for deterministic tasks -├── references/ # Optional: docs loaded contextually -└── assets/ # Optional: output-ready files (NOT loaded in context) -``` - -### SKILL.md Format - -```markdown ---- -name: -description: | - Triggering info goes HERE in the frontmatter, not in the body. - Describe when and why Claude should apply this skill. ---- - -# Skill Name - -[Brief purpose statement] - -## Instructions - -[Numbered steps, imperative form ("Analyze the input" not "You should analyze")] - -## Examples - -[Realistic input/output scenarios] - -## Guidelines - -[Best practices, gotchas, warnings] - -## Reference - -[Optional: command tables, API refs, schemas] -``` - -### Checklist - -- [ ] Name is lowercase with hyphens only -- [ ] Triggering info is in YAML `description`, not the body -- [ ] Instructions use imperative form -- [ ] Examples are realistic scenarios (examples > descriptions) -- [ ] Content is under 5,000 words -- [ ] Degrees of freedom match the task risk level -- [ ] Resources (scripts/references/assets) documented if present -- [ ] One level of nesting max for references - ---- - -## Agent Assignment - -### Metadata - -> **IMPORTANT**: The very first step should _ALWAYS_ be validating this metadata section to maintain a **CLEAN** development workflow. - -```yml -agent: "" -branch: "agent/" -worktree_path: "worktrees/" -pull_request: "FROM agent/ TO development" -``` - -### Workflow - -```bash -# Enter the assigned agent's sandbox -make NAME= shell -claude - -# When complete — PR from agent branch to development -cd worktrees/ -git add -A && git commit -m "skill(): " -git push -u origin agent/ -gh pr create --base development --title "skill(): " --body "Closes #" -``` - ---- - -## Acceptance Criteria - -- [ ] Skill directory exists at `.claude/skills//` -- [ ] SKILL.md has valid YAML frontmatter -- [ ] Skill triggers correctly on matching user requests -- [ ] Does not trigger on unrelated requests -- [ ] PR targets `development` branch diff --git a/.github/ISSUE_TEMPLATE/task.md b/.github/ISSUE_TEMPLATE/task.md deleted file mode 100644 index 4268f13..0000000 --- a/.github/ISSUE_TEMPLATE/task.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -name: Task -about: A discrete unit of work to be completed -title: "[TASK] " -labels: task -assignees: "" ---- - -## Description - - - -## Context - - - ---- - -## Agent Assignment - -### Metadata - -> **IMPORTANT**: The very first step should _ALWAYS_ be validating this metadata section to maintain a **CLEAN** development workflow. - -```yml -agent: "" -branch: "agent/" -worktree_path: "worktrees/" -pull_request: "FROM agent/ TO development" -``` - -### Workflow - -```bash -# Enter the assigned agent's sandbox -make NAME= shell -claude - -# When complete — PR from agent branch to development -cd worktrees/ -git add -A && git commit -m "task(): " -git push -u origin agent/ -gh pr create --base development --title "task(): " --body "Closes #" -``` - ---- - -## Done When - -- [ ] -- [ ] -- [ ] PR targets `development` branch diff --git a/.gitignore b/.gitignore index dedbe53..4fbf634 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ **/.env* -worktrees/* -!worktrees/.gitkeep +.worktrees/* +!.worktrees/.gitkeep diff --git a/worktrees/.gitkeep b/.worktrees/.gitkeep similarity index 100% rename from worktrees/.gitkeep rename to .worktrees/.gitkeep diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fb18a33 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,98 @@ +# 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 sandboxed agent workspaces in `.worktrees/`. + +## Permissions + +You are restricted to git operations only (`git add`, `git commit`, `git push`). No `make`, `docker`, or shell execution. All coding, building, and testing happens INSIDE sandboxes, never at root. + +## Lifecycle + +### Setup + +Provision a new agent sandbox. The human runs all host commands. + +1. Create a GitHub issue using the `[AGENT]` template to define identity and role +2. Provision the sandbox: + ```bash + make NAME= quickstart + ``` + Creates: git worktree at `.worktrees/` on branch `agent/` (from `development`), Docker image, running container, provisioned environment. +3. Enter and start the agent: + ```bash + make NAME= shell + claude # or codex, pi + ``` + +### Validate + +Verify a sandbox is healthy. + +1. **Check running sandboxes**: + ```bash + make list + ``` +2. **Verify workspace** (inside the sandbox via `make NAME= shell`): + - `AGENTS.md`, `SOUL.md`, `MEMORY.md` exist in workspace + - Target agent CLI is installed (`claude --version`, `codex --version`, `pi --version`) + - Docker socket accessible if needed (`docker ps`) +3. **Check heartbeat** (if configured): + ```bash + make NAME= heartbeat-status + ``` + +### Teardown + +Remove an agent sandbox. Preserve work first if needed. + +1. **Save unmerged work** (if the agent branch has uncommitted changes): + ```bash + cd .worktrees/ + git add -A && git commit -m ": " && git push -u origin agent/ + ``` +2. **Stop the sandbox**: + ```bash + make NAME= stop + ``` +3. **Full cleanup** (removes container, image, and worktree): + ```bash + make NAME= clean + ``` + +## Git Workflow + +| Item | Convention | +|------|-----------| +| Base branch | `development` | +| Agent branches | `agent/` | +| PR target | `development` | +| Commit format | `: ` (`feat`, `fix`, `task`, `audit`, `skill`) | + +## What You Do + +- Commit and push changes to the harness itself (Makefile, docker/, install/, workspace/ templates) +- Manage branches and worktree state via git +- Review diffs across agent branches +- Advise the human on which `make` targets to run + +## What You Do NOT Do + +- Run `make`, `docker`, or any shell commands beyond git +- Build images or start containers +- Write application code +- Enter sandboxes or execute agents + +## Project Structure + +``` +.worktrees/ # Sandboxed agent worktrees (gitignored) +docker/ # Dockerfile and compose files +install/ # Provisioning scripts (setup.sh, heartbeat.sh, entrypoint.sh) +workspace/ # Template for all agent workspaces + AGENTS.md # In-sandbox agent instructions (separate from this file) + SOUL.md # Agent persona template + MEMORY.md # Long-term memory template + heartbeats.conf # Periodic task schedule +Makefile # Human-operated sandbox automation +.github/ISSUE_TEMPLATE/ # agent, task, bug, feature, audit, skill +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/Makefile b/Makefile index e74079d..eb46fb4 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ HEARTBEAT_AGENT ?= claude ifdef NAME IMAGE = $(REGISTRY)/$(NAME):$(TAG) export NAME - WORKTREE = worktrees/$(NAME) + WORKTREE = .worktrees/$(NAME) # Use worktree if it exists, otherwise fall back to repo root PROJECT_ROOT = $(if $(wildcard $(WORKTREE)/Makefile),$(WORKTREE),.) COMPOSE_FILES = -f $(PROJECT_ROOT)/docker/docker-compose.yml