pi-agents-config: Skill for Claude Code

Write Todos

Write todos that a worker agent can execute without access to the planning conversation. Every todo must be self-contained — a worker reading only the todo and the plan artifact must produce the correct result.

Why This Matters

Workers implement exactly what's described. If a todo contains a code sketch using plain classes, the worker builds plain classes — even if the plan says "use functional code for everything." Architectural intent that only lives in the plan's prose gets lost. Every constraint must be in the todo body itself.

Todo Structure

Every todo body follows this structure:

**Plan:** `plans/YYYY-MM-DD-<name>.md`

## What
[One paragraph: what this todo produces and why it matters]

## Constraints
- [Explicit architectural constraints that MUST be followed]
- [Libraries/patterns to use — or explicitly NOT use]
- [Reference existing code patterns: "Follow the pattern in src/foo.ts"]

## Files
- `src/path/to/file.ts` — [what this file does]
- `src/path/to/other.ts` — [what this file does]

## Expected Outcome
[Concrete description of what the finished code looks like]

### Example
[Short code snippet showing the expected shape — imports, key patterns, structure]

## Acceptance Criteria
- [ ] [Specific, verifiable criterion]
- [ ] [Another criterion]
- [ ] [Build/lint/test passes]

Rules

1. Constraints Are Explicit, Not Implied

If the plan says "use Effect v4 for all services," every service todo must repeat that:

Bad (implicit)	Good (explicit)
"Build the EventBus service"	"Build the EventBus as an Effect v4 service. Import from effect. Use Effect.gen, Layer, and Context.Tag — not plain classes."
"Add WebSocket support"	"Add WebSocket support using the ws package. Do NOT use socket.io."
"Create the component"	"Create the component using React 19 + Tailwind v4 utility classes. No CSS modules, no styled-components."

2. Examples Show The Real Shape

Include a short code snippet showing the expected import style, patterns, and structure. This is the single most effective way to prevent drift.