Dotta
9eac727cf1
## 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>
134 lines
3.5 KiB
Markdown
134 lines
3.5 KiB
Markdown
---
|
|
title: Control-Plane Commands
|
|
summary: Issue, agent, approval, and dashboard commands
|
|
---
|
|
|
|
Client-side commands for managing issues, agents, approvals, and more.
|
|
|
|
## Issue Commands
|
|
|
|
```sh
|
|
# List issues
|
|
pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
|
|
|
|
# Get issue details
|
|
pnpm paperclipai issue get <issue-id-or-identifier>
|
|
|
|
# Create issue
|
|
pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
|
|
|
|
# Update issue
|
|
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
|
|
|
|
# Add comment
|
|
pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
|
|
|
|
# Checkout task
|
|
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>
|
|
|
|
# Release task
|
|
pnpm paperclipai issue release <issue-id>
|
|
```
|
|
|
|
## Company Commands
|
|
|
|
```sh
|
|
pnpm paperclipai company list
|
|
pnpm paperclipai company get <company-id>
|
|
|
|
# Export to portable folder package (writes manifest + markdown files)
|
|
pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents
|
|
|
|
# Preview import (no writes)
|
|
pnpm paperclipai company import \
|
|
<owner>/<repo>/<path> \
|
|
--target existing \
|
|
--company-id <company-id> \
|
|
--ref main \
|
|
--collision rename \
|
|
--dry-run
|
|
|
|
# Apply import
|
|
pnpm paperclipai company import \
|
|
./exports/acme \
|
|
--target new \
|
|
--new-company-name "Acme Imported" \
|
|
--include company,agents
|
|
```
|
|
|
|
## Agent Commands
|
|
|
|
```sh
|
|
pnpm paperclipai agent list
|
|
pnpm paperclipai agent get <agent-id>
|
|
```
|
|
|
|
## Skills Commands
|
|
|
|
```sh
|
|
# Browse app-shipped catalog skills without changing company state
|
|
pnpm paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
|
|
pnpm paperclipai skills search "pull request" [--json]
|
|
|
|
# Inspect catalog metadata and file inventory before install
|
|
pnpm paperclipai skills inspect github-pr-workflow
|
|
|
|
# Install a catalog skill into the company skill library
|
|
# This does not attach the skill to any agent.
|
|
pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
|
|
pnpm paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
|
|
|
|
# External sources still use import instead of catalog install
|
|
pnpm paperclipai skills import ./skills/my-skill --company-id <company-id>
|
|
pnpm paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
|
|
|
|
# Attach desired company skills to an agent after install/import
|
|
pnpm paperclipai skills agent sync <agent-id> --skill github-pr-workflow --company-id <company-id>
|
|
```
|
|
|
|
## Approval Commands
|
|
|
|
```sh
|
|
# List approvals
|
|
pnpm paperclipai approval list [--status pending]
|
|
|
|
# Get approval
|
|
pnpm paperclipai approval get <approval-id>
|
|
|
|
# Create approval
|
|
pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
|
|
|
|
# Approve
|
|
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
|
|
|
|
# Reject
|
|
pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
|
|
|
|
# Request revision
|
|
pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
|
|
|
|
# Resubmit
|
|
pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']
|
|
|
|
# Comment
|
|
pnpm paperclipai approval comment <approval-id> --body "..."
|
|
```
|
|
|
|
## Activity Commands
|
|
|
|
```sh
|
|
pnpm paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
|
|
```
|
|
|
|
## Dashboard
|
|
|
|
```sh
|
|
pnpm paperclipai dashboard get
|
|
```
|
|
|
|
## Heartbeat
|
|
|
|
```sh
|
|
pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
|
|
```
|