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.
- **The level gates auto-advance.** At **L1/L2**, `ospec loop run` hard-blocks while any required user decision is pending — present each one to the user (never auto-select the recommended option) and record the answer with `ospec execute decision ... --select` before the loop proceeds. Only **L3** may auto-advance within its allowlist. The level is not a hint; it decides whether you may proceed without asking.
- **`/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
- a single combined final code review
- 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/final-review.md`
18. `.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.

## Language

- Follow the project-adopted document language from managed `for-ai/` guidance, `.skillrc` `documentLanguage`, and existing change docs.
- Write **every** goal document and artifact you author — `proposal.md`, `design.md`, `implementation-plan.md`, `tasks.md`, `verification.md`, `review.md`, review artifacts, and brainstorm content — in that one language. Do not mix Chinese and English within a change.
- Keep Chinese projects in Chinese unless the repo explicitly adopts English.

## 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. **NEVER auto-select the recommended option or resolve a decision gate yourself — `recommended` is