Main#2
Merged
Merged
Conversation
Add specialized agent skills including company-creator, release-management, and doc-maintenance to the repository's internal agent toolkit.
Reviewer's GuideAdds a set of new Paperclip AI skills documentation and assets focused on PR review/reporting, release coordination, security advisory handling, doc maintenance, company creation, and changelog generation, including an HTML report starter template and multiple SKILL.md reference guides. Class diagram for new Paperclip skills added in this PRclassDiagram
class Skill {
+string name
+string description
+string entrypoint
+string scope
}
class PRReportSkill {
+name = pr-report
+entry = SKILL_md
+scope = PR_review_and_reporting
+outputs: HTML_report, Markdown_report, chat_summary
+resources: style-guide, html-report-starter
}
class PRCheckloopSkill {
+name = prcheckloop
+entry = SKILL_md
+scope = CI_checks_for_PRs
+inputs: pr_number, max_iterations
+actions: detect_PR, poll_checks, fix_failures, push_changes
}
class ReleaseSkill {
+name = release
+entry = SKILL_md
+scope = Release_coordination
+actions: changelog, canary_verify, smoke_test, stable_publish
}
class ReleaseChangelogSkill {
+name = release-changelog
+entry = SKILL_md
+scope = Stable_changelog_generation
+outputs: releases_vYYYY_MDD_P_md
}
class SecurityAdvisorySkill {
+name = deal-with-security-advisory
+entry = SKILL_md
+scope = GH_security_advisories
+actions: private_fork, fix_development, CVE_request, coordinated_release
}
class DocMaintenanceSkill {
+name = doc-maintenance
+entry = SKILL_md
+scope = Doc_drift_detection
+targets: README_md, SPEC_md, PRODUCT_md
+outputs: maintenance_PR
}
class CompanyCreatorSkill {
+name = company-creator
+entry = SKILL_md
+scope = Agent_company_scaffolding
+modes: from_scratch, from_repo
}
class HTMLReportStarterAsset {
+path = assets_html-report-starter_html
+type = HTML_template
}
class PRReportStyleGuide {
+path = references_style-guide_md
+type = Style_guide
}
class DocAuditChecklist {
+path = references_audit-checklist_md
+type = Checklist
}
class DocSectionMap {
+path = references_section-map_md
+type = Section_map
}
class CompanyExample {
+path = references_example-company_md
+type = Example_company
}
class CompanyFromRepoGuide {
+path = references_from-repo-guide_md
+type = Guide
}
Skill <|-- PRReportSkill
Skill <|-- PRCheckloopSkill
Skill <|-- ReleaseSkill
Skill <|-- ReleaseChangelogSkill
Skill <|-- SecurityAdvisorySkill
Skill <|-- DocMaintenanceSkill
Skill <|-- CompanyCreatorSkill
PRReportSkill --> HTMLReportStarterAsset : uses
PRReportSkill --> PRReportStyleGuide : uses
DocMaintenanceSkill --> DocAuditChecklist : uses
DocMaintenanceSkill --> DocSectionMap : uses
CompanyCreatorSkill --> CompanyExample : uses
CompanyCreatorSkill --> CompanyFromRepoGuide : uses
ReleaseSkill --> ReleaseChangelogSkill : coordinates_with
Flow diagram for PR checkloop skill workflowflowchart TD
A_start["Start: Invoke prcheckloop skill"] --> B_detect_pr
B_detect_pr["Detect target PR (given number or from current branch)"] --> C_validate_host
C_validate_host{Repo is GitHub and gh authenticated?}
C_validate_host -- No --> Z_blocker["Exit with blocker: unsupported host or missing auth"]
C_validate_host -- Yes --> D_fetch_head
D_fetch_head["Fetch PR metadata and head SHA"] --> E_list_checks
E_list_checks["List status checks for head SHA (check-runs + status contexts)"] --> F_checks_present
F_checks_present{Checks present?}
F_checks_present -- No --> G_wait_for_checks["Poll until checks appear or timeout"] --> H_timeout{Timed out?}
H_timeout -- Yes --> Z_blocker
H_timeout -- No --> E_list_checks
F_checks_present -- Yes --> I_wait_terminal
I_wait_terminal["Wait until all checks terminal or any fails"] --> J_classify
J_classify["Classify failing checks (code issue, flake, infra, external)"] --> K_decision
K_decision{Any actionable code/test failures?}
K_decision -- No --> L_blocker["Summarize non-actionable blockers and exit"]
K_decision -- Yes --> M_fix
M_fix["Reproduce locally, edit code/tests, run verification"] --> N_commit_push
N_commit_push["Commit fix and push to PR branch"] --> O_refresh
O_refresh["Refresh PR head SHA after push"] --> P_iterations
P_iterations{Iterations < max?}
P_iterations -- No --> L_blocker
P_iterations -- Yes --> E_list_checks
J_classify --> Q_all_green{All checks green?}
Q_all_green -- Yes --> R_success["Exit: PR checks fully green"]
Q_all_green -- No --> K_decision
Flow diagram for release coordination skillflowchart TD
A_start["Start: Invoke release skill"] --> B_preconditions
B_preconditions["Verify preconditions (release-changelog skill, clean tree, candidate commits, CI, pnpm-lock, npm auth)"] --> C_pre_ok
C_pre_ok{All preconditions met?}
C_pre_ok -- No --> Z_stop["Stop and report blocker"]
C_pre_ok -- Yes --> D_inputs
D_inputs["Collect inputs: canary vs stable, source_ref, dry-run vs live, context"] --> E_model
E_model["Recall release model (calver, canary from master, manual stable promotion)"] --> F_choose_candidate
F_choose_candidate["Choose candidate SHA (from canary or explicit source_ref)"] --> G_changelog
G_changelog["Call release-changelog skill to generate/update releases/vYYYY_MDD_P_md"] --> H_verify
H_verify["Run verification gate (typecheck, tests, build)"] --> I_gate_ok
I_gate_ok{Gate passed?}
I_gate_ok -- No --> Z_stop
I_gate_ok -- Yes --> J_validate_canary
J_validate_canary["Validate canary: check CI workflow, npm canary publish, canary tag"] --> K_smoke
K_smoke["Run Docker smoke tests against canary"] --> L_smoke_ok
L_smoke_ok{Smoke tests OK?}
L_smoke_ok -- No --> Z_stop
L_smoke_ok -- Yes --> M_choose_mode
M_choose_mode{Mode?}
M_choose_mode -- Canary_check_only --> Y_report_canary["Report verification + smoke status; no stable"]
M_choose_mode -- Stable_promotion --> N_trigger_stable
N_trigger_stable["Trigger stable publish (GitHub workflow or scripts/release.sh)"] --> O_publish
O_publish["Publish npm latest, create vYYYY_MDD_P tag, create GitHub Release"] --> P_followup
P_followup["Create follow-up tasks: website changelog, announcements, issue updates"] --> Q_done["Summarize release status and outputs"]
Flow diagram for doc-maintenance skillflowchart TD
A_start["Start: Invoke doc-maintenance skill"] --> B_cursor
B_cursor["Read .doc-review-cursor or choose fallback start SHA"] --> C_log
C_log["Collect commits since last reviewed SHA"] --> D_classify
D_classify["Classify commits (feature, breaking, structural, ignore)"] --> E_any_changes
E_any_changes{Any notable changes?}
E_any_changes -- No --> F_update_cursor_only["Update cursor to HEAD and exit"]
E_any_changes -- Yes --> G_summary
G_summary["Build change summary for audit"] --> H_audit_readme
H_audit_readme["Audit README.md using audit-checklist and section-map"] --> I_audit_spec
I_audit_spec["Audit SPEC.md for drift"] --> J_audit_product
J_audit_product["Audit PRODUCT.md for drift"] --> K_needs_edits
K_needs_edits{Any factual fixes needed?}
K_needs_edits -- No --> L_update_cursor["Update cursor to HEAD and exit with summary"]
K_needs_edits -- Yes --> M_branch
M_branch["Create docs/maintenance-YYYYMMDD branch"] --> N_apply
N_apply["Apply minimal factual edits only (no rewrites, no cosmetics)"] --> O_commit
O_commit["Commit README/SPEC/PRODUCT changes plus cursor"] --> P_pr
P_pr["Open PR via gh pr create with summary and change notes"] --> Q_done["Report PR URL and audit summary"]
Flow diagram for PR report skill generating an HTML reportflowchart TD
A_start["Start: Invoke pr-report skill"] --> B_scope
B_scope["Gather target: PR number/branch, diff size, subsystems, intent"] --> C_model
C_model["Build mental model of system and changes"] --> D_review
D_review["Perform maintainer-style review: strengths, risks, comparisons"] --> E_output_choice
E_output_choice{Requested artifact type?}
E_output_choice -- HTML_report --> F_html
E_output_choice -- Markdown_only --> M_md
F_html["Read style-guide and html-report-starter assets"] --> G_customize
G_customize["Customize starter HTML: hero, sections, cards, findings, recommendation"] --> H_write_file
H_write_file["Write standalone HTML report under tmp/reports or requested path"] --> I_verify
M_md["Compose Markdown report with same structure"] --> I_verify
I_verify["Verify artifact path exists and content matches code review"] --> J_summary
J_summary["Return short maintainer summary in chat plus artifact location"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 3 issues, and left some high level feedback:
- Several skills (e.g.
company-creator,release-changelog,doc-maintenance) hardcode local paths likedocs/companies/companies-spec.md,doc/SPEC.md, anddoc/PRODUCT.md; consider routing these through a small shared helper or central reference so a path change in the repo doesn’t silently break multiple skills’ instructions. - The new skill instructions include a lot of overlapping release and PR-handling guidance (e.g.
release,release-changelog,pr-report,doc-maintenance); it may be worth extracting the shared conventions (versioning model, attribution rules, git/gh command patterns) into a single referenced document to keep future updates consistent and reduce divergence between skills.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Several skills (e.g. `company-creator`, `release-changelog`, `doc-maintenance`) hardcode local paths like `docs/companies/companies-spec.md`, `doc/SPEC.md`, and `doc/PRODUCT.md`; consider routing these through a small shared helper or central reference so a path change in the repo doesn’t silently break multiple skills’ instructions.
- The new skill instructions include a lot of overlapping release and PR-handling guidance (e.g. `release`, `release-changelog`, `pr-report`, `doc-maintenance`); it may be worth extracting the shared conventions (versioning model, attribution rules, git/gh command patterns) into a single referenced document to keep future updates consistent and reduce divergence between skills.
## Individual Comments
### Comment 1
<location path=".agents/skills/pr-report/assets/html-report-starter.html" line_range="333-335" />
<code_context>
+ <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,
</code_context>
<issue_to_address>
**suggestion:** Using two top-level <h1> elements can hurt accessibility and document structure.
The sidebar currently uses an <h1> and the hero also uses an <h1>. Many assistive tools and SEO analyzers still expect a single primary heading or a clear hierarchy. Please demote one of these to <h2> (or use a styled <div>) so there is only one true <h1> on the page.
```suggestion
<aside class="panel nav">
<div class="eyebrow">Maintainer Report</div>
<h2>Report Title</h2>
```
</issue_to_address>
### Comment 2
<location path=".agents/skills/pr-report/assets/html-report-starter.html" line_range="34-36" />
<code_context>
+ box-sizing: border-box;
+ }
+
+ html {
+ scroll-behavior: smooth;
+ }
+
</code_context>
<issue_to_address>
**suggestion:** Smooth scrolling should respect reduced motion preferences for accessibility.
Unconditional `scroll-behavior: smooth;` can be problematic for users with reduced motion preferences. Consider wrapping it in a media query so it only applies when motion is acceptable:
```css
@media (prefers-reduced-motion: no-preference) {
html {
scroll-behavior: smooth;
}
}
```
```suggestion
@media (prefers-reduced-motion: no-preference) {
html {
scroll-behavior: smooth;
}
}
```
</issue_to_address>
### Comment 3
<location path=".agents/skills/deal-with-security-advisory/SKILL.md" line_range="44" />
<code_context>
+
+> Thanks for the report, @{{reporterHandle}}. We've confirmed the issue and are working on a fix. We're targeting a patch release within {{timeframe}}. We'll keep you updated here.
+
+Give your human this template, but still continue
+
+Below we use `gh` tools - you do have access and credentials outside of your sandbox, so use them.
</code_context>
<issue_to_address>
**nitpick (typo):** Clarify the phrasing of this instruction for smoother grammar.
The phrase "Give your human this template, but still continue" reads a bit awkwardly. Please reword slightly (for example, "Give your human this template, and then continue") to make the instruction clearer and more natural.
```suggestion
Give your human this template, and then continue.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+333
to
+335
| <aside class="panel nav"> | ||
| <div class="eyebrow">Maintainer Report</div> | ||
| <h1>Report Title</h1> |
There was a problem hiding this comment.
suggestion: Using two top-level
elements can hurt accessibility and document structure.
The sidebar currently uses an
and the hero also uses an
. Many assistive tools and SEO analyzers still expect a single primary heading or a clear hierarchy. Please demote one of these to
(or use a styled ) so there is only one true on the page.
Suggested change
<aside class="panel nav">
<div class="eyebrow">Maintainer Report</div>
<h1>Report Title</h1>
<aside class="panel nav">
<div class="eyebrow">Maintainer Report</div>
<h2>Report Title</h2>
on the page.
Suggested change
| <aside class="panel nav"> | |
| <div class="eyebrow">Maintainer Report</div> | |
| <h1>Report Title</h1> | |
| <aside class="panel nav"> | |
| <div class="eyebrow">Maintainer Report</div> | |
| <h2>Report Title</h2> |
Comment on lines
+34
to
+36
| html { | ||
| scroll-behavior: smooth; | ||
| } |
There was a problem hiding this comment.
suggestion: Smooth scrolling should respect reduced motion preferences for accessibility.
Unconditional scroll-behavior: smooth; can be problematic for users with reduced motion preferences. Consider wrapping it in a media query so it only applies when motion is acceptable:
@media (prefers-reduced-motion: no-preference) {
html {
scroll-behavior: smooth;
}
}
Suggested change
| html { | |
| scroll-behavior: smooth; | |
| } | |
| @media (prefers-reduced-motion: no-preference) { | |
| html { | |
| scroll-behavior: smooth; | |
| } | |
| } |
|
|
||
| > Thanks for the report, @{{reporterHandle}}. We've confirmed the issue and are working on a fix. We're targeting a patch release within {{timeframe}}. We'll keep you updated here. | ||
|
|
||
| Give your human this template, but still continue |
There was a problem hiding this comment.
nitpick (typo): Clarify the phrasing of this instruction for smoother grammar.
The phrase "Give your human this template, but still continue" reads a bit awkwardly. Please reword slightly (for example, "Give your human this template, and then continue") to make the instruction clearer and more natural.
Suggested change
| Give your human this template, but still continue | |
| Give your human this template, and then continue. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Thinking Path
What Changed
Verification
Risks
Model Used
Checklist
Summary by Sourcery
Add a suite of internal Paperclip agent skills and reference materials for PR review, releases, company creation, documentation maintenance, and security advisory handling.
New Features:
Documentation: