Skip to content

flurdy/agent-skills / skills/plan-day

plan-day

Verified

Render today's plan from a My PA workspace — ranked Jira, Trello, Beads and Thoughtbox items assigned to work, project-session, evening or skip blocks, flagged when delegable to an unattended agent session, written to a dated ephemeral plan file.

FileKindSize
SKILL.mdskill md7.0 KB
scripts/plan_day.pyexecutablescript27.7 KB
tests/test_plan_day.pyscript17.3 KB

scripts/plan_day.py

View on GitHub
#!/usr/bin/env python3
"""Helper for the plan-day skill: config loading, collector contract, merge, plan files.

Subcommands print JSON to stdout and fail closed with a non-zero exit and a message on
stderr. The judgement step in SKILL.md consumes the output; nothing here ranks or plans.
"""

from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
import tomllib
from dataclasses import dataclass
from datetime import date, datetime, timedelta
from pathlib import Path
from typing import Any

CONTRACT_FIELDS = {
    "source": str,
    "id": str,
    "title": str,
    "priority": int,
    "due": (str, type(None)),
    "status": str,
    "url": str,
    "repository": str,
    "delegable": bool,
}
SOURCES = ("jira", "trello", "beads", "thoughtbox", "calendar", "dependabot", "grafana")
BLOCK_HOURS = ("work", "project-session", "evening")
WEEKDAYS = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
PLAN_FILE = re.compile(r"^(\d{4}-\d{2}-\d{2})\.md$")
ARTIFACT_DIR = Path(".artifacts") / "plan-day"
NEXT_SCRIPTS = Path.home() / ".agents" / "skills" / "next" / "scripts"
THOUGHTBOX_SCHEMA = 1
BLOCK_TITLES = (
    ("work", "Work"),
    ("project-session", "Project sessions"),
    ("evening", "Evening"),
)
PLAN_ID = re.compile(r"`([^`\n]+)`")


class PlanDayError(Exception):
    """A fail-closed error reported on stderr."""


@dataclass(frozen=True)
class Workspace:
    root: Path
    config: dict[str, Any]

    @property
    def plans_dir(self) -> Path:
        return self.root / self.config["plans"]["directory"]

    @property
    def artifacts_dir(self) -> Path:
        return self.root / ARTIFACT_DIR


def find_root(start: Path | None) -> Path:
    candidate = (start or Path.cwd()).resolve()
    for directory in (candidate, *candidate.parents):
        if (directory / "workspace.json").is_file() and (directory / "pa.toml").is_file():
            return directory
    raise PlanDayError(f"no workspace with workspace.json and pa.toml at or above {candidate}")


def _require(mapping: dict[str, Any], key: str, kind: type, where: str) -> Any:
    value = mapping.get(key)
    if not isinstance(value, kind) or isinstance(value, bool) and kind is int:
        raise PlanDayError(f"pa.toml: {where}.{key} must be {kind.__name__}")
    return value


def _validate_hours(value: str, where: str) -> None:
    if not re.fullmatch(r"\d{2}:\d{2}-\d{2}:\d{2}", value):
        raise PlanDayError(f"pa.toml: {where} must look like HH:MM-HH:MM")


def _validate_members(root: Path, entries: Any, where: str) -> list[dict[str, Any]]:
    if not isinstance(entries, list):
        raise PlanDayError(f"pa.toml: {where} must be an array of tables")
    for entry in entries:
        name = _require(entry, "name", str, where)
        workspace = _require(entry, "workspace", str, f"{where}.{name}")
        if not (root / workspace).is_dir():
            raise PlanDayError(f"pa.toml: {where}.{name}.workspace {workspace} is not a directory")
        hours = _require(entry, "hours", str, f"{where}.{name}")
        if hours not in BLOCK_HOURS:
            raise PlanDayError(f"pa.toml: {where}.{name}.hours must be one of {BLOCK_HOURS}")
    return entries


def load_config(root: Path) -> dict[str, Any]:
    try:
        config = tomllib.loads((root / "pa.toml").read_text(encoding="utf-8"))
    except (OSError, tomllib.TOMLDecodeError) as error:
        raise PlanDayError(f"pa.toml: {error}") from error

    schedule = _require(config, "schedule", dict, "root")
    _require(schedule, "timezone", str, "schedule")
    _validate_hours(_require(schedule, "work_hours", str, "schedule"), "schedule.work_hours")
    for day in _require(schedule, "work_days", list, "schedule"):
        if day not in WEEKDAYS:
            raise PlanDayError(f"pa.toml: schedule.work_days has unknown day {day!r}")
    blocks = _require(schedule, "blocks", list, "schedule")
    for hours in BLOCK_HOURS:
        if hours not in blocks:
            raise PlanDayError(f"pa.toml: schedule.blocks must include {hours!r}")

    plans = _require(config, "plans", dict, "root")
    _require(plans, "directory", str, "plans")
    if _require(plans, "retention_days", int, "plans") < 1:
        raise PlanDayError("pa.toml: plans.retention_days must be at least 1")

    priority = _require(config, "priority", dict, "root")
    for table in ("jira", "trello_labels"):
        for label, level in _require(priority, table, dict, "priority").items():
            if not isinstance(level, int) or not 0 <= level <= 4:
                raise PlanDayError(f"pa.toml: priority.{table}.{label} must be 0-4")

    launcher = config.setdefault("launcher", {})
    launcher.setdefault("command", "cl")
    if launcher["command"] not in ("cl", "pl"):
        raise PlanDayError("pa.toml: launcher.command must be cl or pl")

    sources = _require(config, "sources", dict, "root")
    for name, enabled in sources.items():
        if name not in SOURCES or not isinstance(enabled, bool):
            raise PlanDayError(f"pa.toml: sources.{name} must be a known source set true or false")

    config["clients"] = _validate_members(root, config.get("clients", []), "clients")
    config["projects"] = _validate_members(root, config.get("projects", []), "projects")
    return config


def load_workspace(start: Path | None) -> Workspace:
    root = find_root(start)
    return Workspace(root, load_config(root))


def validate_item(item: Any, where: str) -> list[str]:
    if not isinstance(item, dict):
        return [f"{where}: item must be an object"]
    errors = [f"{where}: missing field {field!r}" for field in CONTRACT_FIELDS if field not in item]
    errors.extend(f"{where}: unknown field {field!r}" for field in item if field not in CONTRACT_FIELDS)
    for field, kind in CONTRACT_FIELDS.items():
        if field not in item:
            continue
        value = item[field]
        if isinstance(value, bool) and kind is int or not isinstance(value, kind):
            errors.append(f"{where}: field {field!r} has wrong type")
    if not errors:
        if item["source"] not in SOURCES:
            errors.append(f"{where}: unknown source {item['source']!r}")
        if not 0 <= item["priority"] <= 4:
            errors.append(f"{where}: priority must be 0-4")
        if item["due"] is not None:
            try:
                date.fromisoformat(item["due"])
            except ValueError:
                errors.append(f"{where}: due must be YYYY-MM-DD or null")
        for field in ("id", "title"):
            if not item[field].strip():
                errors.append(f"{where}: field {field!r} must not be blank")
    return errors


def load_items(path: Path) -> list[dict[str, Any]]:
    try:
        payload = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as error:
        raise PlanDayError(f"{path}: {error}") from error
    if not isinstance(payload, list):
        raise PlanDayError(f"{path}: collector output must be a JSON array")
    errors = [
        error
        for index, item in enumerate(payload)
        for error in validate_item(item, f"{path}[{index}]")
    ]
    if errors:
        raise PlanDayError("\n".join(errors))
    return payload


def hours_for(workspace: Workspace, repository: str) -> str | None:
    for kind in ("clients", "projects"):
        for member in workspace.config[kind]:
            if repository == Path(member["workspace"]).name or repository.startswith(
                member["workspace"] + "/"
            ):
                return member["hours"]
    return None


def merge(workspace: Workspace) -> dict[str, Any]:
    enabled = [name for name, on in workspace.config["sources"].items() if on]
    items: list[dict[str, Any]] = []
    present: set[str] = set()
    for source in SOURCES:
        path = workspace.artifacts_dir / f"{source}.json"
        if not path.is_file():
            continue
        for item in load_items(path):
            present.add(item["source"])
            item = dict(item)
            item["hours"] = hours_for(workspace, item["repository"])
            items.append(item)
    items.sort(key=lambda item: (item["priority"], item["due"] or "9999-99-99", item["source"]))
    return {
        "items": items,
        "missing_sources": sorted(set(enabled) - present),
        "disabled_sources": sorted(set(SOURCES) - set(enabled)),
    }


def plan_files(workspace: Workspace, today: date) -> dict[str, Any]:
    retention = timedelta(days=workspace.config["plans"]["retention_days"])
    plans: list[tuple[date, Path]] = []
    if workspace.plans_dir.is_dir():
        for path in workspace.plans_dir.iterdir():
            match = PLAN_FILE.match(path.name)
            if match and path.is_file():
                plans.append((date.fromisoformat(match.group(1)), path))
    plans.sort()
    previous = [path for day, path in plans if day < today]
    stale = [path for day, path in plans if today - day > retention]
    return {
        "today": str(workspace.plans_dir / f"{today.isoformat()}.md"),
        "previous": str(previous[-1]) if previous else None,
        "stale": [str(path) for path in stale],
    }


def prune(stale: list[str]) -> None:
    for path in stale:
        Path(path).unlink()


def run_process(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
    try:
        return subprocess.run(command, cwd=cwd, capture_output=True, text=True, check=False)
    except FileNotFoundError as error:
        raise PlanDayError(f"{command[0]} is not installed or not on PATH") from error


def run_json(command: list[str], cwd: Path) -> Any:
    result = run_process(command, cwd)
    if result.returncode != 0:
        detail = result.stderr.strip() or result.stdout.strip() or f"exit {result.returncode}"
        raise PlanDayError(f"{' '.join(command)}: {detail}")
    try:
        return json.loads(result.stdout)
    except json.JSONDecodeError as error:
        raise PlanDayError(f"{' '.join(command)}: invalid JSON output") from error


def write_collector(workspace: Workspace, source: str, items: list[dict[str, Any]]) -> Path:
    errors = [
        error for index, item in enumerate(items) for error in validate_item(item, f"{source}[{index}]")
    ]
    if errors:
        raise PlanDayError("\n".join(errors))
    workspace.artifacts_dir.mkdir(parents=True, exist_ok=True)
    path = workspace.artifacts_dir / f"{source}.json"
    path.write_text(json.dumps(items, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    return path


def bead_item(bead: dict[str, Any], repository: str) -> dict[str, Any]:
    labels = bead.get("labels") or []
    specified = bool(str(bead.get("description") or "").strip()) and bool(
        str(bead.get("acceptance_criteria") or "").strip()
    )
    return {
        "source": "beads",
        "id": str(bead.get("id", "")),
        "title": str(bead.get("title", "")),
        "priority": min(max(int(bead.get("priority", 2)), 0), 4),
        "due": None,
        "status": str(bead.get("status", "")),
        "url": "",
        "repository": repository,
        "delegable": specified and bead.get("status") == "open" and "human" not in labels,
    }


def collect_beads(workspace: Workspace) -> dict[str, Any]:
    root = workspace.root
    ready = run_json([str(NEXT_SCRIPTS / "next-bd"), "--json"], root)
    stores = run_json([str(NEXT_SCRIPTS / "next-select"), "stores"], root)
    if not isinstance(ready, list) or not isinstance(stores, dict):
        raise PlanDayError("next helpers returned unexpected JSON")
    items = [bead_item(bead, str(bead.get("repository", ""))) for bead in ready]
    diagnostics: list[str] = []
    for store in stores.get("stores", []):
        if not store.get("usable"):
            diagnostics.append(f"{store.get('repository')}: {store.get('error')}")
            continue
        directory = Path(store["directory"])
        active = run_json(
            ["bd", "-C", str(directory), "list", "--status", "in_progress", "--json", "--readonly"],
            directory,
        )
        items.extend(bead_item(bead, store["repository"]) for bead in active or [])
    return {"items": items, "diagnostics": diagnostics}


def jira_issues(payload: Any) -> list[dict[str, Any]]:
    if isinstance(payload, dict) and isinstance(payload.get("issues"), list):
        issues = []
        for issue in payload["issues"]:
            fields = issue.get("fields") or {}
            issues.append(
                {
                    "key": issue.get("key"),
                    "summary": fields.get("summary"),
                    "status": (fields.get("status") or {}).get("name"),
                    "priority": (fields.get("priority") or {}).get("name"),
                    "duedate": fields.get("duedate"),
                }
            )
        return issues
    if isinstance(payload, list):
        return payload
    raise PlanDayError("jira input must be a search response or a projected issue array")


def collect_jira(workspace: Workspace, client_name: str, source: Path) -> dict[str, Any]:
    client = next((c for c in workspace.config["clients"] if c["name"] == client_name), None)
    if client is None:
        raise PlanDayError(f"pa.toml: no [[clients]] entry named {client_name!r}")
    jira = client.get("jira") or {}
    base_url = str(jira.get("base_url", "")).rstrip("/")
    levels = workspace.config["priority"]["jira"]
    try:
        payload = json.loads(source.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as error:
        raise PlanDayError(f"{source}: {error}") from error
    items = []
    for issue in jira_issues(payload):
        name = issue.get("priority")
        if name not in levels:
            raise PlanDayError(f"pa.toml: priority.jira has no mapping for {name!r}")
        key = str(issue.get("key") or "")
        items.append(
            {
                "source": "jira",
                "id": key,
                "title": str(issue.get("summary") or ""),
                "priority": levels[name],
                "due": issue.get("duedate") or None,
                "status": str(issue.get("status") or ""),
                "url": f"{base_url}/browse/{key}" if base_url else "",
                "repository": Path(client["workspace"]).name,
                "delegable": False,
            }
        )
    return {"items": items, "diagnostics": []}


def thoughtbox_data(command: list[str], cwd: Path) -> Any:
    result = run_process(command, cwd)
    try:
        envelope = json.loads(result.stdout)
    except json.JSONDecodeError as error:
        detail = result.stderr.strip() or "invalid JSON output"
        raise PlanDayError(f"thoughtbox: {detail}") from error
    if not isinstance(envelope, dict) or envelope.get("schemaVersion") != THOUGHTBOX_SCHEMA:
        raise PlanDayError("thoughtbox returned an unsupported JSON envelope")
    if envelope.get("ok") is not True:
        failure = envelope.get("error") or {}
        raise PlanDayError(f"thoughtbox: {failure.get('code', 'UNKNOWN')}: {failure.get('message', '')}")
    return envelope.get("data")


def collect_thoughtbox(workspace: Workspace) -> dict[str, Any]:
    default = workspace.config["priority"]["thoughtbox_default"]
    items: list[dict[str, Any]] = []
    diagnostics: list[str] = []
    resolved = 0
    for member in (*workspace.config["clients"], *workspace.config["projects"]):
        repo = workspace.root / member["workspace"]
        repository = Path(member["workspace"]).name
        try:
            context = thoughtbox_data(
                ["thoughtbox", "context", "resolve", "--repo", str(repo), "--json"], workspace.root
            )
            thoughts = thoughtbox_data(
                [
                    "thoughtbox", "list", "--repo", context["workingDirectory"],
                    "--profile", context["profile"], "--json",
                ],
                workspace.root,
            )
        except PlanDayError as error:
            if "not installed" in str(error):
                raise
            diagnostics.append(f"{repository}: {error}")
            continue
        resolved += 1
        for thought in thoughts or []:
            if not isinstance(thought, dict):
                continue
            if thought.get("kind") == "diagnostic":
                diagnostics.append(f"{repository}: malformed thought {thought.get('id')}")
                continue
            if thought.get("status") != "inbox":
                continue
            text = " ".join(str(thought.get("text") or "").split()) or "Untitled thought"
            items.append(
                {
                    "source": "thoughtbox",
                    "id": str(thought.get("id") or ""),
                    "title": text if len(text) <= 120 else f"{text[:117]}...",
                    "priority": default,
                    "due": None,
                    "status": "inbox",
                    "url": "",
                    "repository": repository,
                    "delegable": False,
                }
            )
    if resolved == 0:
        raise PlanDayError("thoughtbox: no configured workspace resolved to a context; " + "; ".join(diagnostics))
    return {"items": items, "diagnostics": diagnostics}


def collect(workspace: Workspace, args: argparse.Namespace) -> dict[str, Any]:
    if args.source == "beads":
        result = collect_beads(workspace)
    elif args.source == "jira":
        result = collect_jira(workspace, args.client, args.input)
    else:
        result = collect_thoughtbox(workspace)
    path = write_collector(workspace, args.source, result["items"])
    return {
        "source": args.source,
        "count": len(result["items"]),
        "path": str(path),
        "diagnostics": result["diagnostics"],
    }


def repository_path(workspace: Workspace, repository: str) -> Path | None:
    if not repository:
        return None
    if repository == "workspace":
        return workspace.root
    try:
        manifest = json.loads((workspace.root / "workspace.json").read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError):
        return None
    for entry in manifest.get("repositories", []):
        if entry.get("name") == repository:
            return (workspace.root / entry["path"]).resolve()
    return None


def launch_line(workspace: Workspace, repository: str) -> str:
    path = repository_path(workspace, repository)
    if path is None:
        return ""
    home = Path.home()
    shown = f"~/{path.relative_to(home)}" if path.is_relative_to(home) else str(path)
    return f"{workspace.config['launcher']['command']} {shown}"


def schedule_context(workspace: Workspace, now: datetime) -> dict[str, Any]:
    schedule = workspace.config["schedule"]
    weekday = WEEKDAYS[now.weekday()]
    start, end = schedule["work_hours"].split("-")
    clock = now.strftime("%H:%M")
    return {
        "date": now.date().isoformat(),
        "weekday": now.strftime("%A"),
        "work_day": weekday in schedule["work_days"],
        "in_work_hours": weekday in schedule["work_days"] and start <= clock < end,
        "work_hours": schedule["work_hours"],
    }


def previous_ids(path: str | None) -> set[str]:
    if path is None:
        return set()
    try:
        text = Path(path).read_text(encoding="utf-8")
    except OSError:
        return set()
    return set(PLAN_ID.findall(text))


def propose_block(item: dict[str, Any], context: dict[str, Any]) -> tuple[str, str]:
    hours = item.get("hours")
    if hours == "work":
        if context["work_day"]:
            return "work", ""
        return "skip", "outside work days"
    if hours == "project-session":
        if item["delegable"]:
            return "project-session", ""
        return "evening", "needs a person, not delegable"
    if item["source"] == "jira":
        return "skip", "client work without a configured [[clients]] entry"
    return "evening", ""


def draft(workspace: Workspace, now: datetime) -> dict[str, Any]:
    context = schedule_context(workspace, now)
    files = plan_files(workspace, now.date())
    carried = previous_ids(files["previous"])
    merged = merge(workspace)
    items = []
    for item in merged["items"]:
        block, reason = propose_block(item, context)
        items.append(
            {
                **item,
                "block": block,
                "reason": reason,
                "carried": item["id"] in carried,
                "launch": launch_line(workspace, item["repository"]),
            }
        )
    items.sort(key=lambda item: (item["status"] != "in_progress", not item["carried"]))
    return {
        "context": context,
        "plan": files,
        "items": items,
        "missing_sources": merged["missing_sources"],
        "disabled_sources": merged["disabled_sources"],
    }


def load_decisions(path: Path, blocks: list[str]) -> dict[str, Any]:
    try:
        decisions = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as error:
        raise PlanDayError(f"{path}: {error}") from error
    if not isinstance(decisions, dict) or not isinstance(decisions.get("items"), list):
        raise PlanDayError(f"{path}: decisions must be a draft object with an items array")
    for index, item in enumerate(decisions["items"]):
        errors = validate_item(
            {key: item.get(key) for key in CONTRACT_FIELDS}, f"{path}[{index}]"
        )
        if errors:
            raise PlanDayError("\n".join(errors))
        if item.get("block") not in blocks:
            raise PlanDayError(f"{path}[{index}]: block must be one of {blocks}")
        if item["block"] == "skip" and not str(item.get("reason") or "").strip():
            raise PlanDayError(f"{path}[{index}]: a skipped item needs a reason")
    return decisions


def cell(value: Any) -> str:
    return str(value if value not in (None, "") else "—").replace("|", "\\|").replace("\n", " ")


def render_plan(decisions: dict[str, Any]) -> str:
    context = decisions["context"]
    lines = [f"# Plan — {context['weekday']} {context['date']}", ""]
    if not context["work_day"]:
        lines += ["_Not a work day; client work is skipped unless you decide otherwise._", ""]
    items = decisions["items"]
    for block, title in BLOCK_TITLES:
        rows = [item for item in items if item["block"] == block]
        lines += [f"## {title}", ""]
        if not rows:
            lines += ["_Nothing planned._", ""]
            continue
        lines += [
            "| # | Item | Source | Pri | Due | Status | Carried | Delegable | Launch |",
            "|---|---|---|---|---|---|---|---|---|",
        ]
        for index, item in enumerate(rows, 1):
            lines.append(
                "| "
                + " | ".join(
                    (
                        str(index),
                        f"`{item['id']}` {cell(item['title'])}",
                        item["source"],
                        f"P{item['priority']}",
                        cell(item["due"]),
                        cell(item["status"]),
                        "yes" if item.get("carried") else "—",
                        "yes" if item["delegable"] else "—",
                        f"`{item['launch']}`" if item.get("launch") else "—",
                    )
                )
                + " |"
            )
        lines.append("")
    skipped = [item for item in items if item["block"] == "skip"]
    lines += ["## Skipped", ""]
    lines += [f"- `{item['id']}` {cell(item['title'])} — {item['reason']}" for item in skipped] or [
        "_Nothing skipped._"
    ]
    lines += [
        "",
        "## Sources",
        "",
        f"missing: {', '.join(decisions.get('missing_sources') or []) or 'none'}  ",
        f"disabled: {', '.join(decisions.get('disabled_sources') or []) or 'none'}",
        "",
    ]
    return "\n".join(lines)


def render(workspace: Workspace, decisions_path: Path, dry_run: bool) -> dict[str, Any]:
    decisions = load_decisions(decisions_path, workspace.config["schedule"]["blocks"])
    text = render_plan(decisions)
    target = Path(decisions["plan"]["today"])
    pruned: list[str] = []
    if not dry_run:
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(text, encoding="utf-8")
        pruned = list(decisions["plan"].get("stale") or [])
        prune(pruned)
    return {"path": str(target), "written": not dry_run, "pruned": pruned, "plan": text}


def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(prog="plan_day.py", description=__doc__.splitlines()[0])
    parser.add_argument("--workspace", type=Path, help="workspace root (default: search upward)")
    commands = parser.add_subparsers(dest="command", required=True)
    commands.add_parser("config", help="print the validated pa.toml as JSON")
    validate = commands.add_parser("validate", help="check collector JSON against the contract")
    validate.add_argument("files", nargs="+", type=Path)
    collect = commands.add_parser("collect", help="run one collector and write .artifacts/plan-day/<source>.json")
    collect.add_argument("source", choices=("beads", "jira", "thoughtbox"))
    collect.add_argument("--client", help="jira: [[clients]] name owning the input")
    collect.add_argument("--input", type=Path, help="jira: saved MCP search result to normalise")
    commands.add_parser("merge", help="merge validated collector output from .artifacts/plan-day")
    draft_cmd = commands.add_parser("draft", help="merge, propose blocks and launch lines, write draft.json")
    draft_cmd.add_argument("--now", type=datetime.fromisoformat, default=None)
    render_cmd = commands.add_parser("render", help="write plans/YYYY-MM-DD.md from a decisions file")
    render_cmd.add_argument("--decisions", type=Path, default=None, help="default: .artifacts/plan-day/draft.json")
    render_cmd.add_argument("--dry-run", action="store_true", help="print the plan without writing or pruning")
    plans = commands.add_parser("plans", help="locate today's, the previous, and stale plan files")
    plans.add_argument("--today", type=date.fromisoformat, default=None)
    plans.add_argument("--prune", action="store_true", help="delete stale plan files")
    return parser.parse_args(argv)


def main(argv: list[str]) -> int:
    args = parse_args(argv)
    try:
        if args.command == "validate":
            for path in args.files:
                load_items(path)
            print(json.dumps({"valid": [str(path) for path in args.files]}))
            return 0
        workspace = load_workspace(args.workspace)
        if args.command == "config":
            output: dict[str, Any] = {"root": str(workspace.root), **workspace.config}
        elif args.command == "collect":
            if args.source == "jira" and (not args.client or not args.input):
                raise PlanDayError("collect jira needs --client and --input")
            output = collect(workspace, args)
        elif args.command == "merge":
            output = merge(workspace)
        elif args.command == "draft":
            output = draft(workspace, args.now or datetime.now().astimezone())
            workspace.artifacts_dir.mkdir(parents=True, exist_ok=True)
            (workspace.artifacts_dir / "draft.json").write_text(
                json.dumps(output, indent=2, sort_keys=True) + "\n", encoding="utf-8"
            )
        elif args.command == "render":
            decisions = args.decisions or workspace.artifacts_dir / "draft.json"
            result = render(workspace, decisions, args.dry_run)
            print(result.pop("plan"))
            output = result
        else:
            today = args.today or datetime.now().astimezone().date()
            output = plan_files(workspace, today)
            if args.prune:
                prune(output["stale"])
                output["pruned"] = output.pop("stale")
    except PlanDayError as error:
        print(f"plan-day: {error}", file=sys.stderr)
        return 1
    print(json.dumps(output, indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
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: 471kUpdated 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