Skip to content

beifeng724/personal-workbench-skills / skills/personal-workbench-builder

personal-workbench-builder

Verified

Build 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.

FileKindSize
LICENSEother520 B
SKILL.mdskill md6.3 KB
THIRD_PARTY_NOTICES.mdmarkdown1.4 KB
agents/openai.yamlconfig340 B
references/data-lifecycle.mdmarkdown3.0 KB
references/delivery-deployment.mdmarkdown3.3 KB
references/deployment-options.mdmarkdown3.8 KB
references/interview-and-levels.mdmarkdown5.4 KB
references/iteration-and-recovery.mdmarkdown2.1 KB
references/licenses/MIT-HIG-Doctor.txtmarkdown1.3 KB
references/licenses/MIT-Taste-Skill.txtmarkdown1.0 KB
references/licenses/MIT-UI-UX-Pro-Max.txtmarkdown1.0 KB
references/module-contract.mdmarkdown2.6 KB
references/privacy-security.mdmarkdown2.3 KB
references/prompt-pack.mdmarkdown3.6 KB
references/source-registry.jsonconfig2.7 KB
references/ui-audit.mdmarkdown1.6 KB
references/ui-quality.mdmarkdown4.5 KB
references/verification-contract.mdmarkdown2.9 KB
references/workbench-spec-template.mdmarkdown5.0 KB
scripts/create_spec.pyscript9.5 KB
scripts/ui_design_intelligence/core.pyscript16.6 KB
scripts/ui_design_intelligence/data/app-interface.csvother9.5 KB
scripts/ui_design_intelligence/data/charts.csvother18.9 KB
scripts/ui_design_intelligence/data/colors.csvother37.8 KB
scripts/ui_design_intelligence/data/icons.csvother20.2 KB
scripts/ui_design_intelligence/data/motion.csvother10.3 KB
scripts/ui_design_intelligence/data/products.csvother71.8 KB
scripts/ui_design_intelligence/data/stacks/astro.csvother11.6 KB
scripts/ui_design_intelligence/data/stacks/html-tailwind.csvother11.0 KB
scripts/ui_design_intelligence/data/stacks/nextjs.csvother12.2 KB
scripts/ui_design_intelligence/data/stacks/react.csvother12.7 KB
scripts/ui_design_intelligence/data/stacks/shadcn.csvother15.5 KB
scripts/ui_design_intelligence/data/stacks/vue.csvother10.7 KB
scripts/ui_design_intelligence/data/styles.csvother139.3 KB
scripts/ui_design_intelligence/data/typography.csvother48.7 KB
scripts/ui_design_intelligence/data/ui-reasoning.csvother51.7 KB
scripts/ui_design_intelligence/data/ux-guidelines.csvother18.2 KB
scripts/ui_design_intelligence/validate_data.pyscript4.1 KB
scripts/ui_design_intelligence/workbench_design.pyscript12.1 KB
scripts/workflow_guard.pyscript15.0 KB

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()
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