@clawplays/ospec-cli 1.0.1 → 1.1.0

package/README.md

@@ -37,10 +37,10 @@ The official OSpec CLI package is `@clawplays/ospec-cli`, and the official comma
 
 AI coding assistants are powerful, but requirements that live only in chat history are hard to inspect, review, and close out cleanly. OSpec adds a lightweight workflow layer so the repository can hold the change context before code is written and after the work ships.
 
-- Align before code — keep proposal, tasks, state, verification, and review visible in the repo
+- Align before code — keep proposal, design, implementation plan, tasks, state, verification, and review visible in the repo
 - Keep each requirement explicit — the default path moves one requirement through one active change
 - Stay lightweight — keep the normal flow short with `init -> change -> verify/finalize`
-- Use the assistants you already have — OSpec is built for Codex, Claude Code, and direct CLI workflows
+- Use the assistants you already have — OSpec is built for Codex/GPT, Claude Code, Gemini, OpenCode, and direct CLI fallback workflows
 
 ## Install With npm
 
@@ -71,7 +71,7 @@ OSpec, initialize this project.
 Claude / Codex skill mode:
 
 ```text
-$ospec initialize this project.
+/ospec initialize this project.
 ```
 
 <details>
@@ -94,6 +94,7 @@ CLI notes:
 - CLI language resolution order: explicit `--document-language` -> persisted project language in `.skillrc` -> existing project docs / managed `for-ai/*` guidance / asset manifest -> fallback `en-US`
 - OSpec persists the chosen project document language in `.skillrc` and reuses it for `for-ai` guidance, `ospec new`, and `ospec update`
 - new projects initialized by `ospec init` default to the nested layout: root `.skillrc` and `README.md`, with OSpec-managed files under `.ospec/`
+- plain init does not create optional knowledge maps such as `.ospec/knowledge/src/` or `.ospec/knowledge/tests/`; those appear only when a project already has legacy knowledge content to migrate or when future explicit knowledge-generation flows create them
 - CLI commands still accept shorthand like `changes/active/<change-name>`, but the physical path in nested projects is `.ospec/changes/active/<change-name>`
 - if you pass these values, OSpec uses them directly when generating project docs
 - if you do not pass them, OSpec reuses existing docs when possible and otherwise creates placeholder docs first
@@ -113,7 +114,7 @@ OSpec, create and advance a change for this requirement.
 Claude / Codex skill mode:
 
 ```text
-$ospec-change create and advance a change for this requirement.
+/ospec-change create and advance a change for this requirement.
 ```
 
 <details>
@@ -127,6 +128,25 @@ ospec new update-billing-copy .
 
 </details>
 
+### One-Change Agent Execution
+
+The normal AI-assisted path still starts with one active change. OSpec keeps the controller state in repo artifacts, and the current AI harness starts native worker agents when available.
+
+```bash
+ospec session .
+ospec execute bootstrap changes/active/<change-name>
+ospec execute workspace changes/active/<change-name>
+ospec execute status changes/active/<change-name>
+ospec execute dispatch changes/active/<change-name> --limit 2
+ospec execute launch changes/active/<change-name> --task <task-id> --target codex
+ospec execute complete <task-id> changes/active/<change-name> --status DONE --summary "..."
+ospec execute review changes/active/<change-name> --task <task-id> --stage spec
+ospec execute review changes/active/<change-name> --task <task-id> --stage quality
+ospec execute verify changes/active/<change-name> --command "npm test" --status PASSED --exit-code 0
+```
+
+`launch` writes `artifacts/agents/launch-plan.md`; it does not start workers by itself. Codex/GPT use `spawn_agent` / `wait_agent` / `close_agent`, Claude Code uses Task, Gemini uses `@generalist`, and OpenCode uses `@mention`. Use `launch --run --command` or `orchestrate --command` only when the current harness cannot start native subagents.
+
 ### 3. Archive After Acceptance
 
 After the requirement has passed deployment, testing, QA, or other acceptance checks, archive the validated change.
@@ -140,7 +160,7 @@ OSpec, archive this accepted change.
 Claude / Codex skill mode:
 
 ```text
-$ospec archive this accepted change.
+/ospec archive this accepted change.
 ```
 
 <details>
@@ -171,6 +191,7 @@ ospec update
 
 `ospec update` also migrates legacy root-level `build-index-auto.cjs` / `build-index-auto.js` tooling into `.ospec/tools/build-index-auto.cjs` and refreshes OSpec-managed hook entrypoints to use the new location.
 It also repairs older OSpec projects that still have an OSpec footprint but are missing newer core runtime directories, refreshes managed skills and archive layout metadata, and syncs project assets for already-enabled plugins.
+For nested projects that still carry legacy knowledge under `.ospec/src/` or `.ospec/tests/`, `ospec update` migrates those paths into `.ospec/knowledge/src/` and `.ospec/knowledge/tests/`.
 When an already-enabled plugin has a newer compatible npm package version available, `ospec update` upgrades that global plugin package automatically and prints the version transition.
 It does not upgrade the CLI itself, and it does not enable plugins or migrate active / queued changes automatically.
 It also does not switch a classic project layout to nested automatically.
@@ -201,7 +222,19 @@ If you want to convert an older classic project to the new layout, run `ospec la
 ┌─────────────────────────────────────────────────────────────────┐
 │  3. EXECUTION                                                  │
 │     ospec new <change-name>                                    │
+│     ospec brainstorm / plan (optional pre-change aids)         │
+│     ospec session                                              │
+│     ospec session hook                                         │
 │     ospec progress                                             │
+│     ospec execute bootstrap / handoff / doc-review / status    │
+│     ospec execute next                                         │
+│     ospec execute workspace / worktree / worktree --create     │
+│     ospec execute worktree --cleanup / finish                  │
+│     ospec execute dispatch / launch / collect / retry / review │
+│     ospec execute debug                                        │
+│     ospec execute tdd                                          │
+│     ospec execute verify                                       │
+│     ospec execute sync                                         │
 └─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
@@ -225,7 +258,7 @@ If you want to convert an older classic project to the new layout, run `ospec la
 |---------|---------------|
 | **Protocol Shell** | The minimum collaboration skeleton: root `.skillrc` and `README.md`, plus managed OSpec files under `.ospec/` for change state, SKILL docs, index state, `for-ai/` guidance, and project docs. |
 | **Project Knowledge Layer** | Explicit project context such as `docs/project/*`, layered skill files, and index state that AI can read consistently. |
-| **Active Change** | A dedicated execution container for one requirement, usually with `proposal.md`, `tasks.md`, `state.json`, `verification.md`, and `review.md`. |
+| **Active Change** | A dedicated execution container for one requirement, usually with `proposal.md`, `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, `tasks.md`, handoff artifacts, document-review artifacts, launch-plan artifacts, worker-run artifacts, reviewer-run artifacts, retry artifacts, review artifacts, `artifacts/agents/worker-status.md`, `state.json`, `verification.md`, and `review.md`. |
 
 ## Features
 
@@ -233,7 +266,10 @@ If you want to convert an older classic project to the new layout, run `ospec la
 - **Guided initialization**: AI-assisted init can ask once for missing summary or tech stack; direct CLI init falls back to placeholder docs when context is missing.
 - **Stable project language**: the chosen document language is stored in `.skillrc` so later guidance and generated change docs stay consistent unless you explicitly change it.
 - **Docs maintenance**: `ospec docs generate` refreshes or repairs project knowledge docs when you need it later.
-- **Tracked requirement execution**: each change can keep proposal, tasks, state, verification, and review files aligned.
+- **Tracked requirement execution**: each change can keep proposal, design, implementation plan, task graph, tasks, handoff artifacts, document-review artifacts, launch-plan artifacts, worker-run artifacts, reviewer-run artifacts, retry artifacts, worker status, state, verification, and review files aligned.
+- **Optional pre-change aids**: `ospec brainstorm` writes durable exploration artifacts under `.ospec/brainstorms/`, with an optional static visual companion; `ospec plan` writes plan drafts under `.ospec/plans/` and only updates `implementation-plan.md` when `--apply` is passed. The default one-change flow still starts with `ospec new`.
+- **Session brief**: `ospec session` writes `.ospec/session-brief.json` and `.ospec/session-brief.md` so agents or humans entering an existing project can see active changes, queued changes, queue-run state, a cache fingerprint, and the next safe command before touching a change; `ospec session hook` writes opt-in harness startup hook artifacts under `.ospec/hooks/`.
+- **Task graph controller**: `ospec execute bootstrap` writes a one-change startup/resume snapshot with the project session brief snapshot and next safe action; `handoff` writes a cross-tool worker handoff guide with the project session brief snapshot; `doc-review` creates design and implementation-plan reviewer packets before task execution; `status` and `next` report controller state and safe next task candidates; `workspace` records git workspace safety before worker handoff; `worktree` records an isolated-worktree preparation plan by default, while explicit `--create` or `--cleanup` runs the matching git worktree command and captures `artifacts/agents/worktree-runs/`; `finish` records closeout readiness before finalize, archive, push, merge, or worktree cleanup; `dispatch` and `complete` create parallel-safe worker packets with worker profiles and target tool mapping, then record task results as OSpec artifacts; `review --task` creates per-task spec and quality review packets that block dependent tasks until approved, while final `review` creates whole-change reviewer packets; `launch` writes the native agent launch plan for the current AI harness, including Codex/GPT `spawn_agent`, Claude Code Task, Gemini `@generalist`, and OpenCode `@mention` guidance; `orchestrate` is the final CLI fallback for harnesses without native subagents and runs explicit command templates only; `launch --run --command` is the single-worker CLI fallback; `collect` turns a fallback worker run into task completion state; `retry` reopens blocked, needs-context, or failed task work; explicit review `--run --command` captures `artifacts/agents/review-runs/`; `debug`, `tdd`, and `verify` record durable evidence; `sync` rebuilds `worker-status.md` from execution and review artifacts.
 - **Queue helpers**: `queue` and `run` support explicit multi-change execution when one active change is not enough.
 - **Plugin workflow gates**: plugin commands support Stitch design review and Checkpoint automation through npm-installed official plugins.
 - **Skill management**: install and inspect OSpec skills for Codex and Claude Code.
@@ -245,11 +281,11 @@ OSpec supports plugins for UI review and runtime validation.
 Keep the public flow simple:
 
 ```text
-$ospec open Stitch for this project.
-$ospec open Checkpoint for this project.
+/ospec open Stitch for this project.
+/ospec open Checkpoint for this project.
 ```
 
-In AI / `$ospec` flows, requests like "open Stitch" or "open Checkpoint" should be handled as: check whether the plugin is already installed globally, install only when missing, then enable it in the current project.
+In AI / `/ospec` flows, requests like "open Stitch" or "open Checkpoint" should be handled as: check whether the plugin is already installed globally, install only when missing, then enable it in the current project.
 
 Command line fallback:
 

package/SKILL.md

@@ -37,9 +37,10 @@ If the user intent is simply to initialize the project or current directory, tre
 Use this exact behavior:
 
 1. run `ospec init [path]` when the directory is uninitialized or not yet change-ready
-2. if AI assistance is available and the repository lacks usable project context, ask one concise follow-up for summary or tech stack before init when helpful
-3. verify the actual filesystem result before claiming initialization is complete
-4. stop before `ospec new` unless the user explicitly asks to create a change
+2. in AI-assisted init, map an explicit language request or the current conversation language to `--document-language`; do not assume a brand-new repo will infer it
+3. if AI assistance is available and the repository lacks usable project context, ask one concise follow-up for summary or tech stack before init when helpful
+4. verify the actual filesystem result before claiming initialization is complete
+5. stop before `ospec new` unless the user explicitly asks to create a change
 
 Never replace `ospec init` with manual directory creation or a hand-written approximation.
 
@@ -66,7 +67,7 @@ Required checks after `ospec init`:
 - `docs/project/module-map.md`
 - `docs/project/api-overview.md`
 
-During plain init, do not report `docs/SKILL.md`, `src/SKILL.md`, `tests/SKILL.md`, or business scaffold as if they were part of change-ready completion.
+During plain init, do not report `docs/SKILL.md`, optional knowledge maps such as `knowledge/src/SKILL.md` / `knowledge/tests/SKILL.md`, or business scaffold as if they were part of change-ready completion.
 
 ## Prompt Profiles
 
@@ -133,6 +134,7 @@ Use ospec to create a change queue and execute it explicitly with ospec run manu
 Always keep these rules:
 
 - `ospec init` should leave the repository in a change-ready state
+- in AI-assisted init, pass `--document-language` from the explicit language request or current conversation language when the project language is already apparent
 - AI-assisted init may ask one concise follow-up question for missing summary or tech stack; if the user declines, continue with placeholder docs
 - `ospec docs generate` refreshes, repairs, or backfills project knowledge docs after initialization
 - when the user asks to initialize, execute the CLI init command and verify the protocol-shell files and `docs/project/*` files on disk before declaring success
@@ -161,11 +163,35 @@ This CLI now covers:
 Treat these as the source of truth for active delivery work:
 
 - `.skillrc`
+- `.ospec/session-brief.md`
 - `docs/project/overview.md`
 - `docs/project/tech-stack.md`
 - `docs/project/architecture.md`
 - `changes/active/<change>/proposal.md`
+- `changes/active/<change>/design.md`
+- `changes/active/<change>/implementation-plan.md`
+- `changes/active/<change>/artifacts/agents/task-graph.json`
+- `changes/active/<change>/artifacts/agents/bootstrap.md`
+- `changes/active/<change>/artifacts/agents/handoff.md`
+- `changes/active/<change>/artifacts/agents/document-review-dispatches/`
+- `changes/active/<change>/artifacts/agents/workspace-status.md`
+- `changes/active/<change>/artifacts/agents/worktree-plan.md`
+- `changes/active/<change>/artifacts/agents/finish-plan.md`
+- `changes/active/<change>/artifacts/agents/launch-plan.md`
+- `changes/active/<change>/artifacts/agents/worker-runs/`
+- `changes/active/<change>/artifacts/agents/review-runs/`
+- `changes/active/<change>/artifacts/agents/retries/`
+- `changes/active/<change>/artifacts/agents/blockers/`
+- `changes/active/<change>/artifacts/agents/review-feedback-plan.md`
 - `changes/active/<change>/tasks.md`
+- `changes/active/<change>/artifacts/reviews/design-review.md`
+- `changes/active/<change>/artifacts/reviews/implementation-plan-review.md`
+- `changes/active/<change>/artifacts/reviews/spec-compliance.md`
+- `changes/active/<change>/artifacts/reviews/code-quality.md`
+- `changes/active/<change>/artifacts/agents/worker-status.md`
+- `changes/active/<change>/artifacts/agents/debug-evidence.json`
+- `changes/active/<change>/artifacts/agents/tdd-evidence.json`
+- `changes/active/<change>/artifacts/agents/verification-evidence.json`
 - `changes/active/<change>/state.json`
 - `changes/active/<change>/verification.md`
 
@@ -174,6 +200,38 @@ Treat these as the source of truth for active delivery work:
 Before advancing an active change:
 
 - read `.skillrc.plugins` to detect enabled blocking plugins
+- use `ospec session [path]` when entering an existing OSpec project to write `.ospec/session-brief.json` and `.ospec/session-brief.md`; it records active changes, queued changes, queue run state, safe next commands, and a cache fingerprint for session re-entry, and does not launch workers, run tests, inspect git, archive, or edit source files
+- use `ospec session hook [path]` only to write opt-in harness startup hook artifacts under `.ospec/hooks/`; it refreshes session context only and must not launch workers, run tests, inspect git, archive, or edit source files
+- use `ospec brainstorm [path] --topic "..." [--visual]` only for optional pre-change exploration artifacts under `.ospec/brainstorms/`; it does not create a change
+- use `ospec plan [path] --change changes/active/<change> [--apply]` only for optional plan drafts under `.ospec/plans/`; `--apply` is required to update `implementation-plan.md`
+- treat activated built-in quality policy steps such as `tdd_cycle`, `root_cause_debug`, and `verification_evidence` as archive-gated `optional_steps`; cover them in `tasks.md`, `verification.md`, and the matching evidence artifacts before closeout
+- keep `changes/active/<change>/artifacts/agents/task-graph.json` aligned with `implementation-plan.md` and `tasks.md`
+- do not archive while `artifacts/agents/task-graph.json` has unresolved task statuses, invalid dependencies, missing target files, or missing verification commands
+- use `ospec execute bootstrap [changes/active/<change>]` when starting or resuming a single active change to write `artifacts/agents/bootstrap.json` and `artifacts/agents/bootstrap.md`; it summarizes current stage, project session brief snapshot, and next safe action, including `ospec execute launch ... --task ...` when an active dispatch is waiting, without launching workers, syncing worker status, running tests, inspecting git, or editing source files
+- use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules, but does not launch workers, sync worker status, run tests, inspect git, or edit source files
+- use `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` before deriving or dispatching implementation tasks to create document reviewer packets with the project session brief snapshot under `artifacts/agents/document-review-dispatches/`; design review must be approved before implementation plan review, and the command does not launch reviewers, run shell commands, sync worker status, or edit source files
+- use `ospec execute workspace [changes/active/<change>]` before worker handoff to record git workspace safety; if status is `needs_isolation`, defer parallel dispatch until the workspace is clean or moved into an isolated git worktree
+- use `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` to write an isolated worktree preparation plan without running git
+- use `ospec execute worktree [changes/active/<change>] --create [--branch name] [--path path] [--base ref]` only when explicitly asked to run `git worktree add`; it records stdout/stderr/status under `artifacts/agents/worktree-runs/`
+- use `ospec execute worktree [changes/active/<change>] --cleanup [--path path]` only when explicitly asked to run `git worktree remove`; it does not delete branches, push, merge, archive, run tests, or edit project source files
+- use `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` to write an artifact-only closeout readiness plan before finalize, archive, push, PR, merge, or worktree cleanup; review blockers and commands manually
+- use `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` to create a parallel-safe worker packet batch and `artifacts/agents/execution-session.json`; each packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior; use `--task` for one explicit task, use `--limit` to cap dispatch batch size, and use `ospec execute complete <task-id> ...` to record worker results; a terminal worker result opens task-level review gates, so run `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`, then `--stage quality`, before dispatching dependent work
+- use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` after dispatch to write `artifacts/agents/launch-plan.json` and `artifacts/agents/launch-plan.md`; this is the native agent launch artifact and tells the controlling AI how to use the current harness native agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, and `@mention` for OpenCode). It requires an active dispatch and ready workspace status, and does not start workers, run shell commands, or edit source files by itself
+- default to current-harness native subagents for multi-worker execution: create parallel-safe packets with `ospec execute dispatch`, inspect `launch-plan.md`, then dispatch one native agent per safe packet in the current AI session; only use `ospec execute orchestrate [changes/active/<change>] --command "..." [--target codex|gpt|claude|gemini|opencode|shell|generic] [--limit N] [--max-rounds N] [--timeout-ms N]` as the final CLI fallback when the current AI harness cannot dispatch native subagents. The fallback reads or creates parallel-safe dispatches, renders the explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, and collects results into the task graph unless `--no-collect` is passed
+- use `--run --command` with `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] --run --command "..." [--timeout-ms N]` only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; it captures stdout, stderr, exit code, timeout metadata, and run metadata under `artifacts/agents/worker-runs/`, then `ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]` records the task result
+- use `ospec execute retry [changes/active/<change>] --task task-id [--run run-id] [--force]` after a blocked, needs-context, or failed run has been corrected; it writes `artifacts/agents/retries/`, reopens the task, and creates a fresh dispatch packet. Completed tasks require explicit `--force`
+- keep `dispatch`, `launch`, `orchestrate`, `collect`, `retry`, and `complete` artifact-controlled: native subagent dispatch is performed by the current AI harness, while shell commands run only for explicit fallback `launch --run --command` or `orchestrate` with a command template; none of these commands edits project source files directly; when `complete` or `collect` records `NEEDS_CONTEXT` or `BLOCKED`, OSpec writes blocker escalation under `artifacts/agents/blockers/`
+- complete `changes/active/<change>/artifacts/reviews/spec-compliance.md` before `changes/active/<change>/artifacts/reviews/code-quality.md`
+- use `ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality]` to create durable task-level or final reviewer handoff packets with the project session brief snapshot; with `--task`, review one completed task and write `artifacts/reviews/tasks/<task-id>/...`; without `--task`, run the final whole-change review after the task graph is completed; do not dispatch quality review before the matching spec review is approved
+- use `ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality] --run --command "..."` only when explicitly asked to run a local reviewer command; it captures review stdout/stderr under `artifacts/agents/review-runs/` and can update the matching task-level or final review artifact when `--decision` is provided
+- use `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` after a review artifact has a non-`PENDING` decision to write `artifacts/agents/review-feedback-plan.json` and `artifacts/agents/review-feedback-plan.md`; this records how to accept, revise, clarify, or unblock review feedback and does not edit source files or launch workers
+- do not archive while any task-level review or final review decision is `PENDING`, `NEEDS_CHANGES`, or `BLOCKED`
+- update `changes/active/<change>/artifacts/agents/worker-status.md` during implementation and review
+- use `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` when debugging was part of the change to record systematic debugging evidence; this command records evidence only and does not run shell commands
+- use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` after focused test runs to record TDD cycle evidence; this command records evidence only and does not run shell commands
+- use `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` after running fresh project checks to record verification evidence; this command records evidence only and does not run shell commands
+- use `ospec execute sync [changes/active/<change>]` after manual task graph, execution-session, review artifact, or verification checklist edits to rebuild worker status
+- do not claim completion while worker status is `PENDING`, `NEEDS_CONTEXT`, or `BLOCKED`; `controller_status` must be `DONE` before archive
 - if the current change activates `stitch_design_review`, inspect `changes/active/<change>/artifacts/stitch/approval.json`
 - when Stitch approval is missing or `status != approved`, treat the change as blocked and do not claim it is ready to continue or archive
 
@@ -183,9 +241,14 @@ Do not fall back to the old `features/...` layout unless the target repository r
 
 ```bash
 ospec status [path]
+ospec session [path]
+ospec session hook [path]
 ospec init [path]
+ospec init [path] --document-language zh-CN
 ospec init [path] --summary "..." --tech-stack node,react
 ospec docs generate [path]
+ospec brainstorm [path] --topic "..." [--change name] [--output id] [--visual]
+ospec plan [path] [--change changes/active/<change>] [--from-brainstorm file] [--output id] [--apply]
 ospec new <change-name> [path]
 ospec docs status [path]
 ospec skills status [path]
@@ -198,6 +261,31 @@ ospec run status [path]
 ospec run step [path]
 ospec run resume [path]
 ospec run stop [path]
+ospec execute status [changes/active/<change>]
+ospec execute bootstrap [changes/active/<change>]
+ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]
+ospec execute doc-review [changes/active/<change>] [--stage design|plan]
+ospec execute next [changes/active/<change>]
+ospec execute workspace [changes/active/<change>]
+ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]
+ospec execute worktree [changes/active/<change>] --create [--branch name] [--path path] [--base ref]
+ospec execute worktree [changes/active/<change>] --cleanup [--path path]
+ospec execute finish [changes/active/<change>] [--target main] [--remote origin]
+ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]
+ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]
+ospec execute orchestrate [changes/active/<change>] --command "..." [--target codex|gpt|claude|gemini|opencode|shell|generic] [--limit N] [--max-rounds N] [--timeout-ms N] # fallback only
+ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] --run --command "..." [--timeout-ms N] # fallback only
+ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id] [--status DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED] [--summary "..."]
+ospec execute retry [changes/active/<change>] --task task-id [--run run-id] [--summary "..."] [--force]
+ospec execute complete <task-id> [changes/active/<change>] --status DONE --summary "..."
+ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality]
+ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality] --run --command "..." [--timeout-ms N] [--decision APPROVED|APPROVED_WITH_CONCERNS|NEEDS_CHANGES|BLOCKED|PENDING] [--summary "..."]
+ospec execute feedback [changes/active/<change>] [--stage spec|quality] [--summary "..."]
+ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED --command "npm test -- focused" --summary "..."
+ospec execute tdd [changes/active/<change>] --phase red --command "npm test -- focused" --status FAILED --exit-code 1 --summary "..."
+ospec execute tdd [changes/active/<change>] --phase green --command "npm test -- focused" --status PASSED --exit-code 0 --summary "..."
+ospec execute verify [changes/active/<change>] --command "npm test" --status PASSED --exit-code 0 --summary "..."
+ospec execute sync [changes/active/<change>]
 ospec plugins available
 ospec plugins info <plugin>
 ospec plugins install <plugin>
@@ -246,7 +334,7 @@ ospec finalize [changes/active/<change>]
 
 Use `ospec docs generate [path]` later when you need a docs-only maintenance pass.
 
-Use `ospec status [path]` separately when you want an explicit troubleshooting snapshot.
+Use `ospec session [path]` when entering an existing OSpec project and you need a durable project-level brief with active change, queued change, queue-run, safe next command context, and a cache fingerprint. Use `ospec session hook [path]` only to write opt-in startup hook artifacts for a harness. Use `ospec status [path]` separately when you want an explicit troubleshooting snapshot.
 
 For completed changes, archive before commit. Use `ospec archive [changes/active/<change>]` to execute the archive and `--check` only when you want a readiness preview without moving files.
 

package/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "OSpec"
   short_description: "Inspect, initialize, and operate OSpec projects"
-  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: use ospec init so the repository ends in change-ready state, reuse existing project docs when available, ask one concise follow-up for missing summary or tech stack in AI-assisted flows, fall back to placeholder docs when the user skips that context, do not assume a web template when the project type is unclear, do not create the first change automatically, and use ospec status or ospec changes status only when you need an explicit summary."
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: use ospec init so the repository ends in change-ready state, reuse existing project docs when available, map an explicit language request or the current conversation language to --document-language during AI-assisted init instead of assuming a brand-new repo will infer it, ask one concise follow-up for missing summary or tech stack in AI-assisted flows, fall back to placeholder docs when the user skips that context, do not assume a web template when the project type is unclear, do not create the first change automatically, and use ospec status or ospec changes status only when you need an explicit summary."

package/assets/for-ai/ar/ai-guide.md

@@ -22,10 +22,36 @@ tags: [ai, guide, ospec]
 
 ## السلوك المطلوب
 
-- حافظ على `proposal.md` و`tasks.md` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
+- حافظ على `proposal.md` و`design.md` و`implementation-plan.md` و`artifacts/agents/task-graph.json` و`artifacts/agents/bootstrap.md` و`artifacts/agents/handoff.md` و`artifacts/agents/document-review-dispatches/` و`artifacts/agents/workspace-status.md` و`artifacts/agents/worktree-plan.md` و`artifacts/agents/finish-plan.md` و`artifacts/agents/launch-plan.md` و`artifacts/agents/worker-runs/` و`artifacts/agents/review-runs/` و`artifacts/agents/retries/` و`artifacts/agents/blockers/` و`artifacts/agents/review-feedback-plan.md` و`tasks.md` و`artifacts/reviews/design-review.md` و`artifacts/reviews/implementation-plan-review.md` و`artifacts/reviews/spec-compliance.md` و`artifacts/reviews/code-quality.md` و`artifacts/agents/worker-status.md` و`artifacts/agents/debug-evidence.json` و`artifacts/agents/tdd-evidence.json` و`artifacts/agents/verification-evidence.json` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
 - لا تستنتج لغة وثائق change من لغة واجهة المنتج أو locale الموقع أو من متطلب "الإنجليزية أولاً" فقط
 - إذا كان البروتوكول المعتمد للمشروع بالصينية أو كانت وثائق change الحالية بالصينية بالفعل، فاستمر بالصينية ما لم تغيّر قواعد المشروع ذلك صراحةً
 - استخدم الفهرس لتحديد موقع المعرفة قبل قراءة الملفات الهدف
+- عند الدخول إلى مشروع OSpec موجود، شغّل `ospec session [path]` لكتابة `.ospec/session-brief.json` و`.ospec/session-brief.md` مع active change وqueued change وqueue run وcache fingerprint والأمر الآمن التالي؛ هذا project entry brief لا يستبدل `ospec execute bootstrap` للـ active change
+- تعامل مع خطوات built-in quality policy المفعّلة مثل `tdd_cycle` و`root_cause_debug` و`verification_evidence` كـ `optional_steps` خاضعة لـ archive gate؛ غطّها في `tasks.md` و`verification.md` وملفات evidence المطابقة قبل closeout
+- عند تنفيذ change بمساعدة AI، لا تطلب من المستخدم كتابة `design.md` أو `implementation-plan.md` يدوياً؛ أنشئهما أو حدّثهما من المتطلب و`proposal.md` وسياق المشروع قبل اشتقاق `artifacts/agents/task-graph.json` أو تعديل `tasks.md` أو الكود
+- لا تطرح أكثر من سؤال تصميم موجز واحد إلا عندما يغيّر القرار الناقص البنية أو API أو البيانات أو UI أو المخاطر فعلياً؛ وإلا فسجل الافتراضات في `design.md`
+- يجب أن يُشتق `implementation-plan.md` من `design.md`، وأن يُشتق `artifacts/agents/task-graph.json` من `implementation-plan.md`، وأن تُشتق `tasks.md` من task graph، وتُوائم المهام الموجودة بعد تحديث الوثائق السابقة
+- عند بدء أو استئناف active change واحد، استخدم `ospec execute bootstrap [changes/active/<change>]` لكتابة `artifacts/agents/bootstrap.json` و`artifacts/agents/bootstrap.md` مع project session brief snapshot، ثم اتبع الإجراء الآمن التالي المسجل فيه؛ عند وجود active dispatch، يوصي bootstrap بأمر `ospec execute launch ... --task ...` المطابق
+- عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files
+- قبل اشتقاق implementation tasks أو dispatch لها، استخدم `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` لإنشاء document reviewer packets تتضمن project session brief snapshot تحت `artifacts/agents/document-review-dispatches/` وتجهيز `artifacts/reviews/design-review.md` أو `artifacts/reviews/implementation-plan-review.md`؛ يجب اعتماد design review قبل dispatch لمراجعة implementation plan
+- عندما تحتاج إلى عرض controller للمهام ready وblocked وrunning وcompleted والمرشحات التالية الآمنة، استخدم `ospec execute status [changes/active/<change>]` أو `ospec execute next [changes/active/<change>]`
+- قبل handoff إلى worker استخدم `ospec execute workspace [changes/active/<change>]` لتسجيل سلامة git workspace؛ إذا كانت الحالة `needs_isolation`، نظّف workspace أو انقل العمل إلى git worktree معزول قبل parallel dispatch
+- قبل إنشاء git worktree معزول، استخدم `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` لكتابة `artifacts/agents/worktree-plan.json` و`artifacts/agents/worktree-plan.md`؛ هذا الأمر يسجل خطة تحضير فقط ولا يشغّل `git worktree add`
+- قبل الإغلاق النهائي، استخدم `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` لكتابة `artifacts/agents/finish-plan.json` و`artifacts/agents/finish-plan.md`؛ هذا الأمر يسجل الجاهزية ونص الأوامر فقط ولا يشغل finalize أو archive أو push أو merge أو حذف worktree
+- عندما تحتاج إلى handoff artifacts دائمة على مستوى task، استخدم `ospec execute dispatch` لإنشاء batch آمن للتوازي من worker packets و`ospec execute complete` لتسجيل نتائج worker؛ يتضمن كل dispatch packet project session brief snapshot وworker profile يوضح capability tier وrecommended target وtarget tool mapping وrationale وrequired behavior؛ عندما تكون النتيجة `NEEDS_CONTEXT` أو `BLOCKED` يكتب `complete` ملفات `artifacts/agents/blockers/`؛ استخدم `--task` لمهمة واحدة صريحة و`--limit` لتحديد حجم dispatch batch؛ بعد اكتمال كل worker task استخدم `ospec execute review [changes/active/<change>] --task <task-id> --stage spec` ثم `--stage quality` لإجراء task-level review، وتبقى المهام التابعة محجوبة حتى اعتماد المراجعتين؛ وبعد اعتماد كل task-level reviews واكتمال task graph استخدم `ospec execute review` من دون `--task` لإنشاء final spec أو quality reviewer handoff packets؛ وبعد decision غير `PENDING` استخدم `ospec execute feedback` لكتابة `artifacts/agents/review-feedback-plan.md`؛ وبعد تعديل execution أو review artifacts يدويا استخدم `ospec execute sync` لإعادة بناء `worker-status.md`
+- بعد dispatch، استخدم `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` لكتابة native agent launch plan؛ يوجه controlling AI إلى آلية agent الأصلية في harness الحالي: Codex/GPT يستخدم `spawn_agent`/`wait_agent`/`close_agent`، وClaude Code يستخدم Task، وGemini يستخدم `@generalist`، وOpenCode يستخدم `@mention`. هذا الأمر لا يشغّل workers ولا أوامر shell بنفسه
+- default multi-worker execution هو current-harness native subagents: أنشئ safe packets عبر `ospec execute dispatch`، اقرأ `launch-plan.md`، ثم dispatch native worker agent لكل packet آمن، وسجل النتيجة عبر `ospec execute complete`
+- استخدم `ospec execute orchestrate [changes/active/<change>] --command "..."` فقط كـ final CLI fallback عندما لا يدعم harness الحالي native subagents؛ fallback mode يرندر explicit command template ويشغّل worker commands بالتوازي ويسجل `artifacts/agents/orchestration-runs/`
+- استخدم `--run --command` مع `ospec execute launch ... --run --command "..."` فقط كـ single-worker CLI fallback عندما لا تتوفر native subagents أو يتم تجاوزها صراحة؛ ثم استخدم `ospec execute collect ...` لتسجيل fallback task result. بعد إصلاح blocked أو needs-context أو failed work استخدم `ospec execute retry` لإعادة dispatch
+- لا يشغّل OSpec local reviewer command إلا عند استخدام `ospec execute review ... --run --command "..."` صراحة؛ يسجل ذلك `artifacts/agents/review-runs/` ويمكنه كتابة review decision عند تمرير `--decision`
+- عندما يكون debugging جزءا من change، استخدم `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` لتسجيل root-cause وfix evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
+- بعد تشغيل focused tests، استخدم `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` لتسجيل TDD cycle evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
+- بعد تشغيل project checks حديثة، استخدم `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` لتسجيل verification evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
+- `ospec execute doc-review` يسجل artifacts فقط ولا يشغّل reviewers ولا أوامر shell ولا يزامن worker status ولا يعدّل source files
+- لا تؤرشف عندما يحتوي `artifacts/agents/task-graph.json` على حالات مهام غير محسومة أو اعتماديات غير صالحة أو ملفات مستهدفة ناقصة أو أوامر تحقق ناقصة أو عندما لا يكون `status` العلوي `completed`
+- بعد التنفيذ، أكمل كل task-level spec review قبل quality review الخاصة بها، ثم أكمل final `artifacts/reviews/spec-compliance.md` قبل final `artifacts/reviews/code-quality.md`؛ قرارات task-level أو final review غير المحسومة تمنع الأرشفة
+- أثناء التنفيذ والمراجعة، حافظ على اتساق `artifacts/agents/worker-status.md` مع حالات implementer وspec reviewer وquality reviewer وcontroller
+- لا تدّعِ الاكتمال ما دامت أي حالة worker هي `PENDING` أو `NEEDS_CONTEXT` أو `BLOCKED`؛ ويجب أن تكون `controller_status` هي `DONE` قبل الأرشفة
 - اقرأ القواعد المعتمدة للمشروع قبل بدء التنفيذ
 - إذا كان `stitch_design_review` مفعلاً وكان `approval.json.preview_url` أو `submitted_at` فارغاً، فشغّل أولاً `ospec plugins run stitch <change-path>` لتوليد preview ثم أرسل الرابط للمستخدم
 - إذا كانت `.skillrc.plugins.stitch.project.project_id` مضبوطة مسبقاً، فيجب إعادة استخدام مشروع Stitch نفسه وعدم إنشاء مشروع جديد

package/assets/for-ai/ar/execution-protocol.md

@@ -9,22 +9,54 @@ tags: [ai, protocol, ospec]
 ## اقرأ هذا أولاً في كل مرة تدخل فيها إلى مشروع
 
 1. `.skillrc`
-2. `SKILL.index.json`
-3. `docs/project/naming-conventions.md`
-4. `docs/project/skill-conventions.md`
-5. `docs/project/workflow-conventions.md`
-6. ملفات change الحالية: `proposal.md / tasks.md / state.json / verification.md`
-7. إذا وُجد `stitch_design_review` فاقرأ `artifacts/stitch/approval.json`
-8. إذا كنت تحتاج إلى تعديل إعدادات Stitch أو Checkpoint المتعلقة بـ provider أو MCP أو المصادقة أو التثبيت أو التفعيل، فاقرأ أولاً مواصفة الإضافة المحلية المطابقة للغة الوثائق المعتمدة للمشروع، ولا تنتقل إلى لغة أخرى إلا إذا كان الملف المطابق غير موجود
+2. اقرأ `.ospec/session-brief.md` إذا كان موجودا؛ وإلا شغّل `ospec session [path]` في المشاريع المهيأة لإنشائه
+3. `SKILL.index.json`
+4. `docs/project/naming-conventions.md`
+5. `docs/project/skill-conventions.md`
+6. `docs/project/workflow-conventions.md`
+7. ملفات change الحالية: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
+8. إذا وُجد `stitch_design_review` فاقرأ `artifacts/stitch/approval.json`
+9. إذا كنت تحتاج إلى تعديل إعدادات Stitch أو Checkpoint المتعلقة بـ provider أو MCP أو المصادقة أو التثبيت أو التفعيل، فاقرأ أولاً مواصفة الإضافة المحلية المطابقة للغة الوثائق المعتمدة للمشروع، ولا تنتقل إلى لغة أخرى إلا إذا كان الملف المطابق غير موجود
 
 ## القواعد الإلزامية
 
-- حافظ على `proposal.md` و`tasks.md` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
+- حافظ على `proposal.md` و`design.md` و`implementation-plan.md` و`artifacts/agents/task-graph.json` و`artifacts/agents/bootstrap.md` و`artifacts/agents/handoff.md` و`artifacts/agents/document-review-dispatches/` و`artifacts/agents/workspace-status.md` و`artifacts/agents/worktree-plan.md` و`artifacts/agents/finish-plan.md` و`artifacts/agents/launch-plan.md` و`artifacts/agents/worker-runs/` و`artifacts/agents/review-runs/` و`artifacts/agents/retries/` و`artifacts/agents/blockers/` و`artifacts/agents/review-feedback-plan.md` و`tasks.md` و`artifacts/reviews/design-review.md` و`artifacts/reviews/implementation-plan-review.md` و`artifacts/reviews/spec-compliance.md` و`artifacts/reviews/code-quality.md` و`artifacts/agents/worker-status.md` و`artifacts/agents/debug-evidence.json` و`artifacts/agents/tdd-evidence.json` و`artifacts/agents/verification-evidence.json` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
 - لا تعِد كتابة وثائق change إلى الإنجليزية فقط لأن واجهة المنتج أو locale الموقع أو نص المتطلب يميل إلى الإنجليزية
 - إذا كانت وثائق change الحالية بالصينية بالفعل، فاستمر بالصينية ما لم تتطلب قواعد المشروع التحويل إلى الإنجليزية صراحةً
-- لا تتجاوز proposal/tasks وتنتقل مباشرة إلى التنفيذ
+- لا تتجاوز proposal/design/implementation-plan/task-graph/tasks/review-artifacts/worker-status وتدّعي الاكتمال مباشرة
+- عند الدخول إلى مشروع OSpec موجود، استخدم `ospec session [path]` لكتابة `.ospec/session-brief.json` و`.ospec/session-brief.md`؛ يسجل active changes وqueued changes وحالة queue-run وcache fingerprint والأوامر الآمنة التالية فقط، ولا يشغّل workers ولا tests ولا يفحص git ولا يؤرشف ولا يحرر source files
+- تعامل مع خطوات built-in quality policy المفعّلة مثل `tdd_cycle` و`root_cause_debug` و`verification_evidence` كـ `optional_steps` خاضعة لـ archive gate؛ غطّها في `tasks.md` و`verification.md` وملفات evidence المطابقة قبل closeout
+- أثناء تنفيذ change بمساعدة AI، أنشئ `design.md` أو حدّثه بعد `proposal.md` وقبل تعديل `implementation-plan.md` أو `tasks.md` أو الكود
+- لا تطرح إلا سؤال تصميم موجزاً واحداً عندما يغيّر القرار الناقص فعلياً البنية أو API أو البيانات أو UI أو المخاطر؛ وإلا فسجل الافتراضات في `design.md`
+- أنشئ `implementation-plan.md` أو حدّثه من `design.md`، مع الملفات المستهدفة والنتائج المتوقعة وأوامر التحقق والاعتماديات والعمل القابل للتوازي والتعارضات
+- اشتق `artifacts/agents/task-graph.json` من `implementation-plan.md`؛ ويجب أن تتضمن كل مهمة id والحالة والاعتماديات وسلامة التوازي والتعارضات والملفات المستهدفة وأوامر التحقق والنتيجة المتوقعة ودور worker
+- عند بدء أو استئناف active change واحد، استخدم `ospec execute bootstrap [changes/active/<change>]` لكتابة `artifacts/agents/bootstrap.json` و`artifacts/agents/bootstrap.md` مع project session brief snapshot، ثم اتبع الإجراء الآمن التالي المسجل فيه
+- عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files
+- قبل اشتقاق implementation tasks أو dispatch لها، استخدم `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` لإنشاء document reviewer packets تتضمن project session brief snapshot تحت `artifacts/agents/document-review-dispatches/` وتجهيز `artifacts/reviews/design-review.md` أو `artifacts/reviews/implementation-plan-review.md`؛ يجب اعتماد design review قبل dispatch لمراجعة implementation plan. هذا الأمر يسجل artifacts فقط ولا يشغّل reviewers ولا أوامر shell ولا يزامن worker status ولا يعدّل source files
+- قبل توزيع عمل المهام، استخدم `ospec execute status [changes/active/<change>]` أو `ospec execute next [changes/active/<change>]` لفحص حالة controller والمهام التالية الآمنة
+- قبل handoff إلى worker استخدم `ospec execute workspace [changes/active/<change>]` لكتابة `artifacts/agents/workspace-status.json` و`artifacts/agents/workspace-status.md`؛ إذا كانت الحالة `needs_isolation`، نظّف workspace أو انقل العمل إلى git worktree معزول قبل parallel dispatch
+- قبل إنشاء git worktree معزول، استخدم `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` لكتابة `artifacts/agents/worktree-plan.json` و`artifacts/agents/worktree-plan.md`؛ هذا الأمر يسجل خطة تحضير فقط ولا يشغّل `git worktree add`
+- قبل الإغلاق النهائي، استخدم `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` لكتابة `artifacts/agents/finish-plan.json` و`artifacts/agents/finish-plan.md`؛ هذا الأمر يسجل الجاهزية ونص الأوامر فقط ولا يشغل finalize أو archive أو push أو merge أو حذف worktree
+- استخدم `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` لإنشاء batch آمن للتوازي من worker packets و`artifacts/agents/execution-session.json`؛ يتضمن كل packet project session brief snapshot وworker profile يوضح capability tier وrecommended target وtarget tool mapping وrationale وrequired behavior. استخدم `ospec execute complete <task-id> ...` لتسجيل نتائج worker. استخدم `--task` لمهمة واحدة صريحة و`--limit` لتحديد حجم dispatch batch. تزامن هذه الأوامر أيضا `artifacts/agents/worker-status.md`، وتحدّث OSpec artifacts فقط ولا تشغّل workers خارجيين؛ عندما تكون النتيجة `NEEDS_CONTEXT` أو `BLOCKED` يكتب `complete` ملفات blocker escalation تحت `artifacts/agents/blockers/`
+- بعد dispatch، استخدم `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` لكتابة native agent launch plan؛ يوجه controlling AI إلى آلية agent الأصلية في harness الحالي: Codex/GPT يستخدم `spawn_agent`/`wait_agent`/`close_agent`، وClaude Code يستخدم Task، وGemini يستخدم `@generalist`، وOpenCode يستخدم `@mention`. هذا الأمر لا يشغّل workers ولا أوامر shell بنفسه
+- default multi-worker execution هو current-harness native subagents: أنشئ safe packets عبر `ospec execute dispatch`، اقرأ `launch-plan.md`، ثم dispatch native worker agent لكل packet آمن، وسجل النتيجة عبر `ospec execute complete`
+- استخدم `ospec execute orchestrate [changes/active/<change>] --command "..."` فقط كـ final CLI fallback عندما لا يدعم harness الحالي native subagents؛ fallback mode يرندر explicit command template ويشغّل worker commands بالتوازي ويسجل `artifacts/agents/orchestration-runs/`
+- استخدم `--run --command` مع `ospec execute launch ... --run --command "..."` فقط كـ single-worker CLI fallback عندما لا تتوفر native subagents أو يتم تجاوزها صراحة؛ ثم استخدم `ospec execute collect ...` لتسجيل fallback task result. بعد إصلاح blocked أو needs-context أو failed work استخدم `ospec execute retry` لإعادة dispatch
+- بعد اكتمال كل worker task، استخدم `ospec execute review [changes/active/<change>] --task <task-id> --stage spec` ثم `--stage quality` لإنشاء task-level reviewer handoff packets. تحفظ قرارات task-level داخل `artifacts/reviews/tasks/<task-id>/` وتبقى المهام التابعة محجوبة حتى اعتماد المراجعتين
+- بعد اعتماد كل task-level reviews واكتمال task graph، استخدم `ospec execute review [changes/active/<change>] [--stage spec|quality]` من دون `--task` لإنشاء final whole-change reviewer handoff packets داخل `artifacts/agents/review-dispatches/`؛ لا توزّع final quality review قبل اعتماد final spec review
+- لا يشغّل OSpec local reviewer command إلا عند استخدام `ospec execute review ... --run --command "..."` صراحة؛ يسجل ذلك `artifacts/agents/review-runs/` ويمكنه كتابة review decision عند تمرير `--decision`
+- بعد أن يحتوي review artifact على قرار غير `PENDING`، استخدم `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` لكتابة `artifacts/agents/review-feedback-plan.json` و`artifacts/agents/review-feedback-plan.md`؛ حدد accept أو revise أو clarify أو blocked قبل dispatch عمل إضافي
+- عندما يكون debugging جزءا من change، استخدم `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` لتسجيل `artifacts/agents/debug-evidence.json`؛ تعني `CONFIRMED` عزل root cause، وتعني `FIXED` إصلاحا متحققا، وتؤدي `BLOCKED` إلى فشل verify
+- بعد تشغيل focused tests، استخدم `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` لتسجيل `artifacts/agents/tdd-evidence.json`؛ عادة يسجل red الاختبار المتوقع فشله، بينما يجب أن تسجل green/refactor نتيجة ناجحة
+- بعد تشغيل project verification commands حديثة، استخدم `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` لتسجيل `artifacts/agents/verification-evidence.json`؛ لا تدّعِ الاكتمال بمجرد ملخص داخل المحادثة
+- بعد تعديل task graph أو execution session أو review artifacts أو debug evidence أو verification checklist يدويا، استخدم `ospec execute sync [changes/active/<change>]` لإعادة بناء `artifacts/agents/worker-status.md`
+- يجب اشتقاق `tasks.md` من `artifacts/agents/task-graph.json`؛ وإذا كانت المهام موجودة لكن وثائقها السابقة ما زالت قوالب، فحدّث الوثائق السابقة أولاً ثم وائم المهام معها
+- لا تؤرشف عندما يحتوي `artifacts/agents/task-graph.json` على حالات مهام غير محسومة أو اعتماديات غير صالحة أو تفاصيل تنفيذ ناقصة أو عندما لا يكون `status` العلوي `completed`
+- أكمل كل task-level spec review قبل quality review الخاصة بها، ثم أكمل final `artifacts/reviews/spec-compliance.md` قبل final `artifacts/reviews/code-quality.md`؛ قرارات task-level أو final review غير المحسومة تمنع الأرشفة
+- أثناء التنفيذ والمراجعة، حافظ على اتساق `artifacts/agents/worker-status.md` مع حالات implementer وspec reviewer وquality reviewer وcontroller
+- لا تعتبر change مكتملة ما دامت أي حالة worker هي `PENDING` أو `NEEDS_CONTEXT` أو `BLOCKED`؛ ويجب أن تكون `controller_status` هي `DONE` قبل الأرشفة
 - استخدم `state.json` كمصدر الحقيقة لحالة التنفيذ
-- يجب أن تظهر optional steps المفعلة في `tasks.md` و`verification.md`
+- يجب أن تظهر optional steps المفعلة في `artifacts/agents/task-graph.json` و`tasks.md` و`verification.md`
 - إذا كان `stitch_design_review` مفعلاً وكان `approval.json.preview_url` أو `submitted_at` فارغاً، فشغّل أولاً `ospec plugins run stitch <change-path>` لإرسال preview
 - يجب أن تفرض مراجعة تصميم Stitch تخطيطاً canonical واحداً لكل route، ويجب تصنيف الشاشات غير canonical على أنها `archive / old / exploration`
 - في متغيرات الثيم `light/dark` حافظ على التخطيط canonical نفسه وحوّل الثيم البصري فقط من دون إعادة ترتيب الوحدات أو نقل CTA أو تغيير البنية

package/assets/for-ai/en-US/ai-guide.md

@@ -22,10 +22,37 @@ This document is the project-adopted AI guide copied from the OSpec mother spec.
 
 ## Required Behavior
 
-- Follow the project-adopted document language for `proposal.md`, `tasks.md`, `verification.md`, and `review.md`
+- Follow the project-adopted document language for `proposal.md`, `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, `artifacts/agents/bootstrap.md`, `artifacts/agents/handoff.md`, `artifacts/agents/document-review-dispatches/`, `artifacts/agents/workspace-status.md`, `artifacts/agents/worktree-plan.md`, `artifacts/agents/finish-plan.md`, `artifacts/agents/launch-plan.md`, `artifacts/agents/worker-runs/`, `artifacts/agents/review-runs/`, `artifacts/agents/retries/`, `artifacts/agents/blockers/`, `artifacts/agents/review-feedback-plan.md`, `tasks.md`, `artifacts/reviews/design-review.md`, `artifacts/reviews/implementation-plan-review.md`, `artifacts/reviews/spec-compliance.md`, `artifacts/reviews/code-quality.md`, `artifacts/agents/worker-status.md`, `artifacts/agents/debug-evidence.json`, `artifacts/agents/tdd-evidence.json`, `artifacts/agents/verification-evidence.json`, `verification.md`, and `review.md`
 - Do not infer change-document language from product copy, default site locale, or an "English-first" business requirement alone
 - If the project-adopted protocol is Chinese or the current change docs are already Chinese, keep the change docs in Chinese unless the project rules explicitly switch them to English
 - Use the index to locate knowledge before reading target files
+- When entering an existing OSpec project, run `ospec session [path]` to write `.ospec/session-brief.json` and `.ospec/session-brief.md` with active change, queued change, queue-run, cache fingerprint, and safe next command context; this project entry brief does not replace active-change `ospec execute bootstrap`. Use `ospec session hook [path]` only to write optional harness startup hook artifacts
+- Use `ospec brainstorm [path] --topic "..."` only for optional pre-change exploration artifacts; use `ospec plan [path] --change changes/active/<change>` only for optional plan drafts, and pass `--apply` only when updating `implementation-plan.md` deliberately
+- Treat activated built-in quality policy steps such as `tdd_cycle`, `root_cause_debug`, and `verification_evidence` as archive-gated `optional_steps`; cover them in `tasks.md`, `verification.md`, and matching evidence artifacts before closeout
+- In AI-assisted change execution, do not ask the user to hand-write `design.md` or `implementation-plan.md`; draft or update them from the requirement, `proposal.md`, and project context before deriving `artifacts/agents/task-graph.json`, editing `tasks.md`, or editing code
+- Ask at most one concise design question only when the missing decision materially changes architecture, API, data, UI, or risk; otherwise write assumptions into `design.md`
+- Keep `implementation-plan.md` derived from `design.md`, keep `artifacts/agents/task-graph.json` derived from `implementation-plan.md`, keep `tasks.md` derived from the task graph, and reconcile existing tasks after upstream docs are updated
+- When starting or resuming one active change, use `ospec execute bootstrap [changes/active/<change>]` to write `artifacts/agents/bootstrap.json` and `artifacts/agents/bootstrap.md` with the project session brief snapshot, then follow its next safe action; when an active dispatch is waiting, bootstrap recommends the matching `ospec execute launch ... --task ...` command
+- Use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules without launching workers or editing source files
+- Before deriving or dispatching implementation tasks, use `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` to create document reviewer packets with the project session brief snapshot under `artifacts/agents/document-review-dispatches/` plus `artifacts/reviews/design-review.md` or `artifacts/reviews/implementation-plan-review.md`; design review must be approved before implementation plan review
+- Use `ospec execute status [changes/active/<change>]` or `ospec execute next [changes/active/<change>]` when you need a controller view of ready, blocked, running, completed, and safe next task candidates
+- Before worker handoff, use `ospec execute workspace [changes/active/<change>]` to record git workspace safety; if status is `needs_isolation`, clean the workspace or move work into an isolated git worktree before parallel dispatch
+- Before creating an isolated worktree, use `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` to write `artifacts/agents/worktree-plan.json` and `artifacts/agents/worktree-plan.md`; plan mode does not run git. Use explicit `--create` to run `git worktree add`, and explicit `--cleanup` to run `git worktree remove`; both record `artifacts/agents/worktree-runs/`
+- Before final closeout, use `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` to write `artifacts/agents/finish-plan.json` and `artifacts/agents/finish-plan.md`; this command records readiness and command text only and does not finalize, archive, push, merge, or remove worktrees
+- Use `ospec execute dispatch` to create a parallel-safe batch of worker packets and `ospec execute complete` to record worker results when task-level execution needs durable handoff artifacts; each dispatch packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior; `complete` writes `artifacts/agents/blockers/` when the result is `NEEDS_CONTEXT` or `BLOCKED`; use `--task` for one explicit task and `--limit` to cap dispatch batch size; after each `DONE` or `DONE_WITH_CONCERNS` worker result, run task-level review with `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`, then `--stage quality`, before dispatching dependent work; after all task-level reviews complete, use `ospec execute review` without `--task` for final whole-change spec or quality reviewer packets; use `ospec execute feedback` after non-`PENDING` final review decisions to write `artifacts/agents/review-feedback-plan.md`; use `ospec execute sync` to rebuild `worker-status.md` after manual execution or review artifact edits
+- Use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` after dispatch to write the native agent launch plan; it tells the controlling AI how to use the current harness agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, and `@mention` for OpenCode). It does not start workers or edit source files by itself
+- Default to current-harness native subagents for multi-worker execution: create safe packets with `ospec execute dispatch`, inspect `launch-plan.md`, dispatch one native worker agent per safe packet, and record each result with `ospec execute complete`
+- Use `ospec execute orchestrate [changes/active/<change>] --command "..."` only as the final CLI fallback when native subagents are unavailable; fallback mode renders an explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, and collects results unless `--no-collect` is passed
+- Use explicit `--run --command` on `ospec execute launch ... --run --command "..."` only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; runs capture `artifacts/agents/worker-runs/`. Then use `ospec execute collect ...` to record the fallback task result. Use `ospec execute retry` to reopen corrected blocked, needs-context, or failed work with `artifacts/agents/retries/`; completed tasks require explicit `--force`
+- Use explicit `ospec execute review ... --run --command "..."` only when OSpec should run a local reviewer command; it captures `artifacts/agents/review-runs/` and can write the task-level or final review decision when `--decision` is provided
+- When debugging is part of the change, use `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` to record root-cause and fix evidence; it records evidence only and does not run shell commands
+- After focused test runs, use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` to record TDD cycle evidence; it records evidence only and does not run shell commands
+- After running fresh project checks, use `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` to record verification evidence; it records evidence only and does not run shell commands
+- `ospec execute doc-review` records artifacts only and does not launch reviewers, run shell commands, sync worker status, or edit source files; native subagent dispatch is done by the current AI harness, while shell commands run only for explicit worktree create/cleanup, fallback `launch --run --command`, `review --run --command`, or fallback `orchestrate` with an explicit command template
+- Do not archive while `artifacts/agents/task-graph.json` has unresolved task statuses, invalid dependencies, missing target files, missing verification commands, or top-level `status` other than `completed`
+- After implementation, every task-level spec review must complete before that task's quality review, and final `artifacts/reviews/spec-compliance.md` must complete before final `artifacts/reviews/code-quality.md`; unresolved task-level or final review decisions block archive
+- During implementation and review, keep `artifacts/agents/worker-status.md` aligned with implementer, spec reviewer, quality reviewer, and controller statuses
+- Do not claim completion while any worker status is `PENDING`, `NEEDS_CONTEXT`, or `BLOCKED`; the controller status must be `DONE` before archive
 - Read the project-adopted rules before implementation work
 - If `stitch_design_review` is active and `approval.json.preview_url` or `submitted_at` is empty, run `ospec plugins run stitch <change-path>` first to generate a preview, then send the preview URL to the user for review
 - If `.skillrc.plugins.stitch.project.project_id` is already set, you must reuse that exact Stitch project instead of creating a new one