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) <noreply@anthropic.com>
This commit is contained in:
ryaneggzandClaude Opus 4.6 committed
1 parent
5e0f7bc8e7
commit
82d24da11c
11 files changed
+106
-298
No files matched your search
@@ -1,57 +0,0 @@
|
||||
---
|
||||
name: Agent
|
||||
about: Provision a new agent workspace
|
||||
title: "[AGENT] "
|
||||
labels: agent
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: <!-- e.g. researcher, builder, alice -->
|
||||
- **Role**: <!-- What is this agent responsible for? -->
|
||||
|
||||
## Context
|
||||
|
||||
<!-- What should this agent know? What projects, docs, or repos should it have access to? -->
|
||||
|
||||
---
|
||||
|
||||
## 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: "<agent-name>"
|
||||
branch: "agent/<agent-name>"
|
||||
worktree_path: "worktrees/<agent-name>"
|
||||
```
|
||||
|
||||
### 1. Provision the agent
|
||||
|
||||
```bash
|
||||
make NAME=<agent-name> quickstart
|
||||
```
|
||||
|
||||
This will:
|
||||
- Create a git worktree at `worktrees/<agent-name>` on branch `agent/<agent-name>`, 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=<agent-name> shell
|
||||
claude
|
||||
```
|
||||
|
||||
### 3. Verify
|
||||
|
||||
- [ ] Container is running (`make list`)
|
||||
- [ ] Agent can access workspace (`ls ~/workspace`)
|
||||
- [ ] SOUL.md and MEMORY.md are present
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
name: Audit
|
||||
about: Review or audit existing code, config, or processes
|
||||
title: "[AUDIT] "
|
||||
labels: audit
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## Scope
|
||||
|
||||
<!-- What is being audited? Files, directories, systems, or processes. -->
|
||||
|
||||
## Objective
|
||||
|
||||
<!-- What are you looking for? e.g. security issues, dead code, config drift, compliance gaps -->
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] <!-- Area 1 to review -->
|
||||
- [ ] <!-- Area 2 to review -->
|
||||
- [ ] <!-- Area 3 to review -->
|
||||
|
||||
---
|
||||
|
||||
## Agent Assignment
|
||||
|
||||
### Metadata
|
||||
|
||||
> **IMPORTANT**: The very first step should _ALWAYS_ be validating this metadata section to maintain a **CLEAN** development workflow.
|
||||
|
||||
```yml
|
||||
agent: "<agent-name>"
|
||||
branch: "agent/<agent-name>"
|
||||
worktree_path: "worktrees/<agent-name>"
|
||||
pull_request: "FROM agent/<agent-name> TO development"
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
```bash
|
||||
# Enter the assigned agent's sandbox
|
||||
make NAME=<agent-name> shell
|
||||
claude
|
||||
|
||||
# If the audit produces fixes — PR from agent branch to development
|
||||
cd worktrees/<agent-name>
|
||||
git add -A && git commit -m "audit(<issue#>): <description>"
|
||||
git push -u origin agent/<agent-name>
|
||||
gh pr create --base development --title "audit(<issue#>): <shortdesc>" --body "Closes #<issue#>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
- [ ] Findings documented in the PR description or a report file
|
||||
- [ ] Fixes applied (if applicable)
|
||||
- [ ] PR targets `development` branch (if changes were made)
|
||||
@@ -41,7 +41,7 @@ assignees: ""
|
||||
```yml
|
||||
agent: "<agent-name>"
|
||||
branch: "agent/<agent-name>"
|
||||
worktree_path: "worktrees/<agent-name>"
|
||||
worktree_path: ".worktrees/<agent-name>"
|
||||
pull_request: "FROM agent/<agent-name> TO development"
|
||||
```
|
||||
|
||||
@@ -53,7 +53,7 @@ make NAME=<agent-name> shell
|
||||
claude
|
||||
|
||||
# When complete — PR from agent branch to development
|
||||
cd worktrees/<agent-name>
|
||||
cd .worktrees/<agent-name>
|
||||
git add -A && git commit -m "fix(<issue#>): <description>"
|
||||
git push -u origin agent/<agent-name>
|
||||
gh pr create --base development --title "fix(<issue#>): <shortdesc>" --body "Closes #<issue#>"
|
||||
|
||||
@@ -29,7 +29,7 @@ assignees: ""
|
||||
```yml
|
||||
agent: "<agent-name>"
|
||||
branch: "agent/<agent-name>"
|
||||
worktree_path: "worktrees/<agent-name>"
|
||||
worktree_path: ".worktrees/<agent-name>"
|
||||
pull_request: "FROM agent/<agent-name> TO development"
|
||||
```
|
||||
|
||||
@@ -41,7 +41,7 @@ make NAME=<agent-name> shell
|
||||
claude
|
||||
|
||||
# When complete — PR from agent branch to development
|
||||
cd worktrees/<agent-name>
|
||||
cd .worktrees/<agent-name>
|
||||
git add -A && git commit -m "feat(<issue#>): <description>"
|
||||
git push -u origin agent/<agent-name>
|
||||
gh pr create --base development --title "feat(<issue#>): <shortdesc>" --body "Closes #<issue#>"
|
||||
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
name: Skill
|
||||
about: Create a new Claude Code skill
|
||||
title: "[SKILL] "
|
||||
labels: skill
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## Skill Definition
|
||||
|
||||
- **Name**: <!-- lowercase-with-hyphens -->
|
||||
- **Description**: <!-- When should Claude use this skill? What triggers it? -->
|
||||
- **Degrees of Freedom**: <!-- High / Medium / Low -->
|
||||
|
||||
## Purpose
|
||||
|
||||
<!-- What specific problem does this skill solve? What does success look like? -->
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1
|
||||
|
||||
**User**: <!-- "Realistic user request that should trigger this skill" -->
|
||||
**Assistant**: <!-- Expected behavior or output -->
|
||||
|
||||
### Example 2
|
||||
|
||||
**User**: <!-- "Another scenario" -->
|
||||
**Assistant**: <!-- Expected behavior or output -->
|
||||
|
||||
---
|
||||
|
||||
## Skill Structure
|
||||
|
||||
> Skills are modular instruction packages — NOT agents, NOT slash commands. They live at `.claude/skills/<skill-name>/` and follow progressive disclosure: metadata is always loaded, SKILL.md loads when triggered, resources load on demand.
|
||||
|
||||
```
|
||||
<skill-name>/
|
||||
├── 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: <skill-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: "<agent-name>"
|
||||
branch: "agent/<agent-name>"
|
||||
worktree_path: "worktrees/<agent-name>"
|
||||
pull_request: "FROM agent/<agent-name> TO development"
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
```bash
|
||||
# Enter the assigned agent's sandbox
|
||||
make NAME=<agent-name> shell
|
||||
claude
|
||||
|
||||
# When complete — PR from agent branch to development
|
||||
cd worktrees/<agent-name>
|
||||
git add -A && git commit -m "skill(<issue#>): <description>"
|
||||
git push -u origin agent/<agent-name>
|
||||
gh pr create --base development --title "skill(<issue#>): <shortdesc>" --body "Closes #<issue#>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Skill directory exists at `.claude/skills/<skill-name>/`
|
||||
- [ ] SKILL.md has valid YAML frontmatter
|
||||
- [ ] Skill triggers correctly on matching user requests
|
||||
- [ ] Does not trigger on unrelated requests
|
||||
- [ ] PR targets `development` branch
|
||||
@@ -1,52 +0,0 @@
|
||||
---
|
||||
name: Task
|
||||
about: A discrete unit of work to be completed
|
||||
title: "[TASK] "
|
||||
labels: task
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
<!-- What needs to be done? Be specific. -->
|
||||
|
||||
## Context
|
||||
|
||||
<!-- Any relevant background, links, or dependencies. -->
|
||||
|
||||
---
|
||||
|
||||
## Agent Assignment
|
||||
|
||||
### Metadata
|
||||
|
||||
> **IMPORTANT**: The very first step should _ALWAYS_ be validating this metadata section to maintain a **CLEAN** development workflow.
|
||||
|
||||
```yml
|
||||
agent: "<agent-name>"
|
||||
branch: "agent/<agent-name>"
|
||||
worktree_path: "worktrees/<agent-name>"
|
||||
pull_request: "FROM agent/<agent-name> TO development"
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
```bash
|
||||
# Enter the assigned agent's sandbox
|
||||
make NAME=<agent-name> shell
|
||||
claude
|
||||
|
||||
# When complete — PR from agent branch to development
|
||||
cd worktrees/<agent-name>
|
||||
git add -A && git commit -m "task(<issue#>): <description>"
|
||||
git push -u origin agent/<agent-name>
|
||||
gh pr create --base development --title "task(<issue#>): <shortdesc>" --body "Closes #<issue#>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Done When
|
||||
|
||||
- [ ] <!-- Criteria 1 -->
|
||||
- [ ] <!-- Criteria 2 -->
|
||||
- [ ] PR targets `development` branch
|
||||
+2
-2
@@ -1,3 +1,3 @@
|
||||
**/.env*
|
||||
worktrees/*
|
||||
!worktrees/.gitkeep
|
||||
.worktrees/*
|
||||
!.worktrees/.gitkeep
|
||||
File renamed without changes.
@@ -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=<agent-name> quickstart
|
||||
```
|
||||
Creates: git worktree at `.worktrees/<agent-name>` on branch `agent/<agent-name>` (from `development`), Docker image, running container, provisioned environment.
|
||||
3. Enter and start the agent:
|
||||
```bash
|
||||
make NAME=<agent-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=<agent-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=<agent-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/<agent-name>
|
||||
git add -A && git commit -m "<type>: <description>" && git push -u origin agent/<agent-name>
|
||||
```
|
||||
2. **Stop the sandbox**:
|
||||
```bash
|
||||
make NAME=<agent-name> stop
|
||||
```
|
||||
3. **Full cleanup** (removes container, image, and worktree):
|
||||
```bash
|
||||
make NAME=<agent-name> clean
|
||||
```
|
||||
|
||||
## Git Workflow
|
||||
|
||||
| Item | Convention |
|
||||
|------|-----------|
|
||||
| Base branch | `development` |
|
||||
| Agent branches | `agent/<agent-name>` |
|
||||
| PR target | `development` |
|
||||
| Commit format | `<type>: <description>` (`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
|
||||
```
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user