Use when adding skill-behavior rules at Geniro skill phase boundaries OR cross-cutting code-style rules loaded at every code-writing/review step; also for declaring read-only fact-verification sources (## Data Sources) or routing the agent's memory/learnings through a custom backend like an MCP (## Memory Backend). Operations: list, create, edit, validate, delete. Skip for per-file-pattern rules — .claude/rules/.
Use when adding skill-behavior rules at Geniro skill phase boundaries OR cross-cutting code-style rules loaded at every code-writing/review step; also for declaring read-only fact-verification sources (## Data Sources) or routing the agent's memory/learnings through a custom backend like an MCP (## Memory Backend). Operations: list, create, edit, validate, delete. Skip for per-file-pattern rules — .claude/rules/.
[what you want — e.g. 'add a rule to run tests', 'show instructions', 'delete review rules']
Instructions: custom instruction management
3-phase stateless loop: Parse → Execute → Done. CRUD frontend over .geniro/instructions/ — the L4 procedural memory layer. Operations: list, create, edit, validate, delete. Stateless: every invocation is a single transaction; no state file.
Runtime portability.${CLAUDE_PLUGIN_ROOT} is set by Claude Code. When it is unset (another Agent-Skills runtime, e.g. Cursor), resolve it before following any reference: the plugin root is the ancestor directory of this file containing .claude-plugin/plugin.json — substitute it for every ${CLAUDE_PLUGIN_ROOT} occurrence and export it as CLAUDE_PLUGIN_ROOT in every Bash call. Tool and hook substitutions for non-Claude-Code runtimes: ${CLAUDE_PLUGIN_ROOT}/skills/_shared/runtime-portability.md.
Code rules split three ways depending on when they should fire:
.geniro/instructions/code-style.md — cross-cutting code-style rules that apply to all code writing AND all code review done by Geniro pipeline skills (loaded at code-writing/review phases regardless of file pattern).
.claude/rules/<scope>.md with paths: YAML frontmatter — file-pattern-scoped rules (Anthropic-native, auto-loads on matching glob — fires even outside Geniro pipelines).
CLAUDE.md — reserved for always-loaded essentials (commands, project structure, compaction-surviving gates) and should NOT carry code rules.
Loop invariants
Single transaction, no subagents — /geniro:instructions runs entirely in the orchestrator (CRUD is too small for parallelism).
Args validated before exec — every Write preceded by scope validation (regex match) AND file-existence check.
Permission before side-effect — Write/Delete are AUQ-gated.
Bounded structured results — list --with-content truncates per-file body display at ~2000 chars (base list shows only the name/size table).
Hard escalation gates — 3-retry on scope ambiguity → final AUQ abort.
Observations not assumed success — every Read/Write checks return status.
Errors as structured observations — surfaced inline in the final user message (no state file).
Budgets — quality-first
/geniro:instructions has zero hard kill caps. Soft gates: 3-retry scope ambiguity → final AUQ abort, list --with-content body truncation at ~2000 chars/file. Architecture constraints: stateless, no subagent spawns. NOT capped: number of scopes processed in batch mode, files in review-extra/, file size after edit, AUQ chain depth for scope picking.
Write, Edit (.geniro/instructions/* is a persistent-CRUD path — a direct write is hard-blocked by the state-helper hook; see Mode: create Step 5), Agent (no subagents), mcp__github__*, network egress
done
(terminal report)
(none)
External sends: not in /geniro:instructions ACI ever.
Termination case → state mapping
No state file, but failure paths report a structured reason in the final user message.
Cause
Format
User cancelled at any AUQ
aborted: user cancelled at <step>
Scope resolution failed after 3 AUQ retries
aborted: scope unresolved after 3 AUQ rounds
Validation found N issues, user picked "Abort"
aborted: validate surfaced N issues; user picked abort
Write blocked by file-protection hook
aborted: file-protection hook blocked write to <path>; see .geniro/safety.json
Delete blocked by .geniro/ deletion guard
aborted: .geniro/ deletion guard blocked rm of <path>; see .geniro/safety.json
Valid scope set
The stable scope set:
Scope
File path
Layer
Loaded by
Notes
global
.geniro/instructions/global.md
L4
Every pipeline + discovery skill at Step 0 + phase-boundary refresh
Rules and Constraints, plus the one cross-skill ### After worktree-setup event step
code-style
.geniro/instructions/code-style.md
L4
All code-writing skills (implement, refactor) AND all code-review steps (review, implement Phase self-review, refactor Phase verify); pre-inlined into reviewer-agent prompts for the conventions/design/architecture dimensions
Cross-cutting; no per-skill phase mapping
memory
.geniro/instructions/memory.md
L4
Every pipeline + discovery skill (and operational skills that emit L2) at Step 0 + phase-boundary refresh, loaded alongside global.md
Holds the ## Memory Backend block only — no Rules/Constraints/Additional Steps
Directory-style; one file per slug. Frontmatter: slug, description, model, paths, severity-default, requires-context
implement
.geniro/instructions/implement.md
L4
/geniro:implement at Step 0 + phase-boundary refresh
Additional Steps map to phase enum
plan
.geniro/instructions/plan.md
L4
/geniro:plan at Step 0 + phase-boundary refresh
Additional Steps map to phase enum
review
.geniro/instructions/review.md
L4
/geniro:review at Step 0 + phase-boundary refresh
Additional Steps map to phase enum
resolve
.geniro/instructions/resolve.md
L4
/geniro:resolve at Step 0 + phase-boundary refresh
Additional Steps map to phase enum
debug
.geniro/instructions/debug.md
L4
/geniro:debug at Step 0 + phase-boundary refresh
Additional Steps map to phase enum
refactor
.geniro/instructions/refactor.md
L4
/geniro:refactor at Step 0 + phase-boundary refresh
Additional Steps map to phase enum
onboard
.geniro/instructions/onboard.md
L4
/geniro:onboard at Step 0 + phase-boundary refresh
Rules and Constraints only
investigate
.geniro/instructions/investigate.md
L4
/geniro:investigate at Step 0 + phase-boundary refresh
Same as onboard
reflect
.geniro/instructions/reflect.md
L4
/geniro:reflect at Step 0
Rules and Constraints only (stateless — no Additional Steps)
Operational skills (/geniro:setup, /geniro:instructions, /geniro:actions, /geniro:update) do NOT load instruction files beyond global.md.
External instructions dir — read there, manage here. When an external instructions dir is configured (GENIRO_INSTRUCTIONS_DIR or the plugin's instructions_dir option), the pipeline skills' loader READS instruction files from that external location. /geniro:instructions CRUD (list / create / edit / delete / validate) still operates on the in-repo copy at the primary worktree root ("$PRIMARY_ROOT"/.geniro/instructions/) — the path keeps the literal .geniro/ segment, so the atomic-write helper and the .geniro/ deletion guard stay engaged; an external location would bypass both. To manage the external set, edit it directly at its path. The override covers the loaded instruction set (global.md, memory.md, code-style.md, and the per-skill <skill>.md); custom review-extra reviewers (review-extra/<slug>.md) are enumerated separately by ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-reviewers.md and are NOT redirected by the external override — they stay in the in-repo .geniro/instructions/review-extra/.
File shapes
Three shapes across the scope set. The schema itself is owned by the loader that parses these files at runtime — ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-instructions.md §Producer contract; the shapes below and the annotated templates are authoring scaffolds written against it, so a schema change lands there first. The templates for all three, plus the per-scope create scaffolds, live in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md §1 — read that section before rendering a scaffold or judging a body's structure.
Singleton scopes (global, code-style, every per-skill scope) — ## Rules, ## Additional Steps → ### After <phase-enum-value>, ## Constraints, and the optional ## Data Sources.
memory — its own .geniro/instructions/memory.md, carrying the ## Memory Backend block only; no Rules / Constraints / Additional Steps.
review-extra/<slug> — directory-style, one file per custom reviewer, with YAML frontmatter (fields below) plus a # Criteria body.
The optional ## Data Sources section declares read-only sources the verification step in /geniro:plan and /geniro:implement cross-checks load-bearing facts against (related-task chain statuses + the spec's cited claims). Each entry is a label + a (confirms: <fact kind>) hint + ONE source: a backticked read-only shell command, an MCP tool name, or an action name. The full contract — discovery, read-only screening, the max-source cross-check, and per-fact outcomes — lives in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/data-sources.md. Applies to global and the per-skill scopes; absent = no declared sources (verification falls back to the built-in code / git / tracker sources).
memory.md is loaded alongside global.md for every skill. The ## Memory Backend section routes the L2 learnings layer through a custom backend — typically a memory MCP — so agentic knowledge is stored/retrieved there instead of, or alongside, the built-in .geniro/knowledge/learnings.jsonl. Each entry names a layer (learnings), a mode (mirror = file + backend, the default; replace = backend only), and a write + read-only read MCP-tool (or action). The full routing contract — orchestrator-consumed at the emit-learning / query-learnings call-sites, redact-before-store, read-only-screened, fail-open to the file — lives in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/memory-backend.md. Absent file/block = built-in file, unchanged.
Frontmatter field reference (review-extra/<slug>.md)
The single source for every field's value set and length cap — validate-mode's per-scope check resolves here rather than restating them.
slug (required) — lowercase ASCII letters/digits/hyphens, regex ^[a-z][a-z0-9-]*$. Filename without .md must equal this. The slug must not match a built-in dimension name (bugs, security, architecture, tests, optimizations, conventions, regressions, design, pr-metadata, spec-compliance) or a retired-but-reserved name (guidelines, rules-compliance) — the loader treats a colliding slug as the built-in reviewer and the custom criteria silently never run. Keep this list in sync with ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-review-extra.md §Step 2 (Validate the slug), which runs the same collision check.
model (optional) — haiku/sonnet/opus/inherit; omitted = inherit (the reviewer runs at the orchestrator's tier, per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-reviewers.md). Declare a tier only to deliberately pin this reviewer cheaper or stronger than the session.
requires-context (optional) — natural-language directive naming the live external data this reviewer needs (a Notion page, a Linear issue, an API response). The reviewer runs in a subagent that can't call MCP, so the orchestrator pre-fetches the data and injects it as a CUSTOM CONTEXT: block at spawn time, failing open if it's unavailable (per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-reviewers.md §Hydrating requires-context). Omit unless the reviewer genuinely needs external data. Example: requires-context: "Fetch the live Notion Incident Report (latest entry) and provide its incident-pattern list."
Phase 1: Parse intent
Step 0 — Load custom instructions. Apply ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-instructions.md with SKILL_SLUG: instructions, LOAD_TIER: rules-only, MODE: initial-load. The helper's §Echo contract requires one observable line.
Step 0.5 — Locate the instructions directory. Compute PRIMARY_ROOT via the Mode A snippet from ${CLAUDE_PLUGIN_ROOT}/skills/_shared/primary-worktree.md, re-running it in every Bash call that uses the variable (Mode A owns the recompute-per-call rule); every .geniro/instructions/... path in the rest of this skill is prefixed "$PRIMARY_ROOT"/. Instruction files are cross-session content — a cwd-relative write from a linked worktree is lost when the worktree is removed. When PRIMARY_ROOT is not .: create/edit/delete success lines show the resolved absolute path, create/edit lines append — written to the main repo checkout so it survives this worktree's removal., and if a same-named file exists at the cwd-local .geniro/instructions/ path with different content, print one notice after create/edit: Note: this worktree has its own copy of <file>, which takes precedence here when rules load. Notice only — no question, no block.
Action detection
Intent
Aliases
Maps to
List
show, view, list, display, what instructions, current
list
Create
add, new, create, set up, start
create
Edit
change, modify, update, edit, tweak, adjust
edit
Validate
check, verify, validate, lint
validate
Delete
remove, delete, drop, clear
delete
If no arguments: default to list.
Scope detection
Explicit names: global, code-style, memory, review-extra, or a per-skill scope (implement, plan, review, resolve, debug, refactor, onboard, investigate, reflect)
When the block type is ambiguous, ask in the Step 4 interview; default a vague "add a rule" to ## Rules. The ## Additional Steps phase anchor must be a real phase-enum value for the scope (enums in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md §5) — for a /plan post-approval step use ### After user-approve. The sole exception is ### After worktree-setup: a cross-skill event anchor (hosted in global.md, not a per-skill file) that fires when any skill creates a new worktree rather than at a phase boundary.
Ambiguity resolution
Chain up to 3 AUQs across the stable scope set. Use a 2-level chain:
Level 1 — category:
Question: "Which instruction file scope?"
Options:
global — Project-wide rules loaded by every Geniro skill
code-style — Cross-cutting style rules for code writing AND review
memory — Memory-backend routing (## Memory Backend) in its own memory.md
Specific skill or review-extra — Pick from per-skill (9) or review-extra (custom reviewer)
If "Specific skill or review-extra", chain Level 2:
Question: "Which specific scope?"
Options:
review-extra (new custom reviewer) — Add a custom reviewer dimension (asks for slug)
implement / plan / review / resolve — Pipeline skills (chain to L2b)
Level 2b asks for the exact skill (2-3 options, fits in AUQ). Across the stable scope set the chain depth is fixed at 2-3 levels. Cap retry at 3 rounds; after the third, abort with "Could not narrow down — try /geniro:instructions list for the exact set."
Scope validation
Before proceeding, verify resolved scope(s) are valid. If any resolved scope is NOT in the stable scope set, AUQ to ask the user to pick from valid scopes. Do NOT create, edit, or delete files for invalid scopes.
For review-extra, slug-bearing variants of create/edit/delete ALSO require a <slug> argument. Resolve missing-slug cases:
create review-extra no slug → ask via AskUserQuestion "Other" path (free-form text).
edit review-extra / delete review-extra no slug AND one file exists → default to that file.
edit review-extra / delete review-extra no slug AND multiple files exist → AUQ which slug. If >4 files, chain follow-ups per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/per-finding-question.md cap-extension rule.
validate review-extra ignores slug — always validates the whole directory. Print one-line notice if a slug was passed.
If multi-scope, proceed to Batch Mode. Otherwise proceed to the resolved command section.
Phase 2: Execute (Mode dispatch, single-scope)
Branch to the matching ## — Mode: <op> section (list / create / edit / validate / delete).
Batch Mode
For multi-scope (e.g., "edit global and review", "add rules to all"), process each scope sequentially through the same command flow. Across the stable scope set the multi-scope chain stays under 4 AUQ rounds.
ls -la "$PRIMARY_ROOT"/.geniro/instructions/ 2>/dev/null
ls -la "$PRIMARY_ROOT"/.geniro/instructions/review-extra/ 2>/dev/null
Step 2 — Present results
If empty:
No instruction files found.
Run `/geniro:instructions create global` to create your first instruction file,
or `/geniro:instructions create code-style` for project-wide style rules.
Else, table format:
Custom instructions in .geniro/instructions/ (project: my-project):
global.md 348 B modified 3 days ago
code-style.md 1.2 KB modified 2 hours ago
memory.md (none)
implement.md (none — create with /geniro:instructions create implement)
plan.md (none)
review.md 892 B modified 1 week ago
resolve.md (none)
debug.md (none)
refactor.md (none)
onboard.md (none)
investigate.md (none)
reflect.md (none)
review-extra/ (directory — 2 files)
├── sql-bindings.md 1.6 KB modified 4 days ago
└── accessibility-aria.md 2.1 KB modified 1 day ago
13 scopes total · 4 active · 9 not-yet-created
Add --with-content flag to dump file bodies inline (truncated at ~2000 chars per file).
Read CLAUDE.md for tech stack/commands/conventions; check package.json/Makefile for scripts; check for ESLint/Prettier/tsconfig. This context informs scope-specific rule suggestions.
Step 4 — Scope-specific scaffold + interview
Each scope gets a scope-specific scaffold with example Rules to make the empty-file moment less confusing. The four scaffolds (code-style / implement / global / memory) plus their stub-inclusion notes live in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md §1 — render the matching scaffold before the interview.
Capture 1-2 follow-up answers via additional AUQs. Convert vague user input into strong, specific rules (e.g. "make sure we test" → "Always include tests for new public functions. Run npm test to verify before shipping").
Step 5 — Generate the file
Apply the writing principles in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md §2. Show preview via final AUQ Write scaffold? | Edit body before writing | Cancel. On write, route the file through atomic_state_write targeting "$PRIMARY_ROOT"/.geniro/instructions/<scope>.md per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/atomic-state-write.md — .geniro/instructions/* is a T3 persistent-CRUD path, so direct Edit/Write trips the state-helper enforcement hook.
Step 6 — Confirm
Print:
Created `.geniro/instructions/<scope>.md`
This file will be loaded by <affected skills list> at the start of each run.
Edit via `/geniro:instructions edit <scope>`; lint via `/geniro:instructions validate`.
For review-extra, follow the slug-bearing flow in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-review-extra.md.
If missing, branch to create. Else display current body inline.
Step 2 — Three-way AUQ
Question: "How would you like to edit <scope>?"
Options:
Open in editor (external) — Print absolute path; instruct user to edit externally and re-run /geniro:instructions validate <scope> when done. Exit.
Rewrite via dialogue — Interview-style sequence of AUQs (Add a Rule / Add an Additional Step / Add a Constraint / Remove a Rule by number / Done). Apply edits to an in-memory copy; final write AUQ-gated.
Cancel
The dialogue path is intentionally simpler than freeform edit — stays inside AUQ contracts and avoids prompt-injection through user-supplied text.
Step 3 — Re-validate (review-extra only)
After editing a review-extra file, re-run the lint rule set against the edited file. If any rule fails, AUQ revert vs keep-and-fix-later.
Step 4 — Show updated file
Updated `.geniro/instructions/<scope>.md`. The new rules take effect the next time you run `/geniro:<scope>` (or any affected skill for global.md), unless this worktree has its own differing copy of the file — that copy takes precedence here.
Body section invariants (post-edit)
## Rules section present (may be empty list).
## Additional Steps section present (omitted for the rules-only scopes code-style, review-extra/<slug>, onboard, investigate; for global the section is optional and, when present, carries only the cross-skill ### After worktree-setup event anchor).
## Constraints section present (may be empty list).
Violations are not auto-fixed; validate surfaces them on next invocation.
— Mode: validate
Step 1 — Scan + scope
validate accepts <scope> arg (validate one file) or no arg (validate all). Read-only; never mutates.
flag:--max-lines N overrides the default 300-LOC threshold (Step 2, matching the §File-size guidance split point). Use --max-lines 0 to disable the length check entirely. Env override: GENIRO_INSTRUCTIONS_MAX_LINES.
Step 2 — Lint rule set
Structural checks (apply to all scopes):
Check
Severity
Example violation
File parses as valid Markdown
CRITICAL
Binary file masquerading as .md
## Rules heading present (skip for memory.md — it carries the ## Memory Backend block only)
HIGH
File has body but no ## Rules header
## Constraints heading present (skip for review-extra/<slug>.md — uses # Criteria instead; skip for memory.md)
HIGH
Missing ## Constraints
File ≤ 300 lines (threshold env-overridable, see Step 1)
LOW
Anthropic Claude Code memory guidance: "longer files consume more context and reduce adherence". Surface suggested actions inline (split into topic-specific files OR trim redundant rules).
Reference checks:
Check
Severity
No references to dropped skills (/brainstorm, /decompose, /follow-up, /deep-simplify, /features, /learnings, /cleanup, /vendor)
HIGH
No references to dropped phase names (e.g., "Phase 4 (Implement)" — not a value in the current per-skill phase enums)
MEDIUM
Additional Steps subsections match per-skill phase enum (the cross-skill ### After worktree-setup anchor in global.md is the one non-phase exception)
MEDIUM
Per-scope checks:
Scope
Extra checks
review-extra/<slug>.md
Frontmatter parses as YAML and every field satisfies §Frontmatter field reference — the single source for the value sets and the description length cap. Severity: CRITICAL when slug fails its regex, mismatches the filename, or collides with a built-in dimension (the loader then silently runs the built-in and the custom criteria never fire); HIGH for any other field violation. Description quality is graded separately below.
code-style.md
At least 1 rule under ## Rules — LOW warning if empty (no-op file)
## Data Sources lint rules (applied to global.md and per-skill scopes when a ## Data Sources section is present):
Rule
Severity
A shell-command entry fails the read-only screen in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/data-sources.md §4 — it carries a mutating verb, hides its action behind command substitution / a wrapped CLI, or is a SQL command that is not SELECT-shaped (the screen's verb set is single-homed there; do not re-list it here)
HIGH — a mutating data-source command could run against production. Emit: "Data Sources entry <label> carries a mutating or un-screenable command — sources must be read-only (the verification step runs them automatically). Make it a read-only query or remove it (see ${CLAUDE_PLUGIN_ROOT}/skills/_shared/data-sources.md §read-only screening)."
A malformed entry — no source (missing the backticked command / MCP-tool name / action name), or no (confirms: ...) hint
MEDIUM — the entry can't be used. Emit: "Data Sources entry <label> is missing a source or a (confirms: ...) hint — each entry needs a label, a (confirms: <fact kind>) hint, and exactly one read-only source."
The HIGH severity matches the spec verify: read-only doctrine: a data-source shell command runs unattended during fact verification, so a mutating one is the same prod-risk class the /geniro:implement side-effect screen guards. ## Data Sources is optional — absence is not a finding.
## Memory Backend lint rules (applied to memory.md when a ## Memory Backend section is present):
Rule
Severity
A ## Memory Backend block in any file OTHER than memory.md (e.g. left in global.md or a per-skill file — those are not loaded for the memory layer)
MEDIUM — emit: "## Memory Backend belongs in the dedicated memory.md file; move it there or remove it."
memory.md carries ## Rules / ## Constraints / ## Additional Steps (the memory scope is for the backend block only)
LOW — emit: "memory.md holds the ## Memory Backend block only; put rules/steps in global.md or the per-skill file."
An entry missing layer, or layer not learnings (learnings is the only routed layer)
MEDIUM — emit: "Memory Backend entry needs layer: learnings (the only routed layer)."
mode present but not mirror / replace
MEDIUM — emit: "Memory Backend mode must be mirror or replace (default mirror)."
The read tool/command fails the read-only screen in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/data-sources.md §4 (the query op must be read-only; the write op is the declared mutator and is exempt)
HIGH — emit: "Memory Backend read must be a read-only query tool (it runs unattended during retrieval); make it read-only or remove it."
An entry missing write or read
MEDIUM — emit: "Memory Backend entry needs both a write and a read-only read tool."
## Memory Backend is optional — absence is not a finding (memory uses the built-in file).
Description quality rules — the shared source. Applied here to the description: of review-extra/<slug>.md; /geniro:actions validate runs the same three rows against an action's description:, so a severity change here changes both:
Rule
Severity
Describes intent rather than implementation
LOW
Mentions adjacent terms (e.g. for sql-bindings: "SQL", "ORM", "DAO")
LOW
Carries an explicit boundary clause ("Skip for …", "Not for …")
LOW
requires-context lint rules (applied to review-extra/<slug>.md):
Rule
Severity
Criteria body or description references live external data (mcp__, the words "Notion" / "Linear" / "Jira", "fetch from", "the API", or an http(s):// URL) but no requires-context: is declared
MEDIUM — emit: "Criteria reference live external data, but no requires-context: is declared. This reviewer runs in a subagent without MCP access and will see no external data — declare requires-context: so the orchestrator fetches it (see ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-reviewers.md §Hydrating requires-context)."
requires-context: present but not a non-empty string
HIGH
This is the guard that catches the silent-empty-findings trap at authoring time: a reviewer whose criteria say "match the diff against the Notion incident report" but which never declares the dependency will spawn into a subagent that can't fetch it, producing empty or hallucinated findings with no error.
Step 3 — Per-skill phase mapping
Read ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md §5 and check every Additional Steps subsection in the target file against the phase enum listed there for its scope, including the severities for free-form and dropped-phase anchors. That section is the single source; the one exception it records is ### After worktree-setup, a cross-skill event anchor valid only in global.md.
Step 4 — Count caps (review-extra)
Soft warning if >6 files: ⚠ Count {N} exceeds the 4-6 sweet-spot — consider consolidating overlapping reviewers.
Hard error if >10 files: ✗ Count {N} exceeds hard cap of 10 — the loader will refuse to load all reviewers.
These thresholds (sweet-spot 4-6, hard cap 10) mirror the create-flow caps defined canonically in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-review-extra.md §Step 3 AND the runtime enforcer ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-reviewers.md §Step 6 (which actually aborts the review past the cap) — change all three together so the create-flow, validate-mode, and enforcer caps never diverge.
Step 5 — Output format
$ /geniro:instructions validate
Validation results: 4 files checked, 3 issues found.
✓ global.md no issues
⚠ implement.md 1 MEDIUM
└── Line 14: "### After Phase 4 (Implement)" → should be "### After implement"
⚠ code-style.md 1 LOW
└── File is 380 lines (>300). Anthropic guidance: longer files reduce adherence.
Suggestions: split into code-style-database.md + code-style-api.md, or trim redundant rules.
⚠ review-extra/sql-bindings.md 1 LOW
└── Frontmatter description: missing "Skip for" boundary clause (LOW)
To fix: /geniro:instructions edit implement
/geniro:instructions edit code-style
/geniro:instructions edit review-extra sql-bindings
Exit status: 0 if no CRITICAL/HIGH; non-zero otherwise. MEDIUM/LOW are warnings.
No auto-fix
validate reports; it does not mutate. Auto-fix would silently rewrite user-authored instruction content, which is never overwritten without explicit user action.
— Mode: delete
Step 1 — Resolve + read existing file
If missing: print "nothing to delete" and exit. Else continue.
Step 2 — Confirm
AUQ 2-option: Confirm delete / Cancel. Show file size + last-modified for context. For review-extra/<slug>.md, the slug must be specified (no bulk-delete).
Step 3 — Execute
rm -f "$PRIMARY_ROOT"/.geniro/instructions/<scope>.md
# OR for review-extra:rm -f "$PRIMARY_ROOT"/.geniro/instructions/review-extra/<slug>.md
The .geniro/ deletion guard hook allows per-file rm -f of .geniro/instructions/<scope>.md (per the hook's "Per-file rm -f remain allowed" rule); only bulk rm -rf .geniro/instructions/ is blocked.
For review-extra ALL: explicitly refused with "Use /geniro:instructions delete review-extra <slug> per-file; bulk delete protected by guard hook."
Memory I/O
/geniro:instructions is the CRUD frontend for L4 (procedural memory).
Layer
Read
Write
Notes
CLAUDE.md (not a memory layer)
not read
not written
That's /geniro:setup's domain
L2 learnings.jsonl
not read
not written
/geniro:instructions is a CRUD frontend, not a knowledge-emit producer
L3 semantic files
not read
not written
Out of scope
L4 .geniro/instructions/*.md
list reads all; validate reads target; edit reads target before mutation
create/edit write; delete removes
This is /geniro:instructions's entire surface
compaction-survival route:.geniro/instructions/*.md files are file-on-disk. After compaction, the SessionStart hook's suggested-file list re-reads global.md + active skill's <skill>.md + code-style.md via _shared/load-custom-instructions.md. /geniro:instructions's CRUD writes are immediately durable.
Writing effective instructions
Rule / step / constraint writing principles, file-size guidance, and the what-goes-where routing table (.geniro/instructions/ vs .claude/rules/ vs CLAUDE.md) live in ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md §2-§4. Read them before authoring any instruction body at create/edit time.
Custom reviewer authoring (review-extra)
Companion file: ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-review-extra.md. Read before creating or editing any .geniro/instructions/review-extra/<slug>.md.
Anti-rationalization
Reasoning
Why it's wrong
"I'll auto-fix validate issues to save the user a step"
No — auto-fix would silently mutate user-authored content. validate reports; user fixes via edit.
