agento

Files (1)

• SKILL.md

SKILL.md (first lines)

# agento

Use this skill by default for coding change requests.

## When to use

Route coding change requests through Agent-Orchestrator unless the user explicitly asks for mctrl.
Examples:
- "agento spawn worldai-claw-agento fix the login bug"
- "agento status"
- "agento send wa-abc1234 please push your changes"
- "agento fix PR 5879"
- "agento make this PR good"
- "agento keep fixing comments and CI until merge-ready"

## Worktree Requirement

**agento MUST always use a new git worktree** for agent sessions, unless already running inside an AO-managed worktree or session.

- The AO workspace plugin (`worktree`) is configured in `agent-orchestrator.yaml` with `workspace: worktree` for all projects
- Each spawn creates an isolated worktree in `~/.worktrees/<projectId>/<sessionId>/`
- This ensures agents never run directly in the base repo working tree
- Verify: if inside a worktree, `git rev-parse --git-common-dir` should point to the parent repo's .git

## CI & PR Comment Auto-Resolution

**agento automatically resolves CI failures and PR review comments** by default. This is configured in `agent-orchestrator.yaml` reactions:

```yaml
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 10m
  bugbot-comments:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
```

When AO detects:
- A CI check failure → spawns an agent to fix the issue
- Review comments requesting changes → spawns an agent to address them
- Bugbot comments → spawns an agent to investigate

The agent uses the project's `agentRules` which prioritize:
1. Resolve review comments with minimal safe changes
2. Fix failing CI checks
3. Push fixes and update PR

## AO CLI path

```
~/bin/ao
```

## AO Working Directory (Required)

Run AO commands from:

```bash
cd ~/.smartclaw
```

`ao` resolves the config via a walk-up overlay:
1. Looks for `agent-orchestrator.yaml` in the current directory (or symlinks at `~/agent-orchestrator.yaml`).
2. The **canonical config** lives at `~/.smartclaw_prod/agent-orchestrator.yaml` (a symlink at `~/agent-orchestrator.yaml` points to it).
3. The stub at `~/.smartclaw/agent-orchestrator.yaml` is a small base of a few private-org projects that gets **overlaid** by the canonical config. (For the private-org project names + token plumbing, load the machine-local `agentf` companion skill.)

**Pitfall — do NOT add new project entries to `~/.smartclaw/agent-orchestrator.yaml`:** The overlay merges per-project by config key, but uniqueness is checked by `basename(project.path)`. Adding a `worldai` project there with path `${HOME}/repos/jleechanorg/worldarchitect.ai` will collide with the canonical `worldarchitect` project (path `~/projects/worldarchitect.ai`) — both basenames are `worldarchitect.ai`. You'll get `Error: Duplicate project ID detected: "worldarchitect.ai"`. The fix: use the existing canonical project name (`worldarchitect`, `jleechanbrain`, etc.) instead of adding a new local one.

## Available projects (from canonical config `~/.smartclaw_prod/agent-orchestrator.yaml`)

- `agent-orchestrator` — jleechanorg/agent-orchestrator fork
- `browserclaw` — jleechanorg/browserclaw
- `claude-commands` — jleechanorg/claude-commands
- `hermes-agent` — jleechanorg/hermes-agent
- `jleechanbrain` — jleechanorg/jleechanbrain orchestration repo
- `llm_wiki` — jleechanorg/llm-wiki
- `mcp-mail` — jleechanorg/mcp_mail
- `mctrl-test` — jleechanorg/mctrl_test (legacy)
- `openclaw-sso` — jleechanorg/openclaw_sso
- `ralph` — jleechanorg/ralph
- `worldai-claw` — jleechanorg/worldai_claw
- `worldarchitect` — jleechanorg/worldarchitect.ai (Python/Flask game backend) ← use this for all WA work
- `worldclaw-dev` — jleechanorg/worldai_claw (v1.7 branch)

**If PR has no matching project:** Verify the canonical config is being loaded (`cat ~/.smartclaw_prod/agent-orchestrator.yaml | grep "<repo-keyword>"`). All common repos are already there. Spawn directly with the existing project name — do not add a duplicate entry.

**Project-id rule — short names, not GitHub slugs:** The `-p` / `--project` flag takes the **short project key from the canonical config above** (e.g. `worldarchitect`), NOT the GitHub slug (`jleechanorg/worldarchitect.ai`) and NOT the repo name with the org prefix (`worldarchitect.ai`). Verified 2026-06-12 on PR #6873 dispatch: passing `--project worldarchitect.ai` errors with `Unknown project: worldarchitect.ai — Available: agent-orchestrator, ..., worldarchitect, ...`. When in doubt, enumerate: `yq -r '.projects | keys | .[]' ~/.smartclaw_prod/agent-orchestrator.yaml`.

**Per-project concurrent-spawn lock:** AO enforces a single in-flight `ao spawn` per project. If a second `ao spawn --project <id>` fires while the first is still in its "Creating session" phase, it fails with `Another ao spawn is in progress for project "<id>" (PID <pid>, started <ts>). Wait for it to finish.` This is the *correct* behavior — two concurrent spawns on the same project can both create worktrees and race on the `.worktrees/<project>/` directory. Pattern when blocked by a peer spawn: poll `ps -p <pid>` every ~5s; once it's gone, retry. The lock releases within seconds of the first spawn printing its `✔ Session <id> created` line. Don't pre-emptively cancel your spawn; just wait.

**`--claim-pr` does NOT accept `--task`:** Verified 2026-06-12. The CLI parses `--claim-pr` as a flag, not a subcommand, so `--task` is unknown. The task text goes as the **positional argument** after the flag pair: `ao spawn -p <project> --claim-pr <N> "<task text>"`. If your task is long, see the "Long Task Briefs" section below — write it to `/tmp/` and pass a short summary as the positional arg instead.

**`--claim-pr auto` is NOT supported and produces an orphaned worktree.** Verified 2026-06-27 02:35 PT (this turn, follow-up spawn for D2/D5). When you spawn a NEW PR (no existing PR number yet), omit `--claim-pr` entirely — the AO worker will create the PR from its branch. Passing `--claim-pr auto` (or any non-numeric token) results in two failures chained:
1. `gh api repos/jleechanorg/<repo>/pulls/auto` returns 404, the worker session is created but flagged `failed`.
2. The retry without `--claim-pr` succeeds but AO thinks the worktree path `~/.worktrees/<project>/jc-NNNN` is already in use, and fails again: `Found existing worktree for orchestrator branch "<name>" at "<path>", but it is outside AO-managed worktree directories. Reuse it manually or remove it and try again.`
3. Manual cleanup: `rm -rf ~/.worktrees/<project>/jc-NNNN && git worktree prune`. Verified recovery works.

**Pattern for new-PR / new-script spawns:** just `ao spawn -p <project> "<task>"` — no `--claim-pr`. The worker creates the PR as part of its work.

## Architecture: AO is the lane for code change work, NOT mctrl

`mctrl` is the durable jleechanbrain orchestration layer (supervisor + notifier + reconciliation). It owns the canonical task source of truth for jleechanbrain's own reliability roadmap. But for **any code-change or PR work** — including private-org, worldarchitect, and jleechanorg repos — the right path is plain AO (`ao spawn`). Do not route through `mctrl supervisor` for completion notifications of coding tasks. The frontmatter above is explicit: "Never use mctrl unless explicitly requested." When you finish a dispatch, just say "Spawned `aa-2` for PR #170" — do not invoke mctrl supervisor language.

**mctrl is also deprecated as a product name (Jeffrey 2026-06-09).** If a user asks to "purge mctrl" or "remove mctrl references", load the `legacy-term-deprecation-sweep` skill — it has the workflow (catalog before purge, skip frozen artifacts, handle live launchd plists separately) and the 2026-06-09 catalog for the jleechanbrain workspace. Do not bundle a mctrl sweep into a code-change PR — keep it as its own sequenced plan.

## Private-org dispatch (account + token plumbing)

Some repos live under a **separate private GitHub account / org** that AO's
default bot token (`AO_BOT_GH_TOKEN`) cannot see, so `--claim-pr` returns 404
unless you override the token. The full token-override spawn pattern, project
base stub, and self-push / gist-authoring plumbing for that private org are
documented in the machine-local **`agentf` companion skill** (`skills/agentf/SKILL.md`,

From jleechanorg/jleechanbrain, MIT.

More from jleechanorg/jleechanbrain