You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Public outputs MUST keep canonical field ordering where applicable: `status` -> `reason` -> identity/query fields -> `next_action` / `next_actions` -> `summary` -> recovery helpers -> details.
118
+
- Public `reason` values MUST be stable `snake_case`, not prose sentences.
119
+
- Public `next_action` / `next_actions` MUST use canonical labels, not English advice sentences.
120
+
- Do not introduce a new `status`, `reason`, or `next_action` label if an existing one already covers the same decision.
121
+
-`hex-graph` success payloads MUST keep top-level `status: "OK"`; error payloads MUST keep the compact error envelope: `status`, `code`, `summary`, `next_action`, `recovery`.
122
+
-`hex-line` text contracts MUST stay canonical and compact: prefer `summary` / `snippet` / `retry_edit` / `retry_edits` / `suggested_read_call` / `retry_plan` over long prose guidance blocks.
123
+
124
+
**Docs and server-description sync gates**
125
+
126
+
-`README.md`, package site/page content if touched, and `server.mjs` tool descriptions must agree on:
127
+
- tool count
128
+
- primary use cases
129
+
- current output contract fields
130
+
- status/reason/next_action vocabulary
131
+
-`server.mjs` descriptions must describe **when to use** the tool and mention current recovery contract where relevant.
132
+
- If a release changes public output wording or recovery fields, update README examples in the same release.
133
+
134
+
**hex-line-specific release gates**
135
+
136
+
- Hook behavior, `output-style.md`, README, and `hook.mjs` must agree on:
137
+
- whether built-in `Read` / `Edit` / `Write` / `Grep` are redirected or merely advised
138
+
- what Bash commands are redirected
139
+
- PostToolUse truncation thresholds and head/tail counts
140
+
- SessionStart bootstrap behavior
141
+
-`edit_file` conflict output must still expose the current compact recovery contract:
142
+
-`status`
143
+
-`reason`
144
+
-`next_action`
145
+
-`summary`
146
+
-`snippet`
147
+
- recovery helpers such as `retry_edit`, `retry_edits`, `suggested_read_call`, `retry_plan`, `retry_checksum`, `recovery_ranges`
148
+
-`verify` and `changes` must preserve canonical `status` / `reason` / `next_action` outputs; do not publish if they drift back to narrative/prose-first responses.
149
+
150
+
**hex-graph-specific release gates**
151
+
152
+
- Use-case wrappers and server-level overrides must keep the same action vocabulary; no mixed sentence-style `next_actions`.
153
+
-`compact` / default outputs should prune empty sections instead of shipping null-heavy payloads.
154
+
- Query success results must preserve the top-level pattern: `status`, `query`, `summary`, `reason`, `result`, optional `quality`, optional `warnings`, optional `next_actions`.
**CRITICAL:** Commit ALL repo changes (`git add -A`), not just the package directory. Other pending changes (skills, commands, docs) ride along with the release commit. Never scope `git add` to a subdirectory.
146
207
@@ -151,21 +212,21 @@ git tag ${TAG_PREFIX}${NEW_VERSION}
151
212
git push origin master --tags
152
213
```
153
214
154
-
### 9. Verify publish
215
+
### 10. Verify publish
155
216
156
217
Wait ~30s, then:
157
218
```bash
158
219
gh run list --limit 1
159
220
npm view ${PKG_NAME} version
160
221
```
161
222
162
-
### 10. Report
223
+
### 11. Report
163
224
164
225
Display: package name, old → new version, npm URL (`https://www.npmjs.com/package/${PKG_NAME}`), GitHub Actions run status.
| Built-in Grep |`hex-line grep_search`| Before editing found code |
38
-
| Large code file |`hex-line outline` then `read_file` with range | Unfamiliar files over 100 lines |
39
-
40
-
Built-in tools are still fine for images, PDFs, notebooks, Glob, and `.claude/settings*.json`.
30
+
Prefer `hex-line` for code/config/script/test files.
31
+
- Use `outline` before large reads, then `read_file` with ranges.
32
+
- Use `edit_file` / `write_file` for writes, `bulk_replace` for multi-file text rename, `verify` after conflicts or delayed follow-up edits, and `changes` for diff review.
33
+
- Use `hex-graph` only for symbol, reference, architecture, and semantic diff questions.
34
+
- Built-in tools are still fine for images, PDFs, notebooks, Glob, and `.claude/settings*.json`.
41
35
42
36
## Quick Understanding
43
37
@@ -68,6 +62,7 @@ Built-in tools are still fine for images, PDFs, notebooks, Glob, and `.claude/se
68
62
| Questions format |`skills-catalog/shared/references/questions_format.md`|
| Bash `diff`|`hex-line changes`| Semantic diff with symbol-level detail |
38
-
| Re-read after CONFLICT |`hex-line verify`| Check freshness without rereading |
39
-
40
-
**Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json` and `.claude/settings.local.json`.
26
+
Prefer `hex-line` for code/config/script/test files.
27
+
- Use `outline` before large reads, then `read_file` with ranges.
28
+
- Use `edit_file` / `write_file` for writes, `bulk_replace` for multi-file text rename, `verify` after conflicts or delayed follow-up edits, and `changes` for diff review.
29
+
- Use `hex-graph` only for symbol, reference, architecture, and semantic diff questions.
30
+
- Built-in tools are still fine for images, PDFs, notebooks, Glob, and `.claude/settings*.json`.
Copy file name to clipboardExpand all lines: GEMINI.md
+11-17Lines changed: 11 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,8 +10,8 @@ Skills collection for Gemini CLI with config-driven Agile task management (Linea
10
10
11
11
| Rule | When to Apply | Details |
12
12
|------|---------------|---------|
13
-
|**Read Architecture Guide first**| Before working with skills |`cat docs/architecture/SKILL_ARCHITECTURE_GUIDE.md`— L0-L3 hierarchy, SRP, Token Efficiency, Red Flags |
14
-
|**MANDATORY READ pattern**| File references in SKILL.md | Use `**MANDATORY READ:** Load {file}`. Passive refs (`See`, `Per`, `Follows`) are NOT followed by agents. Group multiple into ONE block at section start |
13
+
|**Read Architecture Guide first**| Before working with skills |`cat docs/architecture/SKILL_ARCHITECTURE_GUIDE.md`- L0-L3 hierarchy, SRP, Token Efficiency, Red Flags |
14
+
|**MANDATORY READ pattern**| File references in SKILL.md | Use `**MANDATORY READ:** Load {file}`. Passive refs are NOT followed by agents. Group multiple into ONE block at section start |
15
15
|**Path Resolution**| File paths in SKILL.md | Relative to skills repo root, NOT target project. Every SKILL.md with file refs includes `> **Paths:**` note after frontmatter |
| Built-in Grep |`hex-line grep_search`| Before editing found code (grep→edit pipeline) |
36
-
| Large code file |`hex-line outline` then `read_file` with range | Unfamiliar files >100 lines |
37
-
38
-
**Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json` and `.claude/settings.local.json`.
28
+
Prefer `hex-line` for code/config/script/test files.
29
+
- Use `outline` before large reads, then `read_file` with ranges.
30
+
- Use `edit_file` / `write_file` for writes, `bulk_replace` for multi-file text rename, `verify` after conflicts or delayed follow-up edits, and `changes` for diff review.
31
+
- Use `hex-graph` only for symbol, reference, architecture, and semantic diff questions.
32
+
- Built-in tools are still fine for images, PDFs, notebooks, Glob, and `.claude/settings*.json`.
39
33
40
34
## Quick Understanding
41
35
@@ -45,16 +39,16 @@ Skills collection for Gemini CLI with config-driven Agile task management (Linea
|**[hex-graph-mcp](mcp/hex-graph-mcp/)**| Indexes codebases into a deterministic SQLite graph with framework-aware overlays, capability-first quality tooling, optional SCIP interop, and architecture/reference analysis. | 14 |[README](mcp/hex-graph-mcp/README.md) · [npm](https://www.npmjs.com/package/@levnikolaevich/hex-graph-mcp)|
114
114
|**[hex-ssh-mcp](mcp/hex-ssh-mcp/)**| Hash-verified remote file editing and SFTP transfer over SSH. Normalized output for minimal token usage. | 8 |[README](mcp/hex-ssh-mcp/README.md) · [npm](https://www.npmjs.com/package/@levnikolaevich/hex-ssh-mcp)|
115
115
116
+
Deterministic scope rule: `hex-line` and `hex-graph` keep `path` as the project anchor. In normal use the agent fills it automatically from the active file or project root, so users usually do not need to type it manually. `hex-ssh` runs on Windows/macOS/Linux hosts; remote shell tools stay POSIX-oriented, while SFTP transfers support platform-aware remote paths.
@@ -152,17 +154,16 @@ claude mcp add -s user --transport http linear-server https://mcp.linear.app/mcp
152
154
153
155
### Agent steering
154
156
155
-
MCP servers are installed but Claude won't prefer them over built-ins by default. hex-line-mcp includes tools that teach the agent to use MCP:
157
+
MCP servers can be installed correctly and still lose to built-ins in practice. `hex-line-mcp` keeps Claude aligned through one output style and three Claude hook events:
156
158
157
159
| Mechanism | How it works |
158
160
|-----------|-------------|
159
161
|**[Output style](mcp/hex-line-mcp/output-style.md)**| Injected into system prompt — maps built-in tools to MCP equivalents (`Read` → `hex-line read_file`, `Edit` → `hex-line edit_file`) |
160
-
|**PostToolUse hook**| When Claude uses a built-in, the hook reminds it to use the MCP tool next time |
161
-
|**secret-scanner hook**| Blocks `git commit` if secrets detected |
162
-
|**story-validator hook**| Validates Story context before `ln-400` execution |
163
-
|**code-quality hook**| Reports DRY/KISS/YAGNI violations after Edit/Write |
162
+
|**SessionStart hook**| Injects a compact bootstrap hint and defers to the active `hex-line` output style when present |
163
+
|**PreToolUse hook**| Advises small `Read`/`Edit`, redirects heavier `Read`/`Edit` plus `Write`/`Grep`, selectively redirects simple Bash, blocks dangerous commands |
164
+
|**PostToolUse hook**| Filters only verbose Bash output (50+ lines), keeping first 15 + last 15 lines after normalization and dedupe |
164
165
165
-
Run `hex-line setup_hooks` to install all hooks + output style.
166
+
Hooks and output style auto-sync on `hex-line-mcp` startup. First run after install performs the initial sync automatically.
0 commit comments