@llblab/pi-actors 0.46.1 → 0.48.0

package/skills/swarm/references/development-swarm.md

@@ -1,596 +1,189 @@
-# Small-Team Development Swarm
+# Development Swarms
 
-Also known as `MAWP`: Multi-Agent Worktree Protocol.
+Use this reference when two or more implementation participants can own disjoint mutation zones and one integrator can reconcile them. Keep generic actor execution and lifecycle behavior in `actors`.
 
-Use this protocol when 2–4 implementation agents work on one project at the same time.
-It is intentionally lighter than a full orchestrator runtime.
+## Admission test
 
-Core idea: do not block everything in advance. Isolate work surfaces, declare intent before edits, exchange context only after collisions, and merge through one integrator.
+Use a development swarm only when all are true:
 
-## Core Shape
+- the accepted direction is stable enough to partition;
+- each participant can receive a meaningful bounded scope;
+- shared contracts have one named owner;
+- work can be isolated from the shared target while in progress;
+- one integrator owns merge order and final validation.
 
-```text
-1 project
-→ 1 shared backlog
-→ 2–4 isolated worktrees or branches
-→ each agent owns a small task card
-→ conflicts trigger structured context exchange
-→ one integrator merges
-```
+Do not parallelize implementation when tasks need the same central files, semantic ordering dominates wall-clock time, or the likely conflicts would invalidate the decomposition. Use planning or review first.
 
-Agents should not mutate the same `main` checkout concurrently. Prefer isolated branches or worktrees:
-
-```bash
-git worktree add ../agent-a -b agent/a-task
-git worktree add ../agent-b -b agent/b-task
-git worktree add ../agent-c -b agent/c-task
-```
+## Coordinator role separation
 
-## When To Use
+In a host-coordinator topology, the current Pi instance owns the declarative outcome and participant graph rather than acting as the default implementation worker. It may receive intent through Telegram or another companion extension, but transport does not become a gateway or gain hidden instance-creation authority; participant creation remains an explicit actor-kernel Run.
 
-Use this mode when:
+The coordinator should:
 
-- Work can be split into small file/domain scopes.
-- Agents need to write code, docs, tests, or fixtures concurrently.
-- A human or integrator-agent can merge patches.
-- The project is not high-risk enough to justify a heavy orchestration platform.
+- Translate high-level intent into bounded task cards and dependency edges.
+- Keep user authority, shared contracts, integration order, and final validation local.
+- Remain available for checkpoints, permissions, conflicts, and changing evidence.
+- Consume terminal handoffs, durable artifacts, and Trace attention instead of mirroring participant work.
+- Check overdue work on an evidence-based timer; never replace event-driven completion with a rapid polling loop.
 
-Do not use this mode when:
+A participant should:
 
-- Tasks require the same public API files.
-- The architecture direction is unsettled.
-- The expected conflicts are semantic, not just file-level.
-- No integrator is available.
+- Own one concrete execution or evidence boundary.
+- Avoid global orchestration and undeclared participant creation.
+- Return a bounded handoff that lets the coordinator decide without replaying the entire task.
 
-## Agent Role Split
+Use one ordinary Run under `actors` when only one worker is delegated. Activate this development-swarm protocol when two or more participants, parallel ownership, or explicit integration edges exist. Keep trivial single-boundary work inline when delegation overhead has no compensating value.
 
-Prefer splitting agents by **mutation class**, not by unrelated features.
+## Reasoning profiles
 
-Stable split:
-
-```text
-Agent A: mutate behavior
-Agent B: verify behavior
-Agent C: describe behavior
-Agent D: integrate behavior
-```
+| Role | Default | Raise or fan out when |
+| --- | --- | --- |
+| Bounded implementation author | Reasoning off | The card explicitly owns unresolved diagnosis or design judgement |
+| Reviewer | Medium reasoning, clean context | Stakes require independent lenses or repeated judges |
+| Synthesizer / integrator | Medium reasoning | Evidence conflicts, shared contracts move, or merge order is semantic |
+| Coordinator | Sufficient for decomposition and decisions | Scope, authority, or architecture remains unresolved |
 
-Practical mappings:
+Prefer independent review after implementation over asking one author thread to implement, retain all local assumptions, and then certify itself. When risk justifies the cost, use multiple independent reviewers: different lenses increase breadth, while repeated judges increase confidence. Preserve minority high-impact findings and merge only evidence-backed conclusions.
 
-- `2 agents`: implementation; tests/docs/review.
-- `3 agents`: implementation; tests; docs plus review.
-- `4 agents`: implementation; tests; docs/examples; integrator/refactor/audit.
+More reviewers are not automatically better. Do not fan out when they would inspect unstable code, share contaminated context, repeat one unsupported claim, or exceed the value of the decision. Never change an already-running participant solely to enforce a newer profile; add a fresh review boundary if evidence remains open.
 
-Recommended roles:
+## Decompose by ownership
 
-- `Implementation Agent`: writes logic; avoids docs unless needed for the task.
-- `Test Agent`: writes tests and may expose bugs; avoids changing production logic.
-- `Docs Agent`: updates docs/spec/examples/comments; avoids code.
-- `Review/Integrator Agent`: reviews patches, resolves conflicts, runs checks, and merges.
-
-Dangerous split:
+Prefer mutation-zone ownership over broad feature labels.
 
 ```text
-Agent A: implement feature X
-Agent B: implement feature Y
-Agent C: refactor architecture
-Agent D: clean up types
+behavior owner  → production behavior in one domain
+test owner      → regressions and fixtures for that domain
+docs owner      → affected agent/user contract
+integrator      → shared contracts, merge, final checks
 ```
 
-This creates overlapping semantic ownership. Prefer behavior/test/docs/integration separation so agents do not compete for the same memetic niche.
+A participant may own both behavior and its tests when separating them would force synchronized edits. What matters is one owner per writable surface and an explicit integration edge.
 
-## Task Card
+## Task card
 
-Every implementation agent gets a task card. The card is the unit of delegation.
+Every participant receives one task card before mutation:
 
 ```markdown
-# Task
+# Task Card
 
 Goal:
-
-- What needs to be done.
-
-Allowed files:
-
-- Src/lib/foo.ts
-- Src/routes/game/+page.svelte
-
-Avoid files:
-
-- Src/lib/shared/types.ts
-- Src/lib/stores/\*
-
-Expected output:
-
-- Patch
-- Short summary
-- Tests/checks run
-- Touched files list
-```
-
-A task card should specify mutation zones, not just intent. The smaller the allowed file set, the less coordination machinery is needed.
-
-Scope expansion is the main conflict generator. Agents must not opportunistically refactor unrelated code or silently edit outside the declared task. If an out-of-scope change is needed, write it as a new backlog item or ask the integrator to replan.
-
-## Backlog Partitioning
-
-Use explicit task IDs when a coordinator will split backlog work across agents. File position is too fragile once agents start editing, while stable IDs can appear in scope files, branch names, handoffs, and review reports.
-
-Recommended task card shape:
-
-```markdown
-## T-001: Add trust warnings
-
-Labels:
-
-- Docs
-- Runtime
-
-Allowed files:
-
-- Docs/command-templates.md
-- Lib/schema.ts
-
-Avoid files:
-
-- Package.json
-
-Exit:
-
-- Docs explain the trusted executable boundary.
-- Tests cover warning detection.
-```
-
-Partition by independent mutation zones first, then by effort. Do not split one shared public contract across agents unless a single integrator owns that contract. If task independence is uncertain, assign the risky task to the integrator or run a planning/review swarm before implementation.
-
-## Collaborative Branch Subagents
-
-Use this pattern when a coordinator needs 2-4 implementation agents to work from one backlog without sharing a mutable checkout.
-
-```text
-coordinator reads backlog
-→ coordinator writes one scope file per agent
-→ local async-run adapter starts isolated clone or worktree branches
-→ each subagent works only inside its branch workspace
-→ runner verifies commit and pushes branch
-→ coordinator reviews ready branches
-→ integrator merges through the normal project flow
+Non-goals:
+Allowed files or logical scope:
+Avoided files or shared contracts:
+Execution profile:
+Isolation mode: exclusive paths | isolated worktree | artifact-only
+Shared surfaces reserved for integrator:
+Expected artifact or patch:
+Required evidence:
+Checks:
+Escalate when:
+Handoff destination:
 ```
 
-This is primarily a branch artifact protocol, not real-time agent chat. Subagents do not coordinate with each other during execution. They communicate by branch commits, handoff files, conflict reports, and integrator review. When the local runtime supports resumable sessions, a subagent may also use a coordinator checkpoint to ask the orchestrator for a bounded decision without losing its own context.
-
-Coordinator responsibilities:
-
-1. Read the canonical backlog and project instructions.
-2. Select independent task groups with stable task IDs.
-3. Write one scope file per agent with goal, allowed files, avoided files, exit criteria, checks, and branch name.
-4. Start the local async-run adapter.
-5. Inspect run status and logs until terminal.
-6. Review successful branch diffs before merge.
-7. Record failed or out-of-scope work back into the backlog.
+A useful task card names the smallest scope that can independently reach a validation boundary. It does not ask a participant to "help with" a broad project area. Participants must restate scope before editing and record discovered out-of-scope work rather than performing it.
 
-Scope file rules:
+`swarm/development-tasking` can generate and critique one card when the goal, allowed scope, avoided scope, checks, model, and tools are already known.
 
-- Prefer local files over large inline prompts.
-- Include task IDs and exact workspace path.
-- Include allowed and avoided file lists.
-- Require the agent to restate task IDs, allowed files, and exit criteria before editing.
-- State that commit and push may be handled by the runner when the local adapter owns git finalization.
+## Write ownership
 
-Subagent instruction core:
+- Give each writable file or logical contract one owner.
+- Treat schemas, public APIs, central configuration, migrations, and specifications as exclusive even when textual merges look easy.
+- Parallel readers may inspect a stable shared target.
+- Isolate concurrent mutation through the repository's existing branch/workspace mechanism.
+- Use bounded lock evidence when ownership is not otherwise obvious. A lock records intent; it does not authorize scope expansion.
+- Release ownership at terminal handoff or explicitly transfer it through the integrator.
 
-```text
-Work only in this repository workspace: <work_dir>.
-Read your assigned scope from: <scope_file>.
-Before editing, restate task IDs, allowed files, avoided files, and exit criteria.
-Do not edit outside declared scope.
-If an out-of-scope change is required, write it as a backlog note or handoff risk.
-If blocked by a coordinator-only decision and the runtime supports checkpoints, emit a bounded Coordinator Checkpoint instead of discarding your context.
-Run the checks named in the scope when practical.
-Write a concise handoff report before finishing.
-```
+If a participant discovers that another scope must change, it emits a dependency or conflict report and stops that edge. The coordinator either transfers ownership, serializes the work, or replans.
 
-## Coordinator Checkpoints
+## Isolation modes
 
-A coordinator checkpoint is a deliberate pause, not free-form chat. It is useful when the subagent has built local context that should not be thrown away, but continuing requires a coordinator decision: scope change, ambiguous product choice, conflict policy, credential/account boundary, or release/publish permission.
+- `Exclusive paths`: Writers share one worktree only when their complete writable path sets are disjoint and the shared baseline remains stable.
+- `Isolated worktree`: Use when compilation, generated files, imports, or likely dependencies can touch shared repository state.
+- `Artifact-only`: Use for reports, inventories, proposed patches, fixtures, or reviews that the integrator applies later.
 
-Target behavior for capable adapters:
+The integrator exclusively owns `BACKLOG.md`, `CHANGELOG.md`, lockfiles, generated metadata, public schemas, release manifests, and cross-domain configuration by default. A task card may transfer one of these surfaces to another participant, but never create concurrent ownership. Authors report required shared-surface changes in handoff instead of applying them outside scope.
 
-```text
-subagent reaches a decision gate
-→ subagent emits Coordinator Checkpoint
-→ runner pauses the subagent session without dropping context
-→ coordinator answers the bounded question
-→ runner resumes the same subagent context with the answer
-→ subagent records the decision in its handoff
-```
+## Coordinator checkpoints
 
-Checkpoint payload:
+A checkpoint preserves useful local context while requesting one decision:
 
 ```markdown
 # Coordinator Checkpoint
 
-Agent:
-Task IDs:
-Workspace:
+Task:
+Current scope:
 Question:
-Why coordinator input is needed:
-Options considered:
+Why a coordinator decision is required:
+Options and evidence:
 Recommended option:
 Risk if guessed:
-State to preserve:
+State that must be preserved:
 ```
 
-Coordinator reply should answer only the checkpoint question. It should not inject broad new context unless the subagent explicitly asked for it. If the runtime cannot resume the same subagent context, write the checkpoint as an artifact, stop the branch as degraded, and let the coordinator replan or launch a new subagent with the checkpoint included.
-
-Coordinator prompt template:
+Use checkpoints for scope changes, product choices, shared-contract decisions, permissions, or conflict policy. The coordinator answers only the bounded question. If the participant cannot resume with preserved context, retain the checkpoint as a handoff and start a clean replacement explicitly.
 
-```text
-Read the project backlog and instructions.
-Partition actionable work into <N> independent task groups.
-Prefer groups with non-overlapping allowed files.
-Write one scope file per agent under <run_dir>/scopes/.
-Each scope file must include task IDs, goal, allowed files, avoided files, exit criteria, checks, branch name, and handoff path.
-Do not start execution until every scope has a clear branch artifact contract.
-```
+## Handoff
 
-Scope file template:
+Every participant returns:
 
 ```markdown
-# Scope: agent-01
-
-Run:
-Branch:
-Workspace:
-Handoff path:
-
-Task IDs:
-
-- T-001
-- T-002
-
-Goal:
-
-- ...
-
-Allowed files:
-
-- ...
-
-Avoid files:
-
-- ...
-
-Exit criteria:
-
-- ...
-
-Checks:
-
-- ...
-
-Out-of-scope handling:
-
-- Do not edit outside allowed files.
-- Record required out-of-scope changes in the handoff risk section.
-```
-
-Branch artifact contract:
-
-- Success means the expected branch exists, contains at least one commit for the assigned task group, and has been pushed.
-- The branch name should include the run id and task range or agent id.
-- The handoff report should name task IDs, touched files, checks, risks, and follow-up.
-- A branch with no commit is not a successful artifact, even if the subagent exits with code 0.
-
-Partial failure is normal. Treat a run with some ready branches and some failed branches as degraded, not as total failure. The coordinator should report ready branches, failed branches, failure reasons, and the safest next action for each failed scope.
-
-## Soft-Lock Manifest
-
-For 2–4 agents, start with a simple repository-local manifest rather than a lock server.
-
-Suggested path:
-
-```text
-.agents/locks.md
-```
-
-Example:
-
-```markdown
-# Agent Locks
-
-## agent-a
-
-Task: fix scheduler tests
-Owns:
-
-- Pallets/aaa/src/tests/scheduler/\*
-- Pallets/aaa/src/mock.rs
-
-## agent-b
-
-Task: update fee model docs
-Owns:
-
-- Docs/aaa/fees.md
-- Docs/aaa/spec.md
-
-## agent-c
-
-Task: refactor frontend card component
-Owns:
-
-- Src/lib/components/Card.svelte
-```
-
-Protocol:
-
-1. Read `.agents/locks.md` before starting.
-2. Add or update your section before editing.
-3. Treat `Owns:` as a soft write claim.
-4. Avoid another agent's owned files unless the integrator replans.
-5. On completion, remove the section or mark it done.
-
-This manifest is weaker than an automated lock adapter but easier for humans and agents to inspect. Use a runtime-backed lock protocol when automation, TTL, or conflict enforcement is needed.
-
-## Exclusive Files
-
-Some files create semantic conflicts even when Git merges cleanly. Require exclusive ownership for public contracts and central runtime boundaries.
-
-Examples:
-
-```text
-src/lib/types/*
-pallets/*/src/lib.rs
-runtime/src/*
-docs/spec/*
-package.json
-Cargo.toml
-```
-
-Project-local protocol should define its own exclusive files. If a task needs one, assign it to a single agent or the integrator.
-
-## Conflict Types
-
-### Merge Conflict
-
-Git cannot combine two edits to the same file.
-
-Response:
-
-1. Both agents produce conflict reports.
-2. Resolver/integrator reads both reports.
-3. Resolver merges patch.
-4. Original agents review affected files only.
-
-### Semantic Conflict
-
-Files may merge, but meaning diverges. Example: one agent changes an API while another writes code against the old API.
-
-Response:
-
-1. Stop affected workers.
-2. Integrator decides whether the backlog task is invalidated.
-3. Split or replan before more implementation.
-
-### Architecture Conflict
-
-The task decomposition itself is wrong.
-
-Response:
-
-1. Stop workers on affected scopes.
-2. Re-open planning.
-3. Produce new task cards with corrected ownership.
-
-## Conflict Handshake Protocol
-
-Agents should not freely negotiate in long context-sharing threads. Exchange semantic deltas in a bounded format.
-
-```markdown
-# Conflict Report
-
-Agent:
-Task:
-Conflicting files:
-
-- ...
-
-What I changed:
-
-- ...
-
-Why I changed it:
-
-- ...
-
-What I need preserved:
-
-- ...
-
-Can safely discard:
-
-- ...
-
-Suggested resolution:
-
-- ...
-```
-
-Resolution flow:
-
-```text
-Agent A hits conflict with Agent B
-→ Agent A writes Conflict Report
-→ Agent B writes Conflict Report
-→ Integrator/resolver reads both
-→ Resolver creates merged patch
-→ Original agents review only affected files
-```
-
-The goal is to exchange intent and invariants, not to let agents recursively debate.
-
-## Scope Expansion Rule
-
-Multi-agent work is stricter than solo work.
-
-Required instruction for implementation agents:
-
-```text
-Do not opportunistically refactor unrelated code.
-Do not modify files outside declared scope.
-If you discover a needed out-of-scope change, record it as a backlog item or conflict note.
-```
-
-This is the difference between useful parallelism and diff chaos.
-
-## Handoff Report
-
-Each agent writes a concise handoff after finishing.
-
-Suggested path:
-
-```text
-.agents/handoff/agent-a.md
-```
-
-Template:
-
-```markdown
-# Handoff: agent-a
+# Handoff
 
 Task:
-Branch/worktree:
-
+Status: complete | degraded | blocked
 Summary:
-
-- ...
-
-Touched files:
-
-- ...
-
-Tests/checks:
-
-- ...
-
-Behavior changes:
-
-- ...
-
-Risks / follow-up:
-
-- ...
-
-Integrator notes:
-
-- What must be preserved during merge.
+Touched scope:
+Behavior or contract changes:
+Checks and results:
+Artifacts or patch identity:
+Dependencies discovered:
+Risks and unresolved questions:
+Integrator invariants:
 ```
 
-Example:
-
-```markdown
-# Agent A Handoff
-
-Task:
-A1: Add tests for scheduler window expiry
-
-Touched files:
-
-- Pallets/aaa/src/tests/scheduler/window.rs
+A successful process exit without the expected patch, artifact, or evidence is not a successful handoff. Preserve partial work as degraded evidence when it is useful and safe to integrate.
 
-Summary:
-
-- Added tests for inclusive window end.
-- Added test for close only when current_block > end.
-
-Checks:
+## Conflict evidence
 
-- Cargo test -p pallet-aaa scheduler_window
+Distinguish three conflict classes:
 
-Open questions:
+- **Textual conflict:** edits overlap mechanically.
+- **Semantic conflict:** edits merge but depend on incompatible meanings.
+- **Architecture conflict:** the decomposition or accepted direction is wrong.
 
-- None.
+Each affected owner reports:
 
-Conflict notes:
+```markdown
+# Conflict Report
 
-- Does not touch runtime logic.
+Task and owned scope:
+Conflicting scope:
+Intent:
+Invariant that must survive:
+Change made:
+Evidence:
+Safe-to-discard portion:
+Proposed resolution:
 ```
 
-## Runner Adapter Contract
-
-A local branch runner may be useful, but it is adapter policy rather than portable Swarm core. Keep concrete model names, tool allowlists, async-run syntax, and runtime-specific CLI invocation outside this skill.
-
-Minimum runner behavior:
-
-1. Clone or create an isolated worktree from the requested repo and base branch.
-2. Create the expected feature branch.
-3. Run one subagent with the prepared scope file and bounded tool access.
-4. Verify the current branch is still the expected branch.
-5. Verify there are intentional changes before commit.
-6. Commit with a task-aware summary when the adapter owns git finalization.
-7. Push the expected branch.
-8. Emit a structured result with branch, commit, pushed status, handoff path, checks, and failure reason.
-
-Recommended subagent tools are the smallest set that can complete the task, usually read, edit/write, and shell validation. Avoid broad external account tools inside implementation subagents. External actions such as opening pull requests, merging, publishing, or commenting belong to the coordinator or integrator after review.
-
-Runner exit policy:
-
-- Exit 0 only after commit verification and successful push when the runner owns git finalization.
-- Exit non-zero when clone, checkout, subagent execution, commit verification, or push fails.
-- A failed branch should not cancel sibling branches in the same async fanout.
-- Timeouts should preserve logs and any handoff artifacts for coordinator inspection.
+The integrator resolves from both reports. Architecture conflicts stop affected work and return to planning. Do not let participants recursively negotiate until their independent intent is lost.
 
-## Integrator Protocol
+## Integration protocol
 
-The integrator is the only actor that merges to the shared target branch.
+The named integrator:
 
-Integrator steps:
+1. freezes new author mutations and preserves every terminal handoff before integration;
+2. reads task cards, handoffs, dependency edges, and conflict reports;
+3. verifies each result stayed within scope;
+4. integrates in dependency order, one ownership edge at a time;
+5. resolves conflicts while preserving stated invariants;
+6. runs checks after risky edges and the full agreed validation at the end;
+7. obtains fresh review for conflict-resolved or shared-contract changes;
+8. reports integrated tasks, rejected or deferred work, checks, and residual risks.
 
-1. Read backlog, locks, and handoffs.
-2. Merge one branch at a time.
-3. Resolve conflicts using conflict reports, not guesses.
-4. Run the project's validation gates.
-5. Ask original agents to review affected files when conflict resolution changed their work.
-6. Produce final summary: merged tasks, tests, touched files, residual risks.
+Do not treat a clean merge, participant-local tests, or a collection of terminal Runs as integrated completion. Completion requires retained shared state plus coordinator-owned validation evidence.
 
-## Effective Protocol
-
-```markdown
-# Multi-Agent Protocol
-
-1. Each agent MUST work in a separate branch or worktree.
-2. Before editing, each agent MUST declare task, intended files, forbidden files, and expected output.
-3. Agents SHOULD avoid files already claimed in `.agents/locks.md`.
-4. Public API, storage, runtime, schema, and spec files require exclusive ownership.
-5. Each agent MUST produce a handoff note after completion: touched files, semantic changes, checks run, unresolved risks.
-6. If a conflict occurs, both agents MUST produce Conflict Reports.
-7. Conflict resolution MUST preserve semantic intent, not merely compile.
-8. Integrator merges patches into the shared target after checks pass.
-9. No agent may silently expand task scope.
-```
-
-Context exchange rule:
-
-```text
-Before conflict: minimal shared context.
-At conflict: compressed intent/diff/risk exchange.
-After conflict: update backlog/locks.
-```
-
-Constant agent chat destroys independence. Conflict reports preserve the useful context without contaminating every worker.
-
-## Minimal Directory
-
-```text
-.agents/
-  backlog.md
-  locks.md
-  protocol.md
-  handoff/
-    agent-a.md
-    agent-b.md
-    agent-c.md
-```
+## Stop conditions
 
-This directory is optional. Use it when the repository lacks an existing coordination plane. If the project already has backlog, lock, and handoff conventions, reuse them instead.
+Stop and replan when ownership overlaps, an exclusive contract lacks one owner, task cards cannot be independently validated, an out-of-scope dependency is required, architecture conflict appears, or no integrator can validate the retained result. Prefer a smaller serial cohort over parallel diff chaos.