Skip to content

t1023: Reduce AGENTS.md instruction count from 67 to <50 #1331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 6 commits into from
Feb 13, 2026
Merged

t1023: Reduce AGENTS.md instruction count from 67 to <50 #1331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a9c0ff0
docs: add task completion rules section to plans.md (t1023)
alex-solovyev Feb 12, 2026
bc2280a
docs: add task ID allocation section to plans.md (t1023)
alex-solovyev Feb 12, 2026
759be50
docs: add worktree ownership section to git-workflow.md (t1023)
alex-solovyev Feb 12, 2026
f950d40
docs: add supervisor CLI section to headless-dispatch.md (t1023)
alex-solovyev Feb 12, 2026
2763801
docs: consolidate AGENTS.md sections with pointers to subagents (t1023)
alex-solovyev Feb 12, 2026
01c5eb1
docs: further consolidate AGENTS.md to reach <50 instructions (t1023)
alex-solovyev Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 20 additions & 80 deletions .agents/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,7 @@ All development work MUST follow this lifecycle:

1. **Create a TODO entry** in `TODO.md` before starting any work
2. **Ask the user**: implement now (full-loop) or queue for runner orchestration?
3. **If implementing now**, follow the full-loop development lifecycle:
- Create branch/worktree
- Implement changes
- Run tests (syntax, shellcheck, Docker tests, integration tests as applicable)
- Verify the changes work end-to-end
- Only then offer to commit/PR
3. **If implementing now**, follow full-loop: branch/worktree → implement → test → verify → commit/PR
4. **If queuing**, add the task to `TODO.md` with appropriate metadata (`~estimate`, `#tags`, dependencies) so the supervisor can dispatch it to a runner when orchestration next runs

Never skip testing. Never declare work "done" without verification. The full-loop means: plan -> implement -> test -> verify -> deliver.
Expand Down Expand Up @@ -92,8 +87,7 @@ Full PTY access: run any CLI (`vim`, `psql`, `ssh`, `htop`, dev servers, `Claude
**Critical Rules**:
- Git check before edits (see above)
- File discovery via Bash (see above)
- **ALWAYS Read before Edit/Write** - Edit and Write tools FAIL if the file hasn't been Read in this conversation. Read the file first, then edit. No exceptions.
- Re-read files immediately before editing (stale reads cause errors)
- **ALWAYS Read before Edit/Write** - Re-read immediately before editing (stale reads cause errors)
- Context budget: Never >100K tokens per operation
- NEVER create files in `~/` root - use `~/.aidevops/.agent-workspace/work/[project]/`
- NEVER expose credentials in output/logs
Expand All @@ -103,43 +97,30 @@ Full PTY access: run any CLI (`vim`, `psql`, `ssh`, `htop`, dev servers, `Claude

## Planning & Tasks

Use `/save-todo` after planning. Auto-detects complexity:
- **Simple** → TODO.md only
- **Complex** → PLANS.md + TODO.md reference
Use `/save-todo` after planning. Auto-detects complexity (simple → TODO.md only, complex → PLANS.md + TODO.md reference).

**Key commands**: `/new-task`, `/save-todo`, `/ready`, `/sync-beads`, `/plan-status`, `/create-prd`, `/generate-tasks`

**Task format**: `- [ ] t001 Description @owner #tag ~4h (ai:2h test:1h) started:ISO blocked-by:t002`

**Dependencies**: `blocked-by:t001`, `blocks:t002`, `t001.1` (subtask)

**Auto-dispatch**: Add `#auto-dispatch` to tasks that can run autonomously (clear spec, bounded scope, no user input needed). Default to including it — only omit when a specific exclusion applies. See `workflows/plans.md` "Auto-Dispatch Tagging" for full criteria. The supervisor's Phase 0 picks these up automatically every 2 minutes and auto-creates batches (`auto-YYYYMMDD-HHMMSS`, concurrency = cores/2, min 2) when no active batch exists.
**Auto-dispatch**: Add `#auto-dispatch` to tasks that can run autonomously. See `workflows/plans.md` "Auto-Dispatch Tagging" for criteria.

**Task completion rules** (CRITICAL - prevents false completion cascade):
- NEVER mark a task `[x]` unless a merged PR exists with real deliverables for that task
- Use `task-complete-helper.sh <task-id> --pr <number>` or `task-complete-helper.sh <task-id> --verified` to mark tasks complete in interactive sessions
- The helper enforces proof-log requirements: every completion MUST have `pr:#NNN` or `verified:YYYY-MM-DD`
- The supervisor `update_todo_on_complete()` enforces the same requirement for autonomous workers
- The pre-commit hook rejects TODO.md commits where `[ ] -> [x]` without proof-log
- Checking that a file exists is NOT sufficient - verify the PR was merged and contains substantive changes
- If a worker completes with `no_pr` or `task_only`, the task stays `[ ]` until a human or the supervisor verifies the deliverable
- The `issue-sync` GitHub Action auto-closes issues when tasks are marked `[x]` - false completions cascade into closed issues
- NEVER close GitHub issues manually with `gh issue close` — let the issue-sync pipeline verify deliverables (`pr:` or `verified:` field) before closing. Manual closure bypasses the proof-log safety check
- **Pre-commit enforcement**: The pre-commit hook checks TODO.md for newly completed tasks (`[ ]` → `[x]`) and warns if no `verified:` field or merged PR evidence exists. This is a warning only (commit proceeds) but serves as a reminder to add completion evidence.
- NEVER mark `[x]` unless merged PR exists with real deliverables (or `verified:YYYY-MM-DD`)
- Use `task-complete-helper.sh <task-id> --pr <number>` or `--verified` (enforces proof-log)
- Workers MUST NOT edit TODO.md (supervisor owns all TODO.md updates)

**After ANY TODO/planning edit** (interactive sessions only, NOT workers): Commit and push immediately. Planning-only files (TODO.md, todo/) go directly to main -- no branch, no PR. Mixed changes (planning + non-exception files) use a worktree. NEVER `git checkout -b` in the main repo.
See `workflows/plans.md` "Task Completion Rules" for full enforcement layers and what NOT to do.

**PR required for ALL non-planning changes** (MANDATORY): Every change to scripts, agents, configs, workflows, or any file outside `TODO.md`, `todo/`, and `VERIFY.md` MUST go through a worktree + PR + CI pipeline — no matter how small. "It's just one line" is not a valid reason to skip CI. The pre-edit-check script enforces this; never bypass it by editing directly on main.
**After TODO/planning edit**: Commit and push immediately. Planning files (TODO.md, todo/) go to main. Mixed changes use worktree. NEVER `git checkout -b` in main repo.

**Task ID allocation** (MANDATORY): Use `/new-task` or `claim-task-id.sh` to allocate task IDs. NEVER manually scan TODO.md with grep to determine the next ID — this causes collisions in parallel sessions. The allocation flow:
**PR required** (MANDATORY): ALL non-planning changes MUST go through worktree + PR + CI. No exceptions. See `workflows/git-workflow.md`.

1. `/new-task "Task title"` — interactive slash command (preferred in sessions)
2. `planning-commit-helper.sh next-id --title "Task title"` — wrapper function
3. `claim-task-id.sh --title "Task title" --repo-path "$(pwd)"` — direct script
**Task ID allocation** (MANDATORY): Use `/new-task` or `claim-task-id.sh` to allocate task IDs. NEVER manually scan TODO.md with grep — causes collisions in parallel sessions.

Online mode creates a GitHub/GitLab issue as a distributed lock, then allocates `t(N+1)`. Offline fallback allocates `t(N+100)` to avoid collisions (reconcile when back online). Output format: `TASK_ID=tNNN TASK_REF=GH#NNN TASK_OFFLINE=false`.

**Task ID collision prevention**: If `git push` fails after adding a task, `git pull --rebase` and re-read TODO.md to verify your ID is still unique. If a collision exists, re-run `claim-task-id.sh` to get a fresh ID.
See `workflows/plans.md` "Task ID Allocation" for allocation flow, online/offline modes, and collision prevention.

**Full docs**: `workflows/plans.md`, `tools/task-management/beads.md`

Expand Down Expand Up @@ -177,13 +158,7 @@ Cross-session SQLite FTS5 memory. Commands: `/remember {content}`, `/recall {que

**Namespaces**: Runners can have isolated memory via `--namespace <name>`. Use `--shared` to also search global memory. List with `memory-helper.sh namespaces`.

**Auto-recall**: Memories are automatically recalled at key entry points:
- **Interactive session start**: Recent memories (last 5) surface via conversation-starter.md
- **Session resume**: After loading checkpoint, recent memories provide context
- **Runner dispatch**: Before task execution, runners recall recent + task-specific memories
- **Objective runner**: On first step, recalls recent + objective-specific + failure pattern memories

Auto-recall is silent (no output if no memories found) and uses namespace isolation for runners.
**Auto-recall**: Memories automatically recalled at session start, resume, and runner dispatch. Silent if none found. See `memory/README.md`.

**Full docs**: `memory/README.md`

Expand Down Expand Up @@ -245,52 +220,23 @@ worktree-helper.sh add feature/x # Fallback

**After completing changes**, offer: 1) Preflight checks 2) Skip preflight 3) Continue editing

**PR title format** (MANDATORY): All PRs MUST include task ID from TODO.md: `{task-id}: {description}`. For unplanned work (hotfix, quick fix), create TODO entry first with `~15m` estimate, then create PR. No work should be untraceable. See `workflows/git-workflow.md` "PR Title Requirements" for full guidance.
**PR title format** (MANDATORY): All PRs MUST include task ID: `{task-id}: {description}`. See `workflows/git-workflow.md` "PR Title Requirements".

**Branch types**: `feature/`, `bugfix/`, `hotfix/`, `refactor/`, `chore/`, `experiment/`, `release/`

**Worktree ownership** (CRITICAL): NEVER remove a worktree unless (a) you created it in this session, (b) it belongs to a task in your active batch, AND the task is deployed/complete, or (c) the user explicitly asks. Worktrees may belong to parallel sessions — removing them destroys another agent's working directory mid-work. When cleaning up, only touch worktrees for tasks you personally merged. Use `git worktree list` to see all worktrees but do NOT assume unrecognized ones are safe to remove. The ownership registry (`worktree-helper.sh registry list`) tracks which PID owns each worktree — `remove` and `clean` commands automatically refuse to touch worktrees owned by other live processes.
**Worktree ownership** (CRITICAL): NEVER remove a worktree unless you created it, it's your completed task, or user asks — parallel sessions may be using it. See `workflows/git-workflow.md` "Worktree Ownership" for ownership registry and safe cleanup workflow.

**Safety hooks** (Claude Code only): Destructive commands (`git reset --hard`, `rm -rf`, etc.) are blocked by a PreToolUse hook. Run `install-hooks.sh --test` to verify. See `workflows/git-workflow.md` "Destructive Command Safety Hooks" section.
**Safety hooks**: Destructive commands blocked by PreToolUse hook. See `workflows/git-workflow.md` "Destructive Command Safety Hooks".

**Full docs**: `workflows/git-workflow.md`, `tools/git/worktrunk.md`

## Autonomous Orchestration

**CLI**: `Claude` is the ONLY supported CLI for worker dispatch. Never use `claude` CLI.

**Supervisor** (`supervisor-helper.sh`): Manages parallel task execution with SQLite state machine.

```bash
# Add tasks and create batch
supervisor-helper.sh add t001 --repo "$(pwd)" --description "Task description"
supervisor-helper.sh batch "my-batch" --concurrency 3 --tasks "t001,t002,t003"

# Task claiming (t165 — provider-agnostic, TODO.md primary)
supervisor-helper.sh claim t001 # Adds assignee: to TODO.md, optional GH sync
supervisor-helper.sh unclaim t001 # Releases claim (removes assignee:)
# Claiming is automatic during dispatch. Manual claim/unclaim for coordination.
**Supervisor** (`supervisor-helper.sh`): Manages parallel task execution with SQLite state machine. Cron pulse (every 2 min) is MANDATORY for autonomous operation.

# Install cron pulse (REQUIRED for autonomous operation)
supervisor-helper.sh cron install
**Assignee ownership** (t1017): NEVER remove or change `assignee:` on a task without explicit user confirmation — may be a contributor on another host.

# Manual pulse (cron does this automatically every 2 minutes)
supervisor-helper.sh pulse --batch <batch-id>

# Monitor
supervisor-helper.sh dashboard --batch <batch-id>
supervisor-helper.sh status <batch-id>
```

**Task claiming** (t165): TODO.md `assignee:` field is the authoritative claim source. Works offline, with any git host. GitHub Issue sync is optional best-effort (requires `gh` CLI + `ref:GH#` in TODO.md). GH Issue creation is opt-in: use `--with-issue` flag or `SUPERVISOR_AUTO_ISSUE=true`.

**Assignee ownership** (t1017): NEVER remove or change `assignee:` on a task without explicit user confirmation. The assignee may be a contributor on another host whose work you cannot see. `unclaim` requires `--force` to release a task claimed by someone else. The full-loop claims the task automatically before starting work — if the task is already claimed by another, the loop stops.

**Cron pulse is mandatory** for autonomous operation. Without it, the supervisor is passive and requires manual `pulse` calls. The pulse cycle: check workers -> evaluate outcomes -> dispatch next -> cleanup.

**Session memory monitoring + respawn** (t264, t264.1): Long-running Claude Code/Bun sessions accumulate WebKit malloc dirty pages that are never returned to the OS (25GB+ observed). Phase 11 of the pulse cycle checks the parent session's `phys_footprint` when a batch wave completes (no running/queued tasks). If memory exceeds `SUPERVISOR_SELF_MEM_LIMIT` (default: 8192MB), it saves a checkpoint, logs the respawn event to `~/.aidevops/logs/respawn-history.log`, and exits cleanly for the next cron pulse to start fresh. Use `supervisor-helper.sh mem-check` to inspect memory and `supervisor-helper.sh respawn-history` to review respawn patterns.

**Full docs**: `tools/ai-assistants/headless-dispatch.md`, `supervisor-helper.sh help`
See `tools/ai-assistants/headless-dispatch.md` "Supervisor CLI" for batch creation, task claiming, monitoring, and session memory respawn.

## Session Completion

Expand All @@ -304,13 +250,7 @@ Run `/session-review` before ending. Suggest new sessions after PR merge, domain

When context is compacted (long sessions, autonomous loops), operational state is lost unless persisted to disk. Use `/checkpoint` to save and restore session state.

**Commands**:

- `/checkpoint` or `session-checkpoint-helper.sh save --task <id> --next <ids>` — save current state
- `session-checkpoint-helper.sh load` — reload state after compaction
- `session-checkpoint-helper.sh continuation` — generate a full continuation prompt for new sessions

**When to checkpoint**: After each task completion, before large operations, after PR creation/merge.
**Commands**: `/checkpoint` (save), `session-checkpoint-helper.sh load` (restore), `continuation` (new session prompt). Checkpoint after task completion, before large ops, after PR.

**Compaction survival rule**: When summarizing this conversation for compaction, ALWAYS preserve: current task IDs and states, active batch ID, worktree path, open PR numbers, and the next 3 action items. This operational state is more important than conversation history details.

Expand Down
45 changes: 45 additions & 0 deletions .agents/tools/ai-assistants/headless-dispatch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -517,6 +517,51 @@ BLOCKED: Task says 'update the auth endpoint' but there are 3 auth endpoints
Need clarification on which one(s) to update.
```

## Supervisor CLI

The supervisor (`supervisor-helper.sh`) manages parallel task execution with a SQLite state machine.

### Basic Commands

```bash
# Add tasks and create batch
supervisor-helper.sh add t001 --repo "$(pwd)" --description "Task description"
supervisor-helper.sh batch "my-batch" --concurrency 3 --tasks "t001,t002,t003"

# Task claiming (t165 — provider-agnostic, TODO.md primary)
supervisor-helper.sh claim t001 # Adds assignee: to TODO.md, optional GH sync
supervisor-helper.sh unclaim t001 # Releases claim (removes assignee:)
# Claiming is automatic during dispatch. Manual claim/unclaim for coordination.

# Install cron pulse (REQUIRED for autonomous operation)
supervisor-helper.sh cron install

# Manual pulse (cron does this automatically every 2 minutes)
supervisor-helper.sh pulse --batch <batch-id>

# Monitor
supervisor-helper.sh dashboard --batch <batch-id>
supervisor-helper.sh status <batch-id>
```

### Task Claiming

**TODO.md `assignee:` field** is the authoritative claim source. Works offline, with any git host. GitHub Issue sync is optional best-effort (requires `gh` CLI + `ref:GH#` in TODO.md). GH Issue creation is opt-in: use `--with-issue` flag or `SUPERVISOR_AUTO_ISSUE=true`.

### Assignee Ownership

**NEVER remove or change `assignee:` on a task without explicit user confirmation.** The assignee may be a contributor on another host whose work you cannot see. `unclaim` requires `--force` to release a task claimed by someone else. The full-loop claims the task automatically before starting work — if the task is already claimed by another, the loop stops.

### Cron Pulse

**Cron pulse is mandatory** for autonomous operation. Without it, the supervisor is passive and requires manual `pulse` calls. The pulse cycle: check workers -> evaluate outcomes -> dispatch next -> cleanup.

### Session Memory Monitoring

Long-running OpenCode/Bun sessions accumulate WebKit malloc dirty pages that are never returned to the OS (25GB+ observed). Phase 11 of the pulse cycle checks the parent session's `phys_footprint` when a batch wave completes (no running/queued tasks). If memory exceeds `SUPERVISOR_SELF_MEM_LIMIT` (default: 8192MB), it saves a checkpoint, logs the respawn event to `~/.aidevops/logs/respawn-history.log`, and exits cleanly for the next cron pulse to start fresh.

**Commands**: `supervisor-helper.sh mem-check` (inspect memory), `supervisor-helper.sh respawn-history` (review respawn patterns)

### Integration with Supervisor

The supervisor uses worker exit behavior to drive the self-improvement loop:
Expand Down
32 changes: 32 additions & 0 deletions .agents/workflows/git-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -658,6 +658,38 @@ git remote prune origin
| Unmerged + stale (>30 days) | Ask user about status |
| Unmerged + active | Keep |

### Worktree Ownership

**CRITICAL**: NEVER remove a worktree unless you meet ALL of these conditions:

1. **You created it in this session**, OR
2. **It belongs to a task in your active batch** AND the task is deployed/complete, OR
3. **The user explicitly asks**

**Why this matters**: Worktrees may belong to parallel sessions. Removing them destroys another agent's working directory mid-work.

**Safe cleanup workflow**:

```bash
# 1. Check ownership registry
worktree-helper.sh registry list

# 2. Only remove worktrees you personally merged
# The registry tracks which PID owns each worktree

# 3. Use helper commands (they enforce ownership checks)
worktree-helper.sh remove feature/my-feature # Refuses if owned by another live process
worktree-helper.sh clean # Only removes worktrees you own
```
Comment on lines +671 to +683
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify helper script path to avoid PATH-dependent failures.

Earlier examples use the full ~/.aidevops/agents/scripts/... path, but this block assumes worktree-helper.sh is on PATH. Please align with the canonical path or explicitly state it must be on PATH to prevent confusion in safety-critical cleanup steps.

🔧 Suggested doc tweak 
-# 1. Check ownership registry
-worktree-helper.sh registry list
+# 1. Check ownership registry
+~/.aidevops/agents/scripts/worktree-helper.sh registry list
...
-worktree-helper.sh remove feature/my-feature  # Refuses if owned by another live process
-worktree-helper.sh clean                      # Only removes worktrees you own
+~/.aidevops/agents/scripts/worktree-helper.sh remove feature/my-feature  # Refuses if owned by another live process
+~/.aidevops/agents/scripts/worktree-helper.sh clean                      # Only removes worktrees you own
🤖 Prompt for AI Agents 
In @.agents/workflows/git-workflow.md around lines 671 - 683, The docs show
commands using worktree-helper.sh without a path; update this block to either
use the canonical script path (~/.aidevops/agents/scripts/worktree-helper.sh)
for all examples (e.g., ~/.aidevops/agents/scripts/worktree-helper.sh registry
list, ... remove, ... clean) or add a one-line note above the commands saying
"Ensure ~/.aidevops/agents/scripts is on your PATH or use the full path to
worktree-helper.sh" so that calls to worktree-helper.sh (registry list, remove,
clean) are unambiguous and not PATH-dependent.


**What NOT to do**:

- NEVER assume unrecognized worktrees are safe to remove
- NEVER use `git worktree remove` directly (bypasses ownership checks)
- NEVER remove worktrees for tasks you didn't personally merge

**Ownership registry**: `worktree-helper.sh registry list` shows which PID owns each worktree. The `remove` and `clean` commands automatically refuse to touch worktrees owned by other live processes.
Comment on lines +661 to +691
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for potential duplicates of Worktree Ownership guidance across .agents/
echo "=== Searching for Worktree Ownership related patterns ==="
rg -n --glob '.agents/**/*.md' "Worktree Ownership|ownership registry|worktree-helper\.sh (remove|clean|registry list)" 

echo ""
echo "=== Broader search for worktree cleanup guidance ==="
rg -n --glob '.agents/**/*.md' -i "worktree.*clean|worktree.*remov|git worktree" | head -30

Repository: marcusquinn/aidevops

Length of output: 4727

Consolidate Worktree Ownership guidance—it already exists in .agents/workflows/worktree.md.

The rg scan confirms duplication: worktree ownership, registry patterns, and safe cleanup workflows are already comprehensively documented in .agents/workflows/worktree.md (lines 387–392+). The content added to git-workflow.md:661–691 replicates this existing guidance. Per framework standards, maintain operational guidance in a single authoritative location. Either:

  1. Remove the new section from git-workflow.md and keep the reference in AGENTS.md:227 pointing to worktree.md as the primary source, or
  2. Consolidate into .agents/workflows/worktree.md if this is now the canonical reference, then update AGENTS.md and git-workflow.md to cross-reference it.

Ensure the final structure avoids split ownership guidance across files.

🤖 Prompt for AI Agents 
In @.agents/workflows/git-workflow.md around lines 661 - 691, The "Worktree
Ownership" block duplicated in git-workflow.md (the section with the "Worktree
Ownership" heading and commands like worktree-helper.sh registry list /
worktree-helper.sh remove / worktree-helper.sh clean) must be removed from
git-workflow.md and replaced with a single cross-reference to the canonical
.agents/workflows/worktree.md, or alternatively consolidate by moving any unique
content into .agents/workflows/worktree.md and then update AGENTS.md and
git-workflow.md to point to that canonical file; ensure you keep the ownership
rules and helper command references exclusively in .agents/workflows/worktree.md
and update AGENTS.md and git-workflow.md to reference that file so guidance
isn’t split across sources.


## User Experience Levels

These workflows support all skill levels:
Expand Down
Loading
Loading