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/update-state.py

View on GitHub
#!/usr/bin/env python3
"""Apply a targeted mutation to a Deep Work Plan state.json (state layer).

The state layer stays JSON (ADR 0002); this helper exists so an executing
agent applies a task-close or status change as a bounded delta — set one
task's status, attach its gate records and outcome, recompute counts and the
checkpoint — instead of re-emitting the whole file from context. It writes
atomically (temp file + rename) and only ever assigns fields the closed v2/v5
schema shape knows (the v5 schema is a generation snapshot of v2), and never
touches the declared `schema` URL, so its output validates where the input
did.

Stdlib only (Python 3.9+). It mutates exactly one file: the state.json given
as the first argument. Whole-file regeneration (create, refine recount,
markdown-wins reconciliation) stays a manual, documented operation.

Usage:
  update-state.py STATE.json --task N --status completed \
      [--gate "command|exit_code|evidence"] [--gate ...] \
      [--worked "one line"] [--notes "pointer"] [--commit <sha>] \
      [--checkpoint-step "step"] [--checkpoint-note "note"] \
      [--agent <name>] [--model <name>]

Exit codes: 0 applied · 1 validation error (nothing written) · 2 usage.
"""
import argparse
import datetime
import json
import os
import re
import sys
import tempfile
from pathlib import Path
import hashlib

sys.dont_write_bytecode = True
from state_contract import derive_status, invalidated, state_errors

TASK_STATUSES = ("pending", "in_progress", "completed", "blocked", "skipped")
PLAN_STATUSES = ("pending", "in_progress", "completed", "blocked")
COMMIT_RE = re.compile(r"^[0-9a-f]{7,40}$")
# Closed-schema field budgets (plan-state-v2/v5 schema shape) enforced on write.
LIMITS = {
    "gate.command": 500, "gate.evidence": 500,
    "outcome.worked": 500, "outcome.notes": 1000,
    "checkpoint.step": 200, "checkpoint.note": 500,
    "updated_by.agent": 100, "updated_by.model": 100,
}


def die(msg, code=1):
    print(f"update-state: {msg}", file=sys.stderr)
    sys.exit(code)


def now():
    return datetime.datetime.now(datetime.timezone.utc).isoformat()


def parse_gates(raw):
    """Each --gate is 'command|exit_code|evidence'."""
    gates = []
    for spec in raw:
        parts = spec.split("|", 2)
        if len(parts) != 3:
            die(f"--gate expects 'command|exit_code|evidence', got: {spec!r}")
        command, exit_code, evidence = (p.strip() for p in parts)
        try:
            code = int(exit_code)
        except ValueError:
            die(f"--gate exit_code is not an integer: {exit_code!r}")
        if len(command) > LIMITS["gate.command"]:
            die(f"gate command exceeds {LIMITS['gate.command']} chars")
        if len(evidence) > LIMITS["gate.evidence"]:
            die(f"gate evidence exceeds {LIMITS['gate.evidence']} chars")
        gates.append({"command": command, "passes": code == 0,
                      "last_run": now(), "exit_code": code,
                      "evidence": evidence})
    return gates


def derive_plan_status(state):
    return derive_status(state)


def next_checkpoint(state, task_id, step, note):
    pending = [t["id"] for t in state["tasks"]
               if t["status"] != "completed"]
    if pending:
        target = min(pending)
        step = step or "start"
        note = note or f"Task {task_id} closed. Next: Task {target}."
    else:
        target = task_id
        step = step or "done"
        note = note or "Plan completed."
    if len(step) > LIMITS["checkpoint.step"]:
        die(f"checkpoint step exceeds {LIMITS['checkpoint.step']} chars")
    if len(note) > LIMITS["checkpoint.note"]:
        die(f"checkpoint note exceeds {LIMITS['checkpoint.note']} chars")
    return {"task": target, "step": step, "at": now(), "note": note}


def main():
    ap = argparse.ArgumentParser(add_help=True, description=__doc__.splitlines()[0])
    ap.add_argument("state", help="path to the plan's state.json")
    ap.add_argument("--task", type=int, required=True, metavar="N")
    ap.add_argument("--status", required=True, choices=TASK_STATUSES)
    ap.add_argument("--gate", action="append", default=[], metavar="CMD|EXIT|EVIDENCE")
    ap.add_argument("--gate-json", action="append", default=[], help="JSON gate object; preserves pipes in commands")
    ap.add_argument("--block-reason", default="")
    ap.add_argument("--block-needs", default="")
    ap.add_argument("--resolve-blocker", action="store_true")
    ap.add_argument("--reopen-reason", default="")
    ap.add_argument("--expected-sha256", default="", help="reject stale source state")
    ap.add_argument("--worked", default="")
    ap.add_argument("--notes", default="")
    ap.add_argument("--commit", default="")
    ap.add_argument("--checkpoint-step", default="")
    ap.add_argument("--checkpoint-note", default="")
    ap.add_argument("--agent", default="")
    ap.add_argument("--model", default="")
    args = ap.parse_args()

    for field, value in (("outcome.worked", args.worked), ("outcome.notes", args.notes)):
        if len(value) > LIMITS[field]:
            die(f"--{field.split('.')[1]} exceeds {LIMITS[field]} chars")
    if args.commit and not COMMIT_RE.match(args.commit):
        die(f"--commit is not a commit hash: {args.commit!r}")
    if args.state not in ("", ) and not os.path.isfile(args.state):
        die(f"state file not found: {args.state}")

    try:
        with open(args.state, encoding="utf-8") as fh:
            state = json.load(fh)
    except (OSError, json.JSONDecodeError) as exc:
        die(f"cannot read state: {exc}")

    original = Path(args.state).read_bytes()
    if args.expected_sha256 and hashlib.sha256(original).hexdigest() != args.expected_sha256:
        die("stale state snapshot")
    errors = state_errors(state, plan_dir=Path(args.state).parent)
    if errors:
        die("invalid input: " + "; ".join(errors))
    if state.get("materialization", "ready") != "ready" or state.get("promotion"):
        die("plan is not ready")
    if state.get("approval", "approved") not in ("approved", "pre_approved"):
        die("plan is not approved")
    tasks = state.get("tasks") or []
    task = next((t for t in tasks if t.get("id") == args.task), None)
    if task is None:
        die(f"no task {args.task} in this plan "
            f"(have: {[t.get('id') for t in tasks]})")

    if task['status'] == 'completed' and args.status != 'completed' and not args.reopen_reason:
        die("completed task requires an explicit refine/reopen reason")
    if args.status in ('in_progress', 'completed') and any(t['status'] != 'completed' for t in tasks if t['id'] < args.task):
        die("prior required task is not completed")
    if args.resolve_blocker:
        if not state.get('blocked') or state['blocked']['task'] != args.task:
            die("cannot resolve an unrelated or absent blocker")
        if args.status not in ('in_progress', 'completed'):
            die("blocker resolution must resume or complete its task")
        state['blocked'] = None
    if state.get('blocked') and args.status != 'blocked':
        die("resolve the active blocker explicitly first")
    if args.status == 'blocked':
        if not args.block_reason.strip():
            die("blocking requires a reason")
        if state.get('blocked') and state['blocked']['task'] != args.task:
            die("cannot replace an unrelated blocker")
        state['blocked'] = {'task': args.task, 'reason': args.block_reason,
                            'since': (state.get('blocked') or {}).get('since', now()), 'needs': args.block_needs}
    stamp = now()
    if task["status"] != args.status:
        # Idempotence: timestamps record when a transition happened, so a
        # replayed invocation keeps the original reading.
        if args.status in ("in_progress", "completed", "blocked") and not task.get("started_at"):
            task["started_at"] = stamp
        if args.status == "completed" and not task.get("completed_at"):
            task["completed_at"] = stamp
    task["status"] = args.status
    if args.commit:
        task["commit"] = args.commit
    if args.worked or args.notes:
        outcome = dict(task.get("outcome") or {})
        if args.worked:
            outcome["worked"] = args.worked
        if args.notes:
            outcome["notes"] = args.notes
        task["outcome"] = outcome
    incoming = parse_gates(args.gate)
    for raw in args.gate_json:
        try:
            gate = json.loads(raw)
        except ValueError:
            die("invalid --gate-json")
        if not isinstance(gate, dict):
            die("--gate-json must be an object")
        incoming.append(gate)
    if incoming:
        # Retain unrelated results; latest record for a command wins. Logs keep history.
        records = list(task.get('gates', []))
        for gate in incoming:
            previous = next((g for g in reversed(records) if g.get('command') == gate.get('command')), None)
            if previous and {k:v for k,v in previous.items() if k != 'last_run'} == {k:v for k,v in gate.items() if k != 'last_run'}:
                continue
            records.append(gate)
        task['gates'] = records
    if args.status == 'completed':
        latest = {g.get('command'): g for g in task.get('gates', []) if isinstance(g, dict)}
        if not latest or any(not str(g.get('command', '')).strip() or not str(g.get('evidence', '')).strip()
                             or g.get('passes') is not True or g.get('exit_code') != 0 for g in latest.values()):
            die("completion requires successful gates with command, exit code and evidence")
        stale = [c for c, g in latest.items() if invalidated(g)]
        if stale:
            die("completion requires rerunning evidence invalidated by refine: " + ", ".join(map(str, stale)))

    state["completed_count"] = sum(1 for t in tasks if t["status"] == "completed")
    # Plan-level `blocked` carries its own record (reason/since) authored by
    # the blocked protocol; this helper never guesses it.
    state["status"] = derive_plan_status(state)
    state["updated_at"] = stamp
    state["checkpoint"] = next_checkpoint(state, args.task,
                                          args.checkpoint_step, args.checkpoint_note)
    if args.agent or args.model:
        updated_by = dict(state.get("updated_by") or {})
        if args.agent:
            if len(args.agent) > LIMITS["updated_by.agent"]:
                die(f"--agent exceeds {LIMITS['updated_by.agent']} chars")
            updated_by["agent"] = args.agent
        if args.model:
            if len(args.model) > LIMITS["updated_by.model"]:
                die(f"--model exceeds {LIMITS['updated_by.model']} chars")
            updated_by["model"] = args.model
        state["updated_by"] = updated_by

    if state["status"] not in PLAN_STATUSES:
        die(f"internal: derived invalid plan status {state['status']!r}")

    # Sanity guards for the fields this tool owns, before anything is written.
    for t in tasks:
        if t["status"] not in TASK_STATUSES:
            die(f"task {t.get('id')} has invalid status {t['status']!r}")
    if not 0 <= state["completed_count"] <= state.get("task_count", len(tasks)):
        die("completed_count out of range")

    errors = state_errors(state, strict=True, plan_dir=Path(args.state).parent)
    if errors:
        die("invalid candidate: " + "; ".join(errors))
    if state['status'] == 'completed':
        from finalize_plan import publish
        try:
            publish(Path(args.state).parent, state, hashlib.sha256(original).hexdigest())
        except (OSError, ValueError, KeyError, TypeError) as exc:
            die(str(exc))
        print(f"task {args.task} → completed · plan completed and verified")
        return
    directory = os.path.dirname(os.path.abspath(args.state))
    payload = json.dumps(state, indent=2, ensure_ascii=False) + "\n"
    lock = args.state + '.lock'
    try:
        os.mkdir(lock)
    except FileExistsError:
        die("state is locked; inspect interrupted writer before recovering lock")
    if Path(args.state).read_bytes() != original:
        os.rmdir(lock)
        die("state changed during update")
    fd, tmp_path = tempfile.mkstemp(dir=directory, prefix=".state.json.", suffix=".tmp")
    try:
        with os.fdopen(fd, "w", encoding="utf-8") as fh:
            fh.write(payload)
        os.replace(tmp_path, args.state)
    except BaseException:
        if os.path.exists(tmp_path):
            os.unlink(tmp_path)
        raise
    finally:
        os.rmdir(lock)

    print(f"task {args.task} → {args.status} · "
          f"{state['completed_count']}/{state['task_count']} completed · "
          f"plan {state['status']}")


if __name__ == "__main__":
    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