The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat: add pr-report skill
Dottafbf9d5714f16
diff --git a/skills/pr-report/SKILL.md b/skills/pr-report/SKILL.mdnew file mode 100644index 0000000000..5064b67c09--- /dev/null+++ b/skills/pr-report/SKILL.md@@ -0,0 +1,202 @@+---+name: pr-report+description: >+ Review a pull request or contribution deeply, explain it tutorial-style for a+ maintainer, and produce a polished report artifact such as HTML or Markdown.+ Use when asked to analyze a PR, explain a contributor's design decisions,+ compare it with similar systems, or prepare a merge recommendation.+---++# PR Report Skill++Produce a maintainer-grade review of a PR, branch, or large contribution.++Default posture:++- understand the change before judging it+- explain the system as built, not just the diff+- separate architectural problems from product-scope objections+- make a concrete recommendation, not a vague impression++## When to Use++Use this skill when the user asks for things like:++- "review this PR deeply"+- "explain this contribution to me"+- "make me a report or webpage for this PR"+- "compare this design to similar systems"+- "should I merge this?"++## Outputs++Common outputs:++- standalone HTML report in `tmp/reports/...`+- Markdown report in `report/` or another requested folder+- short maintainer summary in chat++If the user asks for a webpage, build a polished standalone HTML artifact with+clear sections and readable visual hierarchy.++Resources bundled with this skill:++- `references/style-guide.md` for visual direction and report presentation rules+- `assets/html-report-starter.html` for a reusable standalone HTML/CSS starter++## Workflow++### 1. Acquire and frame the target++Work from local code when possible, not just the GitHub PR page.++Gather:++- target branch or worktree+- diff size and changed subsystems+- relevant repo docs, specs, and invariants+- contributor intent if it is documented in PR text or design docs++Start by answering: what is this change *trying* to become?++### 2. Build a mental model of the system++Do not stop at file-by-file notes. Reconstruct the design:++- what new runtime or contract exists+- which layers changed: db, shared types, server, UI, CLI, docs+- lifecycle: install, startup, execution, UI, failure, disablement+- trust boundary: what code runs where, under what authority++For large contributions, include a tutorial-style section that teaches the+system from first principles.++### 3. Review like a maintainer++Findings come first. Order by severity.++Prioritize:++- behavioral regressions+- trust or security gaps+- misleading abstractions+- lifecycle and operational risks+- coupling that will be hard to unwind+- missing tests or unverifiable claims++Always cite concrete file references when possible.++### 4. Distinguish the objection type++Be explicit about whether a concern is:++- product direction+- architecture+- implementation quality+- rollout strategy+- documentation honesty++Do not hide an architectural objection inside a scope objection.++### 5. Compare to external precedents when needed++If the contribution introduces a framework or platform concept, compare it to+similar open-source systems.++When comparing:++- prefer official docs or source+- focus on extension boundaries, context passing, trust model, and UI ownership+- extract lessons, not just similarities++Good comparison questions:++- Who owns lifecycle?+- Who owns UI composition?+- Is context explicit or ambient?+- Are plugins trusted code or sandboxed code?+- Are extension points named and typed?++### 6. Make the recommendation actionable++Do not stop at "merge" or "do not merge."++Choose one:++- merge as-is+- merge after specific redesign+- salvage specific pieces+- keep as design research++If rejecting or narrowing, say what should be kept.++Useful recommendation buckets:++- keep the protocol/type model+- redesign the UI boundary+- narrow the initial surface area+- defer third-party execution+- ship a host-owned extension-point model first++### 7. Build the artifact++Suggested report structure:++1. Executive summary+2. What the PR actually adds+3. Tutorial: how the system works+4. Strengths+5. Main findings+6. Comparisons+7. Recommendation++For HTML reports:++- use intentional typography and color+- make navigation easy for long reports+- favor strong section headings and small reference labels+- avoid generic dashboard styling++Before building from scratch, read `references/style-guide.md`.+If a fast polished starter is helpful, begin from `assets/html-report-starter.html`+and replace the placeholder content with the actual report.++### 8. Verify before handoff++Check:++- artifact path exists+- findings still match the actual code+- any requested forbidden strings are absent from generated output+- if tests were not run, say so explicitly++## Review Heuristics++### Plugin and platform work++Watch closely for:++- docs claiming sandboxing while runtime executes trusted host processes+- module-global state used to smuggle React context+- hidden dependence on render order+- plugins reaching into host internals instead of using explicit APIs+- "capabilities" that are really policy labels on top of fully trusted code++### Good signs++- typed contracts shared across layers+- explicit extension points+- host-owned lifecycle+- honest trust model+- narrow first rollout with room to grow++## Final Response++In chat, summarize:++- where the report is+- your overall call+- the top one or two reasons+- whether verification or tests were skipped++Keep the chat summary shorter than the report itself.diff --git a/skills/pr-report/assets/html-report-starter.html b/skills/pr-report/assets/html-report-starter.htmlnew file mode 100644index 0000000000..be6f0550c8--- /dev/null+++ b/skills/pr-report/assets/html-report-starter.html@@ -0,0 +1,426 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>PR Report Starter</title>+ <link rel="preconnect" href="https://fonts.googleapis.com" />+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />+ <link+ href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=Newsreader:opsz,[email protected],500;6..72,700&display=swap"+ rel="stylesheet"+ />+ <style>+ :root {+ --bg: #f4efe5;+ --paper: rgba(255, 251, 244, 0.88);+ --paper-strong: #fffaf1;+ --ink: #1f1b17;+ --muted: #6a6257;+ --line: rgba(31, 27, 23, 0.12);+ --accent: #9c4729;+ --accent-soft: rgba(156, 71, 41, 0.1);+ --good: #2f6a42;+ --warn: #946200;+ --bad: #8c2f25;+ --shadow: 0 22px 60px rgba(52, 37, 19, 0.1);+ --radius: 20px;+ }++ * {+ box-sizing: border-box;+ }++ html {+ scroll-behavior: smooth;+ }++ body {+ margin: 0;+ color: var(--ink);+ font-family: "IBM Plex Sans", sans-serif;+ background:+ radial-gradient(circle at top left, rgba(156, 71, 41, 0.12), transparent 34rem),+ radial-gradient(circle at top right, rgba(47, 106, 66, 0.08), transparent 28rem),+ linear-gradient(180deg, #efe6d6 0%, var(--bg) 48%, #ece5d8 100%);+ }++ .shell {+ width: min(1360px, calc(100vw - 32px));+ margin: 24px auto;+ display: grid;+ grid-template-columns: 280px minmax(0, 1fr);+ gap: 24px;+ }++ .panel {+ background: var(--paper);+ backdrop-filter: blur(12px);+ border: 1px solid var(--line);+ border-radius: var(--radius);+ box-shadow: var(--shadow);+ }++ .nav {+ position: sticky;+ top: 20px;+ align-self: start;+ padding: 22px;+ }++ .eyebrow {+ letter-spacing: 0.12em;+ text-transform: uppercase;+ font-size: 11px;+ font-weight: 700;+ color: var(--accent);+ }++ .nav h1,+ .hero h1,+ h2,+ h3 {+ font-family: "Newsreader", serif;+ line-height: 0.96;+ margin: 0;+ }++ .nav h1 {+ font-size: 2rem;+ margin-top: 10px;+ }++ .nav p {+ color: var(--muted);+ font-size: 0.95rem;+ line-height: 1.5;+ }++ .nav ul {+ list-style: none;+ padding: 0;+ margin: 18px 0 0;+ display: grid;+ gap: 10px;+ }++ .nav a {+ display: block;+ color: var(--ink);+ text-decoration: none;+ padding: 10px 12px;+ border-radius: 12px;+ border: 1px solid transparent;+ background: rgba(255, 255, 255, 0.35);+ }++ .nav a:hover {+ border-color: var(--line);+ background: rgba(255, 255, 255, 0.75);+ }++ .meta-block {+ margin-top: 20px;+ padding-top: 18px;+ border-top: 1px solid var(--line);+ color: var(--muted);+ font-size: 0.86rem;+ line-height: 1.5;+ }++ main {+ display: grid;+ gap: 24px;+ }++ section {+ padding: 26px 28px 28px;+ }++ .hero {+ padding: 28px;+ overflow: hidden;+ position: relative;+ }++ .hero::after {+ content: "";+ position: absolute;+ inset: auto -3rem -6rem auto;+ width: 18rem;+ height: 18rem;+ border-radius: 50%;+ background: radial-gradient(circle, rgba(156, 71, 41, 0.14), transparent 68%);+ pointer-events: none;+ }++ .hero h1 {+ font-size: clamp(2.6rem, 5vw, 4.6rem);+ max-width: 12ch;+ margin-top: 12px;+ }++ .lede {+ margin-top: 16px;+ max-width: 70ch;+ font-size: 1.05rem;+ line-height: 1.65;+ color: #2b2723;+ }++ .hero-grid,+ .card-grid,+ .two-col {+ display: grid;+ gap: 14px;+ }++ .hero-grid {+ margin-top: 24px;+ grid-template-columns: repeat(4, minmax(0, 1fr));+ }++ .card-grid {+ grid-template-columns: repeat(2, minmax(0, 1fr));+ }++ .two-col {+ grid-template-columns: repeat(2, minmax(0, 1fr));+ }++ .metric,+ .card,+ .finding {+ padding: 18px;+ background: rgba(255, 255, 255, 0.68);+ border: 1px solid var(--line);+ border-radius: 18px;+ }++ .metric .label {+ color: var(--muted);+ font-size: 0.82rem;+ text-transform: uppercase;+ letter-spacing: 0.08em;+ }++ .metric .value {+ margin-top: 8px;+ font-size: 1.45rem;+ font-weight: 700;+ }++ h2 {+ font-size: 2rem;+ margin-bottom: 16px;+ }++ h3 {+ font-size: 1.3rem;+ margin-bottom: 10px;+ }++ p {+ margin: 0 0 14px;+ line-height: 1.65;+ }++ ul,+ ol {+ margin: 0;+ padding-left: 20px;+ line-height: 1.65;+ }++ li + li {+ margin-top: 8px;+ }++ .badge-row {+ display: flex;+ flex-wrap: wrap;+ gap: 8px;+ margin: 18px 0 8px;+ }++ .badge {+ display: inline-flex;+ align-items: center;+ gap: 8px;+ padding: 8px 10px;+ border-radius: 999px;+ font-size: 0.82rem;+ font-weight: 700;+ border: 1px solid var(--line);+ background: rgba(255, 255, 255, 0.68);+ }++ .badge.good {+ color: var(--good);+ }++ .badge.warn {+ color: var(--warn);+ }++ .badge.bad {+ color: var(--bad);+ }++ .quote {+ margin-top: 18px;+ padding: 18px;+ border-left: 4px solid var(--accent);+ border-radius: 14px;+ background: var(--accent-soft);+ }++ .severity {+ display: inline-flex;+ margin-bottom: 12px;+ padding: 6px 10px;+ border-radius: 999px;+ font-size: 0.78rem;+ font-weight: 700;+ text-transform: uppercase;+ letter-spacing: 0.08em;+ }++ .severity.high {+ background: rgba(140, 47, 37, 0.12);+ color: var(--bad);+ }++ .severity.medium {+ background: rgba(148, 98, 0, 0.12);+ color: var(--warn);+ }++ .severity.low {+ background: rgba(47, 106, 66, 0.12);+ color: var(--good);+ }++ .ref {+ color: var(--muted);+ font-size: 0.82rem;+ line-height: 1.5;+ }++ @media (max-width: 980px) {+ .shell {+ grid-template-columns: 1fr;+ }++ .nav {+ position: static;+ }++ .hero-grid,+ .card-grid,+ .two-col {+ grid-template-columns: 1fr;+ }++ .hero h1 {+ max-width: 100%;+ }+ }+ </style>+ </head>+ <body>+ <div class="shell">+ <aside class="panel nav">+ <div class="eyebrow">Maintainer Report</div>+ <h1>Report Title</h1>+ <p>Replace this with a concise description of what the report covers.</p>+ <ul>+ <li><a href="#summary">Summary</a></li>+ <li><a href="#tutorial">Tutorial</a></li>+ <li><a href="#findings">Findings</a></li>+ <li><a href="#recommendation">Recommendation</a></li>+ </ul>+ <div class="meta-block">+ Replace with project metadata, review date, or scope notes.+ </div>+ </aside>++ <main>+ <section class="panel hero" id="summary">+ <div class="eyebrow">Executive Summary</div>+ <h1>Use the hero for the clearest one-line judgment.</h1>+ <p class="lede">+ Replace this with the short explanation of what the contribution does, why it matters,+ and what the core maintainer question is.+ </p>+ <div class="badge-row">+ <span class="badge good">Strength</span>+ <span class="badge warn">Tradeoff</span>+ <span class="badge bad">Risk</span>+ </div>+ <div class="hero-grid">+ <div class="metric">+ <div class="label">Overall Call</div>+ <div class="value">Placeholder</div>+ </div>+ <div class="metric">+ <div class="label">Main Concern</div>+ <div class="value">Placeholder</div>+ </div>+ <div class="metric">+ <div class="label">Best Part</div>+ <div class="value">Placeholder</div>+ </div>+ <div class="metric">+ <div class="label">Weakest Part</div>+ <div class="value">Placeholder</div>+ </div>+ </div>+ <div class="quote">+ Use this block for the thesis, a sharp takeaway, or a key cited point.+ </div>+ </section>++ <section class="panel" id="tutorial">+ <h2>Tutorial Section</h2>+ <div class="two-col">+ <div class="card">+ <h3>Concept Card</h3>+ <p>Use cards for mental models, subsystems, or comparison slices.</p>+ <div class="ref">path/to/file.ts:10</div>+ </div>+ <div class="card">+ <h3>Second Card</h3>+ <p>Keep cards fairly dense. This template is about style, not fixed structure.</p>+ <div class="ref">path/to/file.ts:20</div>+ </div>+ </div>+ </section>++ <section class="panel" id="findings">+ <h2>Findings</h2>+ <article class="finding">+ <div class="severity high">High</div>+ <h3>Finding Title</h3>+ <p>Use findings for the sharpest judgment calls and risks.</p>+ <div class="ref">path/to/file.ts:30</div>+ </article>+ </section>++ <section class="panel" id="recommendation">+ <h2>Recommendation</h2>+ <div class="card-grid">+ <div class="card">+ <h3>Path Forward</h3>+ <p>Use this area for merge guidance, salvage plan, or rollout advice.</p>+ </div>+ <div class="card">+ <h3>What To Keep</h3>+ <p>Call out the parts worth preserving even if the whole proposal should not land.</p>+ </div>+ </div>+ </section>+ </main>+ </div>+ </body>+</html>diff --git a/skills/pr-report/references/style-guide.md b/skills/pr-report/references/style-guide.mdnew file mode 100644index 0000000000..35158d1adc--- /dev/null+++ b/skills/pr-report/references/style-guide.md@@ -0,0 +1,149 @@+# PR Report Style Guide++Use this guide when the user wants a report artifact, especially a webpage.++## Goal++Make the report feel like an editorial review, not an internal admin dashboard.+The page should make a long technical argument easy to scan without looking+generic or overdesigned.++## Visual Direction++Preferred tone:++- editorial+- warm+- serious+- high-contrast+- handcrafted, not corporate SaaS++Avoid:++- default app-shell layouts+- purple gradients on white+- generic card dashboards+- cramped pages with weak hierarchy+- novelty fonts that hurt readability++## Typography++Recommended pattern:++- one expressive serif or display face for major headings+- one sturdy sans-serif for body copy and UI labels++Good combinations:++- Newsreader + IBM Plex Sans+- Source Serif 4 + Instrument Sans+- Fraunces + Public Sans+- Libre Baskerville + Work Sans++Rules:++- headings should feel deliberate and large+- body copy should stay comfortable for long reading+- reference labels and badges should use smaller dense sans text++## Layout++Recommended structure:++- a sticky side or top navigation for long reports+- one strong hero summary at the top+- panel or paper-like sections for each major topic+- multi-column card grids for comparisons and strengths+- single-column body text for findings and recommendations++Use generous spacing. Long-form technical reports need breathing room.++## Color++Prefer muted paper-like backgrounds with one warm accent and one cool counterweight.++Suggested token categories:++- `--bg`+- `--paper`+- `--ink`+- `--muted`+- `--line`+- `--accent`+- `--good`+- `--warn`+- `--bad`++The accent should highlight navigation, badges, and important labels. Do not+let accent colors dominate body text.++## Useful UI Elements++Include small reusable styles for:++- summary metrics+- badges+- quotes or callouts+- finding cards+- severity labels+- reference labels+- comparison cards+- responsive two-column sections++## Motion++Keep motion restrained.++Good:++- soft fade/slide-in on first load+- hover response on nav items or cards++Bad:++- constant animation+- floating blobs+- decorative motion with no reading benefit++## Content Presentation++Even when the user wants design polish, clarity stays primary.++Good structure for long reports:++1. executive summary+2. what changed+3. tutorial explanation+4. strengths+5. findings+6. comparisons+7. recommendation++The exact headings can change. The important thing is to separate explanation+from judgment.++## References++Reference labels should be visually quiet but easy to spot.++Good pattern:++- small muted text+- monospace or compact sans+- keep them close to the paragraph they support++## Starter Usage++If you need a fast polished base, start from:++- `assets/html-report-starter.html`++Customize:++- fonts+- color tokens+- hero copy+- section ordering+- card density++Do not preserve the placeholder sections if they do not fit the actual report.