beifeng724/personal-workbench-skills / skills/personal-workbench-builder
personal-workbench-builder
VerifiedBuild a durable personal or professional workbench as a runnable application, or produce a six-stage generic prompt pack for building it. Use when the user wants to turn a recurring workflow into a dashboard, management system, workspace, personal operating system, or long-lived website with multiple connected modules and persistent state. Trigger for project, CRM, creator, learning, family, finance, travel, teaching, legal, or team workbenches. Do not trigger for marketing sites, one-off scripts, ordinary coding tasks, or informational questions.
scripts/workflow_guard.py
View on GitHub#!/usr/bin/env python3
"""Deterministic guard for workbench decisions, states, scope, and verification."""
from __future__ import annotations
import argparse
import json
from pathlib import Path
import re
from typing import Any
L4_SIGNALS = {
"multi_user_roles", "data_isolation", "audit", "payment", "monitoring",
"ongoing_operations",
}
L3_SIGNALS = {
"login", "cloud_sync", "cloud_database", "file_storage", "scheduled_jobs",
"background_jobs", "credentialed_api", "write_api", "critical_integration",
"external_api",
}
L2_SIGNALS = {"durable_url", "mobile_support", "import_export", "public_readonly_api"}
SENSITIVE = {"legal", "customer", "child", "health", "student", "finance", "company"}
STATE_SEQUENCE = (
"spec-approved", "ui-approved", "implementation-complete", "verification-passed",
)
REQUIRED_DECISIONS = {
"devices": ("devices", "primary_devices"),
"sync_expectation": ("sync_expectation", "sync"),
"data_importance": ("data_importance",),
"acceptable_data_loss": ("acceptable_data_loss", "acceptable_loss"),
"persistence": ("persistence", "persistence_approach"),
"deployment_profile": ("deployment_profile", "deployment"),
}
PRECONDITION_ONLY = {
"http 200", "200 ok", "syntax passed", "syntax ok", "selector exists",
"dom selector exists", "build passed", "lint passed", "typecheck passed",
}
def communication(payload: dict[str, Any]) -> str:
if payload.get("self_declared_beginner"):
return "plain"
if payload.get("consistently_technical"):
return "technical"
return "guided"
def classify(signals: dict[str, Any]) -> str:
active = {key for key, value in signals.items() if value}
if active & L4_SIGNALS:
return "L4"
if active & L3_SIGNALS:
return "L3"
if active & L2_SIGNALS:
return "L2"
return "L1"
def scope_violations(requirements: list[dict[str, Any]]) -> list[str]:
violations = []
for item in requirements:
if item.get("status") != "confirmed":
continue
if item.get("decision") in {"remove", "defer", "alter"} and not item.get("user_approved"):
violations.append(item.get("id") or item.get("text") or "unnamed requirement")
return violations
def state_entry(payload: dict[str, Any], name: str) -> Any:
states = payload.get("states") or {}
return states.get(name, states.get(name.replace("-", "_")))
def state_passed(payload: dict[str, Any], name: str) -> bool:
entry = state_entry(payload, name)
if isinstance(entry, dict):
return bool(entry.get("passed"))
if entry is not None:
return bool(entry)
legacy = name.replace("-", "_")
if name == "spec-approved" and payload.get("spec_approved"):
return True
return bool(payload.get(legacy))
def state_evidence(payload: dict[str, Any], name: str) -> str:
entry = state_entry(payload, name)
if isinstance(entry, dict):
return str(entry.get("evidence") or "").strip()
legacy = payload.get(f"{name.replace('-', '_')}_evidence")
return str(legacy or "").strip()
def decision_value(payload: dict[str, Any], aliases: tuple[str, ...]) -> Any:
decisions = payload.get("decisions") or {}
for alias in aliases:
if alias in decisions:
return decisions[alias]
if alias in payload:
return payload[alias]
return None
def is_missing(value: Any) -> bool:
return value is None or value == "" or value == [] or value == {}
def missing_decisions(payload: dict[str, Any]) -> list[str]:
return [
name for name, aliases in REQUIRED_DECISIONS.items()
if is_missing(decision_value(payload, aliases))
]
def normalize_evidence(value: Any) -> str:
return re.sub(r"[^a-z0-9]+", " ", str(value or "").lower()).strip()
def confirmed_requirement_failures(requirements: list[dict[str, Any]]) -> list[str]:
failures = []
for item in requirements:
if item.get("status") != "confirmed":
continue
item_id = item.get("id") or item.get("text") or "unnamed requirement"
if not str(item.get("acceptance") or item.get("acceptance_condition") or "").strip():
failures.append(f"{item_id}: acceptance condition missing")
implemented = item.get("implemented") is True or item.get("implementation_status") == "implemented"
if not implemented:
failures.append(f"{item_id}: implementation not recorded")
return failures
def control_failures(controls: list[dict[str, Any]], require_results: bool) -> list[str]:
if not controls:
return ["control inventory is empty"]
failures = []
for index, control in enumerate(controls, start=1):
control_id = control.get("id") or f"control-{index}"
behavior = str(control.get("intended_behavior") or control.get("behavior") or "").strip()
acceptance = str(control.get("acceptance_condition") or control.get("acceptance") or "").strip()
if not behavior:
failures.append(f"{control_id}: intended behavior missing")
if not acceptance:
failures.append(f"{control_id}: acceptance condition missing")
if not require_results:
continue
method = str(control.get("test_method") or "").strip()
actual = str(control.get("actual_result") or control.get("result") or "").strip()
evidence = str(control.get("evidence") or "").strip()
status = str(control.get("status") or "not-run").lower()
if status != "passed":
failures.append(f"{control_id}: required status is {status}")
if not method:
failures.append(f"{control_id}: test method missing")
if not actual:
failures.append(f"{control_id}: actual result missing")
if not evidence:
failures.append(f"{control_id}: evidence missing")
normalized = normalize_evidence(actual or evidence)
if normalized in PRECONDITION_ONLY:
failures.append(f"{control_id}: precondition-only evidence is not functional proof")
return failures
def approval_gate(level: str, payload: dict[str, Any]) -> tuple[bool, str]:
if payload.get("output_mode", "direct") != "direct":
return False, "prompt-pack mode does not start implementation"
spec_passed = state_passed(payload, "spec-approved") or bool(payload.get("spec_approved"))
if level == "L1":
allowed = bool(payload.get("requirements_clear")) or spec_passed
return allowed, "L1 fast path recorded" if allowed else "requirements are not clear"
if level in {"L2", "L3"}:
return spec_passed, "specification approved" if spec_passed else "specification approval required"
sections = {"features", "data", "permissions", "deployment", "cost", "other_ideas"}
confirmed = set(payload.get("l4_confirmed_sections", []))
allowed = bool(payload.get("explicit_complete_plan_approval")) and sections <= confirmed and spec_passed
missing = sorted(sections - confirmed)
reason = "complete L4 approval recorded" if allowed else "L4 approval incomplete: " + (
", ".join(missing) if missing else "explicit approval or spec state missing"
)
return allowed, reason
def transition_checks(payload: dict[str, Any], target: str | None) -> tuple[list[str], list[str]]:
state_errors: list[str] = []
verification_failures: list[str] = []
if not target:
return state_errors, verification_failures
if target not in STATE_SEQUENCE:
return [f"unknown target_state: {target}"], verification_failures
target_index = STATE_SEQUENCE.index(target)
for prior in STATE_SEQUENCE[:target_index]:
if not state_passed(payload, prior):
state_errors.append(f"{prior} must pass before {target}")
elif not state_evidence(payload, prior):
state_errors.append(f"{prior} evidence is missing")
if not state_passed(payload, target):
state_errors.append(f"{target} is not recorded as passed")
if state_passed(payload, target) and not state_evidence(payload, target):
state_errors.append(f"{target} evidence is missing")
requirements = payload.get("requirements", [])
controls = payload.get("controls", [])
if target_index >= STATE_SEQUENCE.index("implementation-complete"):
verification_failures.extend(confirmed_requirement_failures(requirements))
verification_failures.extend(control_failures(controls, require_results=False))
if target_index >= STATE_SEQUENCE.index("verification-passed"):
verification_failures.extend(control_failures(controls, require_results=True))
return state_errors, verification_failures
def evaluate(payload: dict[str, Any]) -> dict[str, Any]:
level = classify(payload.get("signals", {}))
violations = scope_violations(payload.get("requirements", []))
target = payload.get("target_state")
missing = missing_decisions(payload) if payload.get("output_mode", "direct") == "direct" and target else []
state_errors, verification_failures = transition_checks(payload, target)
allowed, reason = approval_gate(level, payload)
if missing:
allowed = False
reason = "required decisions missing"
if violations:
allowed = False
reason = "confirmed requirements changed without user approval"
if payload.get("frontend_contains_secret"):
allowed = False
reason = "frontend secrets are prohibited"
if state_errors:
allowed = False
reason = "workflow state transition blocked"
if verification_failures:
allowed = False
reason = "implementation or verification contract failed"
transition_allowed = allowed and not missing and not state_errors and not verification_failures
completion_allowed = transition_allowed and target == "verification-passed"
return {
"communication_mode": communication(payload),
"complexity": level,
"development_allowed": allowed,
"reason": reason,
"scope_violations": violations,
"privacy_review_required": bool(set(payload.get("data_categories", [])) & SENSITIVE),
"target_state": target,
"transition_allowed": transition_allowed,
"completion_allowed": completion_allowed,
"missing_decisions": missing,
"state_errors": state_errors,
"verification_failures": verification_failures,
}
def complete_decisions() -> dict[str, Any]:
return {
"devices": ["desktop"],
"sync_expectation": "none",
"data_importance": "replaceable",
"acceptable_data_loss": "all sample data",
"persistence": "browser-local",
"deployment_profile": "local-single-device",
}
def passed_states(*names: str) -> dict[str, dict[str, Any]]:
return {name: {"passed": True, "evidence": f"recorded {name}"} for name in names}
def self_test() -> None:
decisions = complete_decisions()
cases = [
({"self_declared_beginner": True, "requirements_clear": True}, "plain", "L1", True),
({"consistently_technical": True, "signals": {"public_readonly_api": True}, "spec_approved": True}, "technical", "L2", True),
({"signals": {"credentialed_api": True}, "spec_approved": False}, "guided", "L3", False),
({"signals": {"write_api": True}, "spec_approved": True}, "guided", "L3", True),
({"signals": {"external_api": True}, "spec_approved": True}, "guided", "L3", True),
({"signals": {"multi_user_roles": True}, "spec_approved": True, "explicit_complete_plan_approval": True,
"l4_confirmed_sections": ["features", "data", "permissions", "deployment", "cost"]}, "guided", "L4", False),
({"signals": {"multi_user_roles": True}, "spec_approved": True, "explicit_complete_plan_approval": True,
"l4_confirmed_sections": ["features", "data", "permissions", "deployment", "cost", "other_ideas"]}, "guided", "L4", True),
]
for payload, mode, level, allowed in cases:
result = evaluate(payload)
actual = (result["communication_mode"], result["complexity"], result["development_allowed"])
assert actual == (mode, level, allowed), result
missing = evaluate({
"requirements_clear": True,
"target_state": "spec-approved",
"states": passed_states("spec-approved"),
})
assert not missing["transition_allowed"] and set(missing["missing_decisions"]) == set(REQUIRED_DECISIONS), missing
out_of_order = evaluate({
**decisions,
"requirements_clear": True,
"target_state": "implementation-complete",
"states": passed_states("implementation-complete"),
})
assert not out_of_order["transition_allowed"] and len(out_of_order["state_errors"]) == 2, out_of_order
violation = evaluate({
"requirements_clear": True,
"requirements": [{"id": "R1", "status": "confirmed", "decision": "defer", "user_approved": False}],
})
assert not violation["development_allowed"] and violation["scope_violations"] == ["R1"], violation
privacy = evaluate({"requirements_clear": True, "data_categories": ["finance"]})
assert privacy["privacy_review_required"], privacy
precondition_only = evaluate({
**decisions,
"requirements_clear": True,
"target_state": "verification-passed",
"states": passed_states(*STATE_SEQUENCE),
"requirements": [{
"id": "R1", "status": "confirmed", "acceptance": "record remains after refresh", "implemented": True,
}],
"controls": [{
"id": "save", "intended_behavior": "save a record", "acceptance": "record remains after refresh",
"test_method": "click and refresh", "actual_result": "HTTP 200", "evidence": "request log", "status": "passed",
}],
})
assert not precondition_only["completion_allowed"] and any(
"precondition-only" in item for item in precondition_only["verification_failures"]
), precondition_only
verified = evaluate({
**decisions,
"requirements_clear": True,
"target_state": "verification-passed",
"states": passed_states(*STATE_SEQUENCE),
"requirements": [{
"id": "R1", "status": "confirmed", "acceptance": "record remains after refresh", "implemented": True,
}],
"controls": [{
"id": "save", "intended_behavior": "save a record", "acceptance": "record remains after refresh",
"test_method": "create, refresh, and compare", "actual_result": "record 42 remained after refresh",
"evidence": "tests/save-persistence.json", "status": "passed",
}],
})
assert verified["completion_allowed"], verified
print(f"SELF TEST PASSED: {len(cases) + 6} workflow guard cases")
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("input", type=Path, nargs="?")
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
self_test()
return
if not args.input:
parser.error("input JSON is required unless --self-test is used")
payload = json.loads(args.input.read_text(encoding="utf-8"))
print(json.dumps(evaluate(payload), ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |