Skip to content

chore(skills): CLAUDE.md prompt-rule compliance + script-first onboarding design#236

Open
coseto6125 wants to merge 11 commits into
mainfrom
chore/skill-sample-rename-to-ecp
Open

chore(skills): CLAUDE.md prompt-rule compliance + script-first onboarding design#236
coseto6125 wants to merge 11 commits into
mainfrom
chore/skill-sample-rename-to-ecp

Conversation

@coseto6125
Copy link
Copy Markdown
Owner

@coseto6125 coseto6125 commented May 20, 2026 •
edited
Loading

Summary

Two related fixes to the ecp + ecp-onboard skill prompts:

1. CLAUDE.md prompt-writing guide compliance

  • skill_sample/claude/simplify/SKILL.md mirrored from the modern codex/simplify (already used the ecp review aggregator); the Claude variant still referenced the retired gnx binary and non-existent gnx scan / gnx search. After this change, both simplify variants are byte-identical.
  • skill_sample/claude/SKILL.md:
    • Reordered Decisions (abstract rules) before Tool selection (specific commands), per CLAUDE.md "abstract rules first".
    • Rewrote Never find-replace and don't add :Method filter as positive instructions.
    • Removed non-existent ecp scan rows (command never shipped).
    • Fixed factual errors: title (egent-code-plexus-rs → egent-code-plexus); cache path (~/.ecp/<repo-name>__<hash>/); default graph (.ecp/graph.bin); ecp find mode description (default exact, not auto-picked).
  • docs/skills/ecp-onboard/{SKILL,ONBOARDING,guides/04-mcp,guides/05-summary}.md:
    • Collapsed the duplicate Hard "don't" list into Directives (each rule appears exactly once).
    • Rewrote each Never X / Do not X as a positive instruction.
    • Deduped never silently retry which appeared in both Directives and Hard list.

2. Script-first onboarding design (ecp admin <agent> install)

The current onboarding had the wizard write IDE config files directly via jq / cat. The CLI already has scriptable installers (ecp admin claude install, ecp admin codex install, ecp admin gemini install) that handle every write + merge + backup. The wizard now:

  • Directive 5 now states the wizard never edits IDE config files directly. Scriptable IDEs flow through ecp admin <agent> install <component>. Unscriptable IDEs (Cursor / Zed / VS Code) get a paste snippet, not an auto-write.
  • Directive 1 strengthened: before any apply step, restate exact files / paths the action will touch and wait for explicit confirmation.
  • Phase 04 Step 4 now records mode: scripted vs paste-snippet per IDE.
  • Phase 04 Step 5 confirms the Phase 05 plan (specific commands + paste targets) before any apply.
  • Phase 05 Step 4 (Write MCP configs → Apply IDE integrations) replaces the jq direct-write with the per-agent install call. Summary template entries reflect "ran command" vs "emitted snippet".

3. Drive-by fixes

  • End-of-file corruption in ONBOARDING.md + guides/05-summary.md (rwrite the summary) line + dangling code fence).
  • Obsolete _shared/cli/<version>/admin-index.md references updated to the flat _shared/cli/admin-index.md layout that exists on disk.

Test plan

  • grep -rE 'cgn |gnx|code-graph-nexus' skill_sample/ docs/skills/ returns nothing (one legitimate registry dir-name hit excluded)
  • grep -rE 'jq .*mcpServers|cat > .target.|cp .*\.mcp\.json' docs/skills/ skill_sample/ returns nothing — no direct config-file writes remain
  • grep -rE 'MUST NOT' docs/skills/ skill_sample/ returns nothing — negative phrasing replaced
  • grep -rE 'Hard "don' docs/skills/ skill_sample/ returns nothing — duplicate list removed
  • diff skill_sample/claude/simplify/SKILL.md skill_sample/codex/simplify/SKILL.md is empty
  • ecp admin claude/codex/gemini install --help confirms the new directives reference real commands
  • ecp find --help confirms --mode exact|fuzzy|bm25 (default exact) — matches the rewritten Tool-selection row
  • ecp scan --help errors (command was never shipped) — matches the removal of ecp scan rows

@coseto6125 coseto6125 added skills Changes to skill_sample/ (LLM agent skills for ecp) documentation Improvements or additions to documentation labels May 20, 2026
@coseto6125 coseto6125 changed the title chore(skills): align claude/simplify with ecp review aggregator chore(skills): CLAUDE.md prompt-rule compliance + script-first onboarding design May 20, 2026
@coseto6125 coseto6125 enabled auto-merge (squash) May 20, 2026 22:25
@coseto6125 coseto6125 force-pushed the chore/skill-sample-rename-to-ecp branch from 64f8345 to 42b0bd4 Compare May 21, 2026 00:02
coseto6125 added a commit that referenced this pull request May 21, 2026
@coseto6125
ci: drop paths-ignore so required checks always report
9845f5b 
Branch protection requires Code Quality / Test×3 / Supply-chain / Lint
Actions workflows to report success on every PR. `paths-ignore` skipped
the whole workflow on docs-only PRs — those required checks then never
reported success and the PR sat in `BLOCKED` forever (PRs #236, #278).

Drop the path-filter on both push and pull_request triggers. The cost
on a real docs-only PR is bounded by the cargo build cache; the first
PR after a Cargo.lock change pays the full cost but subsequent ones hit
the warm cache. This is cheaper than maintaining a synthetic skip-job
that pretends success — and it gives docs PRs the same correctness
guarantee as code PRs (no chance of an inadvertent code change sneaking
into a "chore(docs)" PR and skipping CI, the original #226 hazard the
paths-ignore comment alluded to).

The `.github/workflows/*` change in this same PR triggers CI on #278
itself, unblocking the doc-restoration commit that landed alongside it.
coseto6125 added a commit that referenced this pull request May 21, 2026
@coseto6125
docs(plans): restore symbol-graph-core-roadmap from session jsonl (#278)
6686072 
* docs(plans): restore symbol-graph-core-roadmap from session jsonl

The original 51 KB / 822-line roadmap draft was authored in a worktree
that was subsequently deleted before its branch was pushed to origin.
The branch was then pruned from local refs and `git fsck`'d dangling
commits don't contain the file — the doc was effectively lost from
git history.

Reconstructed by replaying the original Write tool call (line 1087 of
the session jsonl, 38 KB base body) plus 23 of 24 subsequent Edits
captured in the same session. One Edit was skipped because its
old_string was already absent at restore time — almost certainly a hunk
that was reverted later in the same session.

Added a single restoration-note callout + a status snapshot table
mapping each T-task to its shipped / in-flight / pending state and
PR number. The body itself is verbatim from the reconstruction;
nothing was rewritten, only the metadata block at the top was changed
to flag the restoration.

Source jsonl (referenced for provenance; not committed):
~/.claude/projects/-home-enor-code-graph-nexus--claude-worktrees-rename-cgn-to-ecp/9289733a-d3f9-4333-88f0-42190a9e88df.jsonl

This makes the roadmap an actual repo artefact again so future agents
(and the remaining ~50 pending T-tasks) have the design rationale,
the D1-D7 decision log, and the dependency graph available without
having to scrape session logs.

* ci: drop paths-ignore so required checks always report

Branch protection requires Code Quality / Test×3 / Supply-chain / Lint
Actions workflows to report success on every PR. `paths-ignore` skipped
the whole workflow on docs-only PRs — those required checks then never
reported success and the PR sat in `BLOCKED` forever (PRs #236, #278).

Drop the path-filter on both push and pull_request triggers. The cost
on a real docs-only PR is bounded by the cargo build cache; the first
PR after a Cargo.lock change pays the full cost but subsequent ones hit
the warm cache. This is cheaper than maintaining a synthetic skip-job
that pretends success — and it gives docs PRs the same correctness
guarantee as code PRs (no chance of an inadvertent code change sneaking
into a "chore(docs)" PR and skipping CI, the original #226 hazard the
paths-ignore comment alluded to).

The `.github/workflows/*` change in this same PR triggers CI on #278
itself, unblocking the doc-restoration commit that landed alongside it.
@coseto6125 coseto6125 mentioned this pull request May 21, 2026
Merged
3 tasks
coseto6125 added a commit that referenced this pull request May 21, 2026
@coseto6125
ci: short-circuit heavy jobs for docs-only PRs (no branch-protection …
8d9d928 
…deadlock) (#287)

* ci: short-circuit heavy jobs on docs-only PRs (preserve required-check semantics)

Adds a `detect-changes` job that classifies PR changes via shell-based
git diff against `github.base_ref`. Downstream code-quality / test / audit
jobs gate every heavy step on `needs.detect-changes.outputs.code == 'true'`
but still RUN as jobs — so branch protection's required-check list keeps
seeing SUCCESS on docs-only PRs (e.g. #286 roadmap refresh) instead of
burning ~10 min × 3 OS on cargo nextest + ~2 min on audit/deny.

Why not paths-ignore?
  paths-ignore skips the whole workflow → required checks never report →
  docs-only PRs stuck `BLOCKED` (the #236 / #278 deadlock).

Why not job-level `if: false` for docs?
  Same problem: SKIPPED ≠ SUCCESS for branch protection's required list.

Why this design (step-level `if:`)?
  Job-level execution stays unconditional (SUCCESS reports), but the heavy
  steps short-circuit when `code != true`. Each job's first step prints a
  visible "✓ Docs-only PR — skipping ..." log line so it's obvious in the
  Actions UI what happened.

Code-relevant path classification (positive list — anything else is treated
as docs/config/license-only):
  crates/  Cargo.toml  Cargo.lock  .github/  scripts/  rust-toolchain*
  deny.toml  clippy.toml  rustfmt.toml

`actionlint` keeps running unconditionally — it lints the workflow YAML
itself (always present), and the ~30s cost is negligible.

Push-to-main events always default to `code=true` regardless of detected
paths (merge commits must get full validation).

* ci: fix actionlint SC2001 (replace sed with while loop)
coseto6125 added a commit that referenced this pull request May 21, 2026
@coseto6125
perf(builder, rename): simplify memory allocs and fix collision index…
38b8d17 
… sync (#296)

* ci: short-circuit heavy jobs on docs-only PRs (preserve required-check semantics)

Adds a `detect-changes` job that classifies PR changes via shell-based
git diff against `github.base_ref`. Downstream code-quality / test / audit
jobs gate every heavy step on `needs.detect-changes.outputs.code == 'true'`
but still RUN as jobs — so branch protection's required-check list keeps
seeing SUCCESS on docs-only PRs (e.g. #286 roadmap refresh) instead of
burning ~10 min × 3 OS on cargo nextest + ~2 min on audit/deny.

Why not paths-ignore?
  paths-ignore skips the whole workflow → required checks never report →
  docs-only PRs stuck `BLOCKED` (the #236 / #278 deadlock).

Why not job-level `if: false` for docs?
  Same problem: SKIPPED ≠ SUCCESS for branch protection's required list.

Why this design (step-level `if:`)?
  Job-level execution stays unconditional (SUCCESS reports), but the heavy
  steps short-circuit when `code != true`. Each job's first step prints a
  visible "✓ Docs-only PR — skipping ..." log line so it's obvious in the
  Actions UI what happened.

Code-relevant path classification (positive list — anything else is treated
as docs/config/license-only):
  crates/  Cargo.toml  Cargo.lock  .github/  scripts/  rust-toolchain*
  deny.toml  clippy.toml  rustfmt.toml

`actionlint` keeps running unconditionally — it lints the workflow YAML
itself (always present), and the ~30s cost is negligible.

Push-to-main events always default to `code=true` regardless of detected
paths (merge commits must get full validation).

* ci: fix actionlint SC2001 (replace sed with while loop)

* fix(builder, rename): simplify memory allocs and correct collision index sync
coseto6125 added 10 commits May 23, 2026 11:03
@coseto6125
chore(skills): align claude/simplify with ecp review aggregator
aa9da3d 
claude/simplify still referenced the retired `gnx` binary and the
non-existent `gnx scan` / `gnx search` commands. codex/simplify was
already modernized for the `ecp review` aggregator (impact + coverage
+ tool-map + shape-check + diff in one call). Mirror that content
into the Claude variant so both stay in sync.

After this change `skill_sample/` has zero `cgn / gnx / code-graph-nexus`
residue, and the two simplify variants are byte-identical.
@coseto6125
chore(skills): apply CLAUDE.md prompt rules + script-first onboarding…
dc3a132 
… design

Two changes bundled because both touch the ecp + ecp-onboard skill
prompts and both were flagged in the same review:

1) CLAUDE.md prompt-writing guide compliance:
   - skill_sample/claude/SKILL.md: reorder "Decisions" before "Tool
     selection" (abstract rules first); rewrite "Never find-replace"
     and "don't add :Method filter" as positive instructions; remove
     non-existent `ecp scan` rows; fix factual errors in title /
     cache path / default graph / `ecp find --mode` description.
   - docs/skills/ecp-onboard/SKILL.md & ONBOARDING.md & guides/04-mcp.md
     & guides/05-summary.md: collapse the duplicate "Hard don't list"
     into Directives; rewrite each negative phrase as a positive
     instruction; dedupe the "never silently retry" rule that appeared
     in both Directives and the Hard list.

2) Script-first onboarding design (raised by reviewer):
   - Directive 5 now states the wizard never edits IDE config files
     directly; scriptable IDEs (claude / codex / gemini) flow through
     `ecp admin <agent> install <component>`; unscriptable IDEs
     (Cursor / Zed / VS Code) get a paste snippet, not an auto-write.
   - Phase 04 Step 4 records `mode: scripted` vs `paste-snippet` per
     IDE; Phase 04 Step 5 confirms the Phase 05 plan (specific
     commands + specific paste targets) before any apply.
   - Phase 05 Step 4 ("Write MCP configs" → "Apply IDE integrations")
     replaces the `jq` direct-write with the per-agent install call;
     summary template entries reflect "ran command" vs "emitted
     snippet" instead of "wrote file".
   - Directive 1 strengthened: before any apply step, restate exact
     files / paths the action will touch and wait for confirmation.

Also fixes a pre-existing end-of-file corruption in ONBOARDING.md +
guides/05-summary.md (an extra "rwrite the summary)" line + dangling
code fence) and updates obsolete `_shared/cli/<version>/admin-index.md`
references to the flat `_shared/cli/admin-index.md` layout that
actually exists on disk.
@coseto6125
docs(readme): add platform + agent compatibility badges
21cec5b 
Linux / macOS / Windows badges link to the GitHub releases page (all
three are real targets in release.yml: x86_64-linux, aarch64-linux,
x86_64-apple-darwin, aarch64-apple-darwin, x86_64-pc-windows-msvc).

Agent badges link to the relevant skill / install doc:
  - Claude Code  → skill_sample/claude/SKILL.md
  - Codex CLI    → skill_sample/codex/ecp/SKILL.md
  - Cursor       → docs/skills/ecp-onboard/guides/04-mcp.md
                  (MCP paste-snippet flow; no scripted installer yet)

Mirrored the badge block into docs/readme_i18n/README_zh-TW.md to keep
the two READMEs in sync.
@coseto6125
docs(readme): hoist OpenSSF Scorecard above platform / agent badges
50cd482 
Trust signals (Scorecard, Star History) go above compatibility shields
— matches the convention in most security-conscious READMEs and makes
the security score the first thing readers see.
@coseto6125
docs(readme): move Star History to its own bottom section
f077584 
Star History is a community/social signal — render it as a full-size
chart in a dedicated `## Star History` section at the end of the README
rather than as a small badge at the top. Trust signal (OpenSSF
Scorecard) stays at the top alone.
@coseto6125
docs(readme): brutalist-terminal redesign + content rewrite
0f9d196 
Hero, sectioning, and tone reworked to match the "CLI for agents"
identity instead of the generic SaaS-emoji README template.

Visual:
  - ASCII box hero with the tool's positioning + the 4 numbers that
    actually matter (cold index / query p50 / languages / edge policy)
  - Section headers reframed as `── name ──` instead of emoji prefixes
  - Hero metric card immediately below badges; trust signal (Scorecard)
    isolated above platform/agent compatibility badges

Content:
  - Mission rewritten as 4 punch-line bullets (stateless / honest /
    token-cheap / polyglot) instead of long paragraphs
  - Added "30-second demo" section showing a real `ecp impact` TOON
    output — the README finally has a show-don't-tell anchor
  - "vs. upstream gitnexus" kept visible (positioning) but scalability
    sub-tables collapsed into <details> (reference, not pitch)
  - CLI surface: agent commands stay visible (value prop); admin
    commands collapsed
  - Codex CLI native integration (50+ niche lines) collapsed into
    <details>; the agent-facing scripted path (`ecp admin <agent>
    install`) stays in the MCP server section
  - License paragraph slimmed; the 9-dep acknowledgments list
    collapsed into <details>

zh-TW README rewritten in lockstep so the two stay structurally
identical. Internal links audited — all point to real files.
@coseto6125
docs(i18n): add 7 README translations (zh-CN / es / ru / hi / ja / ko…
e83992a 
… / pt-BR)

The English README at repo root remains the source of truth; each
translation mirrors its section structure 1-for-1. ASCII hero box,
badges, metrics card, command names, flag names, JSON snippets, and
table numbers stay identical across all locales.

New files:
  docs/readme_i18n/README_zh-CN.md   (Simplified Chinese, derived
                                      from zh-TW via opencc tw2sp)
  docs/readme_i18n/README_es.md      (Spanish)
  docs/readme_i18n/README_ru.md      (Russian)
  docs/readme_i18n/README_ja.md      (Japanese — です/ます polite form)
  docs/readme_i18n/README_ko.md      (Korean — 합니다 polite form)
  docs/readme_i18n/README_pt-BR.md   (Brazilian Portuguese)
  docs/readme_i18n/README_hi.md      (Hindi — Devanagari prose around
                                      English technical terms)
  docs/readme_i18n/CONTRIBUTING.md   (guide for contributing
                                      translations + quality bar +
                                      add/remove-locale flow)

Picker: every README now has a language-switcher line right under the
metrics block, with the current locale shown bolded (no link) and the
other 8 linked. All relative paths verified against the actual file
layout (../../README.md from translations, ./README_xx.md between
translations, ./docs/readme_i18n/README_xx.md from root English).

Quality note: zh-CN / zh-TW / es / ru / pt-BR / ja / ko are
near-native-fluent. Hindi is best-effort with technical terminology
kept in English (Devanagari for technical CLI/library names is awkward
and not standardized in the Indian dev community). Native-speaker
review PRs welcome — the new CONTRIBUTING.md explains the flow.
@coseto6125
docs(readme): tighten layout per CLAUDE.md signal-density principle
4a03974 
The previous brutalist redesign violated CLAUDE.md's priority order
('Signal density — every byte of output costs context window. No
prose, no UI cruft.' / 'When perf and prettiness conflict, perf wins.').
Hero had 7 visual blocks before any content; section headers carried
'── name ──' decoration that added bytes without information.

Tightenings applied uniformly across the English source + 8 translations:

- Drop the 6-line ASCII box hero — H1 already names the project.
- Inline the 4-line metric card as a single backtick string:
  `cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot
  edges (no hallucinated dispatch) · 60× upstream gitnexus`
- Strip `## ── name ──` decoration on every section header → plain
  `## name`. Saves ~80 bytes per file across 13 headers.
- Strip inter-section `---` HRs. Keep only two boundary HRs (hero →
  content and content → Star History) per file. GitHub's `##`
  rendering provides the visual separation already.
- Replace the synthetic `validateUser` demo with a real ecp symbol:
  `parse_with_budget` (crates/ecp-analyzer/src/parse_budget.rs:28).
  The actual 22-language polyglot fan-out — every per-language
  `parser.rs` calls into the budget primitive — is the value prop
  ecp is selling, so showing it instead of a fabricated auth example
  honours the 'Never fabricate' principle from CLAUDE.md and gives
  readers a real signal of polyglot reach.

Result: -366 lines total (264 in / 630 out) across 9 files. English
README 377 → 307; each translation 377 → 340.
@coseto6125
chore(skills): port claude/cgn skill body → claude/ecp
f8743ef 
The Phase 1 rename moved codex/cgn → codex/ecp but inadvertently
dropped claude/cgn without porting. This restores the claude-side
sample by porting cgn/SKILL.md → ecp/SKILL.md with command/flag
references updated to current ecp surface, frontmatter name/description
rewritten, and layout aligned with the layered structure used by
codex/ecp/SKILL.md (Directive layer + Tool Selection table).

Changes:
- Frontmatter: name cgn → ecp, description updated to reference ecp
- All commands: cgn → ecp
- Flag updates: --direction upstream → --direction up (current ecp)
- Removed: scan command (no longer in ecp)
- Paths: ~/.cgn/ → ~/.ecp/, code-graph-nexus-rs → egent-code-plexus
- Structure: added Layer 1/2/3 hierarchy from codex/ecp pattern
@coseto6125
docs(readme + skills): document new schemas + Cursor/Windsurf/Cline M…
a4ed2ad 
…CP snippets

- README.md + zh-TW: add manual mcp.json snippet block for Cursor / Windsurf
  / Cline (the three hosts without scripted installer). Per-IDE config path
  table inside <details>.
- skill_sample/claude/ecp/SKILL.md: refresh NodeKind / RelType lists to
  cover schema additions on origin/main since the branch diverged —
  EnumVariant, PathLiteral, TransactionScope, Annotation, Struct/Enum/Trait
  /Impl/Namespace/Module/SchemaField/EventTopic node kinds + Decorates /
  OpensTxScope / UsesPathLiteral / MirrorsField / Publishes / Subscribes /
  EventTopicMirror / Overrides rel types.
@coseto6125 coseto6125 force-pushed the chore/skill-sample-rename-to-ecp branch from d75685d to a4ed2ad Compare May 23, 2026 03:15
@coseto6125 coseto6125 added the ci:run fire CI test matrix on this PR label May 23, 2026
@coseto6125 coseto6125 disabled auto-merge May 23, 2026 05:37
@coseto6125 coseto6125 removed the ci:run fire CI test matrix on this PR label May 23, 2026
@coseto6125
release: 0.3.0 -> 0.4.0 — bump workspace + crate versions
7109127 
Bump workspace package + all 4 crates + intra-workspace path-dep pins
+ Cargo.lock from 0.3.0 to 0.4.0 in preparation for the v0.4.0 tag.

Versions touched:
- workspace.package.version (Cargo.toml)
- ecp-core, ecp-analyzer, ecp-cli per-crate versions
- ecp-mcp inherits via workspace.version
- intra-workspace path-deps: ecp-analyzer -> ecp-core,
  ecp-cli -> {ecp-core, ecp-analyzer, ecp-mcp}

Scope of v0.4.0 (covered in the release notes when the tag is cut):
49 commits between v0.3.0 (PR #330 close-out) and this PR — cypher
perf wins (Accumulator + predicate pushdown + kind-CSR + walk_rel
closure + Binding VarMap), MCP host distribution paths (#395),
GitHub-native auto-merge replaces Mergify (#401), `ecp insight`
telemetry, `ecp dev pr-analyze`, schema-bindings rollouts,
benchmark realign with hot-path query coverage, and the RTK-style
skill rewrite landed in PR #419.
This was referenced May 24, 2026
Merged
Merged
coseto6125 added a commit that referenced this pull request May 25, 2026
@coseto6125
docs(readme): promotional rewrite + 8-language i18n coverage (#456)
516faba 
Rewrite the main README around a single positioning — a code-intelligence
graph built for AI agents, not humans. New hero (tagline + stat badges +
language switcher), a three-failure-mode opening (token waste / broken
refactors / hallucinated deps) distilled into a problem→answer table, and
design principles tied to mechanisms (mmap, rkyv, BlindSpot). All benchmark
numbers, CLI surface, and the honest release-status caveat are preserved.

Add full i18n parity with PR #236's language set: zh-TW (rewritten), plus new
zh-CN, ja, ko, es, pt-BR, ru, hi under docs/readme_i18n/. Each carries the
8-language switcher, correct ../ / ../../ relative link targets, localized
number formats where idiomatic (pt-BR 22.645 / 2,6 s), and identical
structure to the English source.

Final English version selected by iterating 20 variants across 5 design
routes, then ranking with 10 evaluation passes (hook / scannability /
credibility / differentiation / fact-check / link-integrity / visual /
completeness / newcomer-conversion / holistic). Winner: balanced-hybrid v20.

The query-latency figure is unified to <175 ms (the measured 174.2 ms worst
case) across hero, badge, and the vs-GitNexus table — fixing the prior
<170/<150 ms mismatch.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation skills Changes to skill_sample/ (LLM agent skills for ecp)

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@coseto6125