instructions

name	instructions
description	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/.
context	main
model	inherit
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","AskUserQuestion"]
argument-hint	[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

1. Single transaction, no subagents — /geniro:instructions runs entirely in the orchestrator (CRUD is too small for parallelism).
2. Args validated before exec — every Write preceded by scope validation (regex match) AND file-existence check.
3. Permission before side-effect — Write/Delete are AUQ-gated.
4. Bounded structured results — list --with-content truncates per-file body display at ~2000 chars (base list shows only the name/size table).
5. Hard escalation gates — 3-retry on scope ambiguity → final AUQ abort.
6. Observations not assumed success — every Read/Write checks return status.
7. 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.

ACI surface per phase

Phase	Allowed tools	Forbidden tools
parse	Read, Bash (read-only: ls, cat, find, grep), Glob, AskUserQuestion	Write, Edit, mutating Bash, all mcp__*, network
execute	Read, Bash (atomic_state_write, mkdir -p, rm after AUQ confirm), Glob, Grep, AskUserQuestion	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
review-extra/<slug>	.geniro/instructions/review-extra/<slug>.md (directory-style)	L4	/geniro:review Phase llm-spawn, /geniro:implement Phase self-review, /geniro:refactor Phase verify via ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-reviewers.md	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.
• description (required) — one-line summary, ≤250 chars.
• 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.
• paths (optional) — list of globs.
• severity-default (optional) — CRITICAL/HIGH/MEDIUM/LOW; default MEDIUM.
• 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)
• Contextual: "add a rule to review" → scope=review · "create debug instructions" → scope=debug · "code-style" / "style" / "naming conventions" → scope=code-style · "custom reviewer" / "review dimension" → scope=review-extra
• Explicit slug form: review-extra <slug> (e.g., review-extra sql-bindings)
• Multi-scope: "all", "every", "global and review" → collect into list
• "all" / "every" → expand to all valid scopes that have existing files (for edit/validate/delete) or all valid scopes (for create)

Block-type detection (which section the request fills)

A create/edit request implies WHICH block to author, not just which scope. Map the user's intent to the block type so the right section is filled:

User intent (examples)	Block type	Scope
"always do X" / "never Y" / a standing rule	## Rules	the named/contextual scope
"run X after <phase>" / a project-specific post-phase step (e.g. duplicate the plan into OpenSpec, archive after ship)	## Additional Steps → ### After <phase-enum-value> (e.g. ### After user-approve for /plan, ### After ship for /implement)	the per-skill scope
"run X every time a new worktree is created" / a per-worktree workspace bootstrap (e.g. build a per-worktree code index for an MCP)	## Additional Steps → ### After worktree-setup (a cross-skill event anchor, not a phase)	global
"hard limit" / "must not exceed" / a gate	## Constraints	the named scope
"verify facts against my " / "cross-check status from <db/MCP>"	## Data Sources (per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/data-sources.md)	global or per-skill
"change how memory/knowledge works" / "store learnings in my MCP" / "use a custom memory backend"	## Memory Backend (per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/memory-backend.md)	memory (its own dedicated file)

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)
• debug / refactor — Pipeline skills (chain to L2b)
• onboard / investigate / reflect — Discovery 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.

Print summary after all scopes complete:

## Batch Complete

| Scope | Action | Result |
|-------|--------|--------|
| global | edit | Updated — added 2 rules |
| review | edit | Updated — added 1 constraint |

— Mode: list

Step 1 — Scan directory

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).

— Mode: create

Step 1 — Check for existing file

cat "$PRIMARY_ROOT"/.geniro/instructions/<scope>.md 2>/dev/null

If file exists: AUQ "File exists — overwrite, edit instead, or cancel?". Branch accordingly.

Step 2 — Ensure directory exists

mkdir -p "$PRIMARY_ROOT"/.geniro/instructions
mkdir -p "$PRIMARY_ROOT"/.geniro/instructions/review-extra # if scope == review-extra

Step 3 — Gather project context

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.

Use AskUserQuestion after showing the scaffold:

• Question: "Add what kind of rules?"
• Options (scope-tailored): Documentation / Quality gates / Workflow steps / Free-form (Other path)

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.

— Mode: edit

Step 1 — Resolve scope (Phase 1) + Read existing file

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).
• Frontmatter (for review-extra/<slug>.md) parses YAML cleanly.

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.

Clean up empty parent dirs silently:

rmdir "$PRIMARY_ROOT"/.geniro/instructions/review-extra/ 2>/dev/null
rmdir "$PRIMARY_ROOT"/.geniro/instructions/ 2>/dev/null

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.
"I'll silently overwrite existing instruction file"	No — for create on existing, present overwrite/edit-instead/cancel via AUQ.
"I'll skip the per-skill phase-enum check because the user said ### After Phase 1"	No — old enums fail silently in the loader. Validate-mode catches and suggests the canonical name.
"I'll spawn a subagent to do the freeform rule synthesis"	No — /geniro:instructions is a small CRUD frontend; subagents add no parallelism benefit and complicate the stateless single-transaction model.
"I'll output the questions as plain text instead of AskUserQuestion"	No — every WAIT gate uses AskUserQuestion.
"I'll rename a per-skill scope to something custom (e.g., implement → my-flow)"	No — scope names are fixed; pick from the stable scope set.
"I'll skip showing the scope-specific scaffold to save tokens"	No — scaffolds make the empty-file moment less confusing; they're not optional.

Definition of done

• Intent detected from freeform arguments (or default to list)
• Scope(s) resolved — single or batch — within 3 AUQ retry cap
• File operations completed successfully
• User confirmed before any destructive operation (delete)
• Validation checked structure, phase names, scope validity, dropped-skill refs, and description rules
• All user interactions used AskUserQuestion — no plain-text questions
• review-extra files validated against slug uniqueness, built-in collision, model/severity-default value sets, paths syntax, and count caps
• Scope-specific scaffold shown on create (not skipped)

Cross-references

• ${CLAUDE_PLUGIN_ROOT}/skills/_shared/state-tier-spec.md — T3 persistent-CRUD tier for .geniro/instructions/ and the optimistic mtime check
• ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-instructions.md — the L4 procedural-memory loader for .geniro/instructions/*.md
• ${CLAUDE_PLUGIN_ROOT}/skills/_shared/atomic-state-write.md — write helper for instruction files
• ${CLAUDE_PLUGIN_ROOT}/skills/instructions/instructions-authoring-reference.md — file shapes, create scaffolds, writing principles, and the per-skill phase enums validate-mode checks Additional Steps anchors against (§5)
• /geniro:actions — its validate mode reads the §Description quality rules table above as its source for those three rows