From 884a6aeb2cfaa14c6e6783a36556d33b1c4f6374 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 11 Jul 2026 07:29:58 +0000 Subject: [PATCH] =?UTF-8?q?feat(skills):=20rename=20ce-plan=20=E2=86=92=20?= =?UTF-8?q?gitnexus-plan;=20add=20cross-CLI=20(Codex)=20entrypoints?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renames the skill dir, frontmatter, output filename convention, plan H1 (GitNexus Engineering Plan), the future executor handle (gitnexus-implement), the .gitignore whitelist entry, and all AGENTS.md/CLAUDE.md references. Follows the pr-swarm-review cross-CLI pattern: SKILL.md is the canonical CLI-neutral spec, AGENTS.md § Engineering planning is the Codex/any-agent entrypoint, and the README documents the optional user-level ~/.codex/prompts/gitnexus-plan.md slash command plus an invocation matrix. Skill prose de-branded from Claude Code (agent-neutral verification layer). Also fixes two post-review README contradictions: the anti-reread claim now names the ledger's allowed escalations, and 'read-only by contract' is now 'planning-only' (the skill writes exactly one repo file — the plan); the scope-creep rule and template §12 now agree on where deferred follow-ups land. Drops the stale plugin-collision limitation. Co-Authored-By: Claude Fable 5 --- .../{ce-plan => gitnexus-plan}/README.md | 50 +++++++++++++------ .../{ce-plan => gitnexus-plan}/SKILL.md | 20 ++++---- .../references/context-ledger.md | 2 +- .../references/context-pack.md | 4 +- .../references/pdg-slice.md | 0 .../references/plan-template.md | 5 +- .gitignore | 2 +- AGENTS.md | 19 ++++--- CLAUDE.md | 4 +- 9 files changed, 65 insertions(+), 41 deletions(-) rename .claude/skills/{ce-plan => gitnexus-plan}/README.md (55%) rename .claude/skills/{ce-plan => gitnexus-plan}/SKILL.md (92%) rename .claude/skills/{ce-plan => gitnexus-plan}/references/context-ledger.md (97%) rename .claude/skills/{ce-plan => gitnexus-plan}/references/context-pack.md (92%) rename .claude/skills/{ce-plan => gitnexus-plan}/references/pdg-slice.md (100%) rename .claude/skills/{ce-plan => gitnexus-plan}/references/plan-template.md (95%) diff --git a/.claude/skills/ce-plan/README.md b/.claude/skills/gitnexus-plan/README.md similarity index 55% rename from .claude/skills/ce-plan/README.md rename to .claude/skills/gitnexus-plan/README.md index 5e372ed85..f9d25812d 100644 --- a/.claude/skills/ce-plan/README.md +++ b/.claude/skills/gitnexus-plan/README.md @@ -1,22 +1,43 @@ -# ce-plan — Compound Engineering Plan +# gitnexus-plan — implementation-ready engineering plans Generates deep, implementation-ready engineering plans by combining GitNexus repository intelligence, statement-level Program Dependence Graph analysis, -and Claude Code's native targeted source verification. +and the agent's native targeted source verification. ## Invocation +| CLI | How to invoke | Adapter file | +|-----|---------------|--------------| +| **Claude Code** | `/gitnexus-plan ` | `.claude/skills/gitnexus-plan/SKILL.md` | +| **Codex CLI** | Ask: "run gitnexus-plan for " (Codex reads `AGENTS.md`) — or install the user-level prompt below | `AGENTS.md` § Engineering planning | +| **Any AGENTS.md-aware agent** | Ask it to "read `.claude/skills/gitnexus-plan/SKILL.md` and follow it for " | `AGENTS.md` § Engineering planning | + ``` -/ce-plan Add retry support to the ingestion pipeline -/ce-plan Fix the stale warm-cache invalidation bug in exportedTypeMap -/ce-plan depth:deep impact_depth:3 Migrate the emit phase to streaming COPY +/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-ce-plan-.md` — a 13-section plan whose +Output: `docs/plans/YYYY-MM-DD-gitnexus-plan-.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. -## Architecture note: how GitNexus and Claude Code interact +### Codex (optional user-level slash command) + +Codex prompts are user-level only (not repo-shareable). To get a +`/gitnexus-plan` slash command, create `~/.codex/prompts/gitnexus-plan.md`: + +```markdown +--- +description: Implementation-ready engineering plan via GitNexus + PDG + source verification +argument-hint: +--- +Read `.claude/skills/gitnexus-plan/SKILL.md` in this repo and follow it for: $ARGUMENTS +Load 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: @@ -30,14 +51,16 @@ Three layers, strictly ordered: 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. **Claude Code verifies** (targeted line-range reads). Current source is +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 or a -contradiction surfaced. The ledger also enforces symbol budgets (5 primary / +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. @@ -64,8 +87,5 @@ of context until the phase that needs them. - `pdg_query` is intra-procedural; cross-function flow comes from `explain` (taint) or `impact {mode:"pdg"}` inter-procedural reach. -- If the `compound-engineering` plugin is installed alongside this repo skill, - both expose a skill named `ce-plan` (the plugin's under the - `compound-engineering:` namespace). Invoke this one as the bare `/ce-plan`; - disambiguate by full name if your harness prompts. -- The skill is read-only by contract; it will not fix what it finds. +- The skill is planning-only by contract: the only repository file it writes + is the plan document — it will not fix what it finds. diff --git a/.claude/skills/ce-plan/SKILL.md b/.claude/skills/gitnexus-plan/SKILL.md similarity index 92% rename from .claude/skills/ce-plan/SKILL.md rename to .claude/skills/gitnexus-plan/SKILL.md index 7ec7e2b25..5a9c281cd 100644 --- a/.claude/skills/ce-plan/SKILL.md +++ b/.claude/skills/gitnexus-plan/SKILL.md @@ -1,21 +1,21 @@ --- -name: ce-plan -description: "Use when you need a deep, implementation-ready engineering plan for a code change — built from GitNexus graph intelligence, statement-level PDG analysis, and targeted source verification, compact enough that an implementation agent can start without re-investigating. Examples: \"/ce-plan Add retry support to the ingestion pipeline\", \"/ce-plan Fix the stale warm-cache invalidation bug\", \"plan this change using the knowledge graph\"." +name: gitnexus-plan +description: "Use when you need a deep, implementation-ready engineering plan for a code change — built from GitNexus graph intelligence, statement-level PDG analysis, and targeted source verification, compact enough that an implementation agent can start without re-investigating. Examples: \"/gitnexus-plan Add retry support to the ingestion pipeline\", \"/gitnexus-plan Fix the stale warm-cache invalidation bug\", \"plan this change using the knowledge graph\"." --- -# ce-plan — Compound Engineering Plan +# gitnexus-plan — implementation-ready engineering plans Produce an implementation-ready plan for an engineering task. GitNexus is the navigation layer (where to look), statement-level PDG is the constraint layer -(what gates and feeds the behavior), Claude Code source reads are the -verification layer (what is actually true right now). The output is a plan +(what gates and feeds the behavior), and your native targeted source reads are +the verification layer (what is actually true right now). The output is a plan document plus a compact, machine-readable **implementation context pack** -that a follow-up implementation agent (a future `ce-implement`, or any +that a follow-up implementation agent (a future `gitnexus-implement`, or any executor) can consume without repeating the investigation. ``` -/ce-plan -/ce-plan impact_depth:3 depth:deep # knob overrides, see Configuration +/gitnexus-plan +/gitnexus-plan impact_depth:3 depth:deep # knob overrides, see Configuration ``` **This skill plans. It never implements.** Do not modify production code, @@ -37,7 +37,7 @@ is the plan document (a working ledger kept outside the repo is fine). - **No fabrication.** Never invent symbols, filenames, test names, tool results, or PDG edges. Unknowns go to *Assumptions and Open Questions*. - **No scope creep.** Adjacent refactors the task didn't ask for go to plan - §12 as suggestions, not into Proposed Changes. + §12 as explicitly-deferred follow-ups, not into Proposed Changes. - **Stop when you have enough.** Sufficient evidence ends exploration; plans do not improve monotonically with tokens spent. @@ -147,7 +147,7 @@ and executable behavior → compiler/build/lint output → GitNexus graph and PD evidence-backed inferences, assumptions, and open questions. 2. Build the implementation context pack per `references/context-pack.md` (this is section 11 of the plan). -3. Write the document to `docs/plans/YYYY-MM-DD-ce-plan-.md` under the +3. Write the document to `docs/plans/YYYY-MM-DD-gitnexus-plan-.md` under the root of the repo being planned (the Phase 1 target repo, not necessarily the cwd). Create the directory if missing; kebab-case slug, 3–5 words. The `out:` knob overrides the destination (use it for read-only diff --git a/.claude/skills/ce-plan/references/context-ledger.md b/.claude/skills/gitnexus-plan/references/context-ledger.md similarity index 97% rename from .claude/skills/ce-plan/references/context-ledger.md rename to .claude/skills/gitnexus-plan/references/context-ledger.md index 75051baa4..caf5bdc9f 100644 --- a/.claude/skills/ce-plan/references/context-ledger.md +++ b/.claude/skills/gitnexus-plan/references/context-ledger.md @@ -1,6 +1,6 @@ # Context ledger -The ledger is ce-plan's working memory. It exists to make repeated +The ledger is gitnexus-plan's working memory. It exists to make repeated investigation impossible-by-discipline: **before every GitNexus call and every repo file read, check it.** Keep it as structured notes in your working context (or a scratchpad file *outside the repo* for very long sessions); it diff --git a/.claude/skills/ce-plan/references/context-pack.md b/.claude/skills/gitnexus-plan/references/context-pack.md similarity index 92% rename from .claude/skills/ce-plan/references/context-pack.md rename to .claude/skills/gitnexus-plan/references/context-pack.md index f9e0ae6f0..59d828a0e 100644 --- a/.claude/skills/ce-plan/references/context-pack.md +++ b/.claude/skills/gitnexus-plan/references/context-pack.md @@ -1,7 +1,7 @@ # Implementation context pack Section 11 of the plan. The stable, machine-readable contract a follow-up -implementation agent (a future `ce-implement`, or any executor) consumes to +implementation agent (a future `gitnexus-implement`, or any executor) consumes to start work **without repeating the investigation**. Distilled from the ledger; every entry traceable to verified evidence. @@ -67,7 +67,7 @@ implementation_context: ## Stability contract -Field names above are the interface for a future `ce-implement`. Add fields +Field names above are the interface for a future `gitnexus-implement`. Add fields freely; do not rename or repurpose existing ones. `assumptions` and `avoid` are load-bearing: an executor treats `assumptions` as things to re-verify cheaply before relying on them, and `avoid` as hard constraints. diff --git a/.claude/skills/ce-plan/references/pdg-slice.md b/.claude/skills/gitnexus-plan/references/pdg-slice.md similarity index 100% rename from .claude/skills/ce-plan/references/pdg-slice.md rename to .claude/skills/gitnexus-plan/references/pdg-slice.md diff --git a/.claude/skills/ce-plan/references/plan-template.md b/.claude/skills/gitnexus-plan/references/plan-template.md similarity index 95% rename from .claude/skills/ce-plan/references/plan-template.md rename to .claude/skills/gitnexus-plan/references/plan-template.md index 1c8000805..f17c0d920 100644 --- a/.claude/skills/ce-plan/references/plan-template.md +++ b/.claude/skills/gitnexus-plan/references/plan-template.md @@ -11,7 +11,7 @@ output, not source-confirmed), `[inferred]` (evidence-backed reasoning), narrative, not evidence. ```markdown -# Compound Engineering Plan +# GitNexus Engineering Plan > Task: > Evidence verified at commit ; GitNexus index . @@ -109,7 +109,8 @@ The machine-readable context pack — see `context-pack.md`. ## 12. Assumptions and Open Questions -Clearly separate assumptions from confirmed facts. +Clearly separate assumptions from confirmed facts. Explicitly-deferred +follow-up suggestions (adjacent work the task didn't ask for) land here too. ## 13. Definition of Done diff --git a/.gitignore b/.gitignore index d3adf4347..1f24f6e8b 100644 --- a/.gitignore +++ b/.gitignore @@ -98,7 +98,7 @@ gitnexus/vendor/**/node_modules/ .claude/skills/* !.claude/skills/gitnexus/ !.claude/skills/gitnexus-pr-swarm-review/ -!.claude/skills/ce-plan/ +!.claude/skills/gitnexus-plan/ .history/ diff --git a/AGENTS.md b/AGENTS.md index 055978926..d670c25e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,20 +55,23 @@ listed in [`pr-swarm-review/README.md`](pr-swarm-review/README.md); edit review in the canonical files, never in the wrappers. The review is read-only — it never edits, commits, or posts. -## Engineering planning (`/ce-plan`) +## Engineering planning (`/gitnexus-plan`) -To produce a deep, implementation-ready plan for a code change, invoke the **`ce-plan`** -skill (`.claude/skills/ce-plan/SKILL.md`): GitNexus graph intelligence for navigation, -statement-level PDG slices for behavioral constraints, targeted source reads for -verification. Output lands in `docs/plans/` with a reusable implementation context pack -(section 11) that a follow-up implementation agent consumes without re-investigating. -The skill is planning-only — it never edits code. +To produce a deep, implementation-ready plan for a code change, follow the canonical, +CLI-neutral spec **`.claude/skills/gitnexus-plan/SKILL.md`** (plus its `references/` +files): GitNexus graph intelligence for navigation, statement-level PDG slices for +behavioral constraints, targeted source reads for verification. Claude Code invokes it +as the `/gitnexus-plan` skill; Codex or any other agent reading this file should read +that SKILL.md and follow it directly (an optional user-level Codex prompt is documented +in `.claude/skills/gitnexus-plan/README.md`). Output lands in `docs/plans/` with a +reusable implementation context pack (section 11) that a follow-up implementation agent +consumes without re-investigating. The skill is planning-only — it never edits code. ## Changelog | Date | Version | Change | |------|---------|--------| -| 2026-07-11 | 1.9.0 | Added Engineering planning (`/ce-plan`) section; registered the `ce-plan` skill (`.claude/skills/ce-plan/`). | +| 2026-07-11 | 1.9.0 | Added Engineering planning (`/gitnexus-plan`) section; registered the `gitnexus-plan` skill (`.claude/skills/gitnexus-plan/`). | | 2026-05-22 | 1.8.0 | Kotlin added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). Closes #1756 (companion-vs-instance dispatch) and #1757 (lambda scopes); refs #1746. RFC §6.4 corpus criterion waived (corpus-mode wiring is #927-scope); fixture criterion met. | | 2026-04-23 | 1.7.0 | TypeScript added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). | | 2026-04-20 | 1.6.0 | Added scope-resolution pipeline pointer (RFC #909 Ring 3); Python migrated to registry-primary. | diff --git a/CLAUDE.md b/CLAUDE.md index 7fc47268a..3ddb98933 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,13 +37,13 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g - **This repository:** [AGENTS.md](AGENTS.md) (Cursor + monorepo notes), [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [GUARDRAILS.md](GUARDRAILS.md). - **Call & inheritance resolution:** See ARCHITECTURE.md § Scope-Resolution Pipeline. Shared pipeline code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` / `ScopeResolver` hooks instead (see AGENTS.md). (The legacy call-resolution DAG was removed in #942.) - **GitNexus:** `.claude/skills/gitnexus/`; MCP and indexed-repo rules live only in [AGENTS.md](AGENTS.md) (`gitnexus:start` … `gitnexus:end`). See **GitNexus rules** below. -- **Engineering plans:** `/ce-plan ` — implementation-ready plans via GitNexus + statement-level PDG + source verification; spec in `.claude/skills/ce-plan/SKILL.md` (see AGENTS.md § Engineering planning). +- **Engineering plans:** `/gitnexus-plan ` — implementation-ready plans via GitNexus + statement-level PDG + source verification; spec in `.claude/skills/gitnexus-plan/SKILL.md` (see AGENTS.md § Engineering planning). ## Changelog | Date | Version | Change | |------|---------|--------| -| 2026-07-11 | 1.4.0 | Added `/ce-plan` pointer to Reference Documentation. | +| 2026-07-11 | 1.4.0 | Added `/gitnexus-plan` pointer to Reference Documentation. | | 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. | | 2026-03-24 | 1.2.0 | Removed duplicated gitnexus:start block and scope table; replaced with pointers to AGENTS.md. | | 2026-03-23 | 1.1.0 | Updated agent instructions to match AGENTS.md. |