GitNexus — Code Intelligence

This project is indexed by GitNexus as dhpk.

Index stale? Run node .gitnexus/run.cjs analyze --skip-agents-md from the project root to refresh the index while preserving repository guidance. Check analyze --help before using version-specific options. No .gitnexus/run.cjs yet? Bootstrap with npx, bunx, or pnpm dlx — e.g. bunx gitnexus@latest analyze --skip-agents-md (npm 11 npx crash; #1939).

Always Do

• MUST run impact before editing a function, class, or method. Use impact({target: "symbolName", direction: "upstream"}) or node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo .; report callers, processes, and risk. Never substitute grep for graph analysis. Prose, skill, and guidance files have no call-graph symbol: use detect_changes before commit. A target-not-found impact is not a gate for those files.
• MUST analyze graph changes before committing. Use detect_changes({scope: "all"}) (MCP) or node .gitnexus/run.cjs detect-changes --scope all --repo . (CLI fallback). partial: true or truncated: true is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: detect_changes({scope: "compare", base_ref: "main"}) or node .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo ..
• MUST warn on HIGH/CRITICAL risk pre-edit; never use riskSharedAxes to waive a HIGH/CRITICAL risk warning. Compare File/symbol: MCP File omits axes; Graph-RAG expands File.
• MUST treat risk: UNKNOWN as unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). impact pairs UNKNOWN with a riskNote saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
• MUST use query({query: "concept"}) for concepts/flows, context({name: "symbolName"}) for a named symbol, or impact for blast radius, on read-only callers, dependencies, imports, or execution flow. Graph first; text search only for empty/UNKNOWN/literals.
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method before MCP/CLI impact analysis.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read UNKNOWN as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
• NEVER rename symbols with find-and-replace — use rename which understands the call graph.
• NEVER commit before MCP/CLI graph change analysis.

Resources

CLI

• Editing plugin sources, skills, agents, rules, or guidance: load the matching page from the agent guidance index, including plugin development and writing for agents; Codex projection rules live in Codex guidance. For specifications and development records, follow document storage by type and OpenSpec authoring, including superpowers workflows.
• Changing skill or guidance prose that ships in a package: follow daily skill prose: edit the canonical file, refresh the marketplace companion, commit that clean tree, then generate surfaces outside the checkout. Release-shaped output still uses the generated-output preflight. Surface ownership stays in distribution surfaces.
• Orchestrating implementation: follow the canonical execution policy — record decision state, run the read-only reasoner before a writer when required, keep planner/review/CI/archive/PR checkpoints, and leave external /opsx:apply unchanged.
• Developing dhpk: follow the repository's Project Convention for branches, changelog, applicable OpenSpec delivery, closeout, and shell habits. Consumer projects supply their own conventions.
• Project workflow defaults: Agent-First and multi-file Plan Mode are task-fit recommendations; use them when ownership, uncertainty, risk, or coordination supports them. Apply an 80% coverage target only when project/task acceptance or runner configuration makes it applicable; do not invent a universal threshold. See the execution policy and testing governance. They do not override stronger current-session instructions or change user-global settings.

Agent skills

Issue tracker

GitHub Issues 是本專案的 issue tracker。依 docs/agents/issue-tracker.md 使用 gh。

Triage labels

使用 needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。詳見 docs/agents/triage-labels.md。

Domain docs

本專案採 single-context。讀取根目錄的 GLOSSARY.md 和相關 docs/adr/。詳見 docs/agents/domain.md。

Guidance ownership

AGENTS.md is the only repository instruction entrypoint source. Edit it directly; CLAUDE.md, codex/AGENTS.md, and cursor/AGENTS.md are relative symlinks to this file. Resolve reference links from the repository root. Load Codex guidance for Codex work and Cursor guidance for Cursor work; these are topic references, not separate instruction entrypoints.