agent-goal-stack

Cross-LLM goal stack for Claude Code and Codex CLI.

Two skills under the /ags: namespace:

• /ags:goal-prep — pre-execution intake. 6-question diagnostic ladder + anti-patterns + goal.md charter + a copy-clear-paste flow that hands you a ready-to-run /goal command. The condition itself tells the main model to read the charter on turn 1, so no heavy preamble paste needed.
• /ags:autoresearch — keep-or-revert metric loop. Commit before verify, revert on regression. Optional cross-LLM rescue hook on stuck iterations; pre-merge cross-LLM review on completion.

Does not replace native /goal — adds warmup, anti-patterns, and an orthogonal metric loop on top.

Quick start

# Charter + ready-to-run /goal for any goal
/ags:goal-prep find P1 bugs in checkout/*

# Skill prints a /goal command. Copy it, type /clear, then paste.
/goal Five P1 bugs in checkout/* logged with repro+expected+actual. Read .ags/<slug>/goal.md first for non-negotiables and audit table; fill audit before declaring done. Or stop after 20 turns.

# Or run a metric loop directly
/ags:autoresearch reduce p95 latency of /api/search

Install for Claude Code

/plugin marketplace add DefaultPerson/agent-goal-stack
/plugin install ags@agent-goal-stack
/reload-plugins

/ags:goal-prep, /ags:autoresearch, and the ags:autoresearch-worker subagent become available. For development with live edits in the current session: git clone … && claude --plugin-dir ./agent-goal-stack.

Install for Codex CLI

Paste this entire block into a Codex agent session — it will execute each step in order:

Install agent-goal-stack into Codex CLI. Run these steps in order:

1. Enable Codex plugins (one-time): edit ~/.codex/config.toml and set
   `plugins = true` under the [features] table. Save.
2. Add the marketplace via Bash:
     codex plugin marketplace add DefaultPerson/agent-goal-stack
3. Enable the plugin (marketplace add does NOT auto-enable). Append:
     [plugins."ags@agent-goal-stack"]
     enabled = true
   to ~/.codex/config.toml — or type `/plugins` in a Codex session and
   toggle the `ags` entry on through the interactive browser.
4. Restart Codex session.
5. Verify: type /help and confirm /ags:goal-prep and /ags:autoresearch
   appear. If they don't, double-check step 3 and re-run
     codex plugin marketplace upgrade agent-goal-stack
6. (Optional) Install the Claude CLI for cross-LLM hooks:
     npm i -g @anthropic-ai/claude-code
   Without it the skills still work but skip the cross-LLM review step.
7. (Optional) Sync later via:
     codex plugin marketplace upgrade agent-goal-stack

How /ags:goal-prep works

Validates objective length, asks one opt-in question for cross-LLM adversarial review, runs a silent 11-field intake compiler, walks a 6-question diagnostic ladder (3 batches), classifies the goal kind, writes goal.md under <cwd>/.ags/<slug>/ (commit it to the repo if the goal is part of project history; otherwise add .ags/ to .gitignore), and prints a copy-clear-paste flow that hands you the /goal <condition> command. The condition tells the main model to Read .ags/<slug>/goal.md first on turn 1, so anti-patterns + audit table enter context via the Read tool. Strictly non-execution — the skill itself never reads implementation files or browses repos.

How /ags:autoresearch works

Setup once, then per iteration: ideate → modify + commit → verify → keep or revert. State on disk (autoresearch-scratchpad.md + autoresearch-history.tsv on branch autoresearch/<slug>); requires git.

Host differences:

• Claude Code: per-iteration MODIFY+COMMIT delegated to the ags:autoresearch-worker subagent (keeps parent context constant). Paces via ScheduleWakeup (sub-hour) or CronCreate (multi-hour, multi-session).
• Codex CLI: MODIFY+COMMIT inline (no subagent — Codex doesn't ship one). Loop runs in-session sequentially; multi-day runs need manual /ags:autoresearch --continue per fresh session.

Unattended by default (v0.3.1): no AskUserQuestion mid-loop. On 3 consecutive failures plus cross_llm_review_enabled=true, the cross-LLM rescue is auto-invoked (codex:codex-rescue subagent on Claude Code; claude -p via Bash on Codex) and its suggestion lands in scratchpad ## Next to try. Pre-merge review at Phase 8 EXIT is read-only — findings are surfaced, never auto-applied.

License

MIT. See LICENSE.