mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-08-28 05:25:25 +00:00
830a045911
Every optimization targets a measured fixed-cost component (eval/workflow_bench ground base: workflow arm −211% to −333% vs baseline, all tasks resolved): - Plan form is category-priced: compact form (core sections w/ § anchors preserved, ≤80 lines excl. pack, mini-pack subset of the context pack) for narrow/default categories; the full 13 sections only for deep work (refactor/security/performance/concurrency/architecture). A compact plan outgrowing its cap reclassifies to full rather than overflowing. - Freshness gate is category-priced: compact categories default to accept (source-weighted, refresh only when a graph claim becomes load-bearing); strict stays the default for full-plan categories — the rebuild+re-index was the largest single fixed cost. - Turn economy: per-category tool-call budgets (~10 to ~45; architecture uncapped); budget exhaustion routes open questions to §12 instead of more digging. - gitnexus-work fast path: HEAD == evidence pin → skip all citation re-reading (the pin's entire point); mini-pack fields tolerated. - lfg Lane 1 boundary triage: tasks below the measured ~35-turn boundary get offered gitnexus-work direct mode before the plan lane is spent. Copies re-synced (npm skills/, plugin, ~/.agents); steering + sync guards green. Re-measurement of the workflow arm follows to verify the numbers actually improve. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
120 lines
6 KiB
Markdown
120 lines
6 KiB
Markdown
# gitnexus-plan — implementation-ready engineering plans
|
||
|
||
Generates deep, implementation-ready engineering plans by combining GitNexus
|
||
repository intelligence, statement-level Program Dependence Graph analysis,
|
||
and the agent's native targeted source verification.
|
||
|
||
## Invocation
|
||
|
||
| CLI | How to invoke | Adapter file |
|
||
|-----|---------------|--------------|
|
||
| **Claude Code** | `/gitnexus-plan <task>` | `.claude/skills/gitnexus-plan/SKILL.md` |
|
||
| **Codex CLI** | Ask: "run gitnexus-plan for <task>" (Codex reads `AGENTS.md`) — or install the user-level prompt below | `AGENTS.md` § Engineering planning & execution |
|
||
| **Any AGENTS.md-aware agent** | Ask it to "read `.claude/skills/gitnexus-plan/SKILL.md` and follow it for <task>" | `AGENTS.md` § Engineering planning & execution |
|
||
|
||
```
|
||
/gitnexus-plan Add retry support to the ingestion pipeline
|
||
/gitnexus-plan Fix the stale warm-cache invalidation bug in exportedTypeMap
|
||
/gitnexus-plan depth:deep impact_depth:3 Migrate the emit phase to streaming COPY
|
||
```
|
||
|
||
Output: `docs/plans/YYYY-MM-DD-gitnexus-plan-<slug>.md` — a 13-section plan whose
|
||
section 11 is a machine-readable **implementation context pack** that a
|
||
follow-up agent can consume without re-investigating the repository.
|
||
|
||
### Codex (user-level install)
|
||
|
||
Codex discovers SKILL.md skills from `~/.agents/skills/` (the same path the
|
||
other `gitnexus-*` skills install to). To make this skill auto-discoverable in
|
||
every Codex session:
|
||
|
||
```
|
||
cp -r .claude/skills/gitnexus-plan ~/.agents/skills/gitnexus-plan
|
||
```
|
||
|
||
Codex prompts are user-level only (not repo-shareable). Optionally, for an
|
||
explicit `/gitnexus-plan` slash command, also create
|
||
`~/.codex/prompts/gitnexus-plan.md`:
|
||
|
||
```markdown
|
||
---
|
||
description: Implementation-ready engineering plan via GitNexus + PDG + source verification
|
||
argument-hint: <task description>
|
||
---
|
||
Use the gitnexus-plan skill for: $ARGUMENTS
|
||
|
||
Read `~/.agents/skills/gitnexus-plan/SKILL.md` (if this repo has its own copy at
|
||
`.claude/skills/gitnexus-plan/SKILL.md`, prefer that one) and follow its phases in
|
||
order, loading its `references/` files at the phases that call for them. Planning
|
||
only — never edit code; the only repo file you write is the plan document.
|
||
```
|
||
|
||
## Architecture note: how GitNexus and the agent interact
|
||
|
||
Three layers, strictly ordered:
|
||
|
||
1. **GitNexus navigates** (`query` → `context` → `impact`/`trace` →
|
||
`cypher` last-resort). The graph answers *where to look* and *what is
|
||
connected*: execution flows, callers/callees, blast radius, related tests.
|
||
Every call must answer a named planning question.
|
||
2. **PDG constrains** (`pdg_query` controls/flows, `impact {mode:"pdg",
|
||
direction, line}` statement slices, `explain` for taint). The
|
||
statement-level layers
|
||
answer *what gates and feeds the behavior* inside the few functions the
|
||
change centers on. Results are filtered into a bounded slice
|
||
(`references/pdg-slice.md`), never dumped.
|
||
3. **The agent verifies** (targeted line-range reads). Current source is
|
||
authoritative; graph results are navigation hints until verified. On
|
||
disagreement: trust source, record the discrepancy, recommend re-indexing.
|
||
|
||
Token efficiency comes from the **context ledger**
|
||
(`references/context-ledger.md`): every query and read is recorded with the
|
||
question it answered, and nothing is re-fetched unless the source changed, a
|
||
contradiction surfaced, or one of the ledger's defined escalations applies
|
||
(summary→detail drill-down, ambiguity narrowing, a changed parameter answering
|
||
a new question). The ledger also enforces symbol budgets (5 primary /
|
||
20 related by default), and progressive disclosure keeps the big schemas out
|
||
of context until the phase that needs them.
|
||
|
||
## Files
|
||
|
||
| File | Purpose |
|
||
| --- | --- |
|
||
| `SKILL.md` | The skill: phases 0–5, hard rules, config, fallback |
|
||
| `references/pdg-slice.md` | PDG slice construction: tools, inclusion criteria, schema, security/performance modes |
|
||
| `references/context-ledger.md` | Ledger schema + anti-reread rules |
|
||
| `references/plan-template.md` | The 13-section plan document template |
|
||
| `references/context-pack.md` | Implementation context pack schema + stability contract |
|
||
|
||
## Requirements and graceful degradation
|
||
|
||
- Requires a GitNexus index; statement-level sections additionally require the
|
||
`--pdg` layers.
|
||
- Freshness is a gate, priced by category: full-plan categories (refactor,
|
||
security, performance, concurrency, architecture) default to `freshness:
|
||
strict` — a stale index (or missing PDG layer) is refreshed once with
|
||
`analyze --index-only [--pdg]` — run via `node .gitnexus/run.cjs` when the
|
||
project has one, else the installed `gitnexus` CLI (`npm install -g
|
||
gitnexus`), else `npx gitnexus` — before the graph is relied on.
|
||
Compact-plan categories default to `accept` (source-weighted, refresh only
|
||
if a graph claim becomes load-bearing) because the refresh is the largest
|
||
fixed cost a planning session carries (measured: `eval/workflow_bench/`).
|
||
`--index-only` touches only the `.gitnexus` store, never repo files. When the repo builds the analyzer from source (like this one:
|
||
`gitnexus/dist`), the gate first ensures `dist/` is current (`npm run
|
||
build` when src is newer) so the refresh doesn't re-index with outdated
|
||
extraction logic. `freshness: accept` (or a failed/impractical refresh)
|
||
plans on the stale graph instead, source-weighted and labelled in the plan
|
||
header.
|
||
- PDG layer still unavailable after that → the plan says so and skips
|
||
statement-level claims (never reconstructs fake edges).
|
||
- No GitNexus at all → fallback mode: targeted grep/read exploration, findings
|
||
labelled **source-derived**, with a recommendation to index.
|
||
|
||
## Limitations
|
||
|
||
- `pdg_query` is intra-procedural; cross-function flow comes from `explain`
|
||
(taint) or `impact {mode:"pdg"}` inter-procedural reach.
|
||
- The skill is planning-only by contract: the only repository file it writes
|
||
is the plan document, and the only other state it may touch is the
|
||
`.gitnexus` index store (freshness refresh) plus the analyzer's `dist/`
|
||
build output (runner build check) — it will not fix what it finds.
|