/hook-plan

Plan a version-2 business hook. Do not write hook files.

Outcome

You hold {collection}-{slug}-hook-plan.md. The hook .ts is unchanged.

Assumptions

• The work is one hook. If more than one hook must change, use /logic-plan.
• Skill file: .agents/skills/hook-plan/SKILL.md

Non-goals

• Do not call create_hook, scaffold, or edit *.hook.ts.
• Do not run the coder implement station.
• Do not emit hook source.

Contract

Grain is one business hook. The skill plans the hook. It does not implement the hook.

Pass 0 is local intake. Pass 1 binds job. Pass 2 calls MCP and writes the hook-plan.

Pass 2 is illegal until job is a Pass 2 job. Skip does not bind a job.

Accuracy in Pass 2 requires MCP evidence, exactly one pattern, Pattern grammar order, replay, and transaction.

Syntax

The first message does not name a job. It does not name a type.

/hook-plan uses Ground: for operands. It does not use Problem: or Open:.

Label	Holds	Must not hold
Ground:	@*.hook.ts, *-hook-plan.md, or collection/slug	verbs, job names, option lists

At most five Read calls. Zero reads are legal.

/hook-plan

Ground: warehouse/freeze-bin

∞AgentExtra High

If the slash name does not start the skill, put @.agents/skills/hook-plan/SKILL.md on line 1.

Expected result: An <intake> block. Then the question: what job is this run? Select a live job in the question box.

Question

What job is this run?

1. Aimpact — a user story that may have upstream/downstream blast
2. Bpatch — a change to the seen hook
3. Cspawn — a new hook
4. Dretire — unwiring or deleting the seen hook
5. Eexplain — reading the seen stream with no change planned

SkipContinue↵

Fields

Passes

Pass	Name	Tool budget	Enters when
0	local intake	at most five Read	skill invoked
1	job bind	none	Pass 0 filled seen / kind
2	MCP and plan	MCP + path-load	job is a Pass 2 job

No MCP in Pass 0 or Pass 1.

Job catalog

job	Pass	Prepares
impact	2	a user story that may have upstream/downstream blast
patch	2	a change to the seen hook
spawn	2	a new hook
retire	2	unwiring or deleting the seen hook
explain	1 terminal	read the seen stream with no change planned
handoff-logic-plan	1 terminal	plan many documents and hooks in order
handoff-discovery	1 terminal	find facts first
handoff-critic	1 terminal	audit the hook-plan that exists

Live subset

Pass 0	live
seen=none	spawn, handoff-discovery
kind=hook.ts or named collection/slug	impact, patch, spawn, retire, explain, handoff-logic-plan
kind=hook-plan.md	patch, spawn, handoff-critic

Several hooks or order-of-work → handoff-logic-plan. Do not add jobs outside the catalog.

patch / explain: understand the seen execute() stream only. Do not traverse callee hooks or actions in that step. Extract, split, and reclassify are flavors of patch, not extra jobs.

spawn: a seen hook is a reference only. Do not treat it as the artifact to change.

Pass 2 rules (load, do not recopy)

1. .agents/rules/mcp.md
2. .agents/rules/logic/thinking.md — a hook plan is scope=IN
3. .agents/rules/hook-utils-mcp.md
4. .agents/rules/hook-utils-forbidden-constraints.md
5. .agents/rules/hook-utils-patterns.md
6. .agents/rules/logic/grill.md
7. .agents/rules/hook/coder.md
8. selected authoring specialist from .agents/rules/hook-utils-patterns.md
9. .agents/rules/query/api.md and/or .agents/rules/query/bulk.md as the hook requires
10. .agents/skills/hook-code-style/SKILL.md

Coder stations allowed: preflight, discover, gate_domain, gate_requirements, classify_pattern, sample_exemplars.

Banned station: implement.

The coder rule does not load thinking.md. This skill does, in Pass 2 only.

Pass 2 output

Write {collection}-{slug}-hook-plan.md with all of:

• Pattern decision and rejection of narrower or wrong patterns
• Evidence ledger (VERIFIED / INFERRED / UNKNOWN)
• Decorator fields (idempotent, concurrency, timeout) with justification
• execute() phase list matching Pattern grammar
• Result contract (ok + data)
• Replay, transaction, error policy
• Downstream calls
• Open questions

Then tell the user to run /hook-plan-critic.

Pass 1 intake

<intake>
- seen: none | <path> | <collection/slug>
- kind: hook.ts | hook-plan.md | named-in-prompt | none
- live: comma-separated job ids
- recommend: one live job
</intake>

Constraints

• Choose exactly one LogicHookPattern. Counterexample the others.
• Mapping execute() onto the selected Pattern grammar is mandatory. Reorder is a BLOCKER.
• Every required identity, field, status, key, or relationship that is UNKNOWN must be asked.
• If required MCP tools are missing, stop. No filesystem fallback for what MCP owns.
• English in the skill must obey ASD-STE100. TypeScript, EBNF, paths, MCP names, and catalog tokens stay unchanged.

Errors

Problem	Cause	Action
Tools start in Pass 0	Verb or job in the first message	Keep only paths under Ground:
More than one hook must change	Wrong grain	Call /logic-plan
Only some files read	More than five @ files	Remove files
Grammar order unbound	Phases do not match Pattern grammar	Bind order before COMMIT
Required slot invented	UNKNOWN filled without evidence	Ask. Do not invent

Related

• /logic-plan for many documents and hooks
• /hook-plan-critic after the hook-plan file exists
• /hook-code-style