Implementation Plan: Add Specialized Codex Luna/max Codebase Exploration Agents

[Trecek]

Summary

Implement issue #4443 as one ordered plan with a hard Phase A capability gate followed by the deterministic exploration substrate, two terminal explorer roles, backend-neutral dispatch, telemetry, first-wave adoption, and the complete architecture, experiment, and visualization lens migrations. The implementation keeps L1 backend selection explicit, fixes both Codex roles to gpt-5.6-luna with max reasoning and a verified read-only boundary, and preserves all existing specialist synthesis authority and explicit exclusions.

Requirements

Agent family and tracing

• REQ-AGT-001: Ship at least two materially different read-only leaf behaviors: structural/semantic navigation and repository/artifact/consumer profiling; exact registered names are selected during the Phase 0 spike.
• REQ-AGT-002: Implement symbol/flow tracing as one shared deterministic substrate with one canonical relationship, method-provenance, completeness, and output contract. Leaf prompts must not duplicate that authority.
• REQ-AGT-003: Explorers must be bounded, evidence-returning agents; parents own synthesis, fan-out, and artifact writes. Their runtime must prove that selected read operations succeed while source/file/Git mutation is denied, and target code must not be imported or executed by default.
• REQ-AGT-004: Shared task/output contracts must distinguish facts, inferences, unknowns, edge provenance, searched scope, negative evidence, conflicts, truncation, stale inputs, and unresolved frontier.
• REQ-AGT-005: One typed router-plan object must classify requested and newly discovered relationship/frontier types, parallelize only disjoint frontiers, preserve dependency-ordered traces as sequential work, and merge evidence by stable node/edge identity without hiding conflicts.
• REQ-AGT-006: Shipped role-name collisions with ambient/profile agent definitions must fail preflight, and runtime evidence must bind to the materialized role-definition digest.

Profiles, graph, and completeness

• REQ-PRF-001: Separate a language-neutral repository/artifact core, a generic Python semantic profile, and a versioned AutoSkillit overlay; the overlay adds repository conventions and extractors without copying generic traversal logic, and unsupported language semantics degrade visibly while core artifact queries remain available.
• REQ-PRF-002: AutoSkillit activation requires exact normalized github.com/TalonT-Org/AutoSkillit identity from usable configured remotes, ignoring caller/prompt hints. Only when no usable remote exists may a fixed-path, versioned repository-owned declaration plus content digest and validated marker quorum activate it. Define case, fork, and conflicting-remote behavior; basename, package name, substring host matches, prompt text, or one marker file alone must not activate it.
• REQ-PRF-003: Every migrated AutoSkillit codebase-discovery call site must select at least one AutoSkillit-aware explorer automatically, while the same call site uses only generic profiles for unrelated repositories.
• REQ-PRF-004: Record common-repository identity, concrete worktree, HEAD, index-tree digest, scoped working-tree digest (untracked bytes, modes/symlinks, and ignore policy), activation evidence, and profile/schema/collector-manifest versions; ambiguous identity must fall back visibly to the generic profile.
• REQ-PRF-005: A non-Python fixture must prove that language-neutral artifact/repository queries remain functional and that Python-only collectors report unsupported without false completeness.
• REQ-GRF-001: Define a versioned typed relationship schema covering files/modules/symbols/fields, imports/re-exports/calls, nominal inheritance, structural protocol conformance, runtime wiring, dynamic imports, aliases, patches, overrides/shadowing, registries/configuration, tests/fixtures, skills/agents/recipes, architecture constraints, and generated/source-of-truth artifacts.
• REQ-GRF-002: Every material edge must record origin/target identity, precise evidence, relationship type, method provenance, extractor/index version, full snapshot identity, searched scope, and query-specific completeness/uncertainty. Preserve contradictions for parent synthesis.
• REQ-GRF-003: Generated-artifact edges must record generator identity/version, authoritative inputs, output digest, freshness, and any command/runtime dependency. Observational test edges must record run identity, selected/deselected/skipped status, xdist mode, and collection/setup/call/teardown phase where available.
• REQ-CMP-001: Maintain a bounded frontier/evidence ledger; stopping requires the requested query plan to complete or the unresolved frontier and residual miss risk to be reported explicitly.
• REQ-CMP-002: Exhaustive/closed-world claims are allowed only for a stated scope whose required collectors completed without stale indexes, unsupported dynamics, truncation, or unresolved contradiction.
• REQ-CMP-003: Pagination or grouped summaries may bound high-fan-out results, but must preserve exceptions, contradictions, unresolved items, and a continuation cursor/digest.
• REQ-CMP-004: Every collector reports complete, partial, unsupported, failed, stale, or truncated, plus requested/completed scope, diagnostics, and fallback. Repository-specific registry collectors must enumerate their authoritative registries and completeness predicate.
• REQ-CMP-005: Collectors validate one full snapshot at start/end and publish atomically. Pagination cursors bind normalized query, stable order, total count, full snapshot/profile/schema identity, and collector-manifest digest, and are invalid after mutation.
• REQ-TRC-001: Provide query-specific typed/LSP, structural AST/tree-sitter, repository-extractor, bounded text, and optional runtime-evidence ladders appropriate to provisioned capabilities.
• REQ-TRC-002: Better read tooling must not implicitly grant repository write permission.
• REQ-TRC-003: A grep-only fallback must never claim exhaustive symbol/reference coverage without qualification.
• REQ-TRC-004: Reuse or extract AutoSkillit's AST import/re-export, manifest, architecture-constraint, .pyi, registry, and source-to-test knowledge through typed production-safe adapters; tests/_test_filter.py must not become a production navigation or policy authority.
• REQ-TRC-005: Coverage/source-map/test-collection edges are observational and revision/freshness-scoped; they may corroborate impact but cannot prove that unobserved consumers do not exist.
• REQ-TRC-006: Runtime collectors must not import or execute target code by default; any enabled execution occurs in an isolated subprocess with read-only repository access and no network or inherited credentials.

Codex policy and runtime identity

• REQ-COD-001: Every shipped role's Codex projection, when selected by explicit L1 Codex authority, must resolve to gpt-5.6-luna with max effort. Agent/profile metadata must not select the L1 backend.
• REQ-COD-002: Model and effort must be independently represented in a typed native Codex policy registry without changing global sonnet/opus/haiku alias meanings.
• REQ-COD-003: Invalid, ignored, or unprovable Luna/max policy must fail preflight/conformance rather than silently inherit ambient settings.
• REQ-COD-004: A non-skipped live generated-child probe must prove the effective Luna/max identity from authoritative Codex-owned runtime/config-resolution evidence on supported CLI versions; generated TOML, requested policy, or parent-observed linkage alone is insufficient.
• REQ-COD-005: Phase 0 runtime identity proof is a hard release gate. If the supported Codex CLI cannot expose authoritative effective model and effort evidence, stop after Phase 0 and do not ship the roles.
• REQ-ROU-001: L1 parent backend selection must use explicit backend authority; named-agent syntax must not act as an implicit router.
• REQ-TEL-001: Record requested/effective backend, native model, effort, CLI version, definition identity, and parent/child session linkage.

Dispatch, migration, tests, and docs

• REQ-DSP-001: First-wave call sites must author one backend-neutral typed router plan/task packet; backend-bound materializers alone render Claude or Codex native calls and must not infer backend from tool names or authored syntax.
• REQ-DSP-002: Claude-native invocation remains valid; Luna/max applies to the Codex projection.
• REQ-MIG-001: Maintain an explicit reviewed vector-level inventory for every first-wave skill, marking each exploration vector migrated, retained, or excluded with rationale, relationship classes, role/profile selection, and native-dispatch coverage. Token-only replacement is not migration.
• REQ-MIG-002: Keep review-pr, wp-elaborator, and existing plan-review specialists out of the first migration.
• REQ-TST-001: Add tests for definition validation, authoritative live model/effort identity, actual read-success/write-denial sandbox behavior, collision failure, registration, invalid policy, exact profile activation/non-activation, snapshot mutation/staleness, cursor invalidation, collector statuses, adaptive cross-leaf routing/merge, target-code non-execution, and both native dispatch forms.
• REQ-TST-002: Update the filtered-test manifest so agents/** changes run Codex projection/execution tests.
• REQ-TST-003: Every implementation part must independently pass task test-check; recipe YAML edits must ship regenerated JSON/contract cards in the same part.
• REQ-TST-004: Add seeded graph/trace fixtures covering aliases/re-exports, protocols, registries, string/declarative references, generated artifacts, monkeypatch/tests, stale coverage evidence, unavailable LSP, conflicts, and high-fan-out pagination. Penalize false completeness explicitly.
• REQ-DOC-001: Document the agent-family boundary, generic/profile split and activation evidence, relationship/completeness schema, observational test-impact boundary, L0/L1 backend distinction, model/effort policy, runtime support, and degraded/failure behavior.

Closes #4443

Implementation Plan

Plan file: /home/talon/projects/generic_automation_mcp/.autoskillit/temp/make-plan/add_specialized_codex_luna_explorers_plan_2026-07-31_103354.md

🤖 Generated with Claude Code via AutoSkillit