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.4 KiB

Raw Blame History

name, description, key, recommendedForRoles, tags

name

description

key

recommendedForRoles

Doc Maintenance

Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".

When to use

A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
A user-reported bug traced back to outdated documentation.
A release is being cut and the docs need a pass against the merged commits.
A new feature shipped but only the engineer's PR description describes how to use it.

When not to use

The change is internal-only (private helper rename, refactor) with no user-visible impact.
You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.

The pass

Establish the baseline. Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
Enumerate user-visible changes. Read commits and PR descriptions. List, for each change, what a user can now do differently.
Map changes to docs. For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
Update precisely. Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
Add new entries where needed. New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
Update examples and snippets. Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
Write the release note. One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
Cross-check. Search the docs for the old behavior wording and remove or update stragglers.

Style baseline

Voice: second person ("you can pass --json to ..."). Avoid "we" except in narrative pages.
Tense: present, not future. The behavior exists once shipped.
Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
Code blocks: include the language tag so syntax highlighting works.
Cross-links: link the first mention of a concept on each page; do not link every occurrence.
Avoid promising future behavior. If something is unreleased, mark it experimental or omit it.

Drift detection

A doc page is drifting if any of these are true:

It documents a flag, key, or endpoint that no longer exists.
An example does not run as written.
A default value in the docs does not match the code.
A supported-versions list excludes a version the project actually supports, or includes one it dropped.
A "Coming soon" section references a feature that shipped or was cancelled.

When you find drift, fix it in the same pass and note it in the release note's Fixed group.

Release-note rules

One sentence per item. If two sentences are needed, the item is likely two items.
User impact first, internal cause second. Faster cold start (avoid full bundle download on first run) beats Refactor bootstrap loader.
Link the PR for engineering readers and the docs page for users.
Mark breaking changes explicitly: **Breaking:** prefix. Include migration steps inline or via link.

Anti-patterns

Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
"Updated docs" commit messages with no detail. Make the commit say what changed and why.
Adding to the changelog without updating the reference docs the changelog points to.
Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.

4.4 KiB Raw Blame History