Skip to content

FrancyJGLisboa/agent-skills-platform / references/examples/github-release-briefing-skill

github-release-briefing-skill

Unverified

Create a source-linked briefing for the latest published GitHub release of a public repository. Use for engineering teams tracking a dependency release; do not use it to publish releases or change repositories.

scripts/staleness_check.py

View on GitHub
#!/usr/bin/env python3
"""
Staleness CLI for an agent skill.

Thin orchestrator: reads SKILL.md, runs the three peer modules
(review_staleness, dependency_health, schema_drift), aggregates issues, and
prints / exits. Each concern lives in its own module so it is testable in
isolation and reusable elsewhere.

Usage:
    python3 scripts/staleness_check.py <skill-path> [--json] [--check-deps] [--check-drift]

Exit codes:
    0 - Fresh (no staleness issues)
    1 - Stale (overdue for review)
    2 - Degraded (dependency failures or schema drift)
"""

from __future__ import annotations

import json
import sys
from pathlib import Path

_SCRIPTS_DIR = Path(__file__).resolve().parent
if str(_SCRIPTS_DIR) not in sys.path:
    sys.path.insert(0, str(_SCRIPTS_DIR))

from skill_document import SkillDoc  # noqa: E402
from review_staleness import (  # noqa: E402
    DEFAULT_REVIEW_INTERVAL_DAYS,
    check_review_staleness,
    get_git_last_modified,
)
from dependency_health import check_dependency_health  # noqa: E402
from schema_drift import check_schema_drift, parse_schema_expectations  # noqa: E402

# Re-exported for back-compat (skill_registry historically imported from here).
__all__ = ["DEFAULT_REVIEW_INTERVAL_DAYS", "staleness_check", "main"]


def staleness_check(
    skill_path: str,
    check_deps: bool = False,
    check_drift: bool = False,
) -> dict:
    """Run the staleness checks against the skill at `skill_path`.

    Returns a result dict with keys: fresh (bool), review_status (str),
    days_since_review (int|None), date_source (str), issues (list[dict]).
    """
    all_issues: list[dict] = []
    skill_dir = Path(skill_path).resolve()

    if not skill_dir.exists():
        return _err(f"Path does not exist: {skill_dir}")
    if not skill_dir.is_dir():
        return _err(f"Path is not a directory: {skill_dir}")

    skill_md = skill_dir / "SKILL.md"
    if not skill_md.exists():
        return _err("SKILL.md not found")

    try:
        content = skill_md.read_text(encoding="utf-8")
    except Exception as exc:
        return _err(f"Could not read SKILL.md: {exc}")

    doc = SkillDoc.from_text(content)
    if doc.frontmatter is None:
        return _err("No valid frontmatter found")

    # Phase 1: review staleness
    git_date = get_git_last_modified(skill_path)
    review_issues, review_status, days_since, date_source = check_review_staleness(doc, git_date)
    all_issues.extend(review_issues)

    # Phase 2: dependency health
    if check_deps:
        deps = doc.list_of_objects("metadata", "dependencies")
        if deps:
            all_issues.extend(check_dependency_health(deps))
        else:
            all_issues.append({
                "level": "info",
                "message": "No dependencies declared",
                "detail": "Add metadata.dependencies to enable health checks.",
            })

    # Phase 3: schema drift
    if check_drift:
        expectations = parse_schema_expectations(doc)
        if expectations:
            all_issues.extend(check_schema_drift(expectations))
        else:
            all_issues.append({
                "level": "info",
                "message": "No schema expectations declared",
                "detail": "Add metadata.schema_expectations to enable drift detection.",
            })

    has_errors = any(i["level"] == "error" for i in all_issues)
    return {
        "fresh": not has_errors,
        "review_status": review_status,
        "days_since_review": days_since,
        "date_source": date_source,
        "issues": all_issues,
    }


def _err(message: str) -> dict:
    return {
        "fresh": False,
        "review_status": "unknown",
        "days_since_review": None,
        "date_source": "none",
        "issues": [{"level": "error", "message": message, "detail": ""}],
    }


def _print_human_readable(result: dict, skill_path: str) -> None:
    print(f"Staleness check: {skill_path}")
    print(f"{'=' * 60}")

    status_label = result["review_status"].upper().replace("_", " ")
    print(f"Review status: {status_label}")
    if result["days_since_review"] is not None:
        print(f"Days since review: {result['days_since_review']} (source: {result['date_source']})")
    print("Overall: FRESH" if result["fresh"] else "Overall: STALE / DEGRADED")

    if result["issues"]:
        for level, label in (("error", "[ERROR]"), ("warning", "[WARN] "), ("info", "[INFO] ")):
            bucket = [i for i in result["issues"] if i["level"] == level]
            if bucket:
                print(f"\n{level.capitalize()} ({len(bucket)}):")
                for issue in bucket:
                    print(f"  {label} {issue['message']}")
                    if issue["detail"]:
                        print(f"          {issue['detail']}")

    print(f"{'=' * 60}")


def record_stale(skill_dir: Path, result: dict) -> None:
    """Append the raw staleness/drift evidence to the skill's EVOLUTION.md."""
    from datetime import datetime, timezone

    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    actionable = [i for i in result["issues"] if i["level"] in ("error", "warning")]
    entry = (
        f"## {stamp} — staleness_check {result['review_status'].upper()}\n\n"
        f"- days_since_review: {result['days_since_review']} (source: {result['date_source']})\n"
        f"- raw findings:\n\n"
        "```json\n" + json.dumps(actionable, indent=2) + "\n```\n\n"
    )
    evolution = skill_dir / "EVOLUTION.md"
    if not evolution.exists():
        evolution.write_text(
            "# Evolution log\n\nAppended automatically by scripts/run_evals.py "
            "(and scripts/evolve.py) when a check fails. Each entry is the raw "
            "evidence for a fix/regenerate step.\n\n",
            encoding="utf-8",
        )
    with evolution.open("a", encoding="utf-8") as fh:
        fh.write(entry)


def main() -> None:
    if len(sys.argv) < 2:
        print(
            "Usage: python3 scripts/staleness_check.py <skill-path> [--json] [--check-deps] [--check-drift] [--record]\n"
            "\n"
            "Arguments:\n"
            "  skill-path      Path to the skill directory to check\n"
            "\n"
            "Options:\n"
            "  --json           Output results as JSON to stdout\n"
            "  --check-deps     HTTP-check declared dependency URLs\n"
            "  --check-drift    Detect schema drift in declared API endpoints\n"
            "  --record         On stale/degraded, append raw evidence to EVOLUTION.md\n"
            "\n"
            "Exit codes:\n"
            "  0  Fresh (no staleness issues)\n"
            "  1  Stale (overdue for review)\n"
            "  2  Degraded (dependency failures or schema drift)\n",
            file=sys.stderr,
        )
        sys.exit(1)

    skill_path = sys.argv[1]
    use_json = "--json" in sys.argv
    check_deps = "--check-deps" in sys.argv
    check_drift = "--check-drift" in sys.argv
    record = "--record" in sys.argv

    result = staleness_check(skill_path, check_deps=check_deps, check_drift=check_drift)

    if use_json:
        print(json.dumps(result, indent=2))
    else:
        _print_human_readable(result, skill_path)

    has_dep_or_drift_errors = any(
        i["level"] == "error" and "review" not in i["message"].lower()
        for i in result["issues"]
    )

    if record and (result["review_status"] == "overdue" or has_dep_or_drift_errors):
        record_stale(Path(skill_path), result)

    if result["review_status"] == "overdue":
        sys.exit(1)

    if has_dep_or_drift_errors:
        sys.exit(2)

    sys.exit(0)


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