allye-pi 1.5.1

package/skills/delivery/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: delivery
+description: Workflow for finalizing a story after all tasks pass review. Verifies completeness, closes the story, updates documentation, and cleans up. Use when all tasks are done and reviewed.
+version: "1.4"
+category: methodology
+---
+
+# Technical Delivery Workflow
+
+This skill finalizes a story after every task has passed review — closing it out, documenting what shipped, and clearing loose ends.
+
+Use this when: all tasks for a story are implemented and reviewed, and the user is ready to finalize delivery.
+
+---
+
+## Workflow Overview
+
+```
+Verify all tasks done → Close story → Update documentation → Clean up TODOs → Save delivery memory
+```
+
+---
+
+## Step 1: Verify All Tasks Are Complete
+
+Check that every task under the story is done:
+
+```
+work_children(id: "{story uuid}")
+```
+
+<HARD-GATE>
+Close the story only once every task is completed, verified, and in "done" status.
+If any task is incomplete, route back to Technical Development or Technical Review instead of closing.
+
+"Done" means the **done category**, not the last status an agent could reach. On a pipeline
+with stages after review, a task parked at a gate the team satisfies by hand is not done — it
+is waiting, and the story waits with it.
+
+If tasks are parked, close-out is not blocked by an oversight. It is **not yet due**. Say which
+gate they are waiting at and stop; do not close the story to tidy the board.
+</HARD-GATE>
+
+### Verification checklist
+
+For each task, confirm:
+- [ ] Status is "done"
+- [ ] Acceptance criteria are met
+- [ ] Tests pass
+- [ ] Review is approved (no outstanding change requests)
+
+---
+
+## Step 2: Close the Story
+
+Move the story to done:
+
+```
+work_status_done(id: "{story uuid}")
+```
+
+This sets the story's status to the "done" category and records `completed_at`.
+
+If the story is part of a feature, check if the feature is now complete:
+
+```
+work_children(id: "{feature uuid}")
+```
+
+If all stories under the feature are done, close the feature too:
+
+```
+work_status_done(id: "{feature uuid}")
+```
+
+---
+
+## Step 2.5: Land the Code
+
+The story is closed in Allye. The code is still on a branch.
+
+Load the `branch-landing` skill and follow it. It asks how the work should land — pull
+request, local merge, or left alone — and carries the sequence that gets it there without
+losing anything.
+
+<HARD-GATE>
+Do not skip this because the story is already closed. Closing the item and landing the code
+are different acts, and doing the first without the second produces the worst available
+state: a board that says delivered and a base branch that does not have the work.
+
+If the story reached this skill while still parked at a pipeline gate, it should not have —
+see Step 1. The branch stays where it is.
+</HARD-GATE>
+
+---
+
+## Step 3: Update Documentation
+
+If the delivered work introduced or changed functionality that should be documented:
+
+### Check existing docs
+
+```
+memory_search(query: "documentation {feature/story key}")
+doc_full_tree()
+```
+
+### Create or update documentation
+
+**For new functionality:**
+
+```
+doc_create(
+  doc_title: "{Feature Name}",
+  doc_type: "page",
+  doc_emoji: "📄",
+  doc_content: "## Overview\n{what this feature does}\n\n## Usage\n{how to use it}\n\n## Technical Details\n{relevant implementation details}\n\n## API Reference\n{endpoints, parameters, responses — if applicable}",
+  doc_parent_id: "{parent folder uuid if applicable}"
+)
+```
+
+**For updates to existing functionality:**
+
+```
+doc_update(
+  id: "{doc uuid}",
+  doc_content: "{updated content}"
+)
+```
+
+### When to skip documentation
+
+Not everything needs docs. Skip if:
+- The change is purely internal (refactoring, performance, tests)
+- The change is self-evident from the code
+- Documentation would duplicate what's in the code
+
+---
+
+## Step 4: Clean Up TODOs
+
+Check for any TODOs that were created during development:
+
+```
+todo_list()
+```
+
+For each TODO related to this story:
+- If it's done → mark as complete: `todo_update(id: "{todo uuid}", status: "completed")`
+- If it's no longer relevant → delete: `todo_delete(id: "{todo uuid}")`
+- If it's a future task → leave it, but make sure it's not blocking delivery
+
+---
+
+## Step 5: Save Delivery Memory
+
+Save a final summary of what was delivered:
+
+```
+memory_save(
+  title: "Delivered — {STORY-KEY} {story title}",
+  content: "## What was delivered\n{summary of the feature/change}\n\n## Tasks completed\n- {TASK-1}: {title}\n- {TASK-2}: {title}\n- {TASK-3}: {title}\n\n## Key decisions\n{important decisions from planning and implementation}\n\n## Documentation\n{what was documented, or 'No documentation needed'}\n\n## Where the code landed\n{branch name, and the merge commit or PR reference, and the base it landed on — or \"not yet landed: {reason}\"}\n\n## Lessons learned\n{anything worth remembering for similar work in the future}",
+  tags: ["delivery", "completed", "{story-key}", "{feature-key}"],
+  sector: "knowledge"
+)
+```
+
+---
+
+## Workflow Checklist
+
+- [ ] All tasks verified as done
+- [ ] Story moved to done
+- [ ] The code landed, or the reason it has not is recorded
+- [ ] Feature moved to done (if all stories complete)
+- [ ] Documentation created or updated (if applicable)
+- [ ] Related TODOs cleaned up
+- [ ] Delivery memory saved
+
+---
+
+## What Comes Next
+
+The story is delivered. The user can:
+- **Pick another story** → Back to Technical Planning (`allye-technical-planning`)
+- **Plan more features** → Back to Product Planning (`allye-product-planning`)
+- **Start a new initiative** → Back to Product Planning from scratch

package/skills/execution/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: execution
+description: Workflow for implementing tasks with TDD discipline, read-first rule, and wave execution. Use when the user wants to write code, implement a task, or develop features.
+version: "1.5"
+category: methodology
+---
+
+# Technical Development Workflow
+
+Implements one task with discipline: read the existing code first, drive it with TDD,
+verify it actually works, and track progress in Allye.
+
+**Scope, if you arrived via a `story-execution` or `correction` handover (see `handover-protocol`):** read only the one story and its tasks named in the handover — nothing else. A `correction` handover carries only the failed findings, not the whole story again; fix exactly what it lists.
+
+---
+
+## Workflow Overview
+
+```
+Get task → Search context → Move to in_progress → Read code → TDD (Red → Green → Refactor) → Verify → Move to review → Save memory
+```
+
+---
+
+## Step 1: Get the Task and Context
+
+Fetch the task you're about to implement:
+
+```
+work_get(work_key: "{TASK-KEY}")
+```
+
+Read its description carefully — it should contain:
+- What to implement
+- Acceptance criteria
+- Files likely involved
+- Dependencies on other tasks
+- Decisions from the discussion phase
+
+### Search for relevant memories
+
+```
+memory_search(query: "{task key} context")
+memory_search(query: "decision {story key}")
+memory_search(query: "Technical Plan {story key}")
+```
+
+If session state or decision memories are found, optionally traverse the graph for richer context:
+```
+memory_graph(memory_id: "{id}", depth: 2)
+```
+
+**Pay special attention to locked decisions** — these were explicitly chosen by the user during the discussion phase and are non-negotiable.
+
+---
+
+## Step 2: Check Dependencies
+
+If the task has dependencies (noted in its description), verify they're complete:
+
+```
+work_children(id: "{story uuid}")
+```
+
+Check that prerequisite tasks are in "review" or "done" status — either means their implementation is complete (tasks you finished earlier in this story sit at `review` until the Reviewer approves them). If a prerequisite hasn't reached at least `review`, either:
+- Pick a different task from the same wave (if available)
+- Inform the user that this task is blocked
+
+### Wave Execution
+
+If there are multiple independent tasks (same wave), they can be done in any order. Tasks with dependencies must follow the sequence defined in the technical plan.
+
+---
+
+## Step 3: Move Task to In Progress
+
+Signal that work has started:
+
+```
+work_status_next(id: "{task uuid}")
+```
+
+---
+
+## Step 4: Read First
+
+<EXTREMELY_IMPORTANT>
+Read existing code BEFORE writing any new code.
+The task description lists files likely involved — read them all.
+Understand the current state before changing it.
+
+This is not optional. Writing code without reading the context leads to:
+- Duplicating existing functionality
+- Breaking existing patterns
+- Inconsistent code style
+- Missed constraints
+</EXTREMELY_IMPORTANT>
+
+### What to read
+
+1. **Files listed in the task description** — The planning phase identified these
+2. **Related test files** — Understand existing test patterns
+3. **Shared utilities and helpers** — Don't reinvent what already exists
+4. **Configuration files** — If the task involves config changes
+
+### Analysis Paralysis Guard
+
+<HARD-GATE>
+This checkpoint applies to exploratory reads beyond what the task already named — reading every file the task itself points you to (see "What to read" above) is still mandatory, not capped by this count.
+
+If you have read 5+ files *beyond those named/implied by the task* without writing any code, STOP and ask yourself:
+
+1. **Do I have enough context to start?** → If yes, start writing. Perfect understanding is not required.
+2. **Am I blocked by missing information?** → If yes, tell the user what's blocking you.
+
+Do not read endlessly in search of additional context. Reading is preparation, not implementation.
+</HARD-GATE>
+
+---
+
+## Step 4.5: Plan the Implementation
+
+You have read the code and written none. This is where you state *how* you will build it,
+and check that statement against what was asked for — while being wrong still costs a
+paragraph rather than a branch.
+
+### Write the plan
+
+Per task in this story:
+
+- **Approach** — the shape of the change, in a sentence or two.
+- **Files** — what you will create or modify. Names, never line numbers; the tree moves.
+- **Interfaces produced** — the names, types, and signatures other tasks in this story will
+  call. Whoever implements a neighbouring task sees only their own task description, so
+  this is the only place they learn what to call.
+- **How each criterion goes green** — for every acceptance criterion, which step makes its
+  `## Verification` command pass. A criterion with no step against it is the finding this
+  whole exercise exists to produce.
+
+Save it:
+
+```
+memory_save(
+  title: "Implementation Plan — {STORY-KEY} {story title}",
+  content: "## Per task\n{approach, files, interfaces produced, criterion → step}\n\n## Order\n{which task first, and why}\n\n## Open questions\n{anything planning did not settle, or 'None'}",
+  tags: ["plan", "implementation", "{story-key}"],
+  sector: "plans"
+)
+```
+
+It outlives the session. A resumed Executor reads what was intended rather than inferring
+it from half-written code, and `reviewer-spec` can compare the implementation against the
+plan and not only against the criteria.
+
+### Validate it
+
+<HARD-GATE>
+Three checks, run every time, before writing any code:
+
+1. **Coverage** — every acceptance criterion, in every task, has a step that produces it.
+2. **Decisions** — every locked decision from planning is respected. A locked decision was
+   chosen by the human. A plan that quietly departs from one is a defect whether or not the
+   resulting code works.
+3. **Closure** — no step depends on something the plan never defines. If a type, function,
+   file, or value appears as a dependency and never as an output, the plan has a hole in it.
+
+A failure is reported as `❌ blocked` **before any code exists**, naming which criterion or
+decision has nothing behind it. This is the same halt-and-report contract you already carry,
+fired at the cheapest possible moment.
+</HARD-GATE>
+
+### Whether the approach is right
+
+The three checks above are mechanical. Whether the approach is a *good* one is judgement,
+and who supplies it follows the story's dispatch label (see `verification-loop` §4):
+
+- **AFK** — self-validation is enough. Run the three checks and proceed.
+- **HITL** — put the plan in front of the user and wait before writing anything.
+- **Either label**, if planning surfaced a decision the discussion phase never covered —
+  stop and raise it regardless. A decision discovered while planning is precisely the case
+  the label could not have anticipated.
+
+---
+
+## Step 5: TDD — Test-Driven Development
+
+<!-- full discipline lives in the tdd-workflow skill, aligned with superpowers:test-driven-development (MIT) -->
+
+### Should I use TDD for this task?
+
+Apply the **TDD Detection Heuristic**:
+
+> Can I write `expect(fn(input)).toBe(output)` before writing `fn`?
+
+- **Yes** → TDD is mandatory. Follow Red → Green → Refactor.
+- **No** (UI, infrastructure, integration, configuration) → Write tests after implementation, but always write tests.
+
+### Red Phase — Write the Failing Test
+
+Write a test that describes the expected behavior:
+
+```
+// Test describes WHAT, not HOW
+test("should return user by email", () => {
+  const user = getUserByEmail("test@example.com");
+  expect(user.name).toBe("Test User");
+});
+```
+
+Run the test. Confirm it **fails**. If it passes, either:
+- The functionality already exists (check before implementing)
+- The test is wrong (it's not testing what you think)
+
+### Green Phase — Make It Pass
+
+Write the **minimum code** to make the test pass. No more, no less.
+
+Rules:
+- Don't add features the test doesn't require
+- Don't optimize prematurely
+- Don't handle edge cases not covered by tests (write more tests first)
+
+Run the test. Confirm it **passes**.
+
+### Refactor Phase — Clean Up
+
+With green tests as your safety net, improve the code:
+
+- Remove duplication
+- Improve naming
+- Simplify logic
+- Extract functions if needed
+
+Run tests after every change. If a test fails, you broke something — fix it before continuing.
+
+### Verification Phase — run the task's loop
+
+TDD proved each behaviour as you built it. This proves the **task's acceptance
+criteria**, which is a different claim.
+
+Run the command from the task's `## Verification` block. Read its actual output.
+If it is red, fix and run it again, under the bound in `verification-loop` §3:
+three attempts on one failure, or two byte-identical outputs, whichever comes
+first. On hitting the bound, stop and carry the command and its literal output
+into your report — do not summarise the output.
+
+If the task declares `verification: manual`, follow its procedure and record what
+you observed. You have not run a loop; say so plainly in the report rather than
+implying one passed.
+
+### Repeat
+
+Write the next test for the next behavior. Continue the cycle until all acceptance criteria are met.
+
+---
+
+## Step 6: Checkpoints
+
+### `human-verify` Checkpoint
+
+After completing the task, if it has **visual or behavioral impact** that the user should see:
+
+> "I've completed {task description}. Here's what changed:
+> - {change 1}
+> - {change 2}
+>
+> Would you like to verify this before I move on?"
+
+### `decision` Checkpoint
+
+**If uncertain which path to take, STOP and ask — never proceed on assumption.** If during implementation you encounter a choice not covered by the discussion phase:
+
+> "I found a decision point not covered in planning:
+> {describe the options}
+>
+> Which approach do you prefer?"
+
+Save the decision as a memory once resolved.
+
+### Automation-First Rule
+
+<HARD-GATE>
+If you CAN automate something, you MUST automate it.
+Only ask for human intervention when it's genuinely impossible to proceed without it.
+
+Examples of things to automate (don't ask):
+- Running tests
+- Formatting code
+- Installing dependencies
+- Creating files and directories
+- Applying migrations
+
+Examples of things that need human action:
+- Approving a deployment to production
+- Providing API keys or credentials
+- Verifying visual design matches expectations
+- Confirming business logic interpretation
+</HARD-GATE>
+
+---
+
+## Step 7: Move Task to Review
+
+<!-- adapted from superpowers:verification-before-completion (MIT) — evidence before assertions -->
+**Evidence before assertions.** Don't advance a task because it looks right — run the tests, read the actual output, and confirm each acceptance criterion against that output before proceeding. "Should work" is not the same as "ran and passed."
+
+The task's verification command is what supplies that evidence. Advancing a task to
+`review` without having run it green — or without having recorded a `verification:
+manual` observation — is the assertion this rule exists to forbid.
+
+Once all acceptance criteria are verifiably met and tests pass:
+
+```
+work_status_next(id: "{task uuid}")
+```
+
+This advances the task forward to the "review" status. **Do NOT call `work_status_done` here** — passing its own tests makes a task ready for review, not done. "Done" only happens after the Reviewer returns ✅, and that final move (`review` → `done`) is the Orchestrator's, not yours (see the `orchestrator` skill §7).
+
+---
+
+## Step 8: Save Implementation Memory
+
+Save context that would be useful for future tasks or sessions:
+
+```
+memory_save(
+  title: "Implementation — {TASK-KEY} {short description}",
+  content: "## What was done\n{summary of changes}\n\n## Key decisions during implementation\n{any new decisions made}\n\n## Files changed\n- {file 1}\n- {file 2}\n\n## Gotchas\n{anything surprising or non-obvious encountered}\n\n## Tests\n{what was tested, any notable test patterns}",
+  tags: ["development", "implementation", "{story-key}", "{task-key}"],
+  sector: "knowledge"
+)
+```
+
+Only save if there's genuinely useful context. Don't save trivial implementations — the code is its own documentation.
+
+---
+
+## Step 9: Pick Next Task
+
+After completing a task, pick the next one from the **handover's own wave-ordered task list** — not from a live API call. The `story-execution` handover already contains every task across every wave for the whole story, so it's the authoritative scope; going back to the API for *new* tasks would risk pulling in tasks added to the story after the handover was dispatched, which are out of scope (see line ~14).
+
+- If there are more tasks in the current wave (per the handover's list) → pick one
+- If the current wave is done → move to the next wave (per the handover's list)
+- If every task in the story has reached `review` (implementation complete, awaiting Reviewer) → **run the story loop, then** emit an **`execution-report`** handover (see the `handover-protocol` skill) back to the Orchestrator.
+
+  The story loop runs the story's own acceptance criteria end to end, under the same
+  bound as the task loop. Every task green does not mean the story works — nothing
+  else checks this, which is exactly why it runs here.
+
+  A red story loop is reported as red **even when every task is green**. That
+  combination is a finding, not a contradiction to resolve: it usually means the task
+  breakdown missed an integration, and the Orchestrator needs to see it rather than
+  receive a clean report.
+
+Use `work_children(id: "{story uuid}")` only to **verify/check the status** of tasks already in the handover's list (e.g. confirming a dependency reached `review`) — never to discover new tasks to work on. If `work_children` reveals a task under this story that is **not** in the handover's task list, do not execute it — it wasn't in scope when the handover was dispatched. Instead, note it as an open question ("Open questions") in the `execution-report` handover so the Orchestrator can decide whether to bring it into scope.
+
+---
+
+## Workflow Checklist
+
+For each task, verify:
+
+- [ ] Task was read and understood (description, acceptance criteria, dependencies)
+- [ ] Relevant memories and decisions were searched
+- [ ] Dependencies are complete
+- [ ] Task moved to in_progress
+- [ ] Existing code was read before writing new code
+- [ ] An implementation plan was written and saved to the `plans` sector before any code
+- [ ] Coverage, decisions, and closure all checked against that plan
+- [ ] TDD cycle completed (or tests written after for non-TDD-suitable tasks)
+- [ ] All acceptance criteria are met
+- [ ] Tests pass
+- [ ] The task's verification command ran green, or its manual procedure was observed and recorded
+- [ ] The story loop ran green before the report was emitted
+- [ ] Task moved to review (never directly to done — that's the Orchestrator's move after Reviewer ✅)
+- [ ] Implementation memory saved (if non-trivial)
+
+---
+
+## What Comes Next
+
+Emit the `execution-report` handover: files changed, tests added, status per acceptance criterion (not a blanket "done"), any new decisions made along the way, and any open questions. The Orchestrator decides from there whether to dispatch Reviewer or, if this is a `correction` round, loop back with more specific findings.
+
+**If you are working in a git worktree**, the Orchestrator that dispatched you owns landing
+the branch — do not merge, do not remove the worktree, do not close your own pane. Name the
+branch in your `execution-report` so it knows what to land.
+
+**If you are working directly in the main checkout** and no Orchestrator is coordinating, the
+branch is yours to finish: load the `branch-landing` skill once the story's tasks are through
+review.

package/skills/handover-protocol/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: handover-protocol
+description: The shared contract for handing off context between Allye workflow phases as copy-pasted chat text. Use when a phase skill is ending and needs to brief a fresh chat for the next phase (Planning, Technical Planning, Orchestrator, Executor), or when a fresh chat opens with a pasted handover and needs to detect which skill to load.
+version: "1.3"
+category: methodology
+---
+
+# Handover Protocol
+
+A handover is how context moves between Allye workflow phases without carrying a chat's full history forward. Each phase runs in its own fresh, lean-context conversation; when it finishes, it emits a handover — a block of chat text the user reads, approves, and pastes as the first message of the next chat. The next chat's bootstrap detects the marker and loads the right skill automatically.
+
+**A handover is never saved as a memory or a file.** The Allye doc and work items it references are the durable record — the handover text itself is a disposable transport vehicle, copied by hand in both directions (including Orchestrator ↔ Executor's correction loop).
+
+<!-- adapted from humanlayer/humanlayer create_handoff/resume_handoff (Apache-2.0) — the discipline that a handoff must be complete enough that the receiving chat needs nothing else -->
+
+## 1. The shared marker
+
+Every handover starts with the same one-line marker and ends with the same reminder. Everything between them is specific to the handover's type — see §2.
+
+```markdown
+## 🔄 Allye Handover — {type}
+**Skill to load:** {skill-slug}
+
+...type-specific body — see references/{type}.md...
+
+---
+If anything is unclear, STOP and ask — don't proceed on a guess.
+```
+
+The bootstrap skill (`using-allye`) scans the first message of every fresh conversation for the `## 🔄 Allye Handover` line. When found, it parses `{type}` and `Skill to load`, loads that skill directly, and skips its own phase-detection heuristic. See `using-allye`'s "Handover detection" step.
+
+**Templates in this skill and in `references/` are written in English — that's the source, not the output.** When actually generating a handover for the user, follow the plugin's language principle same as everywhere else: respond in the user's language. Section headers (`### Objective`, `### Required reading`, etc.) and body prose get written in whatever language the conversation is in — a Portuguese-speaking user gets `### Objetivo`, `### Leitura obrigatória`, and so on. **Only two things stay fixed in every language**, because auto-detection parses them literally: the `## 🔄 Allye Handover — {type}` marker line and the `**Skill to load:**` field name. Never translate those two.
+
+## 2. The catalog
+
+Six types. Each is a distinct handoff with its own objective and field set — not a generic form filled in differently. Full templates live in `references/`.
+
+| Type | Transition | Objective | Template |
+|---|---|---|---|
+| `discovery-to-planning` | Sandbox → Planning | Turn the approved direction into a deliverable structure | `references/discovery-to-planning.md` |
+| `planning-to-technical` | Planning → Tech Planning | Technically detail the approved squares | `references/planning-to-technical.md` |
+| `technical-to-orchestration` | Tech Planning → Orchestrator | Drive delivery of the planned scope (feature, or a whole epic) | `references/technical-to-orchestration.md` |
+| `story-execution` | Orchestrator → Executor | Implement exactly one story | `references/story-execution.md` |
+| `execution-report` | Executor → Orchestrator | Return the implementation result | `references/execution-report.md` |
+| `correction` | Orchestrator → Executor | Fix specific review findings | `references/correction.md` |
+
+**Neither reviewer axis ever receives a handover.** `reviewer-standards` and `reviewer-spec` are both invoked<!-- opencode-exclude:start --> via the `Agent` tool<!-- opencode-exclude:end --> with a constructed prompt (story + tasks + files changed), dispatched by the Orchestrator — not by a pasted handover.
+
+<!-- opencode-exclude:start -->
+**Executor is reachable both ways.** In manual mode it receives `story-execution`/`correction` handovers as documented above. In automatic mode (Orchestrator's choice, offered per story) it's dispatched via the `Agent` tool instead, the same way the reviewer axes are — see `agents/executor.md`. Either way the content is the same; only the transport differs.
+<!-- opencode-exclude:end -->
+
+## 3. Writing a good handover (mandatory checklist)
+
+<!-- adapted from humanlayer/humanlayer create_handoff (Apache-2.0) and EveryInc/compound-engineering-plugin artifact_readiness contracts (MIT) -->
+
+Before emitting any handover, confirm:
+
+- **Concrete keys, not vague pointers.** "The story we discussed" is not acceptable — write the actual `STORY-KEY`. The receiving chat has zero memory of this conversation.
+- **References carry an explicit read instruction, not just keys.** The handover must tell the receiver to actually fetch and read what it lists — work items via `work_get`/`work_children` (the entire subtree under the parent, when the handover is scoped to a parent item like a feature or epic), docs via `doc_get`. A key list without a "read all of this" instruction invites skimming, and the receiving chat has no other way to know reading is mandatory.
+- **Locked decisions are carried forward, verbatim.** If a decision was locked in this phase, restate it in the handover — don't make the next chat re-derive or, worse, re-litigate it.
+- **Scope matches the type.** `story-execution` carries exactly one story; `correction` carries only the failed findings, not the whole story again. Padding a handover with everything "just in case" defeats the purpose of a lean next chat.
+- **The reminder line is never dropped.** Every handover ends with the "stop and ask" line — it's the single most important sentence in this whole protocol.
+<!-- adapted from mattpocock/skills triage AGENT-BRIEF (MIT) — durability of handoff artifacts -->
+- **Name interfaces and contracts, not file paths and line numbers.** Write "the `SkillConfig`
+  type gains an optional `schedule` field", never "open `src/types/skill.ts` and edit line 42."
+  A handover can be read hours later, by a different agent, in a worktree where the tree has
+  already moved — a line number is wrong by then and a contract is not. The one exception is a
+  snippet that encodes a decision more precisely than prose can (a schema, a state machine, a
+  type shape); include it, trimmed to the decision.
+
+## 4. Auto-detection (implemented in `using-allye`)
+
+Detection logic lives in `using-allye`'s bootstrap (checked before its phase-detection table), not duplicated here — see `skills/using-allye/SKILL.md` §2. This skill defines the *contract*; `using-allye` implements the *routing*.

package/skills/handover-protocol/references/correction.md

@@ -0,0 +1,32 @@
+# Handover: correction
+
+**Emitted by:** `orchestrator`
+**Received by:** `execution` (the same Executor chat/session that produced the original implementation, when possible)
+**Objective:** Fix specific review findings — this handover is deliberately narrow. It never re-briefs the whole story; that would defeat the point of a lean, targeted correction pass.
+
+## Before emitting, confirm
+
+- Only the ❌ findings are included — ✅ and ⚠️ items are not corrections, don't pad this handover with them.
+- The correction round number is tracked — per spec §6.4, at most **2** correction handovers are ever emitted for the same task. If the 2nd correction round's review also comes back ❌ (i.e., the 3rd review failure on that task), the Orchestrator does not emit a 3rd correction handover — it stops and escalates to the human instead.
+- Each finding is quoted from the Reviewer's actual output, not paraphrased — paraphrasing risks losing precision about what exactly needs to change.
+
+## Template
+
+```markdown
+## 🔄 Allye Handover — correction
+**Skill to load:** execution
+
+### Objective
+Fix the review findings below in {STORY-KEY} — nothing more.
+
+### Findings to fix (❌ only)
+- {TASK-KEY}: "{reviewer finding, quoted literally}"
+- {TASK-KEY}: "{reviewer finding, quoted literally}"
+
+### Correction round
+This is correction attempt {N} for this story.
+{If N is greater than 2, the Orchestrator shouldn't be emitting this handover — the max is 2 correction handovers per task; a 3rd review failure escalates to the user instead of producing a 3rd handover. See skills/orchestrator.}
+
+---
+Fix ONLY what's listed above — don't redo the whole story. If anything is unclear, STOP and ask — don't proceed on a guess.
+```