Skip to content

bestdeejay-design/agent-skills / skills/plan-skill

plan-skill

Verified

FileKindSize
SKILL.mdskill md8.6 KB
examples/implementation-plan-example.mdmarkdown2.2 KB
scripts/plan_validator.pyscript4.2 KB
skill.jsonconfig1.8 KB
templates/implementation-plan.mdmarkdown1.5 KB

scripts/plan_validator.py

View on GitHub
#!/usr/bin/env python3
"""Validate an implementation plan Markdown file (superpowers-style).

Checks the plan is execution-ready:
  1. Has Goal, Constraints, Steps, Verification sections.
  2. Contains no placeholder markers (TBD, TODO, "...", "решим потом").
  3. Each "Step N" subsection has a Files record with a concrete file path.
  4. Steps are bite-sized (no huge step bodies).
  5. Acceptance criteria are checkable (no subjective phrasing).

Returns exit code 0 when the plan is ready, 1 otherwise (with a list of issues).

Usage:
    python3 plan_validator.py <plan.md> [--verbose]
"""
import re
import sys

PLACEHOLDER_PATTERNS = [
    r"\bTBD\b",
    r"\bTODO\b",
    r"\bFIXME\b",
    r"\.\.\.\s*$",
    r"решим потом",
    r"доделать позже",
    r"в процессе",
    r"XXX",
]

SUBJECTIVE_PATTERNS = [
    r"хорошо[ея]\b",
    r"красив[оы]",
    r"правильно\b",
    r"оптимальн[оы]",
]

REQUIRED_SECTIONS = ["goal", "constraints", "steps", "verification"]
MAX_STEP_LINES = 8


def _heading_level(line: str) -> int:
    m = re.match(r"^(#{1,6})\s+", line.strip())
    return len(m.group(1)) if m else 0


def _split_sections(lines: list[str]) -> dict[str, list[int]]:
    headings: list[tuple[int, int, str]] = []
    for i, line in enumerate(lines):
        lvl = _heading_level(line)
        if lvl:
            headings.append((i, lvl, line.strip().lstrip("#").strip().lower()))

    sections: dict[str, list[int]] = {}
    for idx, (start, level, title) in enumerate(headings):
        end = start
        for nxt in headings[idx + 1 :]:
            if nxt[1] <= level:
                end = nxt[0]
                break
        else:
            end = len(lines)
        sections.setdefault(title, []).extend(range(start + 1, end))
    return sections


def find_issues(lines: list[str], verbose: bool) -> list[str]:
    issues: list[str] = []
    sections = _split_sections(lines)

    for req in REQUIRED_SECTIONS:
        if not any(req in header for header in sections):
            issues.append(f"Missing section: '{req}'")

    for lineno, line in enumerate(lines, 1):
        for pattern in PLACEHOLDER_PATTERNS:
            if re.search(pattern, line, re.IGNORECASE):
                issues.append(f"Placeholder at line {lineno}: '{line.strip()[:60]}'")

    for lineno, line in enumerate(lines, 1):
        for pattern in SUBJECTIVE_PATTERNS:
            if re.search(pattern, line, re.IGNORECASE) and "acceptance" not in line.lower():
                issues.append(f"Subjective wording at line {lineno}: '{line.strip()[:60]}'")

    step_headers = [h for h in sections if re.match(r"step\s*\d+", h)]
    if not step_headers:
        issues.append("No 'Step N' subsection found in Steps")

    for header in step_headers:
        body = [lines[i] for i in sections[header]]
        files_cell = next((l for l in body if l.strip().startswith("- Files:")), None)
        if files_cell is None:
            issues.append(f"{header}: missing 'Files:' record")
        elif not re.search(r"[A-Za-z0-9_\-./]+\.[A-Za-z0-9]+", files_cell):
            issues.append(f"{header}: 'Files:' record has no concrete file path")
        real = [l for l in body if l.strip() and not re.match(r"^\s*[-*]\s+\[[ xX]\]", l)]
        if len(real) > MAX_STEP_LINES:
            issues.append(f"{header}: step body too large ({len(real)} lines, max {MAX_STEP_LINES})")

    if verbose:
        print(f"[debug] {len(lines)} lines, sections={sorted(sections)}")
    return issues


def main() -> None:
    args = [a for a in sys.argv[1:] if not a.startswith("-")]
    verbose = "--verbose" in sys.argv
    if not args:
        print(__doc__)
        sys.exit(2)

    path = args[0]
    try:
        with open(path, encoding="utf-8") as f:
            lines = [l.rstrip("\n") for l in f]
    except OSError as e:
        print(f"❌ Cannot read {path}: {e}")
        sys.exit(1)

    issues = find_issues(lines, verbose)
    if issues:
        print(f"❌ Plan {path} is NOT execution-ready ({len(issues)} issue(s)):")
        for i in issues:
            print(f"   - {i}")
        sys.exit(1)

    print(f"✅ Plan {path} is execution-ready")


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: 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