Files

T

Dotta 9eac727cf1 [codex] Add skills CLI and catalog management (#6782 )

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies through
company-scoped control-plane workflows.
> - Agents need reusable, inspectable skills that can be installed,
reset, audited, exported, and assigned without bespoke local setup.
> - The existing skill truth model needed cleanup so bundled skills,
optional catalog skills, runtime skills, and adapter-provided skills
have clear provenance.
> - Operators also need a practical CLI and board UI for discovering and
managing company skills.
> - This pull request adds the skills CLI, packaged skills catalog,
company skills APIs, and catalog-aware board UI.
> - The benefit is a more reusable Paperclip company setup where skills
are portable, auditable, and easier for operators and agents to manage.

## What Changed

- Added `paperclipai skills` CLI commands and coverage for catalog
listing, installing, resetting, and inspecting company skills.
- Added a packaged `@paperclipai/skills-catalog` workspace with bundled
and optional skill content plus validation/build tests.
- Added shared company-skill types and validators used across CLI,
server, and UI contracts.
- Added server catalog APIs/services for company skill catalog
operations, reset semantics, audit behavior, and portability provenance.
- Updated adapter skill handling so runtime/catalog provenance remains
explicit across local adapters.
- Added board UI support for browsing and managing catalog-backed
company skills.
- Updated docs for the skills CLI/catalog flow and the company skills
Paperclip skill reference.
- Rebased the branch onto current `paperclipai/paperclip:master`; no
`pnpm-lock.yaml`, `.github/workflows`, or migration files are included
in the final PR diff.

## Verification

- Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run
cli/src/__tests__/skills.test.ts
packages/skills-catalog/src/catalog-builder.test.ts
packages/skills-catalog/src/shipped-catalog.test.ts
packages/shared/src/validators/company-skill.test.ts
packages/adapter-utils/src/server-utils.test.ts
packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts
server/src/__tests__/company-skills-catalog-service.test.ts
server/src/__tests__/company-skills-routes.test.ts
server/src/__tests__/company-portability.test.ts`.
- Passed: `pnpm exec vitest run
server/src/__tests__/workspace-runtime.test.ts -t "default
branch|origin/master|symbolic-ref"`.
- Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four
provisioning tests failed while seeding an isolated worktree database
from the local Paperclip instance because the local plugin schema dump
contains a duplicate-column foreign key
(`plugin_content_machine_18a7bc327b.content_case_signals`). The
default-branch tests touched by the rebase conflict passed in the
focused run above.
- Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and
no migration-file changes relative to `master`.

## Risks

- Medium: this is a broad skills/catalog change touching CLI, server
APIs, shared contracts, adapter skill sync, and UI.
- Catalog validation and reset semantics need careful reviewer attention
because they affect reusable company setup and portability.
- No database migrations are included in this PR, so there is no
migration ordering/idempotency risk in the final diff.
- No lockfile is included by design; dependency resolution will be
handled by the repository lockfile workflow.

## Model Used

- OpenAI Codex coding agent based on GPT-5, running in Paperclip via the
`codex_local` adapter with shell, git, GitHub CLI, and code-editing tool
access. Exact hosted model build/context-window metadata is not exposed
in this runtime.

## 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 run targeted tests locally and documented the local
workspace-runtime seed failure above
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, screenshots were intentionally
omitted per PAP-10124 instructions; UI behavior is covered by tests and
reviewer inspection
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

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

2026-05-28 07:33:51 -10:00

4.3 KiB

Raw Blame History

name, description, key, recommendedForRoles, tags

name

description

key

recommendedForRoles

Release Announcement

Write the channel-appropriate announcement for a release without churn. Different surfaces need different shapes: a changelog entry is not a blog post is not a social card. The bar is: a reader of the chosen surface can decide in under 30 seconds whether this release affects them, and if so what to do.

When to use

A version, feature, or fix is shipping and needs writeup for at least one surface.
A previously private feature is going GA.
A breaking change needs broadcast before users hit it.

When not to use

An internal-only change with no user impact. Update internal docs; do not announce.
The release is incomplete (still in active development). Wait until it ships, even if marketing wants the post.

Determine the audience and channel first

Audience	Best channel	Tone
Existing power users	Changelog, in-app note	Terse, factual, links
Engineering teams adopting your API	Release notes, dev blog	Examples, migration steps, version pins
Prospective customers	Landing page, marketing blog	Story arc, problem → solution, social proof
Broad audience	Social post, email newsletter	One-sentence pitch, link to depth
Internal team	Slack/Discord post	What changed, who to ping if it breaks

Pick the audience for this writeup. One release often needs several writeups; do not blend them.

Universal structure

Whatever the channel, lead with:

What changed. One sentence in the user's vocabulary.
Who it affects. Which user role / use case.
What to do. Migrate now / opt-in / no action needed.

Everything else is depth that supports those three.

Channel templates

Changelog entry (terse)

## v1.42.0 — 2026-05-26

### Added
- <feature> — <one-line user benefit>. ([#1234](link))

### Changed
- <change> — <one-line impact>. ([#1235](link))

### Fixed
- <bug> — <one-line user-visible symptom>. ([#1236](link))

### Deprecated
- <thing>. Replaced by <thing>. Removal planned for v<x>.

### Breaking
- <change>. **Migration:** <one-line> or <link to guide>.

Release notes (for adopters)

Same as changelog, plus:

Migration guide section with before/after code.
Compatibility table (versions, runtimes, OS).
Known issues and workarounds.
Acknowledgements (contributors, reporters of fixed bugs).

Dev blog post (300–800 words)

Hook (1 paragraph): the problem the release solves, in a real-world scenario.
What's new (3–5 bullets with sub-paragraphs): features, with one code or screenshot example each.
Upgrade (1 paragraph): how to upgrade, what to check.
What's next: one sentence about the next direction. Avoid promises.

In-app note

1 sentence.
1 link.
Dismiss after seen.

1 sentence pitch.
1 link.
1 image or short clip.
No threadbait. If it needs a thread, write a blog post instead.

Writing rules

Lead with the user, not the team. You can now export to CSV beats We've added CSV export.
Numbers beat adjectives. 60% faster cold start beats much faster. Cite the methodology.
Show, don't just tell. One code snippet, one screenshot — more is noise.
Date the post. Undated release content rots fastest.
Link the migration path explicitly. Do not bury it.
Mark breaking changes with **Breaking:** prefix. Repeat in the email/social channel.

Avoid

"We are excited to announce" filler.
Lists of changes that mix user-visible and internal items.
Marketing claims without a way to verify.
Promised dates for unshipped work.
Pre-announcing something the team has not yet committed to ship.

Post-publish checklist

Changelog is in source control alongside the release.
Blog post date matches actual ship date.
All links work (release tag, PRs, docs sections).
Breaking changes are also in the upgrade guide, not only the post.
Internal team is notified before the public post goes live, not after.

4.3 KiB Raw Blame History Unescape Escape