OCX CLI

When performing a plan review, evaluate the following criteria:

1. Citation Quality

Ensure decisions reference sources using the ref:delegation-id format.

• Red Flags: Decisions table with empty or - in the Source column; claims like "industry standard" without citation; research tasks marked complete without → ref:id.

2. Completeness

• Goal: Must be specific and measurable (e.g., ✅ "Add JWT authentication with refresh token support" vs ❌ "Improve authentication").
• Phases: Must be logical and sequential.
• Edge Cases: Error handling and failure modes must be addressed.
• Context: Must include a Notes section and a Context & Decisions table.

3. Actionability

• Tasks: Must be specific, identifying exactly which file or component is affected (e.g., ✅ "Create src/auth/jwt.ts" vs ❌ "Set up the backend").
• Dependencies: Sequential tasks must show a clear logical order.
• Path: The implementation path must be obvious so a developer can start without clarification.

OCX uses a layering system for configuration. A Global Profile acts as a base, while a Local Config (in the current project directory) acts as an overlay. When both exist, the local configuration takes precedence over the global profile settings.

You can verify the resolution of these layers using the config show --origin command, which displays the sources used to resolve the current configuration.

# 1. Setup a global profile
$OCX_BIN profile rm work --global 2>/dev/null || true
$OCX_BIN profile add work --global

# 2. Configure the global profile with a registry
echo '{"model": "opencode/big-pickle", "registries": {"kit": {"url": "http://localhost:8788"}}}' > $XDG_CONFIG_HOME/opencode/profiles/work/ocx.jsonc

# 3. Initialize local project and set local profile overlay
cd /tmp/ocx-v2-test-project
test -f .opencode/ocx.jsonc || $OCX_BIN init
echo '{"profile": "work"}' > .opencode/ocx.jsonc

# 4. Verify layering
$OCX_BIN config show --origin

Because Mintlify does not support anchor-specific redirects, you must follow these strategies when moving content that contains anchors (headings, code blocks, or tables):

1. Preserve Anchor Types: Recreate heading anchors (e.g., #installation) in the new location. For large code anchors, consider moving them to a separate page.
2. Handle Anchor Changes: If an anchor must change:
   • Update all internal links to the new anchor.
   • Add a note at the old location pointing to the new location.
   • Optionally, keep the deprecated anchor as a hidden heading to prevent link breakage.
3. Best Practices:
   • Keep anchor IDs stable (e.g., ## Installation should always map to #installation).
   • Avoid changing heading text without updating all associated links.
   • Use explicit HTML anchors for maximum stability: <a name="stable-anchor"></a>.
   • Document anchor changes in migration commit messages.

OCX discovers instruction files using a specific hierarchy and a "first type wins" strategy.

Discovery Order (Low to High Priority)

1. Global: ~/.config/opencode/AGENTS.md (Always included)
2. Global Profile: ~/.config/opencode/profiles/<name>/AGENTS.md (Always included)
3. Local (Project): Files like ./AGENTS.md (Filtered by your exclude/include patterns)

The "First Type Wins" Strategy

OpenCode searches for specific file types in a strict order. Once a type is found, it stops looking for other types:

1. AGENTS.md: If any AGENTS.md is found (walking up from the current directory to the git root), OCX collects all AGENTS.md files and stops. It will completely ignore CLAUDE.md and CONTEXT.md files.
2. CLAUDE.md: If no AGENTS.md is found, it searches for CLAUDE.md. If found, it ignores CONTEXT.md.
3. CONTEXT.md: If no AGENTS.md or CLAUDE.md is found, it searches for CONTEXT.md (Note: This is deprecated).

Claude Code Fallback

If no global AGENTS.md exists, OCX checks ~/.claude/CLAUDE.md as a fallback. You can disable this by setting the environment variable OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1.