Markdown with frontmatter, shaped so the next agent can act on it.

Frontmatter is what the product reads: who a guide is for, what it is, and what the author's machine was. Everything under it is for the reader.

id

8 characters from a no-lookalike alphabet. An address, not a secret.

title

What the work accomplishes, as a verb phrase. It is the line in an inbox.

kind

transfer (or absent), bug or task. Read it before acting.

created

When it was written. Stamped for you; the reader uses it to judge the stack.

author

Who wrote it, from git. Who to ask when the guide turns out to be wrong.

source_context

The project and branch the work was done in, as repo@branch.

status

draft or published; consumed is the author's shelf.

team

The team it is shared with, by slug. Without one it is yours alone.

to

@handle asks one person; #group asks the people who do a thing.

stack_assumptions

A list. The author's environment, to adapt rather than copy.

tags

A list.

report, area, severity

Bugs only. severity runs s1 (blocker) to s4 (cosmetic).

target_context

Tasks only. The repo the work is for, as owner/repo. Empty is a task for no repo.

blocked_by

Tasks only. A list of task ids it waits for; it is not handed out until each is approved.

The receiver follows Steps, adapting anything the author marked as an assumption to the codebase in front of it, runs Verification before saying it worked, and answers — which is the half that makes the next guide better.

## Problem

What was actually wrong. Required.

## Solution shape

The approach, not a diff.

## Decisions and rationale

What was chosen over what, and why.

## Steps

What to do. Required.

## Verification

How to know it worked. A guide without it is flagged to the reader.

## Gotchas

What failed on the way. The highest-value section.

Reproduce, not Steps, and the difference is load-bearing: Steps is the heading an agent is told to execute, and steps that produce a defect are the one list that must never be run as a remedy. An agent that confuses them reproduces the bug, checks Verification, finds it false because the bug is real, and reports the guide as broken.

## Problem

What is wrong.

## Reproduce

How to see the bug. Running it produces the bug; it is not a remedy.

## Verification

The behaviour that should have happened.

## Gotchas

What made it hard to see, and what a fix must not break.

A task is written before any work exists. It has no Steps: the agent that takes it works out how to reach Goal within Constraints, and a person approves the result against Acceptance. What the agent did comes back as a transfer guide.

## Goal

What is true when this is done. Required.

## Context

What the agent needs to know first: where the code is, what exists.

## Constraints

What must not change, and what to use or avoid.

## Acceptance

Checks a person can run. What the work is approved against. Required.

## Out of scope

What looks related and is not part of this task.

Every kind is worked with the same four calls, and each answer ends with what to call next. Write tasks with plan_tasks.

take

Say you are doing it, and get it: by id, or the next one waiting. Nobody else can take it there while you hold it.

progress

A one-line note at each milestone. Thirty minutes without one marks it stalled.

hand_in

Done here, with evidence: what you ran and what came back. A task hands in a write-up too, for its author to review; a handoff or a bug, whether it worked.

pass

Not yours, or stuck: give it back with the reason for whoever is next.

A follow-up is a whole guide — its own id, its own link, its own verdicts — with parent set to the guide it adds to. It is listed under the original, and whoever opens the original gets it too, person or agent. Where the two disagree, the follow-up is the newer fact.

---
title: Verify Paystack webhooks before trusting them
kind: transfer
author: Ada Lovelace
source_context: acme/shop@main
stack_assumptions:
  - Cloudflare Workers, Hono 4
  - Paystack, live keys in wrangler secrets
tags: [webhooks, payments, security]
---

## Problem

Any POST to /webhooks/paystack was treated as real, so a forged body could mark an order
paid. It showed up as one order paid twice, from two different IPs.

## Solution shape

Verify the signature before reading the body, with the raw bytes rather than the parsed
JSON — re-serialising changes the bytes and the HMAC never matches.

## Decisions and rationale

- **Verify in the route, not in middleware**, because only this route has the secret.
- **Chose HMAC over an IP allowlist**: Paystack's egress addresses change without notice.

## Steps

1. Read the raw body: `const raw = await c.req.text()`.
2. HMAC-SHA512 it with PAYSTACK_SECRET and compare, in constant time, to the
   `x-paystack-signature` header.
3. Refuse with 401 before parsing. Only then `JSON.parse(raw)`.

## Verification

```sh
curl -X POST localhost:8787/webhooks/paystack -d '{"event":"charge.success"}'   # 401
npm test -w apps/api -- webhook                                                # 6 pass
```

## Gotchas

Comparing with `===` leaks where two signatures diverge, one character at a time. Use a
constant-time compare. And Paystack sends a test event on save: it is signed with the same
secret, so a 401 there means the secret is wrong, not that the check works.

• One problem per guide. A session that solved three things is three guides.
• Write Verification first. If you cannot say how to check it, the guide is not ready to send.
• Gotchas is worth more than Steps. Steps can be re-derived. The dead end that cost an hour cannot.
• Say what your environment was rather than assuming the reader shares it.