pi-the-giver

"If you're going to receive memories, they should be whole memories." — Lois Lowry, The Giver

A Pi coding-agent skill that orchestrates a coding task across a Planner + N Workers pipeline with strict context isolation. You talk to Giver; Giver delegates. Giver never edits code — it is the memory keeper that distills context into task briefs and hands them to fresh, scope-bound Workers.

Install

pi install npm:@sng2c/pi-the-giver

Activate

/skill:giver

Or add it to your project instructions (.pi/AGENTS.md) so it activates automatically for coding tasks.

Quick start

Use the giver skill to implement a user authentication module with login, signup, and password reset

Giver will run a Planner → Workers pipeline: write Task #0, call Planner standalone for the exact Worker count N, build a foreground chain of N Workers, then verify and report.

The metaphor — why "The Giver"

In Lois Lowry's The Giver, one Receiver of Memory holds all of society's memories. Everyone else lives in Sameness — no history, no context, no accumulated noise. The Receiver transmits only what's needed, when it's needed. The giving of pain — legacy's hard truths, failures, constraints, things never to repeat — is distilled and injected into a blank-slate Receiver.

The skill is the novel, mapped onto a coding agent:

| Novel | Giver skill | |---|---| | Receiver holds all memories | Giver holds all conversation context | | Community lives in Sameness | Workers and Scout run fresh — zero history | | Receiver transmits only selected memories | Planner/Workers receive only T₀ / task files | | Giving of pain — failures, constraints, never-repeat | Past failures + Constraints injected into T₀ | | Memories never leak downward | Giver's conversation never crosses an agent boundary | | Receiver transmits; does not fix the world | Giver delegates; never edits code directly |

The architecture is not a dressing on top of the skill — the skill is the metaphor. Giver is the memory keeper; every downstream agent is a blank-slate Receiver that gets only the distilled essentials.

Why it's efficient — context isolation + separation of concerns

A coding agent reads files, writes code, and runs tests at every step. This coding I/O (source, test output, error logs) accumulates, and context grows exponentially:

$$ |\text{context}(n)| = |\text{context}(1)| \cdot r^{n-1} \quad (r > 1) $$

As context grows, steering — the directional instructions ("make this file, fix that error", "use approach Y only when Z") — drowns in coding-I/O noise. The agent loses direction: modifying the wrong file, retrying an already-fixed error, drifting from the goal.

Giver attacks this on two orthogonal axes.

Axis 1 — Context isolation (across agent boundaries)

Decompose context into steering (directional instructions) and coding I/O (execution artifacts). Only steering crosses an agent boundary. The coding I/O stays inside the agent that produced it.

• Giver's full conversation (~500K tokens of decisions, back-and-forth, discarded attempts) never reaches a Worker.
• Each Worker runs fresh and emits a tiny RESULT — Files / Signatures / Breaking / Summary, no code bodies, no test output.
• The next Worker receives prior RESULTs through structural injection (the framework's [Read from:] prefix on results.md), not the full execution trace of its siblings.

| Boundary | Crosses (steering) | Isolated (coding I/O) | Isolation | |---|---|---|---| | G → P | T₀ | Giver conversation | ~99% | | P → Wₖ | taskₖ.md | Other Workers' tasks | 83–93% | | Wₖ → G | RESULT | Full Worker execution | 98–99% |

Isolation = 1 − (transmitted size / un-isolated context size).

Axis 2 — Separation of concerns (within the pipeline)

Each role owns exactly one concern and carries no other's I/O:

| Role | Context | Owns | Does not do | |---|---|---|---| | Giver | conversation | decisions → T₀ | edit code | | Planner | fresh | curate task files + exact N + layer order | implement | | Scout | fresh | recon → signatures | implement | | Worker | fresh | its scoped files + self-verification | touch others' scope |

Because concerns are separated, a Worker's context never bloats with another agent's decisions or execution. Because agents are isolated, the pipeline's total context grows additively (sum of small fresh contexts), not exponentially (one snowballing transcript).

Structural, not instructional

results.md flows to downstream Workers via the framework's [Read from: <chainDir>/results.md] prefix — not by asking Workers to "please forward your output." The pipeline's correctness does not depend on an agent faithfully echoing prose. Structure over instruction: the mechanism works whether or not the agent is polite about it.

Pipeline

Request → Giver (Discuss/Decide) → T₀ → Planner (standalone, fresh) → Plan (exact N + task files)
                                              ↓
                       Giver builds a foreground W×N chain
                                              ↓
   W₁ (reads task1.md)                → RESULT #1 → results.md
   W₂ (reads task2.md + results.md)   → RESULT #2 → results.md
   …                                   …
   W_N                                 → RESULT #N → results.md   → chain completes naturally
                                              ↓
                       Giver reads results.md, verifies, reports

• Scout is called standalone by Giver before the chain when signatures/target files need recon.
• Planner runs standalone (out of the chain) and returns the exact count N + dependency-layer ordering, so the chain is sized exactly — no empty slots.
• Workers run inside a single foreground chain, fresh, each receiving only its task file and the accumulated results.md.

Why a sequential pipeline (not parallel)

Workers run W₁ → W₂ → … → W_N in order, not concurrently. The reason is change-impact propagation: a Worker's edits change the real state the next Worker must build on.

• Same file, multiple concerns: W₁ adds UserService, W₂ adds UserController that imports it, W₃ adds tests — all touch user.ts. W₂ must read user.ts after W₁ wrote it; W₃ after both. Parallel would freeze each Worker on a stale snapshot and collide on the shared file.
• Export dependencies: Layer 0 creates symbols, Layer 1 imports them, Layer 2 tests them. Wₖ's task references signatures that only exist once W_{k-1} has run. results.md carries the actual Signatures / Breaking forward so Wₖ builds on real exports, not assumed ones.
• Breaking as a guardrail: if Wₖ removes or renames an export, W_{k+1} sees it in results.md before starting — instead of reading a file, not finding the old symbol, and looping (the "edit → fail → re-read" trap).

Parallelism would require pre-partitioning files with zero overlap and no cross-Worker dependencies — workable only for independent chunks, and brittle: one shared file or one import edge breaks it. Sequential execution preserves Giver's decomposition freedom: split by logical modification group, let groups share files and depend on each other, and let each Worker build on the genuine post-change state. The cost (serial latency) is the price of correctness under shared state — and the chain's structural [Read from: results.md] injection makes that propagation reliable without prose instructions.

Why no completionGuard

Earlier versions (v3.7.5) pre-committed to 10 fixed Worker slots and broke the unused tail via pi-subagents' completionGuard (a no-op Worker writing nothing → the chain error-signals completion). That hack existed only because the Planner ran inside the chain and decided N mid-run, forcing pre-committed slots.

v0.1.0 moves Planner standalone, so N is known before the chain is built. Giver builds a chain of exactly N Workers — no empty slots, no no-op, no [CHAIN COMPLETED], no completionGuard repurposing. The chain completes naturally after W_N. (append-step/async was tried and rejected after e2e testing — see docs/history.md.)

Dependency

Requires pi-subagents latest (foreground chain + structural [Read from:] reads injection).

References

| File | Content | |---|---| | skills/giver/SKILL.md | Full implementation — phases, templates, RESULT format, failure protocol | | giver-principles.md | Mathematical definitions — 6 principles, sets, functions, invariants | | docs/insights.md | Project insights from the v1–v3.7.x evolution | | docs/history.md | Version + design history (v1 → v0.1.0, incl. the append-step → Pattern C test journey) |

Version history (abridged)

| Version | Date | Change | |---|---|---| | v3.0 | 2026-05 | Initial Planner → Workers pipeline | | v3.6.3 | 2026-05 | Target verification scope (−81% verification I/O) | | v3.7.0 | 2026-05 | results.md structural communication | | v3.7.5 | 2026-05 | Fixed 10 slots + completionGuard workaround | | v3.8.0 | 2026-07 | Pattern C — foreground W×N, exact N from standalone Planner (e2e tested) | | v0.1.0 | 2026-07 | Package renamed @sng2c/giver-skill → @sng2c/pi-the-giver; version reset. Architecture = Pattern C (v3.8.0 design) |

License

MIT