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.

## Loop Model

`ospec goal` creates a **session-bound Loop** automatically (`artifacts/loop/loop.json` + `state.json` + `run-log.jsonl`). You do not run a separate init step. Key contracts:

- **ospec is a state-machine brain; it does not execute agents.** `ospec loop run --once` performs a two-phase tick — it first observes the previous pending action's verification evidence, then plans/produces the next controller instruction. The controller (you) executes the instruction and records completion + verification.
- **Safety level chosen at creation via a decision gate.** Prefer presenting an `AskUserQuestion` for L1/L2/L3 as the first decision; otherwise pass `ospec goal <name> --level L1|L2|L3` (default L1). L1 = report-only (findings go to triage, no code changes); L2 = assisted (real changes but required-decision gates hard-block); L3 = unattended within an allowlist.
- **`/goal` is capability-probed, not hardcoded.** `ospec execute launch --primitive goal` produces a native-`/goal` instruction when the target supports it (claude, codex), otherwise an emulated-goal verify-driven plan. CLI-driven targets use `claude -p` / `codex exec` (never `claude --goal`).
- **Scheduling is session-bound.** Controller-driven loops re-run `loop run --once` on the controller's tick cadence (`ospec loop tick-plan`); CLI-driven loops use `ospec loop watch` (dies with the session). Stop with `ospec loop pause` / a `STOP` file / closing the session.
- **Stop condition is three-stage:** run the project's real tests, record 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
- document review for design and implementation plan
- worker dispatch, launch, collection, retry, and review packets
- user decision gates
- workspace and worktree planning
- TDD, debug, and verification evidence
- final spec and code-quality reviews
- 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/SKILL.index.json` for nested projects, or root `SKILL.index.json`
3. `.ospec/for-ai/ai-guide.md` and `.ospec/for-ai/execution-protocol.md`, or legacy `for-ai/`
4. `.ospec/changes/active/<goal>/proposal.md`
5. `.ospec/changes/active/<goal>/design.md`
6. `.ospec/changes/active/<goal>/implementation-plan.md`
7. `.ospec/changes/active/<goal>/artifacts/agents/task-graph.json`
8. `.ospec/changes/active/<goal>/artifacts/reviews/design-review.md`
9. `.ospec/changes/active/<goal>/artifacts/reviews/implementation-plan-review.md`
10. `.ospec/changes/active/<goal>/artifacts/agents/bootstrap.md`
11. `.ospec/changes/active/<goal>/artifacts/agents/workflow-route.md`
12. `.ospec/changes/active/<goal>/artifacts/agents/workspace-status.md`
13. `.ospec/changes/active/<goal>/artifacts/agents/launch-plan.md`
14. `.ospec/changes/active/<goal>/artifacts/agents/worker-runs/`
15. `.ospec/changes/active/<goal>/artifacts/agents/review-runs/`
16. `.ospec/changes/active/<goal>/artifacts/agents/decisions/`
17. `.ospec/changes/active/<goal>/artifacts/reviews/spec-compliance.md`
18. `.ospec/changes/active/<goal>/artifacts/reviews/code-quality.md`
19. `.ospec/changes/active/<goal>/artifacts/agents/worker-status.md`
20. `.ospec/changes/active/<goal>/artifacts/agents/tdd-evidence.json`
21. `.ospec/changes/active/<goal>/artifacts/agents/debug-evidence.json`
22. `.ospec/changes/active/<goal>/artifacts/agents/verification-evidence.json`
23. `.ospec/changes/active/<goal>/tasks.md`
24. `.ospec/changes/active/<goal>/state.json`
25. `.ospec/changes/active/<goal>/verification.md`
26. `.ospec/changes/active/<goal>/review.md`

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

## Visibility & Decisions

- `Announce-Before-Act`: never run the goal workflow silently. Announce in one line which skill you are using (`ospec-goal`) and the current stage; say which `ospec execute ...` command you are about to run and the artifact it writes; when you dispatch native subagents, announce how many workers you launch, which task each takes, and the mechanism (`Task` for Claude Code, `spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, `@generalist` for Gemini, `@mention` for OpenCode); when a gate blocks progress, tell the user what is blocked and what unblocks it.
- `Brainstorm-First`: open each goal with a short brainstorming pass before locking design. Surface the open questions for direction, architecture, API, data, UI, risk, and scope, and ask the user one question at a time instead of silently assuming; persist exploration with `ospec brainstorm [path] --topic "..."` when useful, and do not leave a brainstorm as an unanswered template — ask the user its decision gates and record each answer with `ospec brainstorm resolve [path] --brainstorm <id> --gate <gate-id> --select <option-id>` so it has a result. When any of those is genuinely open, prefer raising a durable decision gate over guessing: `ospec execute decision [changes/active/<goal>] --id <id> --question "..." --option id:label:impact --required`, present the decision report `Chat Prompt` or `artifacts/agents/decisions/index.md`, then record the answer with `--select <option-id>`. Only record an autonomous assumption in `design.md` when the user explicitly defers or is unavailable, and label it as an assumption to confirm. Present options using the best interactive mechanism your harness has: a native question UI (Claude Code `AskUserQuestion`, Gemini `ask_user`) if a