DottaandPaperclip 5498e8ba64 docs(skills): add maintenance bot setup workflow (#16279) ...

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents, skills, and routines support recurring repository
maintenance.
> - Setting up that work requires choices about the instance, agent,
credentials, repository, and trigger.
> - A repeatable setup procedure must preserve those choices and verify
saved configuration.
> - This pull request adds a skill that configures maintenance bots for
any selected maintenance task.
> - Each run creates useful PRs and revises them until required checks
pass.

## Linked Issues or Issue Description

Refs #16211 for the test-audit skill that can serve as one maintenance
task.

**Issue type**

Missing documentation.

**Where is the issue?**

The repository skill library lacks a procedure for setting up a code
maintenance agent and routine.

**What's wrong?**

Users must compose agent selection, skill delivery, scheduling,
workspace access, and PR follow-up themselves. The setup must also work
through the browser when API access fails.

**Suggested fix**

Add a standalone setup skill with API guidance and reusable
maintenance-run instructions. Support existing agents and new hires.
Support scheduled, webhook, and manual triggers.

## What Changed

- Add `setup-code-maintenance-bot` with instance and agent selection.
- Document harness, provider, AI account, repository, skill, and trigger
choices.
- Add API setup guidance, browser fallback, paused setup, and
saved-field verification.
- Add a generic run template with work limits, duplicate-PR checks, and
PR revision until current-head checks pass.
- Keep private run-to-PR mappings on Paperclip execution issues. Publish
internal references only when the target repository permits them.
- Add skill UI metadata.

## Verification

- Skill frontmatter validator passed.
- Relative links, JSON examples, UI metadata, and whitespace checks
passed.
- Compared API shapes and authorization rules with Paperclip source.
- No live agent or routine was created. No maintenance trial was run.
- Local application typecheck, Vitest, and build were not run for this
Markdown/YAML-only change.
- Repository CI and automated review will run on this PR.

## Risks

Low code risk. The change adds instructions and metadata only. API
details can differ by deployment. The skill requires discovery from the
selected instance and verification of saved settings before activation.
Browser setup must preserve the same permissions and approval rules.
Live setup remains untested.

## Model Used

OpenAI Codex, based on GPT-6, with repository inspection, tool use, and
file editing. The exact deployment model ID and context-window size are
not exposed in this session.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (skill/document validation;
application suites were not run)
- [x] I have added or updated tests where applicable (no application
behavior changed)
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-10-14 07:37:00 -05:00

..

paperclip-api.md

docs(skills): add maintenance bot setup workflow (#16279)

2026-10-14 07:37:00 -05:00

run-instructions.md

docs(skills): add maintenance bot setup workflow (#16279)

2026-10-14 07:37:00 -05:00