Orient

Flag Detection

Check if $ARGUMENTS contains special flags:

• --no-confirm: Skip both gates (scope and plan approval). Set NO_CONFIRM=true.
• --no-clarify: Skip clarification step. Set NO_CLARIFY=true.

Strip flags from the task description before passing to pipeline steps.

Step 1: Clarification and Scope Contract

Run the orient pipeline for clarification:

1. Run: node --import tsx/esm src/orient/run-orient.ts --project-root "$(pwd)" --task "{task}" --phase clarification
   • If --no-clarify was detected, add --no-clarify to the command.
2. Parse the JSON output. Store the taskSlug and outputDir for subsequent steps.
3. If needsClarification is true:
   • Present the questions to the user, grouped by topic (scope_boundary, convention_conflict, danger_zone, test_coverage).
   • Format each question with its context for the user to understand why it's being asked.
   • Collect answers from the user.
   • Run: node --import tsx/esm src/orient/run-orient.ts --project-root "$(pwd)" --task "{task}" --phase scope-contract --task-slug "{taskSlug}" --answers '{answersJSON}'
   • Parse the output to get the scopeContractPath.
4. If needsClarification is false:
   • Display: "Task is specific enough -- skipping clarification. Proceeding to research."
   • The scope contract was auto-generated. Read scopeContractPath from the clarification output's outputDir + /scope-contract.md.

Gate 1: Scope Approval

Read the scope contract file and present it to the user:

Scope Contract

{Display the scope contract contents: In Scope / Out of Scope / Affected Files table / Assumptions / Conventions in Scope / Risk Flags}

Approve this scope? [approve / edit / reject]

Handle the response:

• If approve: Display "APPROVED -- proceeding to research and planning." and continue to Step 2.
• If edit: Ask what to change, update the scope contract file, re-present the gate.
• If reject: Display "REJECTED -- returning to clarification with your feedback." Ask for feedback and restart Step 1 with the rejection reason appended to the task.

If NO_CONFIRM is true: skip this gate, display "Scope auto-approved (--no-confirm)." and continue.

Step 2: Research

1. Run: node --import tsx/esm src/orient/run-orient.ts --project-root "$(pwd)" --task "{task}" --phase research --task-slug "{taskSlug}"
2. Parse the JSON output.
3. If topicsResearched is greater than 0 and a researchPrompt is present:
   • Display: "## Researching..."
   • Display: "Found {topicsResearched} external libraries to research. Spawning research agent..."
   • Spawn a research sub-agent using the Agent tool:
     • Pass the researchPrompt as the agent's prompt.
     • The agent should have access to: Read, Bash (for running research commands).
     • Wait for the agent to complete.
     • The agent writes research findings to the execution directory.
   • Display: "Research complete."
4. If topicsResearched is 0:
   • Display: "All affected libraries are internal -- skipping external research. Proceeding to planning."

Step 3: Analysis and Planning

1. Display: "## Planning..."
2. Run: node --import tsx/esm src/orient/run-orient.ts --project-root "$(pwd)" --task "{task}" --phase analysis-and-planning --task-slug "{taskSlug}"
3. Parse the JSON output.
4. Analysis runs directly (graph operations, fast). Display the analysis summary:
   • "Analysis: {affectedFiles} affected files, {blastRadiusFiles} in blast radius, {conventionMatches} conventions, {testFiles} test files, {crossCommunityImpact} communities impacted."
5. The planner module prepares a planning prompt. Spawn a planner sub-agent:
   • Use the Agent tool with the plannerPrompt from the output.
   • The agent produces an execution plan with agent assignments.
   • Wait for the agent to complete.
6. The plan was validated automatically. Display the validation summary:
   • If validationResult.passed is true: "Plan validation: all {checks} checks passed."
   • If auto-fix was needed: "Plan validation: {autoFixAttempts} auto-fix attempt(s) applied."

Gate 2: Plan Approval

Read the execution plan from the planPath in the output and present it:

Execution Plan

{Display the plan contents: agents with wave assignments, execution order table, estimated changes, conventions, hybrid strategy rationale, validation status}

Approve this plan? [approve / edit / reject]

Handle the response:

• If approve: Display "APPROVED -- beginning execution." and continue to Step 4.
• If edit: Ask what to change. Allow task-level modifications: remove tasks, reorder priority, change file assignments, add constraints. Log removed tasks in the plan's "## Removed by User" section. Re-validate by re-running the analysis-and-planning phase. Re-present the gate.
• If reject: Display "REJECTED -- returning to scope contract." Return to Step 1's Gate 1.

If NO_CONFIRM is true: skip this gate, display "Plan auto-approved (--no-confirm)." and continue.

Step 4: Execution

Display: "## Executing..."

1. Run: node --import tsx/esm src/execution/run-execution.ts --project-root "$(pwd)" --task-slug "{taskSlug}" --plan-path "{planPath}"
2. The execution engine prepares agent invocations. Parse the JSON output.

For each wave in the execution plan:

• Display: "Executing wave {N}/{total}: [{agent names}]..."
• For each agent in the wave:
  • Read the agent's prepared invocation from the execution output.
  • Spawn the agent using the Agent tool with the prepared prompt, appropriate tool access (Read, Write, Edit, Bash, Glob, Grep), and timeout.
  • On completion: display "{agent-name} complete ({duration}s, {N} files)"
  • On failure: display "{agent-name} failed ({error}) -- retrying once..."
    • Retry with the same prompt plus error context appended.
    • If retry fails: display "{agent-name} failed after retry -- skipping + {N} dependents"
• After each wave completes, check for failed agents and skip their dependents in subsequent waves.

Step 5: Verification

Display: "## Verifying..."

After execution completes, run the verification pipeline:

1. Read config.yml to determine the agents.eval_judge.model value. This model will be used for the code review sub-agent (per D-25, code review is a judgment task similar to eval).

2. Run: node --import tsx/esm src/verify/run-verify.ts --project-root "$(pwd)" --task-slug "{taskSlug}" --task-description "{task}" --plan-path "{planPath}" --scope-contract-path "{scopeContractPath}" --phase static

3. Parse the JSON output. Check for dispatch requests on stderr.

4. If stderr contains {"type": "dispatch_review", "prompt": "..."}:

   • Spawn a code review sub-agent using the Agent tool with the prompt.
   • Per D-25: When invoking the Agent tool, use the model specified in agents.eval_judge.model from config.yml (e.g., if config says model: claude-sonnet-4-20250514, pass that as the model parameter). Code review is a judgment task and MUST use the eval_judge model, not the default model.
   • The sub-agent should have access to: Read (to examine files referenced in diff).
   • Wait for the sub-agent to return review findings as JSON.
   • Re-run static verify with findings injected (or note findings for the report).

5. Display static verify results:

   • Convention violations count
   • Blast radius: surprises and skips count
   • Code review findings count

6. Run: node --import tsx/esm src/verify/run-verify.ts --project-root "$(pwd)" --task-slug "{taskSlug}" --task-description "{task}" --phase runtime

7. Parse the JSON output. Check for dispatch requests on stderr.

8. If stderr contains {"type": "dispatch_smoke", "prompt": "..."}:

   • Spawn a smoke test sub-agent using the Agent tool with the prompt.
   • The sub-agent should have access to: Read, Write, Bash (to create and run temp test files).
   • Wait for the sub-agent to return smoke test code.
   • Note results for the report.

9. Display runtime verify results:

   • Build: PASS/FAIL
   • Unit Tests: {pass}/{total}
   • Integration Tests: {pass}/{total}
   • E2E: PASS/FAIL/SKIPPED
   • Auto-Smoke: {N} endpoints tested

10. The verify report has been written to .claude/codescope/reports/{taskSlug}-{date}.md.

11. Display: "Verification complete. Report written to {reportPath}."

12. Display: "Proceeding to evaluation... (Phase 6)"

Step 6: Evaluate, Gate, and Debug

After verification completes, evaluate the changes and run the debug loop if needed.

6a. Run Eval

Read config.yml to determine agents.eval_judge.model and eval.mode. Store {execution_dir} as .claude/codescope/execution/{taskSlug}.

Run the eval CLI to score changes on 4 criteria:

node --import tsx/esm src/eval/run-eval.ts \
  --task-slug "{task_slug}" \
  --project-root "{project_root}" \
  --report-path "{report_path}" \
  --scope-contract-path "{scope_contract_path}" \
  --plan-path "{plan_path}" \
  --coordination-path "{coordination_path}" \
  --research-path "{research_path}" \
  --execution-dir "{execution_dir}"

Display: ## Evaluating changes...

Capture stderr for dispatch requests. When you see {"type": "dispatch_eval", "prompt": "..."} on stderr, dispatch a sub-agent (Agent tool) with the eval_judge model from config to act as the LLM-as-judge evaluator. Pass the prompt from the dispatch request. Capture the agent's response (JSON findings array) and pass it back by re-running the eval CLI with the response.

Parse the stdout JSON result. Display: Eval complete: {N} findings ({errors} errors, {warnings} warnings, {info} info)

If result.overallStatus === "PASS", proceed to Step 7 (Learning Capture).

6b. User Gate

Read eval.mode from config.yml:

• interactive: Present findings to the user grouped by criterion using the format from the eval result. For each finding, ask: Action? [debug / ignore / defer]. Collect decisions.

  • debug: Add to debug list
  • ignore: Record ignore pattern in learnings.md (learning system will use this in future evals)
  • defer: Record as TODO in learnings.md with file:line context Display: Gate: {N} to debug, {N} ignored, {N} deferred

• auto-debug: Send all findings to debug agent. Display: {N} finding(s) -- all sent to debug agent automatically.

• auto-skip-minor: Auto-skip INFO findings, send WARN + ERROR to debug. Display: {N_skipped} INFO finding(s) auto-skipped. {N_debug} WARN + ERROR finding(s) sent to debug agent automatically.

If no findings selected for debug, proceed to Step 7 (Learning Capture).

6c. Debug Loop

Write the findings to debug to a temporary JSON file:

echo '{findings_json}' > {execution_dir}/debug-findings.json

Run the debug CLI:

node --import tsx/esm src/debug/run-debug.ts \
  --task-slug "{task_slug}" \
  --project-root "{project_root}" \
  --findings-path "{execution_dir}/debug-findings.json" \
  --scope-contract-path "{scope_contract_path}" \
  --plan-path "{plan_path}" \
  --coordination-path "{coordination_path}" \
  --report-path "{report_path}" \
  --max-cycles "{max_cycles}" \
  --execution-dir "{execution_dir}"

Display: ## Debug cycle {N}/{max}...

Handle stderr dispatch requests:

• {"type": "dispatch_fix", "prompt": "..."}: Dispatch a sub-agent (Agent tool) with the debug model from config. This agent fixes the code. It has full tool access: Read, Write, Edit, Bash, Glob, Grep, WebFetch, and CodeScope MCP tools (codescope_blast_radius, codescope_conventions, codescope_recall, codescope_search, Context7, WebSearch). Per DBUG-02.
• {"type": "dispatch_eval", "prompt": "..."}: Dispatch eval_judge agent for scoped re-eval.
• {"type": "dispatch_verify", "changedFiles": [...]}: Run scoped re-verify on just the changed files.
• {"type": "design_decision", "decision": {...}}: Present design decision to user with options. Display the finding, options with impacts. Get user's choice. Return the chosen option ID.

6d. Loop Termination

The debug CLI handles cycle counting internally (capped at eval.auto_debug_max_cycles from config, default 3).

After debug completes, check the result:

• If result.remaining.length === 0: All findings resolved. Display: All findings resolved after {N} cycle(s).
• If result.remaining.length > 0: Some findings remain. Display: Max debug cycles ({max}) reached. {remaining} finding(s) remain.
  • In interactive mode: ask user Action? [retry / ignore-all / defer-all]
  • In auto modes: log remaining findings and proceed

Proceed to Step 7 (Learning Capture).

Step 7: Learning Capture

After evaluation and debug complete, capture learnings from this pipeline run. Per D-02: runs regardless of whether debug was needed.

1. Check config: read learning.auto_capture from config.yml. If false, display "Learning capture disabled (learning.auto_capture=false). Skipping." and proceed to Step 8.

2. Run the learning capture CLI:

   node --import tsx/esm src/learning/run-learning-capture.ts \
     --project-root "$(pwd)" \
     --task-slug "{taskSlug}" \
     --scope-contract-path "{scopeContractPath}" \
     --plan-path "{planPath}" \
     --coordination-path "{execution_dir}/coordination.md" \
     --report-path "{reportPath}" \
     --execution-dir "{execution_dir}"
   

3. Capture stderr for dispatch requests. When you see {"type": "dispatch_learning", "prompt": "..."} on stderr:

   • Read config.yml to get agents.learning_synthesizer.model.
   • Spawn a learning synthesizer sub-agent using the Agent tool with the prompt from the dispatch request.
   • Use the model specified in agents.learning_synthesizer.model from config.yml.
   • The sub-agent should have access to: Read (to examine pipeline artifacts referenced in the prompt).
   • Wait for the sub-agent to return a JSON array of extracted learnings.
   • The run-learning-capture CLI handles persistence (addLearnings with decay, contradiction check, cap enforcement).

4. Parse the stdout JSON result.

   • If status === "skipped": display "Learning capture skipped ({reason})."
   • If status === "complete": display "Learning capture: {newLearnings} new learning(s) added, {contradicted} contradiction(s) flagged, {skipped} skipped (cap). Active: {capStatus}."
   • If status === "error": display "Learning capture failed: {error}. Pipeline results are still valid."

5. Proceed to Step 8 (Summary).

Step 8: Summary

After all waves, verification, and evaluation complete, display the execution summary:

Summary

Total: {duration}s | Files changed: {N} | Agents: {succeeded}/{total} | Verify: {errors} errors, {warnings} warnings | Eval: {eval_status}

If learning capture ran: | Learnings: +{newLearnings} new, {contradicted} contradicted, {capStatus} active

If there were failures, also display:

• List each failed agent with its error
• "Partial results are in your working tree as uncommitted changes. Review with git diff."
• "To retry failed tasks: /codescope:orient with the same task description."

Error Handling

• If any node --import tsx/esm command exits with code 1, parse the error JSON and display the error message to the user.
• If the graph database is not found, suggest running /codescope:bootstrap.
• If config.yml is missing, suggest running /codescope:onboard.
• If an agent spawn fails due to timeout, log the timeout and continue with the next agent.

Notes

• All artifacts are persisted to disk regardless of outcome (scope contract, plan, coordination log, summary) per D-16.
• The coordination log at .claude/codescope/execution/{taskSlug}/coordination.md provides a full audit trail.
• Plans are always written to .claude/codescope/plans/{taskSlug}.md even if rejected per D-16.
• The execution summary is written to .claude/codescope/execution/{taskSlug}/summary.md.