goal
Autonomous goal-directed execution loop. Establishes an immutable objective pin, durable scratch state (_scratch/goals/GOAL-<slug>.md, whose markdown checklist is the step tracker on pi), a deterministic witness exit-gate, and executes atomic steps until verified.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 48
- Forks
- 16
01 前言 Front Matter
- name
- goal
- metadata
- { "canonical": "../../../.claude/skills/goal/SKILL.md", "generated-by": "fak project-assets sync" }
- description
- Autonomous goal-directed execution loop. Establishes an immutable objective pin, durable scratch state (_scratch/goals/GOAL-<slug>.md, whose markdown checklist is the step tracker on pi), a deterministic witness exit-gate, and executes atomic steps until verified.
- allowed-tools
- Read, Edit, Write, Grep, Glob, Bash
- argument-hint
- [objective] [--witness <command>] [--budget <iters>] [--dry-run]
- user-invocable
- true
- disable-model-invocation
- false
03 SKILL.md 正文
/goal — Autonomous Goal-Directed Execution Loop
An autonomous execution skill that drives a high-level objective to verified completion. While awaiting native OpenCode /goal runtime primitives, this skill provides a battle-tested goal loop immediately across OpenCode, Claude Code, and Codex.
It unifies the best patterns from existing open-source agent systems:
- Ralph Loop (Geoffrey Huntley, Vercel
ralph-loop-agent): Durable state on disk (GOAL.md), surviving context compaction and session restarts. - OpenAI Codex
/goal& Aider/architect: Two-phase structured planning, maintaining the objective anchor, and active checklist management. - All-Hands OpenHands (OpenDevin) & SWE-agent: Reproduction-first discipline, minimal surgical edits, and external exit-gates (rejecting the self-assessment trap).
- Fak Goal Specs & Registry: Native compatibility with
docs/goal-spec.md,docs/templates/GOAL.md, and thefak goalregistry (internal/goalregistry).
The Five Invariants of Goal Execution
- The Objective Pin: The objective statement is pinned verbatim and never mutates during the run. Pinning prevents goal drift (Arike et al., 2025).
- State on Disk, Not Ephemeral Memory: Progress, plans, and scratchpad live in
_scratch/goals/GOAL.md(or_scratch/goals/GOAL-<slug>.md) on disk. Goal specs are noisy, disposable scratchpad memory for surviving context compaction; they are not coordination artifacts. First-class coordination occurs via lane leases (dos arbitrate/internal/leaseref), claims (CLAIMS.md), issue comments, and commit trailers. - External Witness Exit-Gate (and Live Hardware Shift-Left): Model proposes, test disposes. The agent never grades its own work. A goal is satisfied only when a deterministic external command (test suite, buildcheck, validator) exits 0. For tasks touching hardware, compute kernels, or accelerator paths (CUDA, Vulkan, Metal, APU/UMA), bias heavily toward testing sub-components on live physical hardware (divide and conquer) with high volume and frequency (e.g.
fak validate --strix --subkernels=...,make mac-perf,make cuda-test) rather than relying on synthetic host mocks or deferring verification to monolithic post-merge runs. - Atomic S0/S1 Steps (Divide & Conquer, Subdivide, and Scope Abstention): Divide and conquer substantive or multi-concern objectives into atomic leaves (1–3 files touched per step). When tasks have independent components, delegate to isolated subagents or workers (
task: worker, researcher, explore, cross-validator) to prevent coordinator context pollution. Divide and conquer applies to compute pipelines as well: decompose hardware verification into isolated sub-components (sub-kernels, GEMV/GEMM microbenchmarks, Vulkan primitives) to execute on live hardware frequently and in high volume. Parallel subagent cohorts (4–8 parallel subagents across independent packages, tests, or diagnostic probes) are authorized while maintaining the single active goal milestone in the goal checklist. Top-level coordinators fan out subagents, while leaf workers execute directly without nested recursion (#12028). Keep exactly one stepin_progressin the goal checklist. When encountering high-difficulty boundaries (e.g. frozen ABI, kernel SIMD), scope abstention strictly to the bounded aspect: emit a structuredABSTAINrecord for that boundary while advancing all independent, safe, solvable sub-components (reproduction tests, diagnostics, disjoint packages). - Failure Memory Scratchpad & Persistence (Move Forward Over Conclusions): Genuine guard refusals carrying a closed reason token or unexpected process crashes are recorded in
# Scratch / last-refusalin_scratch/goals/GOAL.md(or_scratch/goals/GOAL-<slug>.md). Routine CLI return codes from read-only commands (such asgrepreturning 1 on no match, orgit diff --quietdetecting changes) are normal tool execution results and must not be logged as failures in# Scratch / last-refusal. A refusal or tool crash is diagnostic feedback, not a session abort. Queryfak recover <TOKEN>for structured recovery, adapt the execution path or decompose the step, and maintain momentum on the pinned objective without repeating identical failing calls. Focus on forward momentum over terminal conclusions: rather than defeatist conclusions when a step underperforms (e.g. rather "the next step to get better performance is X" than "X didn't work ... therefore we suck..."), treat unmet targets as empirical data that eliminates a variable, and formulate the concrete next checkable step.
Execution Protocol
Step 1: Intake and Objective Pinning
Parse $ARGUMENTS (e.g. /goal Fix memory leak in auth service --witness "go test ./internal/auth/..."). If no argument was provided, do not prompt the operator - default to acting: derive the best-supported objective from evidence (the active goal, open WIP, tickets, or the repo's default work object) and proceed. Resolve a surfaced choice through the internal/choicetriage fold: take the obvious move (TAKE_OBVIOUS); hand a knowable-but-unobvious question to a fresh context window at the top tier (FRESH_CONTEXT, the default); or decompose scope too large for this context into a ticket (FILE_TICKET). Only an irreducible policy/auth/release/priority/trust decision (HUMAN_RESIDUAL) legitimately returns to a person - and it must be earned by a real authority signal, never manufactured by phrasing status as a question. An unattended goal run that opens by asking a person has silently stalled.
Formulate three fields:
- Objective Pin: Exactly one clear, measurable end-state.
- Non-Goals / Scope Fences: Explicitly state what is NOT part of this run to prevent over-scaffolding and companion abstraction sprawl.
- Witness Criterion: The exact deterministic command that proves success (e.g.
go test -v ./internal/gateway/... -run TestGatewayReadyorfak validate --mine <paths>).
Step 2: Initialize Durable Scratch State (_scratch/goals/GOAL-<slug>.md; its checklist is the step tracker)
Ensure directory exists (mkdir -p _scratch/goals) and create or update _scratch/goals/GOAL.md (or _scratch/goals/GOAL-<slug>.md). Never create or commit a tracked GOAL.md at the workspace root. Goal specs are local, disposable execution scratchpad memory. First-class coordination occurs via lane leases (dos arbitrate), claims (CLAIMS.md), issue comments, and commit trailers ((fak <leaf>)).
<!-- Active goal spec saved under _scratch/goals/GOAL.md or _scratch/goals/GOAL-<slug>.md (never committed) -->
---
loop: goal
witness: <witness command or criterion>
budget: { max_iters: 20 }
---
# Objective
<Pinned objective statement>
# Non-Goals
- <Explicit exclusion 1>
- <Explicit exclusion 2>
# Plan
- [ ] 1. Reproduce baseline behavior or establish failing test
- [ ] 2. Implement minimal surgical fix or feature
- [ ] 3. Run package-level verification and regression checks
- [ ] 4. Execute final witness command
# Scratch / last-refusal
If the fak binary is available, optionally register the goal in the canonical registry:
fak goal create --title "<title>" --summary "<summary>"
If running on pi (or any harness with no todo tool), the plan items ARE the tracker: keep
- [ ] / - [x] state in the goal scratch file and mirror it in the plan block. In
OpenCode, additionally populate todowrite with the plan items, marking the first item
in_progress.
Step 3: Baseline Reproduction First (SWE-agent Invariant)
Before editing code:
- Locate relevant files using
Glob,Grep, andRead. - Execute the existing tests or create a reproduction test case.
- Capture the baseline failure or diagnostic. A defect is only proven fixed when the test failed before and passes after.
Step 4: Atomic Sequential Execution
Iterate through plan items sequentially:
- Divide and conquer by delegation: For substantive, complex, or multi-component goals, launch specialized subagents concurrently for independent parts (e.g.
taskwithworkerfor implementation,researcherfor prior art,cross-validatorfor verification). Pull only compact receipts and decisions into the coordinator. - Keep only one step marked in-progress in the goal checklist.
- Confine edits to 1–3 closely related files using
EditorWrite. - If a command or tool fails:
- Routine CLI return codes from read-only commands (such as
grepreturning 1 on no match, orgit diff --quietdetecting changes) are normal tool execution results and must not be logged as failures in# Scratch / last-refusal. - Log only genuine guard refusals carrying a closed reason token or unexpected process crashes to
# Scratch / last-refusalin_scratch/goals/GOAL.md. - Query structured recovery: if a guard refused the call, run
fak recover <TOKEN>ordos man wedge <TOKEN> --explainto obtain the sanctioned remedy. - For
MERGE_IN_PROGRESS,COLLISION_RISK, orLOCK_BUSY, inspect the typed recovery, wait for quiescence, or continue an independent disjoint subtask. These tokens grant no authority to change the index. - For an actual owned
PRESTAGED_PATH_OVERLAP, the native recovery accepts one existing regular tracked stage-0 modification in its managed ticket checkout. Retain the originalEXECUTINGclaim's worker and explicit epoch, confirm the path is in scope, and preview with full content pins:
Review the preview before applying with its exact generation token and unchanged pins. The owner attestation supplements live SDK/scope checks. A refusal preserves source and index; keep other work and peers untouched.fak-run fak-flow index unstage --repo-root <managed-checkout> --path <owned-path> --expected-head <full-head> --expected-index-blob <stage-0-blob> --expected-worktree-sha256 <sha256> --ticket <ticket> --worker <original-worker> --epoch <original-epoch> --json fak-run fak-flow index unstage --repo-root <managed-checkout> --path <owned-path> --expected-head <full-head> --expected-index-blob <stage-0-blob> --expected-worktree-sha256 <sha256> --ticket <ticket> --worker <original-worker> --epoch <original-epoch> --json --expected-index-generation <preview-token> --owner-authorized --apply - Decompose rather than abandon: if a subtask is blocked or too complex, divide it into smaller verifiable leaves (e.g. capture baseline reproduction tests first) while keeping the pinned objective intact.
- Adapt the approach: halt repetition of the identical failing call; select a sanctioned alternative tool or modified arguments.
- Routine CLI return codes from read-only commands (such as
- Verify the step using package tests (
go test ./internal/<pkg>/...or platform test script). - Mark the task
- [x]in the session's_scratch/goals/GOAL-<slug>.md— on pi that file is the sole step tracker; on OpenCode mirror the same transition into that harness's todo list.
Step 5: Witness Gate Evaluation
Run the declared witness command:
# Example witness commands:
go test -v ./internal/<pkg>/...
fak validate --mine <path1> <path2>
python tools/<validator>.py --check
# Live hardware sub-component witnesses:
fak validate --strix --subkernels=all --ablate=all
make mac-perf
make cuda-accept
- Exit code != 0: Append the failure to
# Scratch / last-refusalin_scratch/goals/GOAL.md, formulate a targeted fix, and re-run. If the failure exposes an insurmountable high-difficulty boundary, land the verified partial deliverables (e.g. reproduction witness), record a scopedABSTAINfor the specific boundary, and state the exact checkable next step rather than dropping the run. - Exit code == 0: Witness criterion is satisfied. Proceed to completion.
Step 6: Completion and Evidence Sealing
- Record final witness evidence and timestamp in
_scratch/goals/GOAL.md. Files under_scratch/are ignored by git (/_*) and must never be staged or committed. - If registered in
fak goal:fak goal transition --id <goal_id> --lifecycle achieved --evidence-class independent_witness --evidence-ref "<witness-command>" - Safe Git Sync, Commit, and Push by Default:
Do more work by default. When the change is verified green, complete the full delivery lifecycle without waiting for an operator prompt:
# 1. Pre-flight safe sync with origin/main: fak sync reconcile --apply # 2. Preview commit subject and lane: fak commit --preview -m "<subject> (fak <leaf>)" --path <p1> --path <p2> # 3. Stage-and-commit by explicit path (never stage _scratch/): fak commit --path <p1> --path <p2> -m "<subject> (fak <leaf>)" # 4. Safe push unprompted: fak sync push # (or combine commit and push: `fak commit --path <p1> ... -m "..." --push`) - Emit a concise, verdict-first completion report (<3 lines), oriented toward forward movement:
- Line 1: Goal status and witness confirmation.
- Line 2: Deliverables and touched paths.
- Line 3: Checkable verification command or next forward step.
Tool Mapping Across Agent Harnesses
| Operation | pi (primary) | OpenCode | Claude Code | Codex / fakc |
|---|---|---|---|---|
| Step tracking | markdown checklist in the goal scratch file (- [ ] / - [x]); pi has no todowrite tool |
todowrite |
TodoWrite / markdown |
update_plan |
| File inspection | read, grep, find, ls |
read, glob, grep |
Read, Glob, Grep |
read_file, glob |
| Code editing | edit, write |
edit, write |
Edit, Write |
edit_file |
| Execution | bash, powershell |
bash |
Bash |
shell_command |
| Subagents | subagent (agent scope user, project, or both) |
task |
Task |
detached worker |
On pi the goal checklist is a plain markdown file, not a tool call. Render the plan
items as - [ ] lines in _scratch/goals/GOAL-<slug>.md, flip the active one to
- [ ]-with-an-in-progress note, and mark finished items - [x]. Editing that file is
the step-tracking operation; there is no separate todo tool to call.
Verification and Witness
Verify this skill definition using the project gates:
# 1. Structural admission and anti-slop verification:
python tools/skill_slop_scorecard.py .claude/skills/goal/SKILL.md --corpus .claude/skills
# 2. Frontmatter portability check:
python tools/skill_frontmatter_lint.py --check
# 3. Synchronize cross-harness adapter for OpenCode (.agents/skills/goal/SKILL.md):
go run ./cmd/fak-project-assets sync --json
# 4. Verify zero unexplained parity gaps across harnesses:
go run ./cmd/fak-project-assets parity --json
Exit code 0 across all checks verifies full portability, compliance with the Agent Skills standard, and zero-gap availability in OpenCode.
04 同仓库更多 Skills
serve-receipt
On-demand research protocol + deterministic receipt for serving a Hugging Face model on a concrete GPU target — fan out research lanes (model facts/files, engine support matrix, serving recipes, KV/state memory math), compute the tiered feasibility verdict with `fak serve-receipt` (never narrated math), and emit a witnessed launch receipt. Use when asked for an "initial config", "serving receipt", or "how do I serve <model> on <GPUs>".
caveman
Ultra-compressed communication mode. Cuts output tokens 65% (measured) by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
quality-report
Score the repo quality and emit a report card.
ctx-overlay
Compact the context window and prune the memory store when a session grows too long.
quality-report
Score the repo quality and emit a report card.
ctx-overlay
Compact the context window and prune the memory store when a session grows too long.