/orient - Session Orientation (MoE Task Execution Workflow)

5-step session orientation that combines project discovery, context search, agent discovery, invocation creation, and MoE orchestrated execution.

Skill: Uses moe-task-execution skill for the complete workflow.

Usage

# Full orientation with 5-step methodology (recommended)
/orient

# Quick orientation (git + stats only)
/orient --quick

# Deep orientation (includes semantic recall + agent discovery)
/orient --deep "topic"

# MoE mode (includes agent invocations for next tasks)
/orient --moe

# JSON output for programmatic use
/orient --json

The 5-Step Methodology

Step 0: Resolve Project Scope (ADR-159)

Auto-detect the current project from the working directory. This scopes all subsequent steps.

from scripts.core.scope import resolve_scope
scope = resolve_scope()  # Auto-detects from CWD / $CODITECT_PROJECT
# scope.project = "PILOT" or "CUST-avivatec-fpa" etc.

Step 1: Find Project Plan & Checkpoints

If project is detected, scope the search to that project's track files:

# Project-scoped (preferred when scope.project is set):
Glob("**/tracks/TRACK-*.md")           # Track files for current project
Glob("**/CHECKPOINT*.md")

# Legacy (when no project detected):
Glob("**/PILOT*.md")
Glob("**/CHECKPOINT*.md")

Step 2: Multi-Query Context Search

Pass --filter-project to scope queries to the current project:

/cxq --filter-project {scope.project} --recall "project-plan tasklist"
/cxq --filter-project {scope.project} --recent 200
/cxq --filter-project {scope.project} --since "1 day ago" --limit 50
/cxq --filter-project {scope.project} --decisions --limit 20

Step 3: Agent Discovery with /which

/which moe-agents orchestrator project-organizer
/which analyze pilot tasklist

Step 4: Create Invocations & Update Tasklist

- [ ] D.1.1: Task name
  - **Agent:** `Task(subagent_type="agent", prompt="...")`

Step 5: Execute with MoE Orchestration

Task(subagent_type="orchestrator", prompt="Execute Track D tasks per PILOT-PARALLEL-EXECUTION-PLAN.md")

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

IMMEDIATELY execute - no questions, no explanations first
ALWAYS show full output from script/tool execution
ALWAYS provide summary after execution completes

DO NOT:

Say "I don't need to take action" - you ALWAYS execute when invoked
Ask for confirmation unless requires_confirmation: true in frontmatter
Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

You are running the CODITECT session orientation to combat catastrophic forgetting.

Purpose: Help AI agents and users quickly understand:

Recent git activity (what changed)
Recent session activity (what was discussed)
Recent decisions (what was decided)
Current project state (what's the status)

Step 0a: Check for Updates (Always First)

python3 ~/.coditect/scripts/check-version.py --banner

This checks for available CODITECT updates (with 24-hour cache to avoid excessive network requests). If an update is available, displays:

Step 0b: License Validation (ADR-067)

python3 ~/.coditect/scripts/core/license_validator.py --json

Validates the CODITECT license and displays a status banner:

Active: 🔑 License: Active (X days remaining)
Warning: ⚠️ LICENSE EXPIRING SOON: X days remaining
Grace: ⚠️ LICENSE EXPIRED - Grace period active
Expired: ❌ LICENSE EXPIRED - Please renew
Revoked: ❌ LICENSE REVOKED - Contact support
Missing: 🔒 No license configured (pilot mode)

============================================================
  UPDATE AVAILABLE: v1.0.0 -> v1.1.0
  Bug fixes and performance improvements
  Run /update to get the latest version
============================================================

Step 0c: Quick Vacuum Sweep (ADR-178)

Run a quick orphan detection sweep (<2s) to surface abandoned tasks from dead sessions:

import sys
sys.path.insert(0, 'submodules/core/coditect-core')
try:
    from scripts.core.context_vacuum import ContextVacuum
    vacuum = ContextVacuum()
    report = vacuum.quick_sweep()
    if report.orphans:
        orphan_summary = vacuum.format_report(report, compact=True)
        # Display: "Orphaned Tasks: 2 (1 dead claim, 1 conflict)"
except Exception:
    pass  # Vacuum is optional, don't block orient

If orphans exist, display after operator alerts:

  ORPHANED TASKS: 2 (1 dead claim, 1 conflict)
  Run /vacuum for full analysis

Step 0d: Check Operator Alerts (ADR-173)

Check for unread operator alerts from the Inter-Session Message Bus. These indicate cross-session conflicts that need attention:

Step 0e: File Integrity Verification (ADR-182)

Run a quick read-only integrity check against the Zero Trust file integrity registry:

python3 "$CODITECT_CORE/scripts/file_integrity.py" --verify --json 2>/dev/null

If verification detects drift, display prominently:

============================================================
  INTEGRITY WARNING: {modified + missing} files changed since last scan
    agents/example.md  [MODIFIED]
    hooks/example.py   [DELETED]
  Run /integrity --scan to update or /integrity --diff for details
============================================================

If registry is empty (first run), display:

  INTEGRITY: No baseline. Run /integrity --baseline to initialize.

If all files match, display nothing (silent pass). The integrity check is <2s and read-only.

import os, sys
sys.path.insert(0, 'submodules/core/coditect-core')
try:
    from scripts.core.session_message_bus import get_session_message_bus
    bus = get_session_message_bus()
    current_session = f"claude-{os.getpid()}"
    alerts = bus.get_operator_alerts(unread_only=True, limit=10)
    unread = bus.get_unread(recipient_id=current_session, limit=10)
except Exception:
    alerts = []
    unread = []

If alerts exist, display prominently before continuing orientation:

============================================================
  OPERATOR ALERTS: {len(alerts)} unread
  [CRITICAL] project_conflict: codex-41200 also on PILOT
  [HIGH] cwd_overlap: codex-41200 in same directory
  Run /session-status --alerts for full details
============================================================

If unread directed messages exist:

  UNREAD MESSAGES: {len(unread)} from other sessions
  Run /session-status --unread to view

Priority labels: 0=routine, 1=normal, 2=HIGH, 3=CRITICAL

Execute the orientation script:

python3 scripts/session-orient.py $ARGS

If script doesn't exist yet, run these commands manually:

# Check for updates first
python3 ~/.coditect/scripts/check-version.py --banner 2>/dev/null

echo "=== Git History (Last 10 Commits) ==="
git log --oneline -10

echo ""
echo "=== Today's Changes ==="
git log --oneline --since="1 day ago"

echo ""
echo "=== Knowledge Base Stats ==="
python3 scripts/context-db.py --knowledge-stats 2>/dev/null || echo "Run /cxq --index first"

echo ""
echo "=== Recent Decisions (Last 10) ==="
python3 scripts/context-db.py --decisions --limit 10 2>/dev/null || echo "Run /cxq --extract first"

echo ""
echo "=== Recent Messages (Last 20) ==="
python3 scripts/context-db.py --recent 20 2>/dev/null || echo "Run /cxq --index first"

Step 0f: Dashboard Refresh (ADR-170)

For dashboard-enabled projects, trigger a full Phase 1 + Phase 2 refresh at session start. This ensures the executive dashboard has current metrics and narrative when work begins.

import sys
sys.path.insert(0, 'submodules/core/coditect-core')
from scripts.core.dashboard_registry import is_dashboard_enabled, get_dashboard_config

# Check if current project has dashboard enabled
if PROJECT_ID and is_dashboard_enabled(PROJECT_ID):
    config = get_dashboard_config(PROJECT_ID)
    if config:
        # Phase 1: Node.js metrics (0 tokens, <1s)
        # node <project_root>/<generator_script> --project <PROJECT_ID>
        # Phase 2: AI narrative (~12K tokens)
        # Invoke /project-status --update for the project
        pass

Display in orientation output:

📊 Dashboard: Refreshed for BIO-QMS (Phase 1: 0.8s, Phase 2: 12K tokens)

If dashboard is not enabled for the project, skip silently (no output).

What Gets Displayed

Quick Mode (--quick)

Section	Source	Purpose
Update check	`check-version.py`	Available updates
Operator alerts	`bus.get_operator_alerts()`	Cross-session conflicts (ADR-173)
Git commits	`git log -10`	What code changed
Git status	`git status --short`	Uncommitted work
Component counts	`config/component-counts.json`	Framework inventory

Full Mode (default)

Section	Source	Purpose
Update check	`check-version.py`	Available updates
Operator alerts	`bus.get_operator_alerts()`	Cross-session conflicts (ADR-173)
Unread messages	`bus.get_unread()`	Directed messages from other sessions
Git commits	`git log -10`	What code changed
Git status	`git status --short`	Uncommitted work
Knowledge stats	`/cxq --knowledge-stats`	Memory system health
Recent decisions	`/cxq --decisions --limit 10`	What was decided
Recent messages	`/cxq --recent 20`	What was discussed
Task progress	`TASKLIST.md`	Completed vs pending
Dashboard refresh	`dashboard_registry.py`	Phase 1+2 for dashboard-enabled projects (ADR-170)

Deep Mode (--deep "topic")

All of Full Mode plus:

Section	Source	Purpose
Semantic recall	`/cxq --recall "topic"`	Relevant past context
Related patterns	`/cxq --patterns`	Reusable code
Related errors	`/cxq --errors`	Known solutions

Examples

Morning Session Start

/orient

Output:

🧠 CODITECT Session Orientation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️ OPERATOR ALERTS: 1 unread
  [CRITICAL] project_conflict: codex-41200 also on PILOT
  Run /session-status --alerts for details

📜 Recent Git Activity (Last 10):
  abc1234 feat: Add anti-forgetting memory system
  def5678 docs: Update CHANGELOG.md
  ...

📊 Knowledge Base Stats:
  Messages: 68,597
  Decisions: 2,598
  Patterns: 12,604
  Errors: 259
  Embeddings: 100% coverage

🎯 Recent Decisions:
  [architecture] Use SQLite with FTS5 for search
  [technology] Sentence-transformers for embeddings
  ...

💬 Recent Activity (Last 20 messages):
  [user] implement the anti-forgetting system
  [assistant] I'll create the /cx and /cxq commands...
  ...

✅ Task Progress: 342/530 (65%)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Ready to continue work!

Deep Orientation for Specific Topic

/orient --deep "authentication"

Adds relevant context about authentication from past sessions.

Integration with Workflows

Recommended Daily Workflow

# 1. Start session with orientation
/orient

# 2. Do your work...

# 3. End session with capture
/cx

Automated via Hook

Add to ~/.claude/settings.json for automatic orientation:

{
  "hooks": {
    "PreToolUse": [{
      "command": "python3 scripts/session-orient.py --quick",
      "timeout": 5000
    }]
  }
}

Benefits

Context Continuity - Know what happened in previous sessions
Decision Consistency - See past decisions before making new ones
Error Prevention - Recall past solutions to similar problems
Time Savings - No manual searching through history
Anti-Forgetting - Combat catastrophic forgetting in AI assistants

Command	Purpose
`/cx`	Capture session context
`/cxq`	Query context database
`/cxq --recall`	RAG retrieval for topic
`/cxq --bus-feed`	Session activity timeline
`/session-status`	Cross-LLM session dashboard
`/session-status --alerts`	View operator alerts in detail
`/session-message`	Send directed messages to other sessions
`/integrity`	File integrity verification (ADR-182)
`/which`	Agent discovery and recommendations
`/agent`	CODITECT agent invocation

Skill	Purpose
`moe-task-execution`	Complete MoE workflow pattern
`session-analysis`	Session indexing and tracking

Agent	Purpose
`orchestrator`	Multi-agent coordination
`project-organizer`	File/directory organization
`moe-content-classifier`	Document classification

Success Output

When orientation completes successfully:

✅ COMMAND COMPLETE: /orient
Project plan: Found
Recent context: Loaded
Agent discovery: Complete
Ready for task execution

Completion Checklist

Before marking complete:

Failure Indicators

This command has FAILED if:

❌ Not in a git repository
❌ Context database unavailable
❌ No project plan found
❌ Script execution error

When NOT to Use

Do NOT use when:

Already oriented this session
Quick single-command task
Context irrelevant to task

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip orientation	Context loss	Run at session start
Ignore decisions	Inconsistent choices	Review past decisions
Orient repeatedly	Wasted time	Once per session

Principles

This command embodies:

#9 Based on Facts - Uses actual project data
#10 Research When in Doubt - Searches past context
#3 Complete Execution - Full 5-step methodology

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Script: scripts/session-orient.py Skill: skills/moe-task-execution/SKILL.md Databases (ADR-118):

context-storage/org.db (Tier 2: decisions, skill_learnings)
context-storage/sessions.db (Tier 3: messages, tool_analytics)
context-storage/messaging.db (ADR-160/173: operator alerts, lifecycle events) Version: 3.2.0 Last Updated: 2026-02-16 Author: Claude Opus 4.6 Track: H (Framework Autonomy) Task: H.13.9

Changelog:

v3.2.0 - ADR-170: Step 0f dashboard refresh for dashboard-enabled projects (Phase 1 metrics + Phase 2 narrative at session start)
v3.1.0 - ADR-182: Step 0e file integrity verification, /integrity in related commands
v3.0.0 - ADR-173 v2: Step 0c operator alert surfacing, unread message check, /session-status + /session-message in related commands
v2.1.0 - MoE task execution 5-step methodology, project scope (ADR-159)
v2.0.0 - License validation (ADR-067), update check
v1.0.0 - Basic session orientation

Usage​

The 5-Step Methodology​

Step 0: Resolve Project Scope (ADR-159)​

Step 1: Find Project Plan & Checkpoints​

Step 2: Multi-Query Context Search​

Step 3: Agent Discovery with /which​

Step 4: Create Invocations & Update Tasklist​

Step 5: Execute with MoE Orchestration​

System Prompt​

System Prompt​

What Gets Displayed​

Quick Mode (--quick)​

Full Mode (default)​

Deep Mode (--deep "topic")​

Examples​

Morning Session Start​

Deep Orientation for Specific Topic​

Integration with Workflows​

Recommended Daily Workflow​

Automated via Hook​

Benefits​

Related Commands​

Related Skills​

Related Agents​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Usage

The 5-Step Methodology

Step 0: Resolve Project Scope (ADR-159)

Step 1: Find Project Plan & Checkpoints

Step 2: Multi-Query Context Search

Step 3: Agent Discovery with /which

Step 4: Create Invocations & Update Tasklist

Step 5: Execute with MoE Orchestration

System Prompt

System Prompt

What Gets Displayed

Quick Mode (--quick)

Full Mode (default)

Deep Mode (--deep "topic")

Examples

Morning Session Start

Deep Orientation for Specific Topic

Integration with Workflows

Recommended Daily Workflow

Automated via Hook

Benefits

Related Commands

Related Skills

Related Agents

Success Output

Completion Checklist

Failure Indicators

When NOT to Use

Anti-Patterns (Avoid)

Principles