DOCSEARCHbyAlgolia
Submit Docs

ccswarm

repository·master·Indexed 40 days ago

https://github.com/nwiizo/ccswarm

An AI Agent Workflow DevOps toolchain and workflow engine designed to complement Claude Code Agent Teams. It implements the 'Sangha' principle—a structured process of shared acceptance criteria, separate assessments, and recorded decisions—to transform uncertain coding tasks into reviewable changes. Version 0.10.1 supports multiple providers including Claude and Codex, offering features such as task queuing, custom workflow (flow) authoring, and agent isolation modes via GitWorktree, Container, or Hybrid strategies.

Tokens
47.4K
Snippets
136
Records
222
Agent score
99%

What's inside ccswarm

  2. Understand Sangha vote validation behavior

    master

    In the current release (v0.10.0+), the Sangha voting mechanism follows these rules:

    • Valid approval votes: Only successfully completed Sangha members can approve. Failed, partial, or unknown results are treated as abstentions.
    • Reachable quorum: Flow validation will reject any quorum that is higher than the effective member count (including default membership).
    • Distinct member results: Generated member IDs are unique to prevent collisions or overwriting other reviews.
    • Quorum Policy: The default policy is a two-of-three quorum.

    Note: This release does not claim a full implementation of the evidence-based Sangha protocol.

  3. Understand Oracles and Assertions in ccswarm

    master

    Oracles are the mechanisms used to validate that a scenario's outcome is correct. Assertions in a scenario file trigger these oracles. Supported oracle types include:

    • Text oracles: Check for the presence (expect_text) or absence (forbid_text) of substrings.
    • File oracles: Verify the existence of specific paths (files_exist).
    • Command oracles: Ensure specific system commands exit with code 0 (command_ok).
    • Policy oracles: Enforce linting, testing, or security gates.
    • Metric oracles: Validate performance and cost constraints, such as max_duration_secs or max_tokens.

  4. Understand the Sangha decision-making model

    master

    Sangha is the core decision engine of ccswarm. It is designed to move from raw evidence to a justified decision through a structured process. The core mental model relies on five essential features:

    1. Shared Subject with Separate Assessments: Multiple members (agents/personas) assess the same subject independently.
    2. Evidence and Objections: Decisions are based on documented evidence and explicit objections rather than just vote totals.
    3. Deterministic Acceptance and Bounded Revision: Acceptance follows strict rules, and revisions are limited to prevent infinite loops.
    4. Decision Reports: The process produces an actionable report containing reasons, evidence, and objections.
    5. Recovery: The system supports resuming workflows while preserving valid evidence and decision checkpoints.

    Note: While the product core aims for these behaviors, current implementations may have gaps in quorum validation, report detail, and strict evidence binding. Always verify that your decision reports contain the necessary justifications before acting on them.

  5. Understand ccswarm execution via A2A REST API

    master

    When configured to use an A2A (Agent-to-Agent) backend, ccswarm interacts with the server using the following pattern:

    1. Discovery: ccswarm models A2A Agent Card fields including name, description, supportedInterfaces, capabilities, version, and skills.
    2. Execution: ccswarm sends a user Message containing a text Part to the POST /message:send endpoint.
    3. Response: ccswarm extracts text parts from the returned message, task, or artifacts.
    4. Processing: The bridge parses the output into structured results (build, test, log, or plain-text), updates agent context, persists session state, and returns token/cost metadata if provided by the backend.

  6. Understand the ccswarm Multi-Agent Architecture

    master

    ccswarm uses a two-layer orchestration model to manage multi-agent workflows. Developers should choose between these layers based on the required level of control and auditability:

    • Layer A (ccswarm orchestration): The outer control plane. It owns the flow YAML, stages, gates, reports, event logs, retries, and recovery. Use this when results must be independently auditable, cross-provider, or recoverable on a per-child basis.
    • Layer B (provider-native subagency): The inner layer where a single provider (like Claude or Codex) spawns and manages its own child agents within a single stage. Use this when all children share one provider, the task is read-heavy or highly parallelizable, and you only need the aggregate result from the provider.

    Rule of thumb: Never assume Layer B support exists just because a provider is used. Always probe capabilities first and fall back to Layer A orchestration.

  7. How Astra capabilities are designed for the Sangha process

    master

    The integration of Astra (GPT-6 Astra) into the Sangha process is designed to make long-running work more responsive. The design focuses on several key behavioral patterns:

    • Async Work: Tracking pending jobs with original call identities so work can continue while waiting for results (e.g., running tests while inspecting documentation).
    • Mid-turn Steering: Accepting user corrections during a run without losing the original task objective. A change in scope or acceptance criteria creates a new decision revision.
    • Adjustable Reasoning: Increasing model effort/reasoning for difficult decisions (ambiguous plans, conflicting evidence) while using cheaper, lower-effort execution for well-specified work.
    • Native Delegation: Using subagents for divisible complex work, keeping them within a single stage with a shared budget and attributable results.
    • Context Continuity: Preserving compact task briefs and evidence references across checkpoints.

  8. Understand the ccswarm Product Model and Vocabulary

    master

    ccswarm organizes work around a specific set of abstractions designed to turn uncertain development tasks into verified, reviewable changes. Understanding these terms is essential for interacting with the CLI and managing workflows:

    • Flow: A reusable workflow state machine.
    • Stage: A single unit within a flow. Stages can execute, judge, branch, fork, call subflows, or govern.
    • Order: A durable work request (richer than a simple queued string).
    • Run: A concrete execution attempt of an order or a direct task.
    • Report: A named output artifact promised by a stage.
    • Gate: A machine or human condition that must pass before a stage or run advances.
    • Verdict: The normalized decision from a stage, judge, Sangha member, or gate.
    • Desk: The primary operator surface for managing completed, failed, partial, and pending work.
    • Escalation: A controlled upgrade of the provider, model, or permissions when progress stalls.
    • Recovery Point: The exact state (flow/stage/order) from which a run can be resumed or retried.

  9. Understand the Sangha product core concept

    master

    Sangha is the core decision-governance layer of ccswarm. Its purpose is to transform uncertain coding work into reviewable, verified changes. Instead of relying on simple agent conversations, Sangha uses a structured process of shared acceptance criteria, separate assessments, and evidence-backed objections to reach a justified acceptance decision.

    Key Mental Models:

    • Providers vs. Workflow Engine: Providers (agents/tools) execute the work, while the Sangha workflow engine decides if the evidence permits moving to the next stage.
    • Two Sangha Checkpoints:
      1. Plan Assessment: Evaluates if the approach is specified, proportionate, and if criteria/verification are feasible.
      2. Change Assessment: Evaluates if the actual code change satisfies the criteria, with all required checks and evidence present.
    • Decision Outcomes: The target outcomes are accepted, needs_revision, and needs_input. These are distinct from execution outcomes like failure, timeout, or cancellation.

  10. Configure Sangha membership and quorum

    master

    Sangha uses a specification (SanghaSpec) to define the participants in a decision process.

    • Default Membership: By default, the specification includes roles for planner, reviewer, and QA.
    • Quorum: The default quorum is set to 2. If a quorum is unreachable (e.g., not enough members provide valid votes), the process is rejected.
    • Implementation Note: Future versions will enforce stricter review coverage requirements. Ensure your configuration provides enough distinct members to meet the required quorum.

  11. Configure Sangha assessment in workflow stages

    master

    You can request a Sangha assessment within a workflow stage by using the sangha: key. This requires defining a quorum (number of approvals needed) and members (personas involved). Members provide assessments that result in SANGHA_DECISION=APPROVE or SANGHA_DECISION=REVISE.

    Note: The permission: readonly setting is requested but is not currently enforced by the Codex adapter, which uses workspace-write.

    stages:
  - id: sangha
    instruction: "Review the plan before implementation"
    permission: readonly
    sangha:
      quorum: 2
      members:
        - { id: planner, persona: planner }
        - { id: reviewer, persona: reviewer }
        - { id: qa, persona: qa }

  12. Best Practices for Frontend Agents

    master

    To ensure high-quality output, Frontend agents should follow these architectural and implementation standards:

    • Architecture: Follow component-based architecture.
    • Design: Implement responsive design principles.
    • Accessibility: Ensure compliance with WCAG guidelines.
    • Performance: Optimize via techniques like lazy loading and code splitting.
    • Code Quality: Write clean, maintainable code accompanied by proper documentation.