dongshuyan/compass-skills / skills/task-planner
task-planner
VerifiedCreate a complete, expandable HTML plan for an agreed task and keep the same report current as plan nodes finish. Use for a new task plan, continuing a planned run, or revising a plan from execution evidence.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| agents/openai.yaml | config | 246 B |
| assets/report.html | other | 27.4 KB |
| references/plan-format.md | markdown | 8.8 KB |
| scripts/events.py | script | 10.9 KB |
| scripts/model.py | script | 9.0 KB |
| scripts/plan.py | script | 5.4 KB |
scripts/model.py
View on GitHub"""The plan tree, prerequisites and observable units of work."""
from __future__ import annotations
from graphlib import CycleError, TopologicalSorter
import math
import re
class Invalid(ValueError):
"""A document or event cannot be applied as written."""
class Conflict(Invalid):
"""The caller needs a fresh view of the current plan."""
def require(condition, message):
if not condition:
raise Invalid(message)
def text(value):
return isinstance(value, str) and bool(value.strip())
def number(value):
return type(value) in (float, int) and math.isfinite(value)
def strings(value, field, *, required=False):
require(isinstance(value, list) and all(text(item) for item in value), f"{field}: expected a list of text")
require(not required or value, f"{field}: specify observable evidence")
def fields(obj, required, optional=()):
require(isinstance(obj, dict), "expected a JSON object")
missing = set(required) - obj.keys()
extra = obj.keys() - set(required) - set(optional)
require(not missing, "missing fields: " + ", ".join(sorted(missing)))
require(not extra, "unknown fields: " + ", ".join(sorted(extra)))
def estimate(value):
bounds = value if isinstance(value, list) else [value, value]
require(len(bounds) == 2 and all(number(x) for x in bounds) and 0 < bounds[0] <= bounds[1],
"estimate_minutes: use positive minutes or [low, high]")
return bounds
def dependency(value):
if isinstance(value, str):
return value, "passed"
fields(value, ("id", "needs"))
require(text(value["id"]) and value["needs"] in ("passed", "evidence"),
"deps: use a node ID or {id, needs: passed|evidence}")
return value["id"], value["needs"]
NODE_TEXT = ("title", "description", "deliverable", "expected", "acceptance", "rationale")
NODE_FIELDS = ("id", "parent", *NODE_TEXT, "constraints", "estimate_minutes", "deps", "facts")
FORECAST_FIELDS = {"expected", "estimate_minutes", "facts", "rationale", "baseline"}
PROTECTED_ROOT = {"title", "description", "deliverable", "acceptance", "constraints"}
def has_usable_result(entry):
result = entry.get("result", {})
if entry["status"] == "active":
return False
return result.get("verdict") == "passed" or (result.get("verdict") == "deviation"
and bool(result.get("usable_evidence")))
def validate_node(n):
fields(n, NODE_FIELDS, ("baseline", "awaiting_input"))
require(text(n["id"]) and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}", n["id"]),
"id: use a stable letter/number identifier, optionally with . _ or -")
require(n["parent"] is None or text(n["parent"]), f"{n['id']}: invalid parent")
for name in NODE_TEXT:
require(text(n[name]), f"{n['id']}.{name}: supply plain text")
strings(n["constraints"], "constraints")
if n.get("awaiting_input") is not None:
require(text(n["awaiting_input"]), "awaiting_input: describe the outstanding external input")
estimate(n["estimate_minutes"])
require(isinstance(n["deps"], list), "deps: expected a list")
deps = [dependency(d)[0] for d in n["deps"]]
require(len(set(deps)) == len(deps), f"{n['id']}: repeated prerequisite")
require(isinstance(n["facts"], list) and n["facts"], f"{n['id']}: give the basis for the plan")
for fact in n["facts"]:
fields(fact, ("claim", "source", "confidence"))
require(text(fact["claim"]) and fact["confidence"] in ("high", "medium", "low"),
"facts: each claim has high, medium or low confidence")
source = fact["source"]
require(text(source) or (source is None and fact["confidence"] == "low"),
"facts: name the source, or use null and low confidence")
baseline = n.get("baseline")
if baseline is not None:
fields(baseline, ("metric", "method", "node"), ("use",))
require(all(text(baseline[k]) for k in ("metric", "method", "node")),
"baseline: name metric, method and measurement node")
require(baseline.get("use", "input") in ("input", "forecast"), "baseline.use: use input or forecast")
class Tree:
def __init__(self, state):
self.state = state
self.nodes = {n["id"]: n for n in state["nodes"]}
self.work = state["work"]
self.children = {key: [] for key in self.nodes}
self.live = [key for key in self.nodes if self.work[key]["status"] != "retired"]
roots = [key for key in self.live if self.nodes[key]["parent"] is None]
require(len(roots) == 1, "provide exactly one live root node")
self.root = roots[0]
for key in self.live:
parent = self.nodes[key]["parent"]
if parent is not None:
require(parent in self.nodes and self.work[parent]["status"] != "retired",
f"{key}: unknown or retired parent {parent}")
self.children[parent].append(key)
def ancestors(self, key):
parent = self.nodes[key]["parent"]
while parent is not None:
yield parent
parent = self.nodes[parent]["parent"]
def direct_dependencies(self, key):
node = self.nodes[key]
for dep in node["deps"]:
yield dependency(dep)
baseline = node.get("baseline")
if baseline:
default = "input" if not self.children[key] and baseline["node"] != key else "forecast"
if baseline.get("use", default) == "input":
yield baseline["node"], "evidence"
def blockers(self, key):
blocked = []
for owner in (key, *self.ancestors(key)):
for target, needs in self.direct_dependencies(owner):
entry = self.work[target]
ok = entry["status"] == "passed"
if needs == "evidence":
ok = has_usable_result(entry)
if not ok and target not in blocked:
blocked.append(target)
return blocked
def validate(self):
graph = TopologicalSorter()
for key in self.live:
n = self.nodes[key]
start, end = ("start", key), ("end", key)
graph.add(end, start)
if n["parent"] is not None:
graph.add(start, ("start", n["parent"]))
graph.add(("end", n["parent"]), end)
if not self.children[key]:
require(estimate(n["estimate_minutes"])[1] <= 360, f"{key}: a leaf exceeds six hours")
else:
require(not n.get("awaiting_input"), f"{key}: place the external input on a receipt leaf")
for target, needs in self.direct_dependencies(key):
require(target in self.nodes, f"{key}: unknown prerequisite {target}")
if self.work[target]["status"] == "retired":
require(needs == "evidence" and has_usable_result(self.work[target]),
f"{key}: a retired prerequisite cannot provide this result")
else:
graph.add(start, ("end", target))
if n.get("baseline"):
target = n["baseline"]["node"]
require(target in self.nodes and self.work[target]["status"] != "retired",
f"{key}: choose a current measurement node")
try:
graph.prepare()
except CycleError as exc:
raise Invalid(f"cycle between hierarchy and prerequisites: {exc.args[1]}") from exc
def status(self):
pending = [key for key in self.live if self.work[key]["status"] == "planned" and not self.children[key]]
blocked = {key: causes for key in pending if (causes := self.blockers(key))}
eligible = [key for key in pending if key not in blocked]
waiting = {key: self.nodes[key]["awaiting_input"] for key in eligible if self.nodes[key].get("awaiting_input")}
ready = [key for key in eligible if key not in waiting]
return {"revision": self.state["revision"], "goal": self.state["goal"], "root": self.root,
"ready": ready, "awaiting_input": waiting, "blocked": blocked,
"active": [k for k in self.live if self.work[k]["status"] == "active"],
"interrupted": [k for k in self.live if self.work[k]["status"] == "interrupted"],
"awaiting_acceptance": [k for k in self.live if self.children[k]
and self.work[k]["status"] == "active"
and all(self.work[c]["status"] == "passed" for c in self.children[k])],
"deviations": [k for k in self.live if self.work[k]["status"] == "deviation"]}
def validate(state):
require(isinstance(state["nodes"], list) and state["nodes"], "a plan needs at least one node")
for node in state["nodes"]:
validate_node(node)
ids = [n["id"] for n in state["nodes"]]
require(len(ids) == len(set(ids)), "node IDs must be unique")
require(set(ids) == state["work"].keys(), "node definitions and result records disagree")
tree = Tree(state)
tree.validate()
return tree
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |