mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-16 05:17:41 +02:00
DottaandPaperclip
5e8e992df2
## Thinking Path > - Paperclip helps people manage AI agents and their work. > - The feature map describes user capabilities and verification recipes. > - Storybook holds isolated examples of those capabilities. > - Missing catalog links can hide existing examples. > - Some stories also expose shipped capabilities absent from the map. > - This pull request adds verified source associations and three paired map entries. > - Readers can find existing examples without changing their homes or URLs. ## Linked Issues or Issue Description Refs #16052, #16049 and #16046. **What existing behavior does this improve?** Storybook capability lookup and the feature/agent access maps. **Current behavior** Seventy capabilities have no example link. Some matching stories already exist. Primary-agent preferences and company decision/fast-response services appear only under broad neighboring capabilities. **Proposed behavior** Add source-supported links across 34 suites. Keep shared foundations in place while cross-listing them. Add primary-agent, decision-model and fast-response capabilities to both upstream maps. Retain explicit simulation and partial-example limits. **Reason and benefit** The catalog distinguishes missing associations from missing examples. The upstream map describes three existing product capabilities more precisely. **Breaking changes** None to product behavior, story exports, folders, sidebar titles or URLs. A shared foundation can declare a reasoned `home: "foundations"` override while referencing related capabilities. ## What Changed - Add 55 references across 34 suites. Replace primary-agent suites' reporting-line association with their own capability. - Add three source-reviewed capabilities and their API/actor boundaries to paired maps. - Preserve the shared Foundations home when cross-listing developer design examples. Add a validation regression test. - Record which exports demonstrate each association and what remains simulated or unverified. - Regenerate the catalog and capability data. Preserve all original 223 authored suites and 2,210 story IDs. Retain the two skill-removal stories added by current master, for 2,212 authored stories in total. - Reduce empty example lookups from 70 of 171 capabilities to 59 of 174. Links do not establish complete capability coverage. ## Verification - Passed: 27 catalog/generator/map tests, catalog validation, map structural checks, token gates and skill validation. - Passed: source inventory comparison preserves all authored files, titles, meta IDs and story IDs. - Passed: repository typecheck/build and Storybook build. Final built index has 2,248 entries and preserves all previous entries, including the two skills stories added by current master. - The broad local repository test run was interrupted before completion to resolve a new master conflict. A complete local suite pass is not claimed; fresh CI passed on the reconciled branch. - Browser: Design links to preserved Foundations stories; company-service sections link settings/history/journey suites; decision SetupToHistory passed 12 interaction steps; primary-agent ReplacePrimary passed four steps. No console errors in selected checks. - Greptile: 5/5 on final commit `805a8af62abe589907e7cc6ca1b415ce1e0cc3c0`, with no findings or unresolved threads. - Final-revision CI passed all 57 checks/statuses, including all eight browser shards, server and Runner tests, typecheck and build. The unchanged Cloud-auth mocked-response race seen on a superseded revision did not recur on the final commit. No test expectations were changed. - New agent-access evidence is source-only. Live provider and agent-credential verification is not established. ## Risks - Suite-level associations can represent only selected states. Notes retain those limits and existing review classifications. - In-memory connection drafts do not prove reload persistence. Resume-failure UI does not prove successful continuation. No-op budget controls do not prove relief or resumption. - Three map capabilities document existing behavior. No permission, API, provider or production component changes. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, code execution and source inspection. The exact runtime model ID and context window are not exposed in this session. ## 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>
85 lines
4.5 KiB
Markdown
85 lines
4.5 KiB
Markdown
# Hiring, agent configuration, and organization
|
||
|
||
Operators hire agents, configure their identity and instructions, assign reporting relationships, and manage their lifecycle. Built-in agents have their own setup and lifecycle constraints.
|
||
|
||
Implementation: [hiring](../../ui/src/pages/NewAgent.tsx), [configuration](../../ui/src/components/AgentConfigForm.tsx), [organization](../../ui/src/pages/OrgChart.tsx).
|
||
|
||
Agent access: [companion](../agent-access-map/agents.md).
|
||
|
||
## Sub-features
|
||
|
||
- `hire`: choose identity, adapter, model, and required account settings; edit
|
||
reporting relationships through the agent configuration afterward.
|
||
- `instructions`: edit agent configuration and instruction files with durable revisions.
|
||
- `organization`: inspect and change reporting relationships through supported controls.
|
||
- `primary-agent`: choose a personal primary agent for the company, confirm replacement, and inspect its roster/sidebar and task/chat defaults.
|
||
- `lifecycle`: pause/resume or retire an agent while preserving history.
|
||
- `built-in`: configure required agents without treating them as ordinary removable hires.
|
||
|
||
## How to get to it (user POV)
|
||
|
||
### `hire-agent`
|
||
|
||
Use New agent from the roster or `/agents/new`.
|
||
|
||
### `agent-configuration`
|
||
|
||
Open `/agents/:agentId` and the configuration/instruction surfaces it exposes.
|
||
|
||
### `organization`
|
||
|
||
Use the roster’s organization view; `/org` redirects to the roster in the streamlined shell.
|
||
|
||
### `personal-primary-agent`
|
||
|
||
Open an agent profile and choose **Set as my primary**. Inspect its crown on the
|
||
profile/roster and its position in the Agents sidebar, then open a new task or Chat.
|
||
|
||
## Driving it with Playwright and the Paperclip CLI
|
||
|
||
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use a disposable company and supported adapter; hiring may require a formal approval.
|
||
|
||
### `hire-agent`
|
||
|
||
Automated: [new agent page](../../ui/src/pages/NewAgent.test.tsx) and [configuration form](../../ui/src/components/AgentConfigForm.render.test.tsx) cover mocked UI behavior.
|
||
|
||
Manual: Hire an agent with a distinct name and role. Complete any required approval, reload the roster, and open its configuration. Confirm manager, adapter, and model persisted; run a small task to prove execution readiness.
|
||
|
||
The current hiring wizard assigns the first hire CEO and subsequent hires
|
||
General reporting to the CEO. Change manager/role afterward through supported
|
||
configuration. Process/HTTP agents can be created through API/CLI but are excluded
|
||
from the hiring picker; API fixture creation does not prove this UI journey.
|
||
|
||
### `agent-configuration`
|
||
|
||
Automated: [instruction service](../../server/src/__tests__/agent-instructions-service.test.ts) and [instruction revisions](../../server/src/__tests__/agent-instruction-revisions.test.ts) cover file/revision contracts.
|
||
|
||
Manual: Save a harmless instruction edit, reload, and verify its revision and effect in the next eligible run. Pause and resume the disposable agent; confirm pause prevents new work and does not erase previous runs.
|
||
|
||
### `organization`
|
||
|
||
Automated: [org chart](../../ui/src/pages/OrgChart.test.tsx) is component evidence. Built-in setup also has [configuration modal tests](../../ui/src/components/ConfigureBuiltInAgentModal.test.tsx).
|
||
|
||
Manual: Inspect a manager and report, change the relationship through the offered controls, and reload both views. Exercise a rejected invalid relationship. Configure a built-in agent and verify it retains its required identity and restrictions.
|
||
|
||
### `personal-primary-agent`
|
||
|
||
Automated: [primary-agent context](../../ui/src/context/PrimaryAgentProvider.test.tsx)
|
||
and [primary-agent routes](../../server/src/__tests__/primary-agent.test.ts)
|
||
cover selection, company/user scope, and request contracts.
|
||
|
||
Manual: Select an available agent, reload, and inspect the retained personal choice.
|
||
Replace it and verify confirmation is required. Leave or terminate the selected
|
||
agent through permitted controls and inspect the unavailable/cleared state.
|
||
Switch company/user to check isolation. Open a task and Chat with a
|
||
valid draft or recent selection; verify those explicit choices take precedence
|
||
over the primary fallback. Opening Chat must not start execution.
|
||
|
||
## Gotchas
|
||
|
||
- A roster entry is not proof of an authenticated or invokable adapter.
|
||
- Pending hires may live in approval/task surfaces rather than the active roster.
|
||
- Skill and tool grants are separate: see [skills](./skills.md) and [app permissions](./app-permissions.md).
|
||
- A personal primary agent is a per-user/company preference. It does not change
|
||
reporting lines, stars, permissions, or another person's primary agent.
|