0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-06 21:05:21 +02:00

Files

T

DottaandPaperclip 862a5758ba fix(agents): reduce hiring templates to role descriptions (#14985 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work.
> - New agents receive role instructions from onboarding, the hiring skill, or a team package.
> - These sources repeat harness procedures and impose generic work policies.
> - They can crowd out the task and the harness instructions.
> - This pull request reduces those sources to short role descriptions.
> - It preserves configuration, skills, authentication, reporting lines, and approval controls.
> - The benefit is less repeated instruction text with explicit coverage for the default hiring path.

## Linked Issues or Issue Description

Refs #3307. The CEO template can impose a fixed delegation route instead of letting the agent choose how to fulfill the request. This change removes that route. It does not implement autonomous goal selection.

Related work: #14920 preserves stock Codex base instructions. #14948 reduces the generic manual and shared runtime prompts. #14961 improves native completion-tool descriptions. This PR is separate from those changes.

## What Changed

- Select only the short CEO `AGENTS.md` for new default CEO bundles. Keep the three former companion files as compatibility assets.
- Reduce the first-agent chief-of-staff prompt and coder, QA, UX, and security role examples.
- Reduce seven bundled team role bodies. Preserve their role, reporting, and skill metadata. Regenerate the catalog.
- Make hiring examples optional. Replace the long generic role manual with short role drafting guidance. Preserve explicit requester instructions.
- Add configuration and import coverage for native and legacy managed bundles, custom instructions, first-agent rendering, and catalog contents.
- Add an explicit-only hiring eval that starts from the production CEO default and checks one coder hire, independently computed JSON output, saved instructions, and worker reuse.
- Include the full prompt comparison and a separate three-request drafting simulation. Neither is a live provider comparison.

Prompt differences: [before and after](doc/plans/2026-10-02-hiring-template-prompt-diff.md). The CEO default falls from 1,897 to 20 words. The coder example falls from 652 to 18 words. Word counts describe instruction size, not outcome quality or billing.

## Verification

- PASS: 99 focused server tests and eight shipped-catalog tests.
- PASS: catalog generation and validation for four shipped teams.
- PASS: hiring skill validation.
- PASS: `pnpm -r typecheck`.
- PASS: `pnpm build`.
- INCOMPLETE: the full local `pnpm test:run` was stopped before rebase. Its original log is retained. This is not a completed full-suite pass. The full current-head GitHub CI workflow passed: https://github.com/paperclipai/paperclip/actions/runs/37073372419.
- PASS: `pnpm test:e2e:runner:typecheck` and `pnpm test:e2e:runner:unit` (63 files / 843 tests).
- PASS: discovery for the two new hiring cells, 50 existing everyday cells, and the full 438-cell catalog.
- PASS after rebase: 99 server tests, 11 catalog tests, 62 selected E2E support tests, and the E2E typecheck.
- PASS: all current-head PR checks at `57dcee147ed0b2d2e3cc657cd9e50fb16bf9ec25`: 51 successful check runs, two intentional Storybook skips, and successful Snyk status. Fresh Greptile is 5/5 with zero unresolved threads.
- PENDING follow-up: matched live hiring runs on frozen integration refs. No live outcome-quality or non-regression result is claimed from the configuration checks or this merge.

The new suite has two local native cells: Codex and ACPX Claude. It expects five provider turns per cell. It compares source-derived bundles, so the historical long templates remain admissible. Missing successful source-read receipts make a pair uncomparable. They do not establish a behavior regression or equivalence.

## Risks

- New default roles have fewer prescribed procedures. Live checks must determine whether a removed instruction was needed for an outcome.
- Existing custom and saved bundles keep their contents. The retained companion assets avoid a source-file compatibility break.
- Specialized Summarizer, Reflection Coach, and Wiki Maintainer prompts remain unchanged. Their product contracts need separate review.
- The generic non-CEO fallback reduction is in #14948. This PR alone does not provide its eight-word fallback.
- Configuration tests and drafting simulations do not establish live outcome quality. QA, UX, security, and chief-of-staff hiring behavior remain outside the new two-cell comparison.

> 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`.

## Model Used

OpenAI Codex, based on GPT-6, with reasoning, code editing, shell tools, and delegated verification. The runtime does not expose the exact deployment model ID or context-window size.

## 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
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] 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-02 17:56:42 -05:00

6.6 KiB

Raw Permalink 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 compatibility assets. New default CEO hires receive only the short `AGENTS.md`. The legacy `HEARTBEAT.md`, `SOUL.md`, and `TOOLS.md` remain on disk but are not selected into new default bundles. Existing managed/custom bundles are not rewritten. The directory can be removed 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`	Short role description mirrored in `bundled/software-development/product-engineering/agents/senior-coder/AGENTS.md` (runtime procedures come from the harness, repository instructions, and installed skills). Keep the template as a reference for ad-hoc hiring until onboarding switches.
`skills/paperclip-create-agent/references/agents/qa.md`	Short role description mirrored in 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`	Short role description mirrored in `bundled/product/product-design/agents/ux-designer/AGENTS.md`. Both copies describe role responsibility without a default lens dictionary.
`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.6 KiB Raw Permalink Blame History