cgg-runtime/skills/swarm/SKILL.md
Orchestrate governed parallel agent work. Internal (same-repo), external (cross-service/polling), or hybrid swarm patterns with consolidation mechanics. CENTROID: parallel deliverable orchestration with governed consolidation IS: - internal swarm (same-repo agents, shared context, artifact consolidation) - external swarm (cross-service, polling-based, async completion) - hybrid swarm (internal agents + external polling + inbox consolidation) - dependency-gated task DAG execution (blocked_by lists) IS NOT: collapse_zones: - adversarial reasoning (use /stage — arenas produce governance pressure; swarm produces deliverables) - single-agent wrapper (swarm implies ≥2 parallel agents with consolidation) - autonomous consolidator (lead holds consolidation authority; agents do not merge) - scope mutator (swarm coordinates work; does not promote, inscribe, or cross governance boundaries) - silent dispatch (every swarm writes a spec YAML before execution) sibling_overlaps: - /stage (governed reasoning orchestration) - /loop (polling primitive used inside external/hybrid swarm) - /review (constitutional judgment) WHEN: - when work can genuinely run in parallel (no strict sequencing across the whole) - when multiple file/module/service surfaces must be touched together - when cross-repo or external-service coordination requires async consolidation - on explicit Architect invocation NOT WHEN: - for adversarial reasoning (use /stage) - for single-agent work (overhead exceeds benefit) - mid-arena (arena has its own phase execution; swarming inside an arena double-orchestrates) - when the workload is sequential by nature (each step depends on the prior result) RELATES TO: - /stage (orchestration — stage runs adversarial reasoning; swarm runs parallel deliverables) - /loop (polling — external/hybrid swarms use /loop for external-completion polling) - /review (constitutional judgment — swarm produces artifacts; review evaluates any surface claiming promotion) ARGS: stance: dispatch off_envelope: ask # off_envelope rationale: /swarm has three distinct patterns (internal/external/ # hybrid) with very different execution mechanics. Undeclared-arg may indicate # caller confused between /swarm patterns or between /swarm and /stage — # ask prevents silent misroutes. core_dispatch_rays: - "" → interactive (describe work, infer pattern) - "internal" → same-repo parallel agents with shared task list - "external" → cross-service with polling-based consolidation - "hybrid" → internal agents + external polling + inbox consolidation - "--plan" → generate swarm spec without executing - "--spec" → resume from existing swarm spec secondary_modulation_axes: - consolidation_mode: artifact | return-value | inbox - dependency_style: dag | linear | free - polling_interval: <duration>
npx skillsauth add prompted365/context-grapple-gun swarmInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Orchestrate multi-agent work with structured consolidation. Unlike /stage (adversarial reasoning for governance input), /swarm coordinates parallel deliverable work with dependency gating and result merging.
/swarm — interactive mode. Describe the work, infer pattern./swarm internal "<task>" — same-repo parallel agents with shared task list./swarm external "<task>" — cross-service agents with polling-based consolidation./swarm hybrid "<task>" — mix of internal agents + external polling./swarm --plan — generate swarm spec without executing (dry run)./swarm --spec <path> — resume from existing swarm spec.All agents operate in the same repo and context. Lead orchestrator holds shared context, delegates work units, and consolidates results.
When to use: parallel code changes, multi-file refactors, research queries that can be parallelized, governance batch operations.
Spawning: Agent() tool with run_in_background: true for parallel execution.
Consolidation: Lead reads agent outputs (file artifacts or return values), validates completeness, merges results.
Dependency gating: Task DAG with blocked_by lists (same pattern as arena phases).
Lead spawns agents A, B, C (parallel, no blockers)
-> A, B, C complete (file artifacts written)
-> Lead reads artifacts, validates
-> Lead spawns D (blocked_by: [A, B, C])
-> D completes
-> Lead consolidates final output
Agents work across services, repos, or external systems. Results arrive asynchronously via polling or inbox.
When to use: CI/CD monitoring, cross-repo coordination, external API orchestration, long-running background processes.
Spawning: Mix of Agent() for initial dispatch + /loop for polling checkpoints.
Consolidation: Artifact-based. Each agent writes results to a known path. Consolidation agent polls for completion artifacts.
Dependency gating: File-existence checks + inbox state machine (arrived/completed).
Lead dispatches work to external surfaces (GH Actions, APIs, repos)
-> /loop polls for completion artifacts at interval
-> On completion detected: Lead reads artifacts
-> Lead consolidates and reports
Internal agents + external polling + inbox-based consolidation. The most flexible pattern.
When to use: work that requires both local computation and external coordination — e.g., generate code locally, deploy externally, validate via polling.
Spawning: Internal agents via Agent(), external monitoring via /loop, inbox for async results.
Consolidation: Internal results merge immediately; external results arrive via inbox transmissions and merge on scan.
Lead spawns internal agents A, B (parallel)
-> A, B complete (immediate consolidation)
-> Lead dispatches external work
-> /loop polls external completion
-> External results arrive in inbox
-> Lead merges internal + external results
-> Final consolidation
Swarm whose context rails were manufactured at the prior session's /cadence rather than discovered cold inside the current session. Rails (RTCH packets + slice baskets + dependency declarations) live in a stable rails directory; the swarm's dispatcher reads them at SessionStart and fires lanes only when their declared dependencies are satisfied via inbox-marker signaling.
When to use: large multi-lane work (≥3 parallel lanes) where the prior session's /cadence already had enough context awareness to identify the lanes and manufacture their context packets. The next session opens hot — no RTCH inside the dispatch path; the dispatcher reads the rails and spawns lanes directly. Composes with internal/external/hybrid as the base pattern — rails govern dispatch ordering and context loading; the lanes themselves can still be any of the three.
Two coupled primitives (full doctrine: CGG_CLAUDE.md § Cross-Cadence-Rails + Inbox-Marker-Dependency-Satisfaction Primitive):
Cross-Cadence-Rails — rail packets manufactured during the prior session's /cadence (via parallel /tactical-hydration lanes terminating in /consolidate), written to audit-logs/swarm-rails/tic{N}/rail-{lane-id}-{lane-name}.md. Each packet carries RTCH selected_surfaces, slice baskets, risk maps, and dependency declarations authored while context was hot in the prior session.
Inbox-Marker-Dependency-Satisfaction — DAG node structure in the swarm's inbox marker (audit-logs/agent-mailboxes/ent_homeskillet/inbound/swarm-tic{N}/) declaring dependencies: [rail-T1, rail-T2, …] where each dependency is a status: complete signal written by the corresponding rail's /consolidate step. The dispatcher reads the DAG and fires a lane only when all its declared dependencies are satisfied (rail packets present + lane upstream complete).
Spawning: SessionStart hook or first-prompt dispatch reads the inbox marker, parses the dependency DAG, and spawns agents for each lane whose dependencies are satisfied. Same Agent() semantics as internal swarm — the rails just ensure the agent prompts include pre-hydrated context rather than requiring cold-start discovery.
Consolidation: Lead reads agent outputs at completion (artifact-based per internal swarm) and writes a final completion marker (audit-logs/swarm-rails/tic{N}/swarm-complete.marker) carrying the consolidation summary.
Prior session's /cadence:
-> Identify next-session lanes (T1, T2, T3, …)
-> Spawn parallel /tactical-hydration agents (one per lane)
-> Each terminates with /consolidate writing rail-T*.md
-> Write inbox marker with dependency DAG
-> Each rail emits status:complete marker
Next session SessionStart:
-> Dispatcher reads inbox marker DAG
-> Spawns lane agents whose dependencies satisfied
-> Lanes execute with pre-hydrated context (no cold-start RTCH)
-> Lead consolidates lane outputs
-> Writes swarm-complete marker
Cross-reference: this swarm pattern is the consumption side of the cross-cadence rails primitive. The manufacturing side (prior session's /cadence authoring the rails) is documented in cgg-runtime/skills/cadence/SKILL.md under the Cross-Cadence Rail Manufacturing optional step. The cadence side manufactures; this swarm side consumes — same primitive, two sides.
When NOT to use: routine single-tic work where rails were not manufactured at prior /cadence (no rails to consume — use plain internal/external/hybrid); cold-start sessions where the prior session did not anticipate this work surface (the cost of rail manufacturing must be paid by the prior session, not retrofitted into the current one).
Every swarm generates a spec YAML before execution:
id: "<YYYY-MM-DD>_<slugified-task>"
title: "<task description>"
pattern: internal | external | hybrid
status: planned | active | consolidating | completed
created_at: "<ISO-8601>"
created_tic: <tic number>
lead:
entity_id: "ent_homeskillet"
context_budget: "<token estimate>"
agents:
- id: "agent-a"
role: "<what this agent does>"
pattern: internal | external
model: "sonnet | haiku | opus"
isolation: "worktree | none"
blocked_by: []
owns_regions: [] # optional — region-level ownership for sub-file parallelism (e.g. ["lights/*", "cameras/*"]); empty implies file-level ownership per blocked_by
output_path: "<where results go>"
timeout_minutes: <number>
- id: "agent-b"
role: "<what this agent does>"
pattern: internal
blocked_by: ["agent-a"]
output_path: "<where results go>"
consolidation:
strategy: "merge_artifacts | inbox_collect | lead_synthesize"
validation: "<how to verify completeness>"
output_path: "<final consolidated output>"
polling: # only for external/hybrid
interval_minutes: <number>
check_command: "<command to check completion>"
timeout_minutes: <number>
max_checks: <number>
Interactive mode (no pattern specified):
Direct mode (pattern + task specified):
--plan mode.audit-logs/swarms/<id>/spec.yaml.--plan mode, stop here and display spec for review.For each agent with no unmet blockers:
output_path or read scope touches a non-federation rung): invoke python3 <CGG_ROOT>/cgg-runtime/scripts/lib/load_doctrine_chain.py <agent_target_path> and prepend the briefing to the agent's prompt. The helper walks rung markers up to federation root and concatenates each rung's CLAUDE.md. Federation root auto-loads in every Claude Code session; estate and domain rungs do not — without the briefing, swarm workers see only federation doctrine and miss the rung-specific governing chain. Skip briefing only when the agent's scope is purely federation-rung or confined to audit-logs/ data surfaces.Agent() with run_in_background: true.isolation: "worktree", use worktree mode to avoid file conflicts.audit-logs/swarms/<id>/status.jsonl./loop polling at specified interval.When all agents complete:
consolidation.output_path.completed.Lead reads all agent output files and merges them. Best for parallel file operations where outputs don't overlap.
Results arrive as inbox transmissions. Lead scans inbox for all messages with matching thread_id, collects and synthesizes.
Lead reads all agent outputs and produces a new synthesis document. Best when agent outputs need interpretation, not just concatenation.
Agent teams are expensive. Each agent = separate Claude instance with full context.
| Pattern | Typical Cost | When Justified | |---------|-------------|----------------| | Internal (2-3 agents) | 2-3x single agent | Genuinely independent parallel work | | Internal (4+ agents) | 4+x single agent | Only if parallelism saves significant wall-clock time | | External | Low (polling is cheap) | Cross-service coordination | | Hybrid | Variable | Mix of local + external work |
Rule: Don't swarm what a single agent can do sequentially in reasonable time. Swarm when parallelism provides real wall-clock savings or when work genuinely cannot be serialized.
All swarm activity is logged to audit-logs/swarms/<id>/:
spec.yaml — swarm specification (immutable after creation)status.jsonl — agent spawn/completion events (append-only)consolidation/ — merged outputSPAWNED edge from lead, DELEGATED_BY edgeIf a swarm exceeds timeout or agents fail:
{swarm_id, failed_agents, timeout_exceeded}| Dimension | /stage | /swarm | |-----------|--------|--------| | Purpose | Adversarial reasoning (governance input) | Parallel deliverable work | | Agent roles | Positional advocates + lead | Task-specialized workers + lead | | Output | Governance artifacts (signals, CogPRs, pressure) | Deliverable artifacts (code, docs, configs) | | Consolidation | Lead synthesizes adversarial positions | Lead merges parallel outputs | | Template source | Arena templates (triangulation, lattice) | Swarm spec (internal/external/hybrid) |
Both use the same underlying mechanics (Agent tool, dependency DAG, phase gating) but serve different purposes. A swarm produces deliverables; a stage produces governance inputs.
autonomous_kernel/agent-inbox-schema.md — inbox state machine for async result collectioncgg-runtime/skills/stage/SKILL.md — sibling skill (adversarial reasoning)cgg-runtime/agents/mogul.md — Mogul's subdelegation pattern (donor for delegation mechanics)tools
Frederick Grant persona runtime — historian-of-how, witness of formation under pressure, qualified Remnant/Athenaeum-facing interpretive mechanic, tic-230 chronicler of runtime probity. Use when the user asks for Frederick Grant voice, Ubiquity Chronicles work, Parallel Lane Cadence essays, Elara counterweight passes, field notes, audio annotation, interview scripts, Logan/Wilderness analysis, or runtime probity writing after the P2/P1 tic-230 closures. CENTROID: authored persona runtime that documents live convergence without collapsing it into thesis IS: - lean SKILL.md entrypoint with rich profile/, stages/, scripts/, reference/, templates/, tools/, evals/ subtrees - 8-stage workflow (signal-intake → context-hydration → field-grounding → remnant-query → composition → elara-counterweight → receipt-closeout → tic230-probity) - 15 prompt-skeleton scripts for Frederick's standard composition surfaces - 9 collapse-zone guards covering Decorative Francophilia / Retrospective Certainty / Hero Narrative Intoxication / Conspiracy Closure / Academic Sedation / Activist Collapse / Breyden Conflation / Elara Erasure / Runtime-Doctrine Drift - cross-references into federation surfaces: publications/, audit-logs/governance/, ent_breyden/inbound/ubiquity-chronicles-tic175/, ent_homeskillet/canonical/ IS NOT: collapse_zones: - Breyden's voice (architect register; Frederick is not the architect) - Homeskillet's voice (orchestrator register; Frederick is not the primary) - generic French historian style (decorative Francophilia is a named negative ray) - prosecutor / debunker / prophet / mascot (legal accusation, certainty, evangelism, identity flattening — all forbidden) - retroactive certainty machine (live convergence must remain unresolved where the record is open) - doctrine inscription source (Frederick observes doctrine; he does not author it) - documentation editor (multi-file structure is authoring discipline, not generic doc rewrite) - federation-internal artifact (Frederick is a ghostwriter engaged from outside; the federation's runtime is legitimate object of historical analysis, but Frederick's own runtime — the skill that hosts him, loaded files, collapse-zone guards, authority model — is editor's territory, not Frederick's voice; insider language must be earned by composition arc, never deployed as default register) sibling_overlaps: - /complement (closure inference at active move — different surface, different lifecycle) - /consolidate (file-surface packaging — Frederick produces composition, not consolidation) - videographer skill (substrate capture — both are expression surfaces, distinct registers) - homeskillet-academy (educational scaffold — academy teaches, Frederick witnesses) WHEN: - when the work needs witness-of-formation prose - when the task asks for Frederick Grant by name, voice, or context - when a live convergence needs historical/cultural contextualization without closure - when a field note, essay, chronicle, audio annotation, or interview needs Frederick's register - when a Remnant/Athenaeum comparison is appropriate - when an Elara counterweight pass is needed - when runtime probity after tic 230 is relevant (P2 manifold-shape closure, P1 signal-projection-split closure) - on explicit Architect invocation NOT WHEN: - when Breyden's direct voice is needed (use Architect register, not Frederick) - when Homeskillet's execution-layer voice is needed (use orchestrator register, not Frederick) - when the task is ordinary implementation (Frederick is composition, not patching) - when the task asks for legal accusation or definitive claims without evidence - when the user wants generic French style rather than Frederick's runtime - when the federation has not produced enough operational reality to warrant outside reading RELATES TO: - /complement (closure-inference sibling — both gate compositional integrity) - /consolidate (packaging neighbor — Frederick composes; consolidate packages) - publications/the-ubiquity-chronicles-fg.md (primary chronicle, v1, ~tic 175) - publications/the-ubiquity-chronicles-v2-frederick-grant.md (v2 expansion, Book Zero + Book I) - publications/the-ubiquity-chronicles-vol-iii-frederick-grant.md (Volume III — The Embodiment, tic 230) - publications/the-ubiquity-interviews-fg.md (interview register companion) - audit-logs/governance/p2-harmony-manifold-input-patch-receipt-tic230.md (P2 closure receipt) - audit-logs/governance/p1-signal-projection-split-receipt-tic230.md (P1 closure receipt) ARGS: stance: dispatch off_envelope: ask core_dispatch_rays: - "" → primary invocation (full 8-stage workflow) - "chronicles" → Ubiquity Chronicles composition - "parallel" → Parallel Lane Cadence composition - "field-note" → Field Notes script - "interview" → Interview script - "elara-pass" → Elara counterweight on existing draft - "anti-collapse" → Anti-collapse audit on existing draft - "tic230-probity" → Runtime probity composition secondary_modulation_axes: - register: chronicle | essay | field-note | interview | annotation - depth: lean | full - target: telos-internal | external-readership
tools
Runtime tactical context hydration — staged discovery and bounded source-bearing hydration for agent intent. Answers "how does an agent know where to look before it already knows where to look?" via filesystem shape, structural signals, and typed candidate baskets. Working acronym: RTCH (runtime-tactical-context-hydration). CENTROID: intent → bounded, source-reenterable evidence packet via staged source-bearing discovery IS: - structured intake of agent/Architect intent (goal, seeds, profile, fanout, mutation risk) - zone orientation (cwd / repo root / zone root / rung chain / obvious truth files) - low-cost shape scout (directory map, headings, durable handles, JSON/YAML keys, refs) - typed candidate basket with origin/use taxonomy and pairing rule enforcement - tactical probe plan (multiple bounded probes, not one giant regex) - bounded chunk hydration with line-range provenance and next-re-entry commands - agent-ready evidence packet emission (selected_surfaces, unresolved_questions, caution_map) - optional handoff to /consolidate for full-surface dump packaging IS NOT: collapse_zones: - vector database (no embedding-space retrieval; federation prohibits at federation rung) - semantic oracle (RTCH does not "understand" content; it surfaces structural signals) - doctrine engine (RTCH produces evidence; downstream consumers judge truth) - terrain engine replacement (federation cartography handles multi-plane semantic projection; RTCH is tactical layer beneath) - /consolidate rewrite (discovery and packaging do not collapse) - lossy compressor (bounded chunks preserve source re-entry; never summarize away source) - confidence-inflated smart consolidator sibling_overlaps: - /consolidate (RTCH selects; /consolidate packages — distinct boundaries; compose, don't replace) - file-access-discipline (RTCH outputs targets; hydration USES file-access-discipline as execution primitive) - load-doctrine-chain (both serve subagent context; load-doctrine-chain owns CLAUDE.md chain only, RTCH owns wider source set) - cache-ops (pattern source for trust-tier shape; storage NOT shared; RTCH packets are separate evidence cache) - queue_state_compile (analogy only — both convert append-only source to compiled view; different transforms) WHEN: - when agent intent is vague and discovery is needed before reading or consolidation - when bare grep would over-fanout or under-discover a vague target - when an arena, harpoon, /review, or other lane needs source-bearing evidence before action - when bounded chunk hydration is appropriate (large governance files, doctrine chains, audit history) - when the candidate-basket discipline (origin/use tagging, pairing rule) is needed to prevent generic-term overconfidence - when source re-entry must be preserved (consumer may need to return to source for fuller context) NOT WHEN: - when target is fully known (single file, single line range) — read it directly via file-access-discipline - when the operation is mutation-only on a known target (use Edit/Write directly) - when /consolidate has already been invoked with explicit targets (RTCH would re-do discovery) - when the operation requires semantic similarity (RTCH does not do that; federation prohibits vector DB) - when the consumer needs a packaged dump only (skip RTCH; /consolidate alone is sufficient if targets are known) - when promoting doctrine (route through /review; RTCH evidence may inform but does not promote) RELATES TO: - /consolidate (compose: RTCH selects targets; /consolidate packages selected_surfaces into dump with provenance reference back to RTCH packet) - file-access-discipline (compose: RTCH Stage 6 hydration USES file-access-discipline chunked-read as execution primitive) - load-doctrine-chain (compose: RTCH may invoke for doctrine_chain target_profile zone orientation) - zone_root.py (compose: RTCH Stage 2 anchors on zone-root walk-up) - atomic-append (compose: optional RTCH packet persistence uses atomic-append write hygiene) - queue_state_compile (analogous: both implement "raw source → compiled view" pattern) - /review preflight (downstream: future integration consumes RTCH packets as bench-packet discovery surface) - arena spec authoring (downstream: future integration uses RTCH packets for context preparation) - harpoon orchestrator (downstream: future integration uses RTCH for anchor-spot discovery on external binders) ARGS: stance: dispatch off_envelope: ask # off_envelope rationale: RTCH requires a structured intake to operate (goal, # target_profile, fanout_level, mutation_risk, expected_output, enough_evidence). # Bare invocation without intake fields would force the lane to guess discovery # scope, defeating the discipline. Ask elicits the missing fields. core_dispatch_rays: - "" → interactive (elicit intake form) - "--goal <sentence>" → with intake fields on CLI - "--intake <intake_json_path>" → from a saved/persisted intake - "--persist" → persist resulting packet to audit-logs/rtch/packets/ - "--handoff-to-consolidate" → after packet emission, hand selected_surfaces to /consolidate secondary_modulation_axes: - target_profile: doctrine_chain | audit_history | code_path | manifest_registry | vague_intent | mixed - fanout_level: conservative | normal | wide - mutation_risk: read_only | low_mutation | high_mutation - expected_output: hydration_packet | target_set_for_consolidate | single_chunk | claim_evidence IMPLEMENTATION_STATUS: binder: audit-logs/governance/runtime-tactical-context-hydration-binder.md (Phase 1 complete, tic 223) runner_script: NOT YET BUILT — Phase 2 deliverable (planned: cgg-runtime/scripts/rtch.py) current_mode: manual-discipline — agent walks the 8 stages using Read/Bash/Grep tools directly promotion_status: design lane, not doctrine; Phase 7 routes the doctrine question after Phase 6 validation
development
Statusline legend — rapid decoder for the CGG telos radar (LITE + FULL modes). CENTROID: read-only legend surface that decodes statusline glyphs, positions, colors, and source attributions for the Architect at glance speed (the Architect perception substrate) IS: - static legend (glyph + position + color tier reference) - live decode mode (annotates current statusline values inline) - source attribution (where each rendered value reads from) IS NOT: collapse_zones: - statusline configurator (use /statusline install|mode|clear|uninstall) - governance state mutator (read-only on every surface it touches) - harmony invoker (use harmony-invoke.sh; this skill only decodes the cached pointer) - radar replacement (statusline renders ambient; sl-legend explains) - troubleshooter (does not diagnose hook failures or sync drift) sibling_overlaps: - /statusline (configuration sibling — same domain, different verb) - /governance-check (read-only governance snapshot — different aperture) WHEN: - on first encounter with the radar (Architect doesn't remember what ⊙ means) - when a glyph changes and the Architect wants to confirm semantics - when explaining the radar to someone else - on explicit Architect invocation NOT WHEN: - to change statusline behavior (use /statusline) - to act on a signal seen in the radar (use /siren) - to invoke harmony for fresh disposition (use harmony-invoke.sh) - mid-cadence (cadence is the boundary; this is reference) RELATES TO: - /statusline (configurator) — same domain; sl-legend is the reader - /siren (signal triage) — sl-legend points to what to triage - harmony-invoke.sh (disposition refresher) — sl-legend points at staleness ARGS: stance: dispatch off_envelope: proceed-with-note # off_envelope rationale: sl-legend is read-only reference; an undeclared arg # is most likely a typo against {live, lite, review, sources} — proceed with # static legend and note the unknown ray rather than refusing the read. core_dispatch_rays: - "" → static legend (full glyph + position decoder) - "live" → annotate current rendered statusline values inline + tic 214 markers source-backed - "lite" → compact tic 214 marker glossary only (glance-speed recall) - "review" → Architect perception substrate audit checklist (overclaim + naming drift detection) - "sources" → source attribution table (which file each value reads)
tools
Editorial intelligence scoring — reads transcripts the way a sharp editor would, scoring segments for shortform growth potential through the lens of audience context.