lidge-jun/codexclaw / plugins/codexclaw/skills/loop
cxc-loop
VerifiedUse for PABCD completion loops. Triggers: cxc-loop, continue until done, HOTL, repeated PABCD, 루프 돌려, 끝까지 해줘, docs-first.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| agents/openai.yaml | config | 127 B |
| references/divergence-tiers.md | markdown | 4.6 KB |
| references/durable-goalplan.md | markdown | 10.6 KB |
| references/lane-dispatch.md | markdown | 9.3 KB |
| references/runtime-lifecycle.md | markdown | 6.3 KB |
| references/waiting.md | markdown | 6.7 KB |
references/durable-goalplan.md
View on GitHub# Durable goalplan
Read when creating, registering, amending, or inspecting a goalplan.
Mode selection and external permission scope remain in ../SKILL.md.
## HOTL Goal-Setting Rule
When entering HOTL mode, the main agent MUST create a host goal with
`create_goal` before relying on Stop-continuation. The objective should be
detailed, concrete, and approach the host limit of 4000 characters.
The objective must include the [plan output](../../pabcd/references/plan-output.md)
fields, with:
- The concrete outcome to achieve.
- The file change scope and explicit out-of-scope boundaries.
- Acceptance criteria, including what counts as `DONE`, `NOOP`, `BLOCKED`,
`UNSAFE`, `NEEDS_HUMAN`, or `BUDGET_EXHAUSTED`.
- Verification commands or evidence artifacts expected before each completion claim.
- The expected terminal outcome and the first work-phase to run.
A vague or short objective under 500 characters is a discipline violation for
HOTL mode. After `create_goal`, run `cxc loop init --objective "<same text>"
--session <id>` to create the durable local plan bound to the session.
After `loop init`, REGISTER the plan: fill `workPhases[]` (with tasks) and
`criteria[]` in the goalplan file before the first work-phase. An init-only
empty plan now FAILS `cxc loop validate` (E8), and `update_goal
{status:"complete"}` follows the
[completion gate](runtime-lifecycle.md#completion-gate-goal-complete-gate-01-shipped)
(GOAL-COMPLETE-GATE-01); an unregistered plan cannot certify completion.
## Durable Goalplan
Use a durable goalplan when a Codexclaw loop needs more than a chat-local
checklist: goals, work phases, success criteria, checkpoints, evidence,
Interview OPEN ASSUMPTIONS, steering decisions, and quality gates.
### Contract
- Represent goals, work phases, success criteria, checkpoints, and evidence.
- Carry Interview OPEN ASSUMPTIONS (`proposed` and `open` entries, with source,
confidence, consequence if wrong and status) into Plan/Audit instead of dropping
them. Confirmed requirements and rejected assumptions travel in their own plan
sections with their answer reference (INTERVIEW-ASSUME-01 in cxc-interview).
- Record steering decisions with rationale and evidence.
- Reject steering that weakens completion criteria or verification.
- Require a quality gate before final completion.
### Shipped schema
This is the on-disk shape under `<durable root>/goalplans/<slug>/goalplan.json`
(+ `ledger.jsonl`; the durable root is `.codexclaw/` in repo mode, see `cxc state path`). Fill these fields; do not invent parallel ones:
- `objective`, `slug`, `createdAt`, `updatedAt`.
- `workPhases[]` — each `{ id, title, status: pending|in_progress|done, dependsOn?, tasks[], criteriaIds[] }`.
`workPhase.dependsOn` names prerequisite work phases. Optional `workPhase.awaitsDecision?: string[]` names decisions that must be answered before this phase can run. `activeWorkPhaseId` marks the current one.
`workPhases[]` is APPEND-friendly mid-loop: when a new independent unit is discovered
(LOOP-UNIT-CHAIN-01), add its work-phase (+ criteria) as a P-phase amendment instead of
treating the plan as frozen at init or ending the goal.
`tasks[]` are `{ id, title, status: pending|done, dependsOn?, outcome? }`.
Task ids and task dependency references are phase-local: `task.dependsOn` names existing task ids in
the same work phase, never a task in another phase. A done task carries a non-empty `outcome`; a pending
task has no outcome.
- Optional `decisions[]` — each `{ id, question, recommendation?, options?, status: open|decided, answer?, askedAt, decidedAt? }`. When `options` is present it is a non-empty list of distinct entries and `recommendation` must be one of them; the answer stays free text because the host always offers a free-form reply. Open decisions have no answer or decidedAt; decided decisions require both. Decision ids are short lowercase ids. Absent and empty arrays remain distinct on disk, as do absent and empty `awaitsDecision` arrays. Old plans acquire neither field on read/write. Only linked pending or in-progress phases wait; an unrelated open decision does not pause the goal.
- `criteria[]` — each `{ id, scenario, surface, presented?, expectedEvidence, capturedEvidence, status: open|met }`.
`scenario` is the `--criterion` text and `surface` is one of `logic` (default),
`web`, `tui` or `desktop`, set by `add-criterion --surface` on a session-bound plan
(`init` refuses `--surface`). `presented: "native"` is legal only with
`surface: "desktop"` and activates the soft native observation advisory.
`web`, `tui` and `desktop` make the QA receipt
mandatory through validation on schemaVersion 2+ plans with a final gate and through
the final-gate spawn guard on any plan with a recorded finalGate; otherwise the value
is a classification. See [compatibility](#compatibility) before opening these
fields with an old build. `id` is auto-assigned and `status` is derived. `expectedEvidence` has no
CLI flag on `add-criterion` — it stays `""` unless set via a steering batch op or a
hand edit — so do not plan on passing it. `capturedEvidence` is written by
`meet-criterion --evidence`. A criterion only reaches `met` when `capturedEvidence`
is non-empty (fresh proof, not memory).
- `host` — `GoalplanHostLink { armed, armedAt, source: freeze|none }`. `armed` is provenance,
intended to read true only after a freeze-boundary arm (the MAIN session created a host goal).
No shipped CLI flips it automatically and codexclaw never writes the goal DB itself; treat it
as the slot that records that boundary, not an auto-managed flag.
### CLI surface
- `cxc loop init --objective <text> [--session <id>] [--criterion <text>]... [--schema-version <n>] [--cwd <path>]` —
creates the local artifact and binds it to the session when a session id is
supplied; it never writes the host goal DB. Repeat `--criterion` once per
criterion to register them at init.
- `cxc loop show (--slug <slug> | --objective <text> | --session <id>) [--cwd <path>]` — renders the current plan summary.
- `cxc loop validate (--slug <slug> | --objective <text> | --session <id>) [--cwd <path>]` — runs the E8 quality gate; it FAILS
unless the plan is complete and every `met` criterion carries `capturedEvidence`.
- `cxc loop steer --session <id> --batch-json <path-or-json> [--cwd <path>]`
- `cxc loop add-criterion --session <id> --criterion <text> [--surface logic|web|tui|desktop] [--presented native] [--cwd <path>]` —
registers a criterion whose scenario is the `--criterion` text. There is no `--id`:
ids are assigned as `c-1`, `c-2`, ... (max existing `c-N` + 1, in registration
order). A duplicate scenario text is rejected. `--presented native` requires `--surface desktop`.
- `cxc loop add-work-phase --session <id> --id <id> --title <text> [--depends-on <id>]... [--criterion <criterion-id>]... [--cwd <path>]`
- `cxc loop ready (--slug <slug> | --objective <text> | --session <id>) [--json] [--cwd <path>]`
- `cxc loop add-task --session <id> --work-phase <id> --id <id> --title <text> [--depends-on <task-id>]... [--cwd <path>]`
- `cxc loop complete-task --session <id> --work-phase <id> --id <id> --outcome <text> [--cwd <path>]`
- `cxc loop ask --session <id> --id <id> --question <text> [--recommendation <text>] [--option <text>]... [--work-phase <id>]... [--criterion <criterion-id>]... [--cwd <path>]` — record a question after sending it through the host. It never sends a message. Name each dependent phase; `--criterion` (needs `--work-phase`) adds those criteria to each named phase's `criteriaIds`.
- `cxc loop link-criterion --session <id> --work-phase <id> --criterion <criterion-id>... [--cwd <path>]` — add existing criteria to a pending or in-progress phase's `criteriaIds`. `add-work-phase --criterion` and the steering `add-work-phase` op's `criteriaIds` do the same when the phase is created.
- `cxc loop decide --session <id> --id <id> --answer <text> [--cwd <path>]` — record the user reply. This changes only the decision record; phase status and blockedReason stay as they were.
- `cxc loop pr-record --session <id> --pr <url|number> [--cwd <path>]` — record a merged or green PR as this session's completion record ([runtime lifecycle](runtime-lifecycle.md#completion-gate-goal-complete-gate-01-shipped)).
- `cxc loop meet-criterion --session <id> --id <id> --evidence <text> [--cwd <path>]` — `--id` takes
a generated `c-N` id; read it from `cxc loop show` or the goalplan file.
- `cxc goalplan *` — deprecated alias for the same behavior during migration.
The parser rejects unknown flags, stray positionals, missing values, and flags belonging to another verb before dispatch. Every value flag also accepts `--flag=value`, which is the way to pass a value that starts with `--`.
`ready --json` includes `openDecisions` and `awaitingDecisions` when the plan has a decisions field; `show` displays each open question and its waiting phases. At IDLE, Stop releases when every remaining phase and unmet criterion waits on an open user decision; the goal remains active and completion is still gated. An unmet criterion waits only when a waiting phase lists it in `criteriaIds`. When every phase waits but a criterion is unlisted, the Stop block names it and prints the `link-criterion` command; link it only if the criterion truly waits on that answer.
Repeat `--depends-on` once per prerequisite; comma-separated values are one id. Existing dependencies are
not edited after creation. `complete-task` and `meet-criterion` require non-empty proof text.
Ledger events are `created`, `workphase_started`, `workphase_done`, `task_done`, `criterion_met`,
`dependency_registered`, and `host_armed`. `dependency_registered` records only accepted definitions.
### Goal state
The host owns goal state in `goals_1.sqlite`; codexclaw reads it read-only to decide
HITL vs HOTL. A goalplan records work phases, criteria, evidence, and assumptions; it
is not another goal database.
## Compatibility
Builds older than 0.2.37 drop `desktop` on read and erase it on their next write;
builds older than 0.2.38 do the same to `presented`. Do not let an incompatible
build rewrite a plan carrying these fields.
## HOTL resource bounds
Record tool/credential and write scope in each HOTL P-phase loop-spec. Record
only the user's stated token/cost and wall-clock bounds, or
`none stated; host limits apply`; never invent a budget. Follow
[plan output](../../pabcd/references/plan-output.md) and the live host goal-tool
contract. For C4 work, missing unattended tool/credential or write scope is an
ESCALATE-class omission: ask before starting or continuing that work. Hitting a
stated user or host resource bound is `BUDGET_EXHAUSTED`, not `DONE`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |