clawplays/ospec/ospec-goal

OSpec Goal

Use this skill for complex work that needs the full OSpec workflow. A goal is intentionally heavier than a change and is the place to use design docs, implementation planning, task graph dispatch, worker/reviewer handoffs, and durable evidence.

Every rule you need in order to act is in this file. for-ai/execution-protocol.md is the authoritative detail behind those rules — open it only when a named situation actually comes up (per-harness wait primitives, lease expiry, repair convergence, cross-task finding scope, worker-report repair binding, allowlist CAS semantics, deferred external acceptance, force-archive detail), never on goal entry and never on every turn. That file is the goal profile's reference; a classic change reads for-ai/change-protocol.md instead and must never be sent here.

Loop Model

ospec goal creates a session-bound Loop automatically (artifacts/loop/loop.json + state.json + run-log.jsonl). There is no separate init step.

• OSpec is the durable state-machine brain. ospec loop run --once first observes the previous task, review, or verification evidence, then emits a bounded batch of action items from task-graph.json. Execute each one only through the model-native subagent primitive named by its target-bound runtimeAdapter, then record durable evidence.
• IDE controller auto-dispatch is mandatory. Never stop at "Loop initialized" or ask the user to run Loop commands. Run ospec loop run <goal-path> --once --compact-json, consume every returned action, record evidence as each executor finishes, and tick again without another user prompt. Stop only for a required user decision, an unavailable independent/isolated executor, a blocking safety gate, a configured guard/STOP, a terminal failure that needs user authority, an explicit user pause, or done.
• One batched call per controller round. ospec loop step <goal> --batch-file <path|-> applies every claim and every result and ticks in ONE process, then emits the next action batch as compact JSON. It replaces loop heartbeat x N + loop finalize x N + loop run --once; at the default concurrency of 3 that is a measured 7 controller calls down to 2. The ceiling is 2C+1 in the DECLARED capacity C (C=5 measures 11), not in the task count, so the win does not grow as the goal gets more tasks. Send {"claims":[...]} with --no-tick right after dispatching, then {"results":[...]} when the children finish. A missing or mis-keyed envelope key is a hard error, never an empty batch; a partial failure stops, does not tick, and prints exactly which items are already durable.
• Executor lifecycle is durable and bounded. Claim each dispatched child once (the claims array of ospec loop step, or ospec loop heartbeat per item), run ospec loop poll <goal> --json between native waits (it refreshes every lease and reports tickNow), and full-tick only on tickNow=true or right after dispatching. Never make one indefinite wait: stay inside maxWaitMs (60s) while other work is dispatchable; the single idleMaxWaitMs (10min) wait is only for the last outstanding batch. Commit each finished child with its emitted ospec loop finalize ... command, and use ospec loop recover --force only when the prior session or child is known to be gone.
• Match execution shape to graph shape. Maximize task-graph width: every depends_on must be semantically necessary, and the planning review treats an unjustified fully serial chain as a finding. On a reported serialBottleneck the controller may implement that one task inline (executor id controller-inline); reviews stay independent subagents. --review-gating optimistic fits low-risk goals; keep the strict default for high_risk/security_related work.
• Planning quality is fast and bounded. Design preflight, then plan preflight — never launch a reviewer child for either — then the derived task graph, then one independent combined planning review. NEEDS_CHANGES permits one grouped repair and at most one delta-scoped re-review; a repeated semantic failure is a stable blocker, never an open-ended loop.
• Progress documents track reality. Tick each proposal.md acceptance criterion as its evidence passes; tag acceptance lines [verify:<id>] and record ospec execute verify ... --satisfies <id> so ospec execute sync auto-ticks them. Archiving blocks on unchecked items. review.md is derived by sync from the final review — never edit it by hand.
• Required decisions always block. Present every required decision to the user, never auto-select the recommendation, and record it with --answered-by user before the loop proceeds. Brainstorm resolutions need the same provenance.
• `/goal` is capability-probed, not inferred from a target name. ospec execute launch --primitive goal emits a native-/goal instruction only when the harness explicitly reports support; otherwise the same controller runs the verify-driven loop through native subagents.
• Scheduling is session-bound. Unknown native capacity uses the default implementation concurrency of three while keeping conflict-safe review batches under the configured limit. Raise maxParallel only from an authoritative current-session capacity report — never from a provider name or a stale session — and never over dependencies, file conflicts, token funding, or the configured maximum.
• Progress is artifact-backed, and `state.json` is the status source of truth. Task status, review decisions, repair waves, evidence, state.json, and run-log.jsonl carry progress between fresh contexts, and process exit alone does not complete an action. When a document and state.json disagree, reconcile toward state.json instead of reporting the document's value. Dispatch only items returned in actions; a durable pending record with an empty action list is observation state, not work.
• Manual artifact edits need a sync. After hand-editing the task graph, execution session, a review artifact, debug evidence, or the verification checklist, run ospec execute sync [changes/active/<goal>] so artifacts/agents/worker-status.md and the derived checklists rebuild from authoritative state — never only at closeout.
• Guards are enforced before new work. Pause/STOP, iteration/deadline/token/time budgets, no-progress limits, comprehension checkpoints, required decisions, passed preflights and planning review, ready workspace evidence, and optional allowlists can stop or pause the loop.
• Review repair is convergent and regression-aware. A downstream task sharing target files inherits transitive upstream regression obligations. The two-round defaults are convergence thresholds, a blocked final review needs blocker resolution instead of grouped repair, and no limit is ever raised to repeat unchanged work. Cross-task finding scope and worker-report repair binding are specified in for-ai/execution-protocol.md; read it when a finding actually reaches past its own task.
• Verification scope must be proportional. Treat an unscoped docker compose up --build as a required preflight: check repository release guidance and prefer explicit service names. Never rebuild or download unrelated runtimes to verify a scoped change.
• External acceptance may be deferred, never waived, and allowlists never widen silently. Keep device, credential, manual, and third-party acceptance off unrelated critical paths, and treat a configured allowlist as a fail-closed boundary rather than a workflow level. The exact ospec execute defer-blocker and loop allowlist semantics are in for-ai/execution-protocol.md — open it when either situation actually arises.
• Stop condition is three-stage: run the project's real tests separately, record their evidence with ospec execute verify --status, then confirm with ospec verify.

Scope

This skill covers the full lifecycle inside an initialized OSpec project: requirement intake; goal naming or matching; proposal, design, implementation-plan, task graph, and task refinement; deterministic design/plan preflight with inline approval artifacts at artifacts/reviews/design-review.md and artifacts/reviews/implementation-plan-review.md; worker dispatch, launch, collection, retry, and review packets; user decision gates; workspace and worktree planning; TDD, debug, and verification evidence; a single combined final code review; and finish planning, verification, archive readiness, and finalize closeout.

Use ospec-change for small routine changes that only need the classic fast flow.

Read Order

1. .skillrc
2. ospec index query <keyword...> for the relevant .ospec/SKILL.index.json entries — never read the whole index file, which grows without bound as changes archive
3. .ospec/session-brief.md and ospec execute status [goal] --brief. When the brief is missing, run ospec session [path] first: it writes .ospec/session-brief.json and .ospec/session-brief.md with the active profile, queue state, and profile-aware next commands, and it launches no workers and edits no source files
4. the current dispatch, review, decision, or verification packet for the next action
5. target files and only the project or archived-feature docs routed by SKILL.index.json and docs/project/feature-catalog.md; use ospec docs locate --feature <slug> to read one section rather than a whole document

On-demand only, never at entry: the project conventions under for-ai/ (naming-conventions.md, skill-conventions.md, workflow-conventions.md, development-guide.md), and for-ai/execution-protocol.md for the situations named above.

Read proposal.md, design.md, implementation-plan.md, task graph, worker status, evidence, and review artifacts only when the current stage or packet needs their detail. The packet is the default worker context; do not reload every goal artifact on every turn.

For legacy root-layout projects, use the same paths without the .ospec/ prefix.

Language

Write every goal document, artifact, and brainstorm you author in the project document language (.skillrc documentLanguage / managed for-ai/ guidance / existing change docs). Never infer that language from product copy, site locale, or an "English-first" requirement, never switch an already-started goal unless the project rules explicitly say so, and never mix languages within one goal.

Visibility & Decisions