# shellcheck shell=bash usage() { cat >&2 < [--workers worker1,worker2] [--lead-provider ] [--lead-model ] [--worker-model provider=model,...] [--report-writer-provider ] [--report-writer-model ] [--lead-runtime ] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] --project-id [--project-root ] --task-group --task-id --task-brief [--directive ] [--fix-cycle ] summary: $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle. The standalone launcher defaults to an interactive Claude session; in-host skills keep the current registered host session as the native lead. The stable task identifier is composed of project-id + task-group + task-id. Skills, worker agents, and the codex wrapper are installed once per user under ~/.claude and ~/.okstra by scripts/okstra-install.sh. The user's settings.json is never modified; okstra-ctl prepare provisions the project's .claude/settings.local.json as a symlink to ~/.okstra/templates/settings.local.json, which Claude Code auto-loads. required arguments: --project-id Globally unique project ID. Example: sample-project-v2-api. Each project is registered at /.okstra/project.json on first run; subsequent runs verify the projectId there matches. --task-group Logical task group. Example: backend-api, bugfix, linear-8858 --task-id Stable task identifier inside the task group. Example: login-error-analysis --task-type Task type. Also selects prompts/profiles/.md --task-brief Task brief file path. Relative paths are resolved against the target project root. optional arguments: --project-root Absolute path to the target project root. Resolution order when omitted: (1) ancestor of cwd that contains .okstra/project.json, (2) \`git rev-parse --show-toplevel\` from cwd. Errors out if neither resolves. --directive Free-form user-supplied directive carried into the run as a "## Directive" section inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule-gen) may treat this as a hard hint that overrides default heuristics. Use to express intent like "render a Gantt even with single XL task" or "emphasize rollout risk". --fix-cycle When re-entering an entry phase (requirements-discovery / error-analysis / implementation-planning) on a task that already completed through release-handoff, decide whether to record this work as a bug-fix cycle. 'yes' opens a new cycle and attaches this run to it; 'no' or omitted records nothing. --clarification-response Low-level path argument. Carries an edited final-report.md from a prior requirements-discovery or error-analysis run into this run as Section 0 input so the lead can reconcile each prior Q*. Use this for scripted or CI runs where the answer file is already prepared. Interactive users should prefer --resume-clarification, which wraps this flag. --selected-direction Path to a validated implementation-option-selection final report. Required for a new implementation-planning run. Existing planning reruns continue to use --clarification-response with their prior report. --approved-plan Path to the approved final-report.md from a prior implementation-planning run. Required when --task-type=implementation; that report's record (final-report-*.data.json) MUST carry \`frontmatter.approved: true\`. --approve Treat the user's CLI invocation itself as the plan-approval signal. Only meaningful together with --approved-plan and --task-type=implementation. Sets \`frontmatter.approved\` to true on the report record and re-renders the full reading copy from it; editing that reading copy does not approve the plan. Use this for scripted/CI flows or when you want a single command to both approve and launch the next phase. --implementation-option Name of the Option Candidate the user chose from the implementation-planning final-report. Only meaningful together with --approved-plan and --task-type=implementation. The runtime records as \`frontmatter.implementationOption\` on the report record and re-renders the full reading copy from it. When omitted, the implementation run falls back to the plan's \`Recommended Option\`. --qa-waiver : User-recorded waiver for a blocking local io conformance gate. Only meaningful with --task-type=implementation; prepare records the verbatim reason in the matching manifest entry. External DB/HTTP/service QA is advisory and normally needs no waiver. --no-plan-verification Disable the Phase 6 plan-body verification round that runs after the report-writer authors the implementation-planning draft. Default: enabled. Only meaningful with --task-type=implementation-planning; ignored for other task types. When disabled the top-of-report \`User Approval Request\` checkbox renders unconditionally (legacy behaviour). Use this for fast iteration; the default is recommended for handoff-ready plans. --task-key Shorthand for --project-id/--task-group/--task-id. When the matching task-manifest.json exists, brief-path and task-type are auto-filled from it (taskBriefPath, and workflow.nextRecommendedPhase.phase only while its status is \`ready\`). Explicit flags always win. options: --render-only Render the host-neutral lead handoff prompt only. Do not launch a session. --resume-clarification Interactive convenience mode that wraps --clarification-response. Locates the latest requirements-discovery or error-analysis final-report-*.md for the given task-key, opens it in \$EDITOR so you can fill Section 5, then re-execs okstra with --clarification-response set to the edited file. Use this for hand-driven turn-arounds. Requires task identity flags (--project-id/--task-group/--task-id or --task-key). Mutually exclusive with --clarification-response and --approved-plan. --yes Skip interactive prompting and confirmation. Requires all required arguments. --workers Comma-separated worker list for this run. Default: claude,codex,report-writer. Optional read-only providers: antigravity, grok, kimi. --lead-provider Compatibility assertion for the lead assignment. Must match the selected host adapter's native provider. --lead-model Model for the host-native lead. Default: the selected provider's lead policy. --claude-model Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or opus --codex-model Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol --antigravity-model Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro --worker-model Provider-qualified worker override CSV, e.g. grok=grok-4.5,kimi=kimi-k3. --report-writer-provider Provider for report writer. Supported: claude, codex. Default: claude. --report-writer-model Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or sonnet --lead-runtime Registered host ID or alias. Default: claude-code. In-host runs use current-session; terminal launch uses spawn-process readiness. --executor Provider that performs the Executor role during --task-type=implementation. One of: claude | codex | antigravity | grok | kimi. Default: OKSTRA_DEFAULT_EXECUTOR or claude. The Executor is the only worker allowed to mutate project files; the other providers are dispatched as read-only verifiers regardless of this selection. Has no effect on other task types. --critic Provider for the opt-in Phase 5.6 critic pass (coverage gaps / acceptance devil's-advocate). One of: off | claude | codex | antigravity | grok | kimi. Default: off. --related-tasks Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui --work-category Work-category classification for this task. One of: bugfix | feature | refactor | ops | improvement | unknown. Defaults to 'unknown' when omitted. Use this when the lifecycle skipped --task-type=requirements-discovery (where work-category would otherwise be inferred). --base-ref Git ref (branch name, tag, or commit SHA) used as the base of the per-task worktree on the FIRST phase of a task-key. Required on first phase; ignored on subsequent phases (the registered worktree is reused). Typical values mirror the release-handoff PR-base picker: main | dev | staging | preprod | prod | any local ref. --task-type Set the task purpose for this run and select the matching profile file. -h, --help Show this help. model defaults: Host-native lead: provider policy (Claude default: opus; Codex default: gpt-5.6-sol) Report writer worker: selected provider policy (Claude default: sonnet) Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro Grok worker: grok-4.6 Kimi worker: kimi-k2.7-code (analyser) or kimi-k3 (critic) Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity | grok | kimi) output: Stable task bundles are stored under: /.okstra/tasks/// Per-run history is stored under: /.okstra/tasks///runs/ Inside each run date folder, artifacts are grouped by type under: manifests/, state/, prompts/, reports/, status/, sessions/, worker-results/ project-level discovery: Latest $DISPLAY_TOOL_NAME task pointer: /.okstra/discovery/latest-task.json interactive behavior: If required arguments are missing and stdin is interactive, $DISPLAY_TOOL_NAME prompts for them. Before execution, interactive runs show the collected input summary and continue only when you enter y or yes. If --yes is provided, $DISPLAY_TOOL_NAME skips prompting and confirmation and requires all required arguments up front. USAGE_EOF }