SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgoal-loop

goal-loop

General & other

View repository

Updated 10-15 20:13

About this skill

goal-loop Goal-driven loop

Overview

A self-healing closed-loop state machine for long-horizon, cross-module R&D tasks: with theplan file as the sole readable source of truth, it links brainstorming、grilling、research、writing-plans and dual-round-reviewon demand, using tiered testing (L0–L3) and adversarial final review to safeguard delivery quality.

This file is therouting layer: it only declares trigger conditions, invariants, and phase pointers. For phase details, see stage-progression-protocol.md。

When to use / When not to use

Use(if any is met):

  • Involves more than 2 files or modules, or changes a public contract/data model;
  • Expected to take more than about 10 minutes;
  • Requires cross-session/interruption recovery, or has many steps prone to context rot;
  • Requires high-fidelity delivery and tiered testing protection.

Do not use: pure copy tweaks, single-line constant changes, direct read-only Q&A retrieval.

Iron Rules (Invariants)

  1. The plan file is the sole human-readable source of truth. Progress, checkboxes, and checkpoints are written to the plan header; machine state is written to the host's native goal primitive,do not create parallel state files（scripts/goal-state-tracker.sh only does derived read/write).
  2. Read the checkpoint before acting. When entering a new phase or resuming a session, the first action is to read the Active Checkpoint anchor in the plan header.
  3. Without explicit user approval (User Nod), do not write code or write an implementation plan(P-1 gate).
  4. If the selection decision is not complete, do not enter the P1 plan(P0.5 gate); prefer reusing mature solutions, and any in-house development must be defended in writing.
  5. Before P3 starts, confirm the execution backend with the user: host-native subagent / agy headless process / inline in the current session.
  6. Test at the adjudicated level, red first then green: the level is governed by the Test Strategy Adjudication in the plan, and an Exit Code of 0 is required before an atomic commit is allowed.
  7. Branch isolation: work on a feature branch, do not write code directly on main/master .
  8. Before delivery, there must be a Zero Blockers adjudication by an independent subagent: the Heavy Track goes through full two-round adversarial review; the Fast-Track goes through targeted single-round red-team review, and is escalated to full two-round review when it touches a public contract or core path.
  9. Retries are capped: a single error fix is capped at 3 attempts (the 2nd triggers micro-investigation, the 3rd triggers circuit-breaker escalation); smaller scene-level caps (such as 2 compile failures, 2 refactor-induced test breakages) take priority and trigger their corresponding actions; Delta Re-Loop iterations are capped at 5.
  10. Facts are persisted immediately: after every 2 read-only investigations, write the conclusion into .goal-loop/scratchpad.md or a checkpoint anchor.
  11. After writing, Read-Modify-Verify: use git diff, read back key lines, or use test/compile exit codes to confirm the change took effect.
  12. Do not execute destructive Git commands（reset/rebase/revert/restore/clean -fd/force push).

When higher-confidence details are needed, read the corresponding file under references/ ; do not copy the detailed rules back into this file.

Phase Routing

Phase Goal External Skill Artifact / Pointer
P-1 Intent Alignment brainstorming 2–3 alternatives; gate see stage-progression-protocol.md
P0 Solution Stress Testing grilling Requirements Confirmation Document = docs/proposals/RFC-{NNNN}-{slug}.md(convergence exit, In Review); for ledger paragraphs see RFC Standard Template §6; legacy engineering assessment optional evaluation-report-template.md
P0.5 Research and Open-Source Selection research / find-docs research-spike-template.md
P1 Planning and Test Tiering writing-plans goal-plan-template.md + testing-decision-matrix.md
P2 Atomic Task Breakdown — atomic-task-template.md
P3 TDD Loop Implementation Host Execution Backend (ask the user before starting) host-adapters.md
P3.5 Integration Verification Frontend Deliverable Acceptance:frontend-qa-gate(design tasks additionally attach taste-driven-designer） stage-progression-protocol.md
P4 Adversarial Final Review dual-round-review stage-progression-protocol.md
P5 Document Archiving doc-governance(optional) documentation-sync-matrix.md

Track Tailoring：

  • Fast-Track (Agile Lightweight): exempt P-1 / P0 / P0.5 and go directly to the P1 lightweight plan and P3;
  • Maintenance-Patch (Legacy Maintenance): exempt P-1 / P0 / P0.5 / P2; retain the P1 minimal plan (symptoms/reproduction/root cause hypothesis/fix scope/regression tests), P3 localization and regression tests, P3.5 L2 localized regression, and P4 targeted single-round red team review.Mandatorily retain the 3-Tries circuit breaker, reproduce before fixing, fixes must include regression tests, and Diff scope locking; once a public contract must be changed, escalate to Heavy Track.

For decision thresholds, the full Track C procedure, and misclassification downgrade rules see stage-progression-protocol.md the execution track tiering decision matrix.

Exception Recovery

If the same error remains unresolved for 3 consecutive times, trigger the circuit breaker (STOP → RECORD → RESEARCH → ESCALATE), generate a structured arbitration report, and pause pending human adjudication. For the full failure matrix and report template see failure-recovery-protocol.md。

Auxiliary State Script (optional)

scripts/goal-state-tracker.sh provides a breakpoint dashboard and phase switching. The skill directory depends on the installation method (source repository is usually skills/goal-loop, after installation usually .agents/skills/goal-loop）：

SKILL_DIR="<goal-loop 技能实际所在目录>"
bash "$SKILL_DIR/scripts/goal-state-tracker.sh" init "目标名称" "计划文件路径"
bash "$SKILL_DIR/scripts/goal-state-tracker.sh" status
bash "$SKILL_DIR/scripts/goal-state-tracker.sh" set-phase P3
bash "$SKILL_DIR/scripts/goal-state-tracker.sh" complete-task "p3-1"

The plan file is always the single readable source of truth; this script serves only as a derived view.

Reference Navigation