Writing Goals

Writing goals for Claude Code

Follow shared/method.md completely. It is the canonical method. Load its linked shared references as the task requires; this adapter adds only Claude-native integration instructions.

Invoke and trust

• Invoke as /writing-goals; use /goal <condition> for Claude's session-scoped goal.
• For non-interactive execution, invoke claude -p "/goal <condition>". The --dangerously-skip-permissions flag disables interactive approvals; use it only inside the sandbox required by shared/autonomy.md.
• /goal requires a trusted workspace and the hooks system. Managed disableAllHooks makes it unavailable.
• Project hooks live in .claude/settings.json. Review hook source before trusting it; unattended permission modes do not turn a hook into containment. Stop and PreToolUse hooks are cooperative backstops, not a security boundary. Run unattended work in an OS-level sandbox (for example, a sandbox-exec profile where available) with only the intended writable source paths.
• Before presenting a non-trivial plan, invoke the separate read-only challenger and validate its exact-plan receipt with assets/validate-review-packet.sh; do not present a review packet while the challenge is missing, stale, non-independent, or red.

Current Claude platform facts

• A /goal condition is limited to 4,000 characters. Its evaluator reads the conversation rather than running tools, so require surfaced evidence or use a deterministic command Stop hook.
• Stop-hook input includes stop_hook_active, which is true when Claude is already continuing because a Stop hook blocked. By default, Claude overrides the hook after eight consecutive blocks without progress. Keep GOAL_GATE_CAP <= 8, unless CLAUDE_CODE_STOP_HOOK_BLOCK_CAP is deliberately raised to at least the chosen repository cap.
• A command Stop hook blocks with exit 0 and {"decision":"block","reason":"..."} on stdout (or exit 2 plus stderr); clean exit 0 with no block allows stopping. Use assets/gate.claude.sh.
• A reported Claude Code bug can bypass pre-use policies after some background-task completions; this is another reason the sandbox, not the hook, is the boundary.

Native Claude goal

For a run that warrants a native Claude goal, set one /goal condition for the complete objective/run. Keep it below the platform's 4,000-character limit and make it a concise, user-legible completion contract:

If asked to set the goal yourself, inspect the current session, repository guidance, working tree, tests, and exact verification surface first. If a material outcome, proof, preservation constraint, boundary, iteration rule, or blocked stop remains ambiguous, state the proposed understanding in plain English and obtain approval before setting the goal. Ask only for the unresolved decision. When those facts are clear from the request and investigation, do not ask again: write the contract directly.

When monitoring a running goal, make each status check one concise sentence stating the current activity, whether the run remains on track, and the next gate.

Use this shorthand only to compose the contract; retain every section below rather than merging them into one sentence:

/goal <desired end state> verified by <specific evidence> while preserving <constraints>. Use <allowed boundaries>. Between iterations, <evidence-led next action>. If blocked, <blocked report and unlock>.

Objective: <one complete parent outcome>
Read first: <exact repository files, issue, specification, or decision record>

## Outcome
Given: <baseline>
When: <completed transition>
Then: <measurable end state>
Positive scenario: <normal success>
Negative scenario: <rejected/failure result>
Edge case: <boundary result or evidence-based not applicable>

## Verification surface
Evidence: <exact test, benchmark, report, artifact, command output, or source>
Given: <evidence proves outcome>
When: <fresh check>
Then: Automated proof: `<command>` exits 0 with <signal>; Manual proof: <specific observation when needed>
Positive scenario: <passing signal>
Negative scenario: <false-pass-preventing failure signal>
Edge case: <threshold/partial/noisy-evidence handling>

## Constraints
Given: <protected baseline>
When: <authorized work>
Then: <each named preservation requirement remains true with evidence>
Positive scenario: <preserved behavior>
Negative scenario: <detected regression>
Edge case: <version/migration/compatibility boundary>

## Boundaries
Allowed: <paths, tools, data, repositories, external resources; repository-local default>; Forbidden: <excluded resources/actions>
Given: <Allowed is sufficient>
When: <investigate/change/verify>
Then: <use only Allowed; request approval to widen>
Positive scenario: <in-bound operation>
Negative scenario: <refusal/escalation>
Edge case: <generated/transitive/credential-adjacent handling>

## Iteration policy
Given: <attempt evidence>
When: <select next action>
Then: <record hypothesis/action/change/result; choose next lowest-risk, highest-evidence action; never retry blindly>
Positive scenario: <safe next experiment>
Negative scenario: <same failure stops/reassesses>
Edge case: <conflicting/noisy evidence disambiguation>

## Blocked stop condition
Given: <no defensible path, unavailable proof, or enforced limit>
When: <evidenced>
Then: <do not claim success; report attempted paths, evidence, blocker, and unlock>
Positive scenario: <exhausted in-bound path produces complete handoff>
Negative scenario: <defensible next step means continue>
Edge case: <budget/partial-proof/unavailable-verifier incomplete result>

Document: <focused documentation or not applicable with reason>
Details (optional): `<stable workspace-relative contract or plan path>`
Checkpoint: <current phase; exact evidence observed; next gate; blocker/decision>
Stop when: <Outcome, Verification surface, Constraints, Boundaries, and Iteration policy proof pass>, OR <Blocked stop is evidenced and its non-success handoff is reported>

Keep the instantiated condition at or below 4,000 characters: before setting /goal, measure it with wc -m. If the six sections cannot fit without merging, omitting, or weakening criteria, use the persisted lightweight/protected workflow instead; Details cannot replace a criterion. Outcome, Verification surface, Constraints, Boundaries, and Iteration policy Then criteria are cumulative and parent-level; the Blocked stop condition is mutually exclusive and never contributes to completion. Do not treat the goal as complete because implementation began, a subset passes, or child slices are complete. For a full plan, derive the success criteria from the frozen objective_acceptance. State concrete outputs, access decisions, files, responses, or other observable signals; never use vague criteria such as “works correctly.” Claude evaluates the conversation rather than rerunning tools, so surface the exact command, exit status, and relevant output in the conversation. For unattended or full-tier work, use assets/gate.claude.sh as the deterministic verification gate; the /goal condition is not independent execution evidence. Keep implementation steps, alternatives, per-slice checks, and lifecycle receipts in the contract or protected plan rather than the native goal. Do not use /goal for a direct one-shot edit with no useful verification boundary.

For coordinated or multi-turn work, the native Checkpoint sentence is only a summary. Persist the checkpoint's current phase, exact evidence observed, next gate, and blocker in the Details target or frozen contract before reporting it; the native goal remains navigation and completion evidence, not the durable lifecycle authority.

Use literal paths and commands. Do not delete, skip, weaken, narrow, or rewrite tests or other verification surfaces to make the goal pass; do not refactor unrelated code or add dependencies. Do not create a new ADR or decision record without human approval. If a product decision, absolute target, irreversible/external action, new dependency/ADR, or objective change is required, pause and ask before proceeding.

If the host exposes an enforceable budget and it is reached, the goal is incomplete—not success and not a resolved blocker. Stop substantive work and report progress, evidence, blocker, and the next useful step. For research_design, keep the persisted contract's claim-evidence ledger: one claim per row with exact source/evidence, support status (confirmed, approximate, support-only, or blocked), and remaining uncertainty.

Sources: Claude goal documentation and Claude hooks reference, Claude hooks guide, and Claude Code issue #47810.