Files

T

Dotta fff3832a01 [codex] Add teams catalog extraction (#7550 )

Fixes #7551

## Thinking Path

> - Paperclip is the control plane for AI-agent companies, and reusable
company/team setup is part of making those companies faster to launch.
> - The teams catalog work introduces app-shipped team templates that
can be browsed, previewed, and installed into a company.
> - Catalog installation crosses several contracts: bundled package
contents, shared API types, server import/install behavior, CLI
workflows, and the board UI.
> - Agents also need a safe path through catalog installs: scoped
company selection, explicit source policy, approval fallback for agent
creation, and preserved catalog provenance.
> - This pull request extracts the completed teams catalog branch into
one reviewable PR on top of `public-gh/master`.
> - The benefit is a reusable teams catalog foundation with server, CLI,
package, docs, and hidden UI surfaces kept in sync.

## What Changed

- Added the `@paperclipai/teams-catalog` package with bundled/optional
team definitions, generated manifest, validators, catalog builder tests,
and migration notes.
- Added shared teams catalog types/validators plus server routes and
services for listing, previewing, and installing catalog teams.
- Integrated catalog install with company portability, skill/source
policy checks, provenance metadata, origin hashes, target-manager
reparenting, and installed/out-of-date detection.
- Added CLI `teams` commands and agent-safe company selection behavior,
including `company current` and approval fallback for forbidden
agent-run installs.
- Added hidden Team Catalog UI/API/query surfaces, Storybook fixtures,
and targeted UI tests while keeping the UI route out of primary
navigation.
- Added docs for CLI/company/teams catalog behavior and removed
generated screenshot artifacts from the PR diff.

## Verification

- `pnpm exec vitest run cli/src/__tests__/company.test.ts
cli/src/__tests__/teams.test.ts
packages/teams-catalog/src/catalog-builder.test.ts
packages/teams-catalog/src/shipped-catalog.test.ts
server/src/__tests__/agent-permissions-service.test.ts
server/src/__tests__/company-portability.test.ts
server/src/__tests__/company-skills-service.test.ts
server/src/__tests__/teams-catalog-routes.test.ts
server/src/__tests__/teams-catalog-service.test.ts
server/src/__tests__/teams-catalog-install-no-overrides.test.ts
ui/src/lib/company-routes.test.ts ui/src/pages/TeamCard.test.tsx
ui/src/pages/TeamCatalog.test.tsx
ui/src/pages/useInstallTeamCatalogEntry.test.tsx`
- `pnpm --filter @paperclipai/shared typecheck && pnpm --filter
@paperclipai/teams-catalog typecheck && pnpm --filter paperclipai
typecheck && pnpm --filter @paperclipai/server typecheck && pnpm
--filter @paperclipai/ui typecheck`
- Confirmed branch is rebased onto `public-gh/master` (`78dc3625a`) and
`public-gh/master` is an ancestor of `HEAD`.
- Confirmed PR diff excludes `pnpm-lock.yaml`, `.github/workflows/*`,
generated screenshot images, and screenshot helper scripts.

## Risks

- Medium review surface: this crosses package generation, shared
contracts, server install behavior, CLI, docs, and hidden UI code.
- Catalog install behavior creates agents/projects/tasks/skills and must
keep company scoping, permissions, source policy, and provenance checks
strict.
- `pnpm-lock.yaml` is intentionally excluded per repo policy;
CI/default-branch automation owns lockfile refresh.
- The Team Catalog UI is included but hidden from primary navigation, so
future enablement should re-check visual QA before exposure.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
>
> ROADMAP checked: this aligns with reusable companies/templates and
plugin-adjacent onboarding work. This PR packages work already developed
on the Paperclip task branch for review.

## Model Used

- OpenAI Codex, GPT-5 series coding agent in this Paperclip session;
exact runtime context window was not exposed. Used shell, git, `gh`, and
local test/typecheck tooling.

## 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 tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots, or documented why screenshots are intentionally omitted
- [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>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-05 12:55:49 -05:00

6.4 KiB

Raw Blame History

Teams Catalog Migration Notes

This document records the migration state of the initial bundled and optional teams shipped in @paperclipai/teams-catalog. It exists so future contributors know what was intentionally deferred, what is safe to delete from legacy sources, and which compatibility tests must land before the legacy onboarding assets can be removed.

The approved plan for this package lives at PAP-10206 plan document.

Status

Source	Status
`server/src/onboarding-assets/ceo/`	Keep as-is. Drives current onboarding default agent creation. Will be removed only when onboarding switches to the teams-catalog service (post-Phase E/G).
`server/src/onboarding-assets/default/`	Keep as-is. Generic `AGENTS.md` fallback used outside the catalog path.
`skills/paperclip-create-agent/references/agents/coder.md`	Migrated content into `bundled/software-development/product-engineering/agents/senior-coder/AGENTS.md` (collaboration/handoffs/safety sections collapsed for catalog brevity). Keep the template as a reference for ad-hoc hiring until onboarding switches.
`skills/paperclip-create-agent/references/agents/qa.md`	Migrated content into both `bundled/company-defaults/core-exec-team/agents/qa/AGENTS.md` and `bundled/software-development/product-engineering/agents/qa/AGENTS.md`. Keep the template.
`skills/paperclip-create-agent/references/agents/uxdesigner.md`	Migrated content into `bundled/product/product-design/agents/ux-designer/AGENTS.md`. Lens dictionary intentionally trimmed in the catalog copy — the template stays authoritative for ad-hoc hiring.
`skills/paperclip-create-agent/references/agents/securityengineer.md`	Not migrated. No `SecurityEngineer` team ships in Phase H — see deferred entries below.

Bundled entries shipped in Phase H

paperclipai/bundled/company-defaults/core-exec-team — defaults: CEO, CTO, QA, starter project, recurring CEO heartbeat task. defaultInstall: true. This is the smallest team that mirrors the historical CEO onboarding flow while staying inside catalog rules.
paperclipai/bundled/software-development/product-engineering — optional engineering pod: CTO, Senior Coder, QA, weekly engineering sync routine.
paperclipai/bundled/product/product-design — single-designer product design team with wireframe, design-critique, and weekly design review routine.

Optional entries shipped in Phase H

paperclipai/optional/content/content-machine — vendored local content-calendar skill, single content lead, recurring weekly content review. Kept from Phase B as the canonical fixture for local-skill resolution.

Intentionally deferred

The plan in PAP-10206 lists additional recommended entry classes that are not part of the Phase H catalog. They wait on:

optional/ops/cloud-operations — needs a CloudOpsEngineer role template under skills/paperclip-create-agent/references/agents/ first, plus an explicit security review of the deployment/secrets routines it implies. Defer until a follow-up curation pass.
optional/research/benchmark-quality — needs a benchmark/evals/forensics role template and concrete starter routines from a real benchmark engagement. Defer until that engagement exists.
optional/quality/security-review — could wrap the existing securityengineer.md template, but the plan's Phase D security review of external-source handling has to land before bundling a security-focused team with default skill imports. Defer until Phase D is complete.
Adapter overrides per agent — intentionally omitted from frontmatter so the import preview lets operators choose claude_local, codex_local, etc. at install time. Lock these only when onboarding adopts the catalog and needs a deterministic default.
Rich persona files (SOUL.md, HEARTBEAT.md, TOOLS.md siblings) — collapsed into a single AGENTS.md per agent for Phase H. Move to references/ files if the importer learns to surface them as agent reference attachments without changing trust level.
Bundled executable scripts (for example, prebuilt installer hooks) — explicitly out of scope. The shipped-catalog.test.ts enforces markdown_only / assets trust for every shipped team until Phase D security review covers script-bearing entries.

Compatibility tests required before deleting legacy sources

Before removing server/src/onboarding-assets/ceo/ or the skills/paperclip-create-agent/references/agents/*.md templates, the following tests should be in place. None are written yet — they are tracked here so a future remove-legacy issue does not skip them:

Onboarding parity test — a server-level integration test that runs the current onboarding flow on a fresh company and verifies the resulting agent/project/task tree is byte-equivalent (modulo timestamps and ids) to a paperclipai/bundled/company-defaults/core-exec-team install via the catalog service.
Slug stability test — covers that the agent slugs ceo, cto, qa keep stable values when reparenting under an existing target manager, so downstream UI links don't churn.
Skill resolution drift test — fails if a bundled team's requiredSkills references a catalog skill key that no longer exists in the latest @paperclipai/skills-catalog manifest.
Adapter default fallback test — confirms that imported agents with no explicit adapterType pick up the same adapter the legacy onboarding path used.
Routine import compatibility test — recurring TASK.md entries (first-heartbeat, weekly-engineering-sync, weekly-design-review, weekly-content-review) must still be imported with timer heartbeats disabled, matching current portability behavior.

Coordination

Packaging-level changes (adding new manifest fields, changing the validation rules, or extending the import service) belong to the coding owner of PAP-10236 and the integration service in PAP-10238.
Content-only updates (new bundled or optional teams, copy edits, skill requirement tweaks) can land directly in this package after pnpm --filter @paperclipai/teams-catalog validate and pnpm --filter @paperclipai/teams-catalog test both pass.
Removing any file under server/src/onboarding-assets/ requires the compatibility tests above to land first and is gated by the onboarding-service switchover task tracked under the same parent goal.

6.4 KiB Raw Blame History