Code-intelligence tooling for the-architect role

Research state: Current

Summary

No single Rust code-intelligence tool covers every task. the-architect should combine fff for lexical discovery, codedb for code relationships, ast-grep for syntax shape, and rust-analyzer for compiler-resolved navigation, with Cargo tools as verification gates.

One consolidated agent-instructions.md source owns the routing guidance. The role copies that same content to each supported runtime path; it does not maintain parallel guidance documents.

Research question

Which complementary Rust code-intelligence tools should the-architect expose, and how should one global guidance source route each query without overlapping search claims?

Delivery belongs to the external jackin-project/jackin-the-architect repository. The stack is role-scoped and does not require a jackin❯ core change.

Method

The comparison separates four jobs: lexical discovery, structural matching, semantic navigation, and relationship-oriented context. Candidate interfaces, indexing models, runtime support, and instruction behavior were compared against the broader current retrieval-tools comparison and current release register.

Findings

Selected tools

fff and codedb are complementary. fff answers where a file or literal occurs; codedb answers how symbols and files relate. Neither tool's blanket “use me for all search” instruction belongs in the role.

Routing contract

fff           → file / path / literal-content search
codedb        → symbols / callers / dependencies / outline / task context
ast-grep      → structural search and codemods
rust-analyzer → definitions / references / types / implementations
rg / grep     → logs / comments / config keys / error strings

The router prevents duplicate searches: a literal lookup should not fan out across fff and codedb, and a caller or dependency question should not be approximated with lexical search.

Runtime support

An LSP-to-MCP bridge would add another resident server and overlap codedb. The role therefore keeps rust-analyzer on PATH and uses native LSP only where the runtime supports it.

Current trust and resource boundary

The verified releases are fff v0.10.3 and codedb v0.2.5838. Pinned artifacts and role-scoped registration are required because installers, telemetry, hooks, schemas, and runtime behavior are part of the trust boundary. Codedb telemetry stays disabled, and its installer-owned hook that blocks conventional search commands is outside the selected architecture.

Claude Code can defer MCP schemas through native tool search. Runtimes without schema deferral carry the resident server schema cost. Large tree, snapshot, and remote-tree responses must remain bounded so the relationship layer does not cost more context than direct reads.

Both indexes keep cache state in the agent home, never in the mounted workspace or a host path. The indexed project root is the mounted workspace. This preserves a clean operator checkout while keeping third-party cache ownership separate from jackin❯ paths.

Global guidance contract

agent-instructions.md is the sole source for token-optimization and code-intelligence guidance. It is copied as a real file because agent config symlink behavior is not reliable (Codex #11314, Codex #8943).

The copies must remain content-identical. Amp's global path is ~/.config/amp/AGENTS.md. Kimi's home-level auto-load behavior remains uncertain; the upstream discussion is tracked in kimi-cli #2152.

Implications for jackin❯

• The role Dockerfile, preflight hook, and default-home seeding are sufficient extension points; derived-image ownership does not need a new core feature.
• CLI tools stay on PATH for every runtime without per-turn schemas. Resident indexes use MCP only where a warm index supplies distinct value.
• Native LSP wiring and existing runtime state remain independent from the added lexical and relationship layers.
• Tool routing is a role instruction contract, not behavior duplicated in each runtime configuration.

Limitations and unknowns

• Kimi does not have established, reliable home-level global-rule loading at the cited path.
• Current codedb schema size, memory use, and bounded-output behavior need measurement on representative the-architect workspaces.
• ast-index has relationship primitives that codedb lacks, including hierarchy and recursive call-tree queries, but no evidence yet establishes enough distinct benefit for a second index.
• Native Rust LSP capability differs by runtime, so semantic navigation is not uniform across all supported agents.
• fff and codedb are fast-moving projects; release-specific installer and telemetry behavior remains part of every version review.

Sources

• AGENTS.md — cross-tool agent-instructions convention.
• Current retrieval-tools comparison — mechanisms and evaluation boundary.
• Current release register — verified tool versions.
• ast-grep and its official agent skill.
• rust-analyzer.
• fff.
• fff installer — convenience installer excluded from the pinned-artifact contract.
• codedb.
• ast-index.
• Serena — LSP-backed alternative excluded because it adds a bridge that overlaps the selected stack.
• Kimi Code and global-rules request.

Related work

• Creating a Role
• Role Manifest
• The Construct Image