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