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/addon_sync.py

View on GitHub
#!/usr/bin/env python3
"""DeepWorkPlan addon sync planner (onboard Phase 7b, "all addons" and upgrade).

Read-only. For every addon the pack ships it reports what is installed, at
which version, what the repository's registry (``.dwp/config.json``)
recorded, the pack's pin, and the one next action:

  install         absent — offer it; install on acceptance
  upgrade         installed older than the pack's pin
  record          installed at the pin, but the registry is missing or stale
  available       a machine-level tool is present, but this repository never
                  enabled it — offered only in a full setup, never recorded
                  on an upgrade
  current         installed at the pin and recorded — nothing to do
  newer           installed newer than the pin — keep it, never downgrade
  reconcile       hand-written work is present (a docker setup without dck):
                  reconcile through the addon's diff-and-consent flow
  verify          detected, version unreadable — re-check by hand
  declined        the registry records a decline — do not re-offer
  evaluate        the addon decides applicability from the repository
                  (design-system: an interface surface) — run its detection
  not-applicable  nothing to install for (no dependency manifest)

Nothing here installs, upgrades, renders or writes: the onboarding agent
runs each addon's own flow, then records the result with ``config.py
enable``. Running the planner twice on an unchanged repository prints the
same plan. ``pending`` lists only what the repository uses or requires and
is not yet at the pin; ``offers`` lists what fits but was never chosen here,
and ``evaluate`` what the addon itself must decide.

Usage::

    addon_sync.py plan --repo DIR [--json] [--keys k1,k2]
    addon_sync.py self-test

Standard library only (Python 3.9+).
"""

import argparse
import glob
import json
import os
import re
import sys
from typing import Any, Dict, List, Optional, Tuple

sys.dont_write_bytecode = True
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

import config as dwp_config  # noqa: E402  (sibling module)
import resources  # noqa: E402

_HERE = os.path.dirname(os.path.abspath(__file__))
PACK_ROOT = os.path.normpath(os.path.join(_HERE, '..'))
TAG_RE = re.compile(r'v?(\d+)\.(\d+)\.(\d+)')
NOTHING_PENDING = ('current', 'newer', 'available', 'declined', 'evaluate',
                   'not-applicable')

# Repository-level copies a skills CLI install leaves behind.
VENDORED = {'ai-diff-reviewer': 'ai-diff-reviewer', 'dailybot': 'dailybot'}

# Any of these marks a repository with declared dependencies.
MANIFESTS = ('package.json', 'pyproject.toml', 'requirements.txt', 'setup.py',
             'Pipfile', 'Cargo.toml', 'go.mod', 'Gemfile', 'composer.json',
             'pom.xml', 'build.gradle', 'build.gradle.kts', 'mix.exs',
             'pubspec.yaml', 'Package.swift')

# A dev-container setup somebody wrote by hand: the paths dck init would
# reconcile. A production Dockerfile or compose file elsewhere is not one —
# it is reported (``docker_files``) and the row stays an offer.
DEVCONTAINER_FILES = ('.devcontainer/devcontainer.json',
                      'docker/local/docker-compose.yaml')
APP_DOCKER_FILES = ('Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
                    'compose.yml', 'compose.yaml')


def parse_tag(text: Optional[str]) -> Optional[Tuple[int, int, int]]:
    match = TAG_RE.search(text or '')
    return tuple(int(g) for g in match.groups()) if match else None


def as_tag(text: Optional[str]) -> Optional[str]:
    parsed = parse_tag(text)
    return 'v%d.%d.%d' % parsed if parsed else None


def compare(installed: Optional[str], pin: Optional[str]) -> Optional[int]:
    """-1 older, 0 equal, 1 newer, None when either side is unknown."""
    a, b = parse_tag(installed), parse_tag(pin)
    if a is None or b is None:
        return None
    return (a > b) - (a < b)


def skill_version(path: str) -> Optional[str]:
    try:
        with open(path, encoding='utf-8', errors='replace') as handle:
            head = handle.read(4096)
    except OSError:
        return None
    match = re.search(r'(?m)^version:\s*["\']?([^"\'\s]+)', head)
    return as_tag(match.group(1)) if match else None


def surface_version(det: Dict[str, Any]) -> Optional[str]:
    """The ``version`` of a detected JSON surface file (vim's surface.json)."""
    for path in det.get('paths', []):
        if not path.endswith('.json'):
            continue
        try:
            with open(os.path.expanduser(path), encoding='utf-8') as fh:
                doc = json.load(fh)
        except (OSError, ValueError):
            continue
        if isinstance(doc, dict) and isinstance(doc.get('version'), str):
            return as_tag(doc['version'])
    return None


def lock_ref(repo: str, name: str) -> Optional[str]:
    try:
        with open(os.path.join(repo, 'skills-lock.json'), encoding='utf-8') as fh:
            doc = json.load(fh)
        return as_tag((doc.get('skills') or {}).get(name, {}).get('ref'))
    except (OSError, ValueError, AttributeError):
        return None


def registry(repo: str) -> Tuple[Dict[str, Any], Optional[str]]:
    """The repository registry (addons object) and a warning, never raising."""
    path = os.path.join(repo, '.dwp', 'config.json')
    if not os.path.exists(path):
        return {}, None
    parsed, reason = dwp_config.read_config(path)
    if parsed is None:
        return {}, '%s %s — rows ignore the registry' % (path, reason)
    reg = parsed.get('addons')
    return (reg if isinstance(reg, dict) else {}), None


def devcontainer_layout(repo: str) -> Tuple[str, Optional[str]]:
    """('dck', stamp tag) | ('handwritten', None) | ('none', None)."""
    if os.path.isfile(os.path.join(repo, '.devcontainer', 'dck.toml')):
        stamp = None
        for path in sorted(glob.glob(os.path.join(
                repo, 'docker', 'local', '*', 'dck', 'VERSION'))):
            if os.path.isfile(path) and not os.path.islink(path):
                with open(path, encoding='utf-8', errors='replace') as fh:
                    match = re.match(r'^devcontainer-kit (v\S+)', fh.read())
                stamp = as_tag(match.group(1)) if match else None
                break
        return 'dck', stamp
    if any(os.path.exists(os.path.join(repo, p)) for p in DEVCONTAINER_FILES):
        return 'handwritten', None
    return 'none', None


def version_action(version: Optional[str], pin: Optional[str]) -> str:
    order = compare(version, pin)
    if order is None:
        return 'verify'
    return {-1: 'upgrade', 0: 'current', 1: 'newer'}[order]


def with_registry(action: str, entry: Any, pin: Optional[str],
                  version: Optional[str]) -> str:
    """Promote ``current``/``newer`` to ``record`` when the registry lags."""
    if action not in ('current', 'newer'):
        return action
    expected = version if action == 'newer' else pin
    if not isinstance(entry, dict) or entry.get('enabled') is not True:
        return 'record'
    if expected and as_tag(entry.get('version')) != expected:
        return 'record'  # stale, or enabled without the version it runs
    return action


def plan_row(key: str, repo: str, reg: Dict[str, Any]) -> Dict[str, Any]:
    doc, errs = dwp_config.load_descriptor(key)
    product = (doc or {}).get('product') or {}
    pin = product.get('tag')
    det = (doc or {}).get('detect') or {}
    machine = 'command' in det or any(p.startswith('~/') for p in det.get('paths', []))
    entry = reg.get(key)
    row: Dict[str, Any] = {
        'key': key, 'scope': 'machine' if machine else 'repo', 'pin': pin,
        'installed': False, 'version': None, 'registry': entry,
        'action': None, 'reason': None,
        'skill': 'addons/%s/SKILL.md' % key,
    }
    if errs:
        row.update(action='verify', reason='invalid descriptor (%s)' % errs[0])
        return row
    if isinstance(entry, dict) and entry.get('enabled') is False:
        row.update(action='declined', reason='the registry records a decline')
        return row

    if key in VENDORED:
        skill = os.path.join(repo, '.agents', 'skills', VENDORED[key], 'SKILL.md')
        if os.path.isfile(skill):
            version = skill_version(skill) or lock_ref(repo, VENDORED[key])
            row.update(installed=True, version=version, scope='repo')
            row['action'] = version_action(version, pin)
        else:
            row['action'] = 'install'
            row['reason'] = ('required local review (Phase 7a)'
                             if key == 'ai-diff-reviewer' else
                             'offer only when the team uses Dailybot')
        if key == 'dailybot':
            present, _out, _why = resources._run_detect(det['command'])
            row['cli'] = 'present' if present else 'absent'
    elif key == 'devcontainer':
        layout, stamp = devcontainer_layout(repo)
        kit = resources.addon_status(key, repo)
        kit_version = kit.get('version') if kit.get('detected') else None
        row.update(scope='machine+repo', layout=layout, stamp=stamp,
                   kit=kit_version, installed=layout == 'dck',
                   version=stamp,
                   docker_files=[p for p in APP_DOCKER_FILES
                                 if os.path.exists(os.path.join(repo, p))])
        if layout == 'handwritten':
            row.update(action='reconcile',
                       reason='a docker setup without dck markers: dck init '
                              '--dry-run shows each replace as a diff; nothing '
                              'changes without consent, and a backup first')
        elif layout == 'none':
            row['action'] = 'install'
            if row['docker_files']:
                row['reason'] = ('an application docker setup is present (%s); '
                                 'dck renders its own files beside it'
                                 % ', '.join(row['docker_files']))
        else:
            worst = min((compare(v, pin) for v in (stamp, kit_version)
                         if compare(v, pin) is not None), default=None)
            row['action'] = ('verify' if worst is None else
                             {-1: 'upgrade', 0: 'current', 1: 'newer'}[worst])
            if kit_version is None:
                row.update(action='install', reason='layout present; the dck '
                           'kit is not installed on this machine')
    elif key == 'dependency-upgrade':
        present = os.path.isfile(os.path.join(repo, '.agents', 'commands',
                                              'lib-upgrade.md'))
        row['installed'] = present
        if present:
            row['action'] = 'current'  # a reasoned delegator: no version to compare
        elif any(os.path.exists(os.path.join(repo, m)) for m in MANIFESTS):
            row.update(action='install', reason='near-default: declared '
                       'dependencies; the delegator is inert')
        else:
            row.update(action='not-applicable', reason='no dependency manifest')
    elif key == 'design-system':
        present = any(os.path.isfile(os.path.join(repo, p))
                      for p in det.get('paths', []))
        row['installed'] = present
        row['action'] = 'current' if present else 'evaluate'
        if not present:
            row['reason'] = 'offer only when an interface surface is detected'
    else:  # machine-level products: agentkit, herdr, vim, and future ones
        status = resources.addon_status(key, repo)
        enabled = isinstance(entry, dict) and entry.get('enabled') is True
        if status.get('state') == 'installed-without-surface':
            row.update(installed=True, reason=status['reason'],
                       action='upgrade' if enabled else 'available')
        elif status.get('detected'):
            row.update(installed=True,
                       version=status.get('version') or surface_version(det))
            row['action'] = version_action(row['version'], pin)
            if not status.get('compatible') and row['action'] == 'current':
                row.update(action='verify', reason=status.get('reason'))
            if not enabled:
                # present on this machine (perhaps for another project), never
                # enabled here: the registry records only this repo's choices
                row.update(action='available',
                           reason='on this machine (%s, pin %s); not enabled '
                                  'for this repository' % (row['version'] or
                                                           'version unknown', pin))
        else:
            row.update(action='install', reason=status.get('reason'))
    base = row['action']
    row['action'] = with_registry(base, entry, pin, row['version'])
    # The record to run after an accepted step succeeds; never for a tool that
    # is merely present on the machine (`available`): the repository's
    # registry records only what it chose.
    if row['action'] in ('install', 'upgrade', 'record', 'reconcile'):
        tag = row['version'] if base == 'newer' else pin
        row['record'] = ('python3 <pack>/shared/config.py enable %s%s --repo %s'
                         % (key, ' --version %s' % tag if tag else '', repo))
    elif row['action'] == 'available':
        # run only when the developer accepts it in a full setup
        tag = as_tag(row['version']) if compare(row['version'], pin) == 1 else pin
        row['on_accept'] = ('python3 <pack>/shared/config.py enable %s%s --repo %s'
                            % (key, ' --version %s' % tag if tag else '', repo))
    return row


def build_plan(repo: str, keys: Optional[List[str]] = None) -> Dict[str, Any]:
    repo = os.path.abspath(repo)
    reg, warning = registry(repo)
    known = dwp_config.addon_keys()
    selected = [k for k in (keys or known) if k in known]
    rows = [plan_row(k, repo, reg) for k in selected]
    pack = skill_version(os.path.join(PACK_ROOT, 'SKILL.md'))
    vendored = skill_version(os.path.join(repo, '.agents', 'skills',
                                          'deepworkplan', 'SKILL.md'))
    # pending: what this repository uses or requires and is not yet at the
    # pin. offers: what fits but was never chosen here — made once; a
    # decline writes nothing, so an offer never blocks "nothing pending".
    def required(r):
        entry = r['registry']
        return r['key'] == 'ai-diff-reviewer' or (
            isinstance(entry, dict) and entry.get('enabled') is True)
    offer_like = ('install', 'reconcile')
    pending = [r['key'] for r in rows if r['action'] not in NOTHING_PENDING
               and (r['action'] not in offer_like or required(r))]
    offers = [r['key'] for r in rows if r['action'] == 'available'
              or (r['action'] in offer_like and not required(r))]
    to_evaluate = [r['key'] for r in rows if r['action'] == 'evaluate']
    return {'schema': 'dwp-addon-sync/v1', 'repo': repo, 'pack': pack,
            'vendored_pack': vendored,
            'pack_action': (None if vendored is None
                            else version_action(vendored, pack)),
            'rows': rows, 'pending': pending, 'offers': offers,
            'evaluate': to_evaluate,
            'warnings': [warning] if warning else []}


def render(plan: Dict[str, Any]) -> str:
    lines = ['addon               scope         installed   pin         action',
             '------------------  ------------  ----------  ----------  ----------']
    for r in plan['rows']:
        lines.append('%-18s  %-12s  %-10s  %-10s  %s' % (
            r['key'], r['scope'], r['version'] or ('yes' if r['installed'] else '-'),
            r['pin'] or '(in pack)', r['action']))
        if r.get('reason'):
            lines.append('%-18s  %s' % ('', r['reason']))
    if plan['vendored_pack']:
        lines.append('deepworkplan pack   repo          %-10s  %-10s  %s' % (
            plan['vendored_pack'], plan['pack'], plan['pack_action']))
    lines.append('pending: %s' % (', '.join(plan['pending']) or 'nothing'))
    if plan['offers']:
        lines.append('offers: %s (only where they fit; a decline writes nothing)'
                     % ', '.join(plan['offers']))
    if plan['evaluate']:
        lines.append('evaluate: %s (run its detection before reporting done)'
                     % ', '.join(plan['evaluate']))
    for w in plan['warnings']:
        lines.append('warning: %s' % w)
    return '\n'.join(lines)


def self_test() -> int:
    ok = True
    for text, want in (('v1.2.3', (1, 2, 3)), ('herdr-peers 0.1.0 (protocol 1)',
                        (0, 1, 0)), ('x', None)):
        ok &= parse_tag(text) == want
    ok &= compare('v0.4.0', 'v0.5.0') == -1 and compare('v1.0.0', 'v1.0.0') == 0
    ok &= with_registry('current', None, 'v1.0.0', 'v1.0.0') == 'record'
    ok &= with_registry('current', {'enabled': True, 'version': 'v1.0.0'},
                        'v1.0.0', 'v1.0.0') == 'current'
    print('OK: addon_sync self-test' if ok else 'FAIL: addon_sync self-test')
    return 0 if ok else 1


def main(argv: Optional[List[str]] = None) -> int:
    parser = argparse.ArgumentParser(prog='addon_sync.py')
    sub = parser.add_subparsers(dest='command')
    p = sub.add_parser('plan')
    p.add_argument('--repo', required=True)
    p.add_argument('--json', action='store_true')
    p.add_argument('--keys')
    sub.add_parser('self-test')
    args = parser.parse_args(argv)
    if args.command == 'self-test':
        return self_test()
    if args.command != 'plan':
        parser.print_help()
        return 2
    if not os.path.isdir(args.repo):
        print('addon_sync: %s is not a directory' % args.repo, file=sys.stderr)
        return 2
    keys = args.keys.split(',') if args.keys else None
    plan = build_plan(args.repo, keys)
    print(json.dumps(plan, indent=2, sort_keys=True) if args.json else render(plan))
    return 0


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