Plan one hook

Design one hook. Do not write TypeScript in this skill.

Outcome

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

Prerequisites

• The work is one hook. If more than one hook must change, stop. Use Plan the workspace.
• /hook-plan or @.agents/skills/hook-plan/SKILL.md

hook-plan starts with a local intake. It does not call MCP until the job is impact, patch, spawn, or retire. explain and handoff never call MCP.

First message

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:, Open:, or Plan:.

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

Maximum 5 @ files.

/hook-plan

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

Empty call

/hook-plan

The skill must not call MCP. It replies with one new fill-in instruction. The instruction is generated for this turn. It is not copied from this page.

Send the message again.

Ground:
<one new @hook-path or collection/slug>

Minimal example

/hook-plan

Ground:
warehouse/freeze-bin

Expected result: The skill asks what job this run is. Select the choice in the question box.

Ground: examples

One file, no label

/hook-plan
@apps/api/src/app/hooks/manufacturing-production-reporting/validate-production-report/validate-production-report.manufacturing-production-reporting.hook.ts

One file, labeled

/hook-plan

Ground:
@apps/api/src/app/hooks/payment-log/process-bank-import/process-bank-import.payment-log.hook.ts

Name only

/hook-plan

Ground:
warehouse/freeze-bin

Two files

Do not say which file is primary in this message.

/hook-plan

Ground:
@apps/api/src/app/hooks/inventory-management/receive-transfer/receive-transfer.inventory-management.hook.ts
@apps/api/src/app/hooks/inventory-management/update-shipping-and-invoicing-statuses/update-shipping-and-invoicing-statuses.inventory-management.hook.ts

Family of names

/hook-plan

Ground:
@apps/api/src/app/hooks/procurement/create-purchase-order/create-purchase-order.procurement.hook.ts
procurement/create-drop-ship-purchase-order
procurement/create-purchase-order

Hook and a hook-plan file

/hook-plan

Ground:
@apps/api/src/app/hooks/finance-reports/account-credit-exposure-report/account-credit-exposure-report.finance-reports.hook.ts
@finance-reports-account-credit-exposure-report-hook-plan.md

Five files (maximum)

If you have more than 5 files, remove one file. Do not add comments.

/hook-plan

Ground:
@apps/api/src/app/hooks/payment-log/process-bank-import/process-bank-import.payment-log.hook.ts
@apps/api/src/app/hooks/warehouse/freeze-bin/freeze-bin.warehouse.hook.ts
@apps/api/src/app/hooks/inventory-management/receive-transfer/receive-transfer.inventory-management.hook.ts
@apps/api/src/app/hooks/manufacturing-production-reporting/validate-production-report/validate-production-report.manufacturing-production-reporting.hook.ts
@payment-log-process-bank-import-hook-plan.md

After the question

The skill asks: what job is this run? Select the choice in the question box.

The samples below assume Ground: was payment-log/process-bank-import.

explain

Read the execute() stream. No MCP. No plan file.

patch

Change this hook. Stream first. No callee hooks in that step.

After you select patch, send the change in the next message. Example for manufacturing-production-reporting/validate-production-report (pattern: 'validator'). Mix %, scrap/downtime reasons, hours, over/under — gated by manufacturing/settings + work center.

New rule: if mix-percentage policy is strict, reject mix total outside
100 ± 0 (not the tolerance path). Pattern stays `validator`.
Clarify every UNKNOWN. Do not edit the hook.

Then criticize:

/hook-plan-critic

Ground:
@payment-log-process-bank-import-hook-plan.md

If critic is PASS, go to Implement and review.

spawn

A new hook. The attached hook is a reference only.

After you select spawn, send collection, slug, and the insert family. Example neighbor of procurement/create-purchase-order:

New hook, collection procurement, slug create-drop-ship-purchase-order.
Same insert family as procurement/create-purchase-order, but always
draft — no bob.options.status override. Classify pattern. Grammar order.
Unknowns as questions.

Then audit:

/hook-plan-critic

Ground:
@procurement-create-drop-ship-purchase-order-hook-plan.md

Redundancy vs procurement/create-purchase-order. Blast radius. Style.

impact

Graph of callers and callees for a situation that may touch this hook.

If more than one hook must change, stop. Use Plan the workspace.

/logic-plan

Problem:
want: bank import rejects a duplicate hash before a payment-log row is created
got: a second row is created with the same hash

retire

Remove this hook. Disconnect callers.

Named handoff

Each option names who receives the work.

handoff to logic-plan — many documents and hooks, order of work.

/logic-plan

Problem:
want: bank import rejects a duplicate hash before a payment-log row is created
got: a second row is created with the same hash

handoff to logic-discovery — find facts first. .agents/skills/logic-discovery/SKILL.md

handoff to hook-plan-critic — audit the hook-plan that exists. .agents/skills/hook-plan-critic/SKILL.md

Two files

You want	Select
Change one hook	patch
Make a new hook from both	spawn
Put methods from both into one new hook	spawn
Find the effect of one hook	impact
Only read the streams	explain

Checks

• The first message has no job name.
• Empty /hook-plan gets a generated Ground: fill-in, not MCP.

If a problem occurs

Problem	Cause	Action
Tools start at once	Verb or job in the first message	Keep only paths under Ground:
Skill recites inspect / create / update	Option list in the prompt	Use an example from this page
Only some files read	More than 5 @	Remove files
No hook found	@ not in the message	Put the file under Ground:
Problem: used on hook-plan	Wrong altitude	Use Plan the workspace, or move the path to Ground:

Next

• Implement and review after critic PASS
• Run the pipeline for a full walk