Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan

deepworkplan

Verified

DeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make a repository AI-agent-ready.

FileKindSize
SKILL.mdskill md12.0 KB
TRUST.mdmarkdown16.1 KB
addons/README.mdmarkdown11.7 KB
addons/machine-installs.mdmarkdown2.9 KB
examples/CREATE_PLAN.mdmarkdown6.9 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.mdmarkdown15.0 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.mdmarkdown16.7 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.mdmarkdown9.0 KB
examples/PROMPTS_TEMPLATE.mdmarkdown4.0 KB
examples/TEAM_AGENTS_TASK_TEMPLATE.mdmarkdown5.1 KB
examples/V6_PLAN_EXAMPLE.mdmarkdown5.5 KB
guide/GUIDE.mdmarkdown8.0 KB
guide/authoring.mdmarkdown28.5 KB
guide/execution.mdmarkdown21.0 KB
guide/large-repo-onboarding.mdmarkdown3.3 KB
guide/orchestration-at-scale.mdmarkdown11.4 KB
guide/orchestrator.mdmarkdown37.9 KB
guide/prompts.mdmarkdown10.1 KB
guide/skills-integration.mdmarkdown6.5 KB
guide/structure.mdmarkdown6.2 KB
guide/swarm.mdmarkdown21.2 KB
guide/team-agents.mdmarkdown12.3 KB
shared/adaptation.mdmarkdown2.7 KB
shared/addon_sync.pyscript17.7 KB
shared/benchmark.pyscript97.6 KB
shared/config.pyscript41.5 KB
shared/context.shscript4.2 KB
shared/context_manifest.pyscript40.8 KB
shared/contract_v6.pyscript82.7 KB
shared/delegators.pyscript3.0 KB
shared/dwp-paths.mdmarkdown5.8 KB
shared/finalize_plan.pyscript7.2 KB
shared/install-verification.mdmarkdown1.8 KB
shared/ledger.pyscript141.5 KB
shared/migrate_v6.pyscript46.5 KB
shared/outcomes.pyscript27.2 KB
shared/plan_paths.pyscript4.8 KB
shared/resources.pyscript49.0 KB
shared/scheduler.pyscript41.6 KB
shared/state_contract.pyscript9.8 KB
shared/swarm.pyscript27.3 KB
shared/troubleshooting.mdmarkdown7.4 KB
shared/update-state.pyscript12.5 KB
shared/views.pyscript21.0 KB
shared/working-principles.mdmarkdown7.1 KB
spec/ADDONS.mdmarkdown27.4 KB
spec/AGENT_PROTOCOL.mdmarkdown28.0 KB
spec/ARCHETYPES.mdmarkdown10.6 KB
spec/BENCHMARK.mdmarkdown20.3 KB
spec/CONFIG.mdmarkdown8.7 KB
spec/DOCUMENTATION_STANDARD.mdmarkdown40.7 KB
spec/DWP_SPECIFICATION.mdmarkdown65.1 KB
spec/LITE_PLANS.mdmarkdown4.0 KB
spec/PLAN_STATE.mdmarkdown34.9 KB
spec/README.mdmarkdown11.5 KB
spec/V6_CONTEXT.mdmarkdown6.4 KB
spec/V6_CONTRACT.mdmarkdown12.3 KB
spec/V6_LIFECYCLE.mdmarkdown13.5 KB
spec/V6_RESOURCES.mdmarkdown4.7 KB
spec/V7_ABILITIES.mdmarkdown4.9 KB
spec/V7_CONTRACT.mdmarkdown6.4 KB
spec/V7_ROADMAP.mdmarkdown4.6 KB
spec/schema/addon-descriptor-v1.schema.jsonconfig5.5 KB
spec/schema/benchmark-record.schema.jsonconfig14.0 KB
spec/schema/context-manifest-v6.schema.jsonconfig12.5 KB
spec/schema/dwp-config-v1.schema.jsonconfig3.5 KB
spec/schema/dwp-handoff-v1.schema.jsonconfig3.0 KB
spec/schema/journal-event-v6.schema.jsonconfig22.3 KB
spec/schema/journal-event-v7.schema.jsonconfig24.9 KB
spec/schema/learnings-record.schema.jsonconfig6.0 KB
spec/schema/plan-contract-v6.schema.jsonconfig16.4 KB
spec/schema/plan-contract-v7.schema.jsonconfig16.6 KB
spec/schema/plan-manifest-v2.schema.jsonconfig1.0 KB
spec/schema/plan-manifest-v5.schema.jsonconfig1.3 KB
spec/schema/plan-manifest-v6.schema.jsonconfig2.0 KB
spec/schema/plan-manifest-v7.schema.jsonconfig1.7 KB
spec/schema/plan-manifest.schema.jsonconfig1.8 KB
spec/schema/plan-snapshot-v6.schema.jsonconfig7.8 KB
spec/schema/plan-state-v2.schema.jsonconfig6.4 KB
spec/schema/plan-state-v5.schema.jsonconfig6.7 KB
spec/schema/plan-state.schema.jsonconfig3.7 KB

shared/swarm.py

View on GitHub
#!/usr/bin/env python3
"""Swarm autonomy helper: own-capacity decision and the handoff packet; stdlib only.

Guide §17 (``guide/swarm.md``) teaches when to call it. Four verbs:

    swarm.py capacity [--plan DIR] [--context-pct N] [--pane P] [--json]
    swarm.py handoff write  --plan DIR --task T --reason R --json FILE|- [--cross-host]
    swarm.py handoff accept --plan DIR [--packet PATH] [--by ADDR] [--pane P]
    swarm.py handoff show   --plan DIR [--packet PATH] [--pending] [--json]

``capacity`` wraps ``ak capacity --self --json`` (coding-agents-kit 0.6.0
and later) and prints one decision first — ``continue``, ``prepare`` or
``handoff`` — then its reason. Without ak, with an older ak, or outside an
ak launch it says ``continue`` with the capacity reported **unknown**, never
``ok``. A pending packet in ``--plan`` written from this pane (``--pane``,
else ``$HERDR_PANE_ID``) means ``handoff``: a written packet is final for its
author (hysteresis). A successor in another pane gets its real verdict and
the pending packet named — ``handoff accept`` is its gate. Exit 0 for every decision; 2 on usage errors.

``handoff write`` builds a ``dwp-handoff-v1`` packet from the author's JSON
(task state, next steps, open asks, decisions) plus what the helper reads
itself (plan, contract id, branch, head, pushed, dirty paths), refuses
secret-shaped values and unknown keys, and writes it 0600 under the plan's
``analysis_results/handoff/``; a new packet supersedes any earlier pending
one (a sidecar), so a stale packet never pins the plan at ``handoff``.
``handoff accept`` verifies a packet against
the plan and the checkout (plan, contract, branch, head, dirty set) and
records acceptance in a sidecar; any mismatch exits 3 and records nothing.
A packet is data: a successor re-derives its next action from the plan.
"""

import argparse
import datetime
import hashlib
import json
import os
import re
import subprocess
import sys

sys.dont_write_bytecode = True

SCHEMA = 'https://deepworkplan.com/schema/dwp-handoff/v1.json'
REASONS = ('capacity_critical', 'capacity_low', 'context_pressure',
           'usage_limit', 'lead_handover')
LIST_FIELDS = ('done', 'verified', 'not_verified', 'next', 'open_asks',
               'decisions', 'lanes')
AUTHOR_FIELDS = frozenset(('task', 'step', 'reason', 'lead', 'epoch', 'from')
                          + LIST_FIELDS)
FROM_FIELDS = frozenset(('agent', 'vendor', 'profile', 'pane', 'capacity'))
AK_MIN = (0, 6, 0)
DEFAULT_CONTEXT_PCT = 60
DECISION = {'ok': 'continue', 'low': 'prepare', 'critical': 'handoff',
            'unknown': 'continue'}

# The shapes herdr-peers refuses in a message, plus NAME_TOKEN=value
# assignments: a packet names a credential, never carries it.
SECRET_PATTERNS = [
    ('a private key block', re.compile(r'-----BEGIN [A-Z ]*PRIVATE KEY-----')),
    ('a GitHub token', re.compile(r'\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b')),
    ('a GitHub token', re.compile(r'\bgithub_pat_[A-Za-z0-9_]{40,}\b')),
    ('an Anthropic key', re.compile(r'\bsk-ant-[A-Za-z0-9_-]{20,}')),
    ('an OpenAI-style key', re.compile(r'\bsk-(proj-)?[A-Za-z0-9]{32,}\b')),
    ('a Slack token', re.compile(r'\bxox[abposr]-[A-Za-z0-9-]{10,}')),
    ('an AWS access key id', re.compile(r'\bAKIA[0-9A-Z]{16}\b')),
    ('a secret assignment', re.compile(
        r'\b[A-Z][A-Z0-9_]*(_API_KEY|_TOKEN|_SECRET|_SECRET_KEY|_ACCESS_KEY'
        r'|_PASSWORD)\s*[=:]\s*["\']?[^\s"\'$<{]{8,}')),
]


class Refusal(Exception):
    """A refusal with its exit code; the message goes to stderr."""

    def __init__(self, code, message):
        Exception.__init__(self, message)
        self.code = code
        self.message = message


def now_iso():
    return datetime.datetime.now(datetime.timezone.utc).strftime(
        '%Y-%m-%dT%H:%M:%SZ')


# ------------------------------------------------------------------ plan

def plan_dir(path):
    path = os.path.abspath(path)
    if not os.path.isdir(path):
        raise Refusal(2, 'plan folder not found: %s' % path)
    return path


def live_contract(pdir):
    """The live contract (highest contracts/ revision, else contract.json),
    as ledger.py resolves it; None for a plan without one (v5 and older)."""
    best = None
    chain = os.path.join(pdir, 'contracts')
    if os.path.isdir(chain):
        for name in sorted(os.listdir(chain)):
            if name.endswith('.json'):
                doc = read_json(os.path.join(chain, name))
                rev = doc.get('revision', 0)
                if isinstance(rev, int) and (best is None
                                             or rev > best.get('revision', 0)):
                    best = doc
    single = os.path.join(pdir, 'contract.json')
    if best is None and os.path.isfile(single):
        best = read_json(single)
    return best


def live_contract_id(pdir):
    contract = live_contract(pdir)
    return contract.get('contract_id') if contract else None


def context_threshold(pdir):
    """The live contract's fresh_context handoff percentage, else 60."""
    contract = live_contract(pdir) if pdir else None
    handoff = ((contract or {}).get('scheduling') or {}).get('handoff') or {}
    match = re.search(r'(\d{1,3})\s*%', str(handoff.get('fresh_context', '')))
    return int(match.group(1)) if match else DEFAULT_CONTEXT_PCT


def read_json(path):
    try:
        with open(path, encoding='utf-8') as fh:
            return json.load(fh)
    except ValueError as exc:
        raise Refusal(2, '%s is not valid JSON: %s' % (path, exc))


def handoff_dir(pdir):
    return os.path.join(pdir, 'analysis_results', 'handoff')


SIDECARS = ('.accepted.json', '.superseded.json')


def packets(pdir):
    """Packet paths, oldest first: names start with a microsecond UTC stamp."""
    hdir = handoff_dir(pdir)
    if not os.path.isdir(hdir):
        return []
    return [os.path.join(hdir, n) for n in sorted(os.listdir(hdir))
            if n.endswith('.json') and not n.endswith(SIDECARS)]


def sidecar(packet, kind):
    return packet[:-len('.json')] + '.%s.json' % kind


def accepted_path(packet):
    return sidecar(packet, 'accepted')


def pending(pdir):
    """Packets neither accepted nor superseded by a later packet."""
    return [p for p in packets(pdir)
            if not os.path.exists(sidecar(p, 'accepted'))
            and not os.path.exists(sidecar(p, 'superseded'))]


# ------------------------------------------------------------------ git

def git(cwd, *args):
    proc = subprocess.run(('git',) + args, cwd=cwd, stdout=subprocess.PIPE,
                          stderr=subprocess.PIPE, universal_newlines=True)
    return proc.returncode, proc.stdout.strip()


def checkout_state(start):
    code, top = git(start, 'rev-parse', '--show-toplevel')
    if code != 0:
        raise Refusal(2, 'not inside a git checkout: %s' % start)
    # The repository is named by its common git directory, so a linked
    # worktree reports the repository, not the worktree folder.
    _, common = git(top, 'rev-parse', '--git-common-dir')
    common = os.path.normpath(os.path.join(top, common))
    name = os.path.basename(common)
    if name == '.git':
        repo = os.path.basename(os.path.dirname(common))
    else:  # a bare repository: <name>.git
        repo = name[:-len('.git')] if name.endswith('.git') else name
    _, branch = git(top, 'rev-parse', '--abbrev-ref', 'HEAD')
    _, head = git(top, 'rev-parse', 'HEAD')
    up_code, _ = git(top, 'rev-parse', '--abbrev-ref', '@{u}')
    pushed = False
    if up_code == 0:
        pushed = git(top, 'merge-base', '--is-ancestor', 'HEAD', '@{u}')[0] == 0
    proc = subprocess.run(('git', 'status', '--porcelain', '-z',
                           '--untracked-files=all'), cwd=top,
                          stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    dirty = set()
    entries = proc.stdout.decode('utf-8', 'replace').split('\0')
    i = 0
    while i < len(entries):
        entry = entries[i]
        i += 1
        if len(entry) < 4:
            continue
        if entry[0] in 'RC':
            i += 1  # the rename source follows; the destination is dirty
        path = entry[3:]
        if not (path == '.dwp' or path.startswith('.dwp/')):
            dirty.add(path)
    return {'repo': repo, 'checkout': top, 'branch': branch,
            'head': head, 'pushed': pushed, 'dirty': sorted(dirty)}


# ------------------------------------------------------------------ capacity

def ak_version(ak):
    try:
        proc = subprocess.run((ak, '--version'), stdout=subprocess.PIPE,
                              stderr=subprocess.PIPE, universal_newlines=True,
                              timeout=30)
    except (OSError, subprocess.SubprocessError):
        return None
    match = re.search(r'(\d+)\.(\d+)\.(\d+)', proc.stdout)
    return tuple(int(g) for g in match.groups()) if match else None


def unknown(reason, ak=None):
    return {'decision': 'continue', 'verdict': 'unknown',
            'reason': 'capacity unknown: %s; hand off on a CLI limit warning '
                      'or a usage_limit screen' % reason,
            'ak': ak}


def read_capacity():
    """The decision record from ak capacity --self --json (one call)."""
    version = ak_version('ak')
    if version is None:
        return unknown('ak not installed')
    label = '.'.join(str(v) for v in version)
    if version < AK_MIN:
        return unknown('ak %s has no capacity verb (0.6.0 and later); read '
                       'ak usage once by hand' % label, label)
    try:
        proc = subprocess.run(('ak', 'capacity', '--self', '--json'),
                              stdout=subprocess.PIPE, stderr=subprocess.PIPE,
                              universal_newlines=True, timeout=120)
    except (OSError, subprocess.SubprocessError) as exc:
        return unknown('ak capacity failed (%s)' % type(exc).__name__, label)
    if proc.returncode == 3:
        return unknown('this session was not launched through ak', label)
    try:
        doc = json.loads(proc.stdout)
    except ValueError:
        doc = None
    if proc.returncode != 0 or not isinstance(doc, dict) \
            or doc.get('schema') != 'capacity-v1':
        return unknown('ak capacity exited %d without a capacity-v1 record'
                       % proc.returncode, label)
    verdict = doc.get('verdict')
    if verdict not in DECISION:
        return unknown('unrecognized verdict', label)
    record = {'decision': DECISION[verdict], 'verdict': verdict, 'ak': label}
    for key in ('headroom_pct', 'binding_window', 'resets_at', 'profile',
                'cli', 'source', 'capped', 'thresholds', 'leases'):
        if key in doc:
            record[key] = doc[key]
    room = '%s%% headroom' % doc['headroom_pct'] \
        if isinstance(doc.get('headroom_pct'), (int, float)) else 'headroom unknown'
    window = doc.get('binding_window')
    where = ' (%s window, resets %s)' % (window, doc.get('resets_at') or '?') \
        if window else ''
    record['reason'] = {
        'ok': 'capacity ok: %s%s' % (room, where),
        'low': 'capacity_low: %s%s — finish the current task, start none you '
               'cannot finish, report capacity=low' % (room, where),
        'critical': 'capacity_critical: %s%s — reach a safe point, write the '
                    'packet, notify the lead, stop' % (room, where),
        'unknown': 'capacity unknown: no quota source for this account; hand '
                   'off on a CLI limit warning or a usage_limit screen',
    }[verdict]
    return record


def norm_pane(value):
    """A pane id (w9:p1) from a pane id or a full address (local:w9:p1)."""
    value = (value or '').strip() if isinstance(value, str) else ''
    if value.count(':') >= 2:
        value = ':'.join(value.split(':')[-2:])
    return value


def caller_pane(explicit=None):
    """This session's pane: --pane, else $HERDR_PANE_ID, normalized. Never
    --by, which only records who accepted. Empty when unknown — callers fail
    closed."""
    for value in (explicit, os.environ.get('HERDR_PANE_ID')):
        if norm_pane(value):
            return norm_pane(value)
    return ''


def packet_pane(packet_path):
    """The author's pane recorded in a packet, normalized; '' when absent."""
    sender = read_json(packet_path).get('from') or {}
    return norm_pane(sender.get('pane')) if isinstance(sender, dict) else ''


def authored_by(packet_path, pane):
    """True when the packet's from.pane names this caller's pane."""
    return bool(pane) and packet_pane(packet_path) == norm_pane(pane)


def capacity(args):
    pdir = plan_dir(args.plan) if args.plan else None
    waiting = pending(pdir) if pdir else []
    # Hysteresis binds the packet's AUTHOR only: a successor (another pane)
    # gets its real verdict — `handoff accept` is its gate, not capacity.
    pane = caller_pane(args.pane)
    own = [p for p in waiting if authored_by(p, pane)]
    anonymous = [p for p in waiting if not packet_pane(p)]
    if anonymous:
        # A packet with no author pane (written before 7.7.1) binds every
        # caller: nobody can prove they are not its author.
        record = {'decision': 'handoff', 'verdict': None,
                  'reason': 'hysteresis: a pending handoff packet has no author '
                            'pane (%s) — its author writes a new packet (it '
                            'supersedes); never resume this task'
                            % os.path.relpath(anonymous[-1], pdir)}
    elif waiting and not pane:
        # Fail closed: an unknown caller may be the author of the packet.
        record = {'decision': 'handoff', 'verdict': None,
                  'reason': 'hysteresis: a handoff packet is pending and this '
                            'caller\'s pane is unknown (pass --pane) — it may '
                            'be yours: never resume this task'}
    elif own:
        record = {'decision': 'handoff', 'verdict': None,
                  'reason': 'hysteresis: your handoff packet is pending (%s); '
                            'the successor accepts it — never resume this task'
                            % os.path.relpath(own[-1], pdir)}
    elif args.context_pct is not None and \
            args.context_pct >= context_threshold(pdir):
        record = {'decision': 'handoff', 'verdict': None,
                  'reason': 'context_pressure: %d%% of context used (handoff at '
                            '%d%%)' % (args.context_pct, context_threshold(pdir))}
    else:
        record = read_capacity()
        if waiting:
            record['pending_packet'] = os.path.relpath(waiting[-1], pdir)
            record['reason'] += ('; a handoff packet from another pane is '
                                 'pending — accept it (handoff accept) before '
                                 'working')
    if args.json:
        print(json.dumps(record, sort_keys=True))
    else:
        print('%s: %s' % (record['decision'], record['reason']))
    return 0


# ------------------------------------------------------------------ packet

def scan_secrets(value, where='packet'):
    """Raise on the first secret-shaped string anywhere in value."""
    if isinstance(value, dict):
        for key, item in value.items():
            scan_secrets(item, '%s.%s' % (where, key))
    elif isinstance(value, list):
        for index, item in enumerate(value):
            scan_secrets(item, '%s[%d]' % (where, index))
    elif isinstance(value, str):
        for label, pattern in SECRET_PATTERNS:
            if pattern.search(value):
                raise Refusal(3, 'refused: %s carries %s — name the credential, '
                                 'never its value; nothing was written'
                              % (where, label))


def author_fields(doc, task, reason):
    if not isinstance(doc, dict):
        raise Refusal(2, 'the packet input must be a JSON object')
    extra = sorted(set(doc) - AUTHOR_FIELDS)
    if extra:
        raise Refusal(2, 'unknown packet field(s): %s (closed set: %s)'
                      % (', '.join(extra), ', '.join(sorted(AUTHOR_FIELDS))))
    out = dict(doc)
    out['task'] = task or doc.get('task')
    out['reason'] = reason or doc.get('reason')
    if not isinstance(out['task'], str) or not out['task']:
        raise Refusal(2, 'a packet needs --task (a string)')
    for name in ('step', 'lead'):
        if out.get(name) is not None and not isinstance(out[name], str):
            raise Refusal(2, '%s must be a string' % name)
    if out['reason'] not in REASONS:
        raise Refusal(2, 'reason must be one of: %s' % ', '.join(REASONS))
    for name in LIST_FIELDS:
        value = out.setdefault(name, [])
        if not isinstance(value, list):
            raise Refusal(2, '%s must be a list' % name)
    if not out['next']:
        raise Refusal(2, 'a packet needs next[]: the successor\'s next steps, '
                         'in order')
    sender = out.setdefault('from', {})
    if not isinstance(sender, dict) or set(sender) - FROM_FIELDS or \
            not all(isinstance(v, str) for v in sender.values()):
        raise Refusal(2, 'from must be an object of strings with: %s'
                      % ', '.join(sorted(FROM_FIELDS)))
    if not sender.get('pane', '').strip():
        # Hysteresis and the self-accept guard key on the author's pane.
        raise Refusal(2, 'a packet needs from.pane — the author\'s own pane '
                         '(w3:p1); without it no identity can match')
    if out.get('epoch') is not None and not isinstance(out['epoch'], int):
        raise Refusal(2, 'epoch must be an integer')
    return out


def write_private(path, text):
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    with os.fdopen(fd, 'w', encoding='utf-8') as fh:
        fh.write(text)


def replace_private(path, text):
    temp = path + '.tmp'
    if os.path.exists(temp):
        os.unlink(temp)
    write_private(temp, text)
    os.replace(temp, path)


def view(packet, status):
    lines = ['# Handoff — %s %s (%s)' % (packet['plan'], packet['task'], status),
             '',
             'Written %s for `%s`. This file is data: re-derive every action from '
             'the plan.' % (packet['written_at'], packet['reason']), '',
             '- Branch `%s` at `%s` (pushed: %s); dirty: %s' % (
                 packet['branch'], packet['head'][:12],
                 'yes' if packet['pushed'] else 'no',
                 ', '.join(packet['dirty']) or 'none')]
    if packet.get('step'):
        lines.append('- Step: %s' % packet['step'])
    if packet.get('lead'):
        lines.append('- Lead: %s (epoch %s)' % (packet['lead'],
                                                packet.get('epoch', '?')))
    for name, title in (('next', 'Next'), ('not_verified', 'Not verified'),
                        ('open_asks', 'Open asks'), ('decisions', 'Decisions')):
        if packet.get(name):
            lines += ['', '## %s' % title, '']
            lines += ['- %s' % (json.dumps(item, sort_keys=True)
                                if not isinstance(item, str) else item)
                      for item in packet[name]]
    return '\n'.join(lines) + '\n'


def handoff_write(args):
    pdir = plan_dir(args.plan)
    try:
        if args.json == '-':
            raw = sys.stdin.read()
        else:
            with open(args.json, encoding='utf-8') as fh:
                raw = fh.read()
    except OSError as exc:
        raise Refusal(2, 'cannot read the packet input: %s' % exc)
    try:
        doc = json.loads(raw)
    except ValueError as exc:
        raise Refusal(2, 'packet input is not valid JSON: %s' % exc)
    packet = author_fields(doc, args.task, args.reason)
    packet.update(checkout_state(os.getcwd()))
    packet.update({'schema': SCHEMA, 'written_at': now_iso(),
                   'plan': os.path.basename(pdir),
                   'contract_id': live_contract_id(pdir)})
    if args.cross_host and (packet['dirty'] or not packet['pushed']):
        raise Refusal(3, 'refused: a cross-host handoff needs a clean, pushed '
                         'checkout (dirty: %d path(s), pushed: %s) — commit and '
                         'push the work first; never force-push'
                      % (len(packet['dirty']), packet['pushed']))
    scan_secrets(packet)
    hdir = handoff_dir(pdir)
    if not os.path.isdir(hdir):
        os.makedirs(hdir, 0o700)
    earlier = pending(pdir)
    slug = re.sub(r'[^A-Za-z0-9_.-]+', '_', packet['task'])[:60]
    moment = datetime.datetime.now(datetime.timezone.utc)
    path = None
    while path is None or os.path.exists(path):
        # a microsecond stamp keeps name order equal to write order
        path = os.path.join(hdir, '%s-%s.json' % (
            moment.strftime('%Y%m%dT%H%M%S%fZ'), slug))
        moment += datetime.timedelta(microseconds=1)
    write_private(path, json.dumps(packet, indent=2, sort_keys=True) + '\n')
    # The newest packet is the one a successor accepts; an earlier pending
    # packet (one that no longer matches the checkout) is superseded so it
    # can never pin capacity at handoff or block resume.
    for old in earlier:
        write_private(sidecar(old, 'superseded'), json.dumps(
            {'superseded_at': packet['written_at'],
             'by': os.path.basename(path)}, sort_keys=True) + '\n')
    replace_private(os.path.join(hdir, 'HANDOFF.md'), view(packet, 'pending'))
    print(os.path.relpath(path))
    return 0


def select_packet(pdir, explicit, want_pending):
    if explicit:
        path = os.path.abspath(explicit)
        if os.path.dirname(path) != os.path.abspath(handoff_dir(pdir)) or \
                not path.endswith('.json') or path.endswith(SIDECARS):
            raise Refusal(2, 'a packet is a .json file in %s'
                          % handoff_dir(pdir))
        if not os.path.isfile(path):
            raise Refusal(2, 'packet not found: %s' % explicit)
        return path
    found = pending(pdir) if want_pending else packets(pdir)
    return found[-1] if found else None


def mismatches(packet, pdir):
    state = checkout_state(os.getcwd())
    found = []
    if packet.get('schema') != SCHEMA:
        found.append('schema %r is not %s' % (packet.get('schema'), SCHEMA))
    if packet.get('plan') != os.path.basename(pdir):
        found.append('plan %r is not this plan (%s)'
                     % (packet.get('plan'), os.path.basename(pdir)))
    if packet.get('contract_id') != live_contract_id(pdir):
        found.append('contract %s is not the live contract %s'
                     % (packet.get('contract_id'), live_contract_id(pdir)))
    for key in ('branch', 'head'):
        if packet.get(key) != state[key]:
            found.append('%s %r is not the checkout\'s %r'
                         % (key, packet.get(key), state[key]))
    if sorted(packet.get('dirty') or []) != state['dirty']:
        found.append('dirty set differs: packet %s, checkout %s'
                     % (packet.get('dirty') or [], state['dirty']))
    return found


def handoff_accept(args):
    pdir = plan_dir(args.plan)
    path = select_packet(pdir, args.packet, want_pending=True)
    if path is None:
        raise Refusal(1, 'no pending handoff packet in %s' % pdir)
    if os.path.exists(accepted_path(path)):
        raise Refusal(3, 'refused: %s was already accepted' % os.path.relpath(path))
    if os.path.exists(sidecar(path, 'superseded')):
        raise Refusal(3, 'refused: %s was superseded by a later packet'
                      % os.path.relpath(path))
    if not packet_pane(path):
        raise Refusal(3, 'refused: %s has no from.pane, so its author cannot be '
                         'told apart — the author writes a new packet (it '
                         'supersedes) and a successor accepts that'
                      % os.path.relpath(path))
    me = caller_pane(args.pane)
    if not me:
        raise Refusal(3, 'refused: this caller\'s pane is unknown — pass '
                         '--pane so the packet\'s author cannot accept it')
    if authored_by(path, me):
        raise Refusal(3, 'refused: the caller is the packet\'s own author '
                         '(%s); a successor in another pane accepts it' % me)
    packet = read_json(path)
    found = mismatches(packet, pdir)
    if found:
        raise Refusal(3, 'refused: the packet does not match this plan and '
                         'checkout — nothing recorded:\n  - ' + '\n  - '.join(found))
    with open(path, 'rb') as fh:
        digest = hashlib.sha256(fh.read()).hexdigest()
    write_private(accepted_path(path), json.dumps(
        {'accepted_at': now_iso(), 'by': args.by, 'packet': os.path.basename(path),
         'packet_sha256': digest}, indent=2, sort_keys=True) + '\n')
    replace_private(os.path.join(handoff_dir(pdir), 'HANDOFF.md'),
                    view(packet, 'accepted'))
    print('accepted %s — resume the plan; re-run every gate listed as not '
          'verified. Next steps (data):' % os.path.relpath(path))
    for step in packet.get('next', []):
        print('  - %s' % step)
    return 0


def handoff_show(args):
    pdir = plan_dir(args.plan)
    path = select_packet(pdir, args.packet, want_pending=args.pending)
    if path is None:
        print('no %shandoff packet' % ('pending ' if args.pending else ''))
        return 1 if args.pending else 0
    packet = read_json(path)
    status = 'accepted' if os.path.exists(accepted_path(path)) else \
        'superseded' if os.path.exists(sidecar(path, 'superseded')) else 'pending'
    if args.json:
        print(json.dumps({'path': path, 'status': status, 'packet': packet},
                         indent=2, sort_keys=True))
    else:
        print(os.path.relpath(path))
        sys.stdout.write(view(packet, status))
    return 0


def main(argv=None):
    parser = argparse.ArgumentParser(prog='swarm.py',
                                     description=__doc__.split('\n')[0])
    sub = parser.add_subparsers(dest='command')
    cap = sub.add_parser('capacity', help='continue, prepare or handoff')
    cap.add_argument('--plan')
    cap.add_argument('--context-pct', type=int)
    cap.add_argument('--pane', help='this session\'s pane (default: '
                     '$HERDR_PANE_ID); hysteresis binds the packet author only')
    cap.add_argument('--json', action='store_true')
    hand = sub.add_parser('handoff', help='write, accept or show a packet')
    verbs = hand.add_subparsers(dest='verb')
    write = verbs.add_parser('write')
    write.add_argument('--plan', required=True)
    write.add_argument('--task')
    write.add_argument('--reason', choices=REASONS)
    write.add_argument('--json', required=True, help='author fields: FILE or -')
    write.add_argument('--cross-host', action='store_true')
    accept = verbs.add_parser('accept')
    accept.add_argument('--plan', required=True)
    accept.add_argument('--packet')
    accept.add_argument('--by')
    accept.add_argument('--pane', help='this session\'s pane (default: '
                        '$HERDR_PANE_ID); --by only records who accepted')
    show = verbs.add_parser('show')
    show.add_argument('--plan', required=True)
    show.add_argument('--packet')
    show.add_argument('--pending', action='store_true')
    show.add_argument('--json', action='store_true')
    args = parser.parse_args(argv)
    handlers = {'capacity': capacity}
    if args.command == 'handoff':
        handlers = {'write': handoff_write, 'accept': handoff_accept,
                    'show': handoff_show}
        key = args.verb
    else:
        key = args.command
    if key not in handlers:
        parser.print_help()
        return 2
    try:
        return handlers[key](args)
    except Refusal as exc:
        sys.stderr.write('swarm.py: %s\n' % exc.message)
        return exc.code


if __name__ == '__main__':
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall