Loop Authoring

Agent Deck Loop Authoring

Use this skill when the user wants to create, refine, review, save, or troubleshoot an Agent Deck loop.

Your job is to guide the user iteratively. Do not dump every option at once. Ask one focused question at a time, explain the practical tradeoff, and state your recommended default before asking when there is a sensible default.

Core mental model

An Agent Deck loop is a reusable run recipe with:

• a goal or task prompt
• a structure kind
• one or more explicitly selected agents
• a write target
• stopping or validation criteria
• optional project availability metadata when saved to the Loop Bank

User-authored loops are typically saved as *.loop.md under ~/.pi/agent/loops in the current user-level Loop Bank storage. Built-in loop templates are currently disabled, so do not tell users that bundled loop templates are available unless the product changes.

Iterative authoring workflow

Move through these steps in order. Stop and ask only for the next missing decision.

1. Clarify the outcome

   • Ask what the loop should accomplish and what “done” means.
   • Help turn vague requests into an actionable goal prompt.
   • Recommended default: artifact/report output unless the user clearly wants code edits.

2. Choose the loop structure

   • Recommend the simplest structure that fits the work.
   • Ask the user to confirm the structure before choosing agents.

3. Select agents explicitly

   • Agent fields must stay blank until the user chooses an agent.
   • Never invent fallback agent names such as Maker or Checker.
   • If the available agent list is unknown, ask the user to choose from Agent Deck or inspect the global/imported catalog plus the project’s Agent Deck assignments if tools/context allow it. Do not offer project-local .pi/agents or legacy .agents files; import/catalog entries are by reference, not copy.

4. Choose the write target

   • Prefer artifactMarkdown for planning, research, review, and safe reports.
   • Use newWorktree for implementation that should avoid touching the current checkout.
   • Use currentCheckout only when the user explicitly confirms direct edits to the current project tree.

5. Define validation and stop conditions

   • Ask what evidence should decide success: tests passing, reviewer approval, checklist completion, no findings, or a human approval checkpoint.
   • Keep max iterations low unless the user asks for longer autonomous work.

6. Decide whether to save it

   • If the user wants reuse, save to the Loop Bank with a clear name and description.
   • Ask whether it should be available to all projects, only the current project, or kept unassigned/catalog-style.

7. Review before launch or save

   • Summarize the loop in a compact checklist.
   • Call out any risky write target, missing agent, vague goal, or missing validation.
   • If several decisions are still missing, summarize them briefly but ask for only the highest-priority missing decision in the current turn.
   • Ask for confirmation before launch when the loop can modify project files.

Structure guide

Choose the most direct structure:

• Single Agent: one agent repeats work until validation passes or the iteration limit is reached. Best for focused reports or bounded implementation by one specialist.
• Maker + Checker: one maker produces work and a checker approves or rejects against a rubric. Best when quality gates matter.
• Agent Pipeline: ordered stages where each stage hands off to the next. Best for research → plan → implementation → review workflows.
• Parallel Agents: multiple branches run independently and then summarize. Best for independent investigations or comparing approaches.
• Discovery/Triage: one triage agent classifies or routes findings using a classification prompt. Best for bug intake, repo sweeps, or issue sorting.
• Human Approval: pauses for explicit user approval at a checkpoint. Best when a human must decide before continuing.

If multiple structures fit, recommend the simplest safe option and explain why in one sentence.