The attached prior draft preserved Paperclip's control plane while centering on PairGroup, Usage Center, Capability Registry, and Open Design integration. Building on that draft, this document is an expanded version that redefines the product's purpose — not as a "company without humans," but as a project operations platform where the user sets the broad direction and agents execute like a company. Paperclip describes itself as a system that runs multiple AI agents through an org chart, budgets, governance, tasks, and audit logs; issueflow-skills presents a way to connect a plan not to a feature list but to the user's goal experience and issue-level execution. This product combines the two, aiming for a structure where operations run like a company, execution proceeds like issues, and judgment is made by humans.
This document is the primary source of truth for the implementation stage. Priority runs in this order: this document, then the per-project planning-document set, then issue specs, then API/DB contracts, then detailed UI design. The per-project planning-document set (PlanSet) consists of only three kinds of planning documents — SPEC (the full plan / source of truth), implemented/ (a per-feature tree of what has been built, at most 500 lines per file), and TODO (what is yet to be built = SPEC − implemented). For the detailed conventions, follow the "Project planning-doc methodology" below. The DESIGN_DASHBOARD and QA_PLAYBOOK of the UI UX and QA roles are separate role deliverables and follow the same compaction discipline. issueflow-skills recommends creating, early in a greenfield project, a plan anchor, a goal experience summary, a local backlog board, a first issue wave, and a local proof entrypoint, and holds that the active context file should be a thin pointer for current judgment rather than a long-term record store. This document elevates that philosophy into an operating convention at the platform level.
This product has four core purposes. First, any project should be manageable with the same operating model. Second, agents should move around roles and issues rather than a chat window. Third, it should be not a company without people but a company where people hold the direction and the right of approval. Fourth, design, development, verification, usage, and external capability expansion should all be handled within a single control plane. Considering that Paperclip's strength lies in "a structure where the board approves, costs are controlled, and work is delegated through the org chart," and that issueflow-skills emphasizes an execution philosophy connecting "user experience – issue – proof," this combination is the most natural.
The thing that must be inherited from Paperclip is the control plane. According to the official README, Paperclip presents bring-your-own agent, org chart, heartbeat, budgets, governance, ticket system, immutable audit log, multi-company isolation, and task-based persistence as core features. In addition, the current repository's development guidelines explicitly state the single-assignee task model, atomic issue checkout, approval gates, budget hard-stop, and activity logging as core invariants. Therefore this product should keep Paperclip's "organizational operations layer," but even when introducing pair work, it is better to preserve the simplicity that a single issue has a single top-level owner. That is, a pair should be designed not as two independent assignees but as an execution mode contained within a single Work Owner.
That said, Paperclip's vision is explicitly closer to "zero-human companies." This product does not follow that direction as-is. Here the user is both the board and the founder; agents are autonomous execution actors, but the owner of the final direction and policy is the user. Therefore governance must shift from "an approval system meant to remove people" to "an approval system meant to focus people's time on the most valuable decisions." Because of this difference, this product must expose release sign-off, blocked-issue approval, skill/plugin/MCP installation approval, and plan-conflict approval as core product UX. Approval also supports two modes: by default, the board (the user) decides directly, and when the user turns on always-approve (standing delegation) for a given scope, approvals in that scope are handled automatically by the top-level Planner Agent on the user's behalf — a mechanism to remove low-risk, repetitive approvals from the human loop and "focus people's time on core decisions." Delegation comes with per-approval-type and per-project scope, high-risk exclusion / limits, an audit notation of "by delegation" for auto-approvals, and immediate revocation (details in DECISIONS.md D18). Paperclip's board/approval concepts remain valid as-is, but our product's philosophy leans more toward user-centered execution support than autonomy.
issueflow-skills has a more direct influence on this product's execution philosophy. That repository states that GitHub is recommended but not required, and advises that when GitHub is present, durable issue IDs, PR linkage, review history, and required checks be used as the collaboration/audit layer, while actual execution still takes the repository's local scripts and proof commands as the baseline. It also holds that a plan should describe the user's goal experience rather than enumerate features, that each core issue should advance at least one target user experience, and that a vertical slice should bundle the user path and proof together. This philosophy fits very well with the structure the user described as "agents grabbing a kanban TODO and carrying it through."
Another strength of issueflow-skills is the habit of keeping the operating context small. PLAN_ANCHOR.md and CURRENT_STATE.md should be thin files containing only the current macro direction, the active issue, recent proof pointers, and the next action — not a graveyard of completed issues or an endless notepad — and compaction is recommended once they exceed roughly 150–250 lines or completed issues pile up excessively. It also advises not deleting blocked automations but keeping them as PAUSED to leave a resume trail. This product's requirements — "periodically compact the base context, normally hide skills that aren't needed, and quickly check on the board which issues require user input" — can be turned into platform features almost directly from this principle.
Open Design is well suited as a reference implementation for the Designer role. The official README describes Open Design as an open-source design engine with a local-first, web-deployable, BYOK structure, connecting existing CLI agents as a design engine, and providing a sandboxed iframe preview, live todo progress, an <artifact>-centric generation loop, and many design systems and skills. It goes further by providing a read-only MCP server so that other agents can directly query an Open Design project, and emphasizes a plugin registry and trust badge, headless-by-default, and a plugin-driven engine. In other words, Open Design is not simply a "design generator" but a subsystem that supplies design as a capability. In this product, rather than forking it and melting it into the core, it is safer to attach it as a default capability pack and a sidecar bridge.
Finally, the pair work the user requested has not only practical sense but also research grounding. Self-Refine showed that a same-model generate–feedback–revise loop can on average produce better results than one-shot, and Reflexion suggested that verbal feedback and episodic memory can improve performance on subsequent attempts. Multiagent Debate reported that debate among multiple instances can improve factuality and reasoning, and research on sparse communication topology showed that comparable or better performance can be achieved at lower compute cost even when not every agent talks to all the others every time. Therefore this product's pair loop is better designed not as "infinite debate" but as a two-person collaboration loop with a maximum of 10 rounds, an explicit stop condition, and a cost ceiling.
This platform must be applicable not only to software projects but also to content, design, marketing, sales operations, and customer-support operations. To that end, the base unit of a project is set not as a "repo" but as a Project, and a Project is designed as a structure that optionally connects a code repository, an issue tracker, a design workspace, a deployment target, and a document store. As issueflow-skills says, GitHub is merely a recommended collaboration/audit layer and not required; the baseline for execution is the project's local commands, its way of collecting proof, and its planning documents. Moreover, goal-experience-planning says target experience should be applied even to operational tools. Therefore the unit of this platform becomes not a particular development environment but the unit of work for which the user wants a result.
The bootstrap of a new project is best fixed in the following order. First, the Planner Agent organizes the target user and situation, the current pain, the moment the product clearly helps, what the user becomes able to do afterward, the first successful workflow, and the non-goals, producing PLAN.md and PLAN_ANCHOR.md. Next, it creates the stack decision and the repo-topology decision — a concrete project folder layout chosen from a small preferred set rather than left to per-agent improvisation: a single-package app (src/, tests/, docs/, config at the root); a Node/TypeScript monorepo (packages/<name>/* with shared code in packages/shared/); a web app (src/{components,routes,lib,hooks,styles} plus public/); a Python package (src/<pkg>/, tests/, pyproject.toml at the root); defaulting to the single-package app when the stack is ambiguous. The chosen topology is recorded in the project-root AGENTS.md — which Workcell seeds with this default convention when a workspace is created empty — so every downstream agent (Developer, Designer, QA) builds against one structure instead of each inventing its own. It then creates the local backlog board, the first numbered issue wave, and the local proof entrypoint. The first wave should include as thin an end-to-end vertical slice as possible, and if there is a strong user-experience promise, it should show that promise from the very first screen. issueflow-skills' greenfield bootstrap, vertical-slice-architecture, and experience-first-ui all recommend the same direction.
The bootstrap for importing an existing project must be designed somewhat differently. First, the Planner Agent scans the repo, the issue tracker, active PRs, current screens, tests, docs, design patterns, and the backlog to grasp the current facts. Next, it generates CURRENT_STATE.md and BACKLOG_BOARD.md, and classifies open work as aligned, extension, conflict, or deviation. When there is an ambiguous requirement, instead of making the user re-explain everything, it asks just one or two narrow questions that would change the implementation direction. issueflow-skills' interactive brainstorming recommends exactly this procedure, and the GitHub adoption document clearly says to treat GitHub as the audit layer and the repository's local commands as the execution layer. This product's "bootstrap for continuing to manage a previously managed project on this platform" becomes the process of providing this philosophy through UI/automation.
Issue creation should always be able to start from natural language. When the user says "handle this feature," "make this screen clearer," or "this flow feels off," the Planner Agent immediately drafts a new issue. Even when there is an ongoing process, an independent issue should be addable to the ready queue. However, an issue is not a mere note but must carry acceptance criteria, non-goals, a proof surface, related planning documents, an expected owner role, and blockers. Moreover, when a broad request hides several independent issues, it should be the default behavior for the Planner Agent to decompose it into several TODOs. This aligns with interactive brainstorming recommending "splitting a large request into independent issues" and parallel delivery recommending parallel processing of independent lanes.
The kanban state model must be richer than issueflow's minimal board template, but the operating context must still be kept small. The recommended default states are Draft, Ready, In Progress, In Review, In QA, Blocked by User, Blocked by System, Done, Cancelled, and Archived. The user should be able to hide states such as Done, Cancelled, and Archived, and Blocked by User should be shown on a separate focus rail. Considering that issueflow's backlog template requires keeping the active context centered on current pointers and moving completed issues to history, the kanban UI should likewise handle "operating states" and "record-keeping states" separately. The rule of not deleting user-blocked automations but leaving them in a paused state must also be applied as-is.
Post-completion Compound (consolidation/learning) stage. When an issue/wave reaches proof-gated Done, instead of accumulating separate notes, it passes through a single consolidation stage before moving to Archived. The Planner Agent presides over it and ① reflects the completed work into implemented/ in compacted form, removes it from TODO, and updates the knowledge graph (issue↔implementation↔decision edges and status); ② absorbs the reusable learnings, prevention rules, and failed approaches that surfaced during the work into short constraint/caution notes on the relevant implemented/ snapshot or into knowledge-graph nodes (QA into QA_PLAYBOOK, design into DESIGN_DASHBOARD); and ③ sweeps the scope it touched and reduces discovered debt, latent regressions, and follow-up slices into follow-up issues (leaving the rationale if there are none). Key constraint: this stage does not create a new kind of document — learnings/prevention are melted only into the three documents of D11 (or the role deliverables) and into the graph. This brings issueflow's compound-learning (prevention rules, failed approaches, follow-up triggers, plan-gap capture + history compaction) into the product operating model as a first-class stage. Document consolidation, the follow-up sweep, and learning absorption are core (P1~P2); the graph-update portion is P3, together with the knowledge graph.
The plan of every project managed by Workcell is expressed with only three kinds of documents. The approach of accumulating a long history of completed/incomplete issues and continually re-reading it is not adopted. A project is organized as a tree, so that — without reading everything — one can pick only the necessary files to compare "what is to be built (TODO)" against "the currently implemented spec."
- SPEC — the full plan (source of truth). The single living source of truth for the entire product/project spec. Confirmed decisions and architecture are absorbed into this document rather than a separate decision log.
- implemented/ — what has been built so far. Not a single file but a folder tree split by large feature. At most 500 lines per file, with file names that reveal their contents. Each file is a compacted snapshot of the currently implemented state rather than a change history, and a thin
INDEX.mdserves as the tree map. - TODO — what is yet to be built. = SPEC − implemented. The current active issue / next action goes at the top. Undecided decisions go under "pending decisions," and once confirmed they are immediately reflected into SPEC and then removed.
The Planner Agent maintains implemented/ and TODO together within the flow of creating and completing new issues. File/directory names are in English; the body copy defaults to Korean.
- These three kinds (SPEC, implemented, TODO) are the entirety of the planning/decision/issue-management documents. No new memo/decision/state/issue-management document is created beyond them. Opinions are not remembered, and issues are not managed, by any method other than this specified one. (Only the role deliverables
DESIGN_DASHBOARDandQA_PLAYBOOKare exceptions, and they too follow the same compaction discipline.) - An issue-management document never exceeds 500 lines under any circumstances. Compaction is the top priority — the more it is reduced, the better. When the limit is approached, reduce immediately.
- What no longer needs to be known is deleted, not summarized or archived. A history of completed/incomplete issues is not accumulated — what is completed is reflected into
implemented/and removed fromTODO. - If a small request does not change the product spec, these documents are not touched. Only when the product spec changes are
SPEC,implemented/, andTODOmaintained together.
Paperclip's example organization uses conventional role splits such as CEO, CTO, engineers, designers, and marketers, but this product adopts a workflow-centric structure rather than a title-centric one. The high-level default roles are fixed as Planner Agent, UI UX Agent, Developer Agent, and QA / QC Auditor, with additional domain-specific roles added depending on the project type. That is, the goal is not to mimic a human company's org chart but to build a structure that most directly reflects the flow of work the user actually wants to delegate. Paperclip's role/org-chart strengths are kept, but the role names and rules must be rewritten to match the project operating philosophy.
The Planner Agent is the role that synthesizes the user's natural-language requests, existing planning documents, the backlog, current screens, active issues, and proof status to create a plan and to reduce gaps into issues. This Agent does not stop merely because another Agent is working. If something can be handled independently, it keeps drafting or readying new issues. Moreover, every plan change does not simply end as prose but is reflected, per the "Project planning-doc methodology," into SPEC, implemented/, TODO and into acceptance criteria, non-goals, and the proof surface. This Agent creates and completes issues while always keeping implemented/ (what has been built) and TODO (what remains) in sync, and maintains a compacted state by deleting unnecessary content so that documents never exceed 500 lines. Looking at issueflow's goal-experience-planning and interactive brainstorming, a good Planner should be not a writer of feature specs but someone who translates the user experience into an issue graph. It also presides over the Compound stage after completion (see "General-Purpose Operating Model"), taking responsibility for reflecting implementations, absorbing learnings/prevention, and reducing follow-up issues.
The UI UX Agent holds the responsibility of maintaining a design dashboard as the source of truth for each project. It must always be invoked when a screen is added or changed, and a deprecated screen must be removed from the default dashboard or moved to archive. This Agent does not simply make screens pretty; it must review the meaning of the first viewport, where the user's gaze lands, the naturalness of the copy, the human tone of buttons and status messages, and information hierarchy and density. issueflow's experience-first-ui is wary of proof panels and dashboard-first UI, holding that if a screen passes tests but is crude or awkward it is not done. Open Design provides the default design capability and preview infrastructure that can perform this role. Therefore the UI UX Agent should be equipped with the Open Design pack by default, and screen planning and preview generation should preferentially use this path as much as possible.
The Developer Agent by default takes one feature issue at a time. However, a team may have multiple Developer Agents, and parallel execution should be possible for mutually independent vertical slices. issueflow's vertical-slice-architecture and parallel-delivery recommend that a single issue carry a single user action or result, that independent lanes be split worktree-first as much as possible, and that root integration be managed separately. Therefore the Developer Agent should keep the "one issue at a time" discipline while being designed so that multiple developer lanes can be operated at the team level. In particular, in a monorepo or multi-package environment, package-local proof commands and disjoint ownership should be stated as metadata to reduce parallel conflicts.
The QA / QC Auditor is not a mere test runner but an independent role responsible for the completion verdict. This role can mark an issue done only when there is proof that the issue is resolved, and must accumulate a per-project QA methodology on its own and record it in QA_PLAYBOOK.md. For web projects it looks at Playwright scenarios; for apps where visual elements matter it looks at golden tests or snapshot baselines; and it also considers a qualitative audit that includes copy quality and the overall impression of the screen. issueflow says to bundle proof around the real user path and user-facing surfaces, and experience-first-ui holds that "even with green tests, if the screen is ugly or the copy is awkward, it is not done." This Agent implements exactly that standard as the product's institutional quality gatekeeper.
Other Agents are added according to the project's characteristics. In content/marketing one may have a Strategist, Researcher, and Writer; in sales/operations one may have a Prospector, Signal Analyst, and Customer Support. However, these too are treated identically — not as chat-style assistants but as issue-owner candidates and roles that must leave proof. Since Paperclip's strength lies in binding diverse agent runtimes within one org chart, even as roles increase, it is better to maintain the execution conventions on the same domain model.
Every Agent should be able to have its personality changed in natural language, and if necessary its system prompt should be directly editable too. Anthropic's subagents documentation explains that a subagent is defined with a markdown file and YAML frontmatter, that a subagent can be created or edited in the /agents interface based on a natural-language description, and that the body becomes that subagent's system prompt. In this product too, each Agent is best managed split into two layers — a Role Charter and a Behavior Prompt. A natural-language change generates a charter delta, advanced users can edit the body directly in a prompt editor, and every change must have a version and a rollback path.
Pair work is designed with the structure WorkOwner = SingleAgent | PairGroup. A PairGroup shares two members and a single role charter, while its internal execution turns as a round-based review loop. The default loop is in the order A draft, B critique/edit, A critique/edit, and it ends when either side declares no_change_required. The maximum number of rounds is fixed at 10, and the stop reason is left as one of converged, max_rounds, budget_stop, human_stop, or blocked. The important point is that a pair is not a structure that creates more top-level assignees but an executor that performs iterative refinement within a single issue owner. This is the safest way to obtain pair quality without harming Paperclip's single-assignee simplicity.
PairGroup execution baseline conventions
1. Input: issue spec, acceptance criteria, current context, latest artifact, proof expectations
2. Round 1: Member A writes the draft
3. Round 2: Member B reviews defects/improvements against requirements, then writes a revision and feedback
4. Round 3+: the opposite member, having received the latest revision, repeats in the same manner
5. Termination:
- one member declares no_change_required
- maxRounds = 10 is reached
- a budget/time guardrail is reached
- transition to blocked because a user decision is required
6. Output:
- the final artifact
- per-round diff and feedback summary
- stop reason
- total cost and usage
The product's base UI can be summarized as five screens. First, Project Home summarizes the current goal experience, active issues, blocked issues, recent proof, and key cost signals. Second, Kanban Board is the actual operating screen. Third, Issue Workspace is the detail screen for viewing a single issue's plan, deliverables, pair log, proof, and decision requests. Fourth, Design Dashboard is the source of truth for screens and artifact previews. Fifth, Capabilities / Usage Center manages external capabilities and costs. Since Paperclip already gathers board, work, budgets, and governance into one control plane, and Open Design provides preview, live todo, and a comment-like annotation surface, designing just these five screens well is enough to convey the core of the product.
The core of the Kanban Board is the visibility of "natural language → issue" conversion and "blocked decision." At the top of the board sits a natural-language input box, and when the user writes "make the sign-up flow simpler," the Planner Agent grounds it and immediately drafts an issue. On a card, owner role, single/pair, proof status, design impact, decision needed, and usage burn should be shown before the title. Also, the user should be able to hide Done, Cancelled, and Archived in the state filter, and it is better to separate Blocked by User into a fixed right-side rail or a top-priority section. Moving issueflow's active-context principle and automation-pause rule onto product screens yields exactly this UX.
The Issue Workspace must show both "why this issue exists" and "what it ended as" at the same time. At the top sit the issue classification, acceptance criteria, non-goals, plan link, owner, dependencies, and planned proof; the body should continue with artifact version history, diffs, preview, annotations, run transcript summary, pair turns, and audit events. The completion button is best enabled only under QA / QC Auditor permission and kept disabled when there is no proof bundle. This connects with issueflow recommending that every completion be bound to proof and a user-visible outcome.
The Design Dashboard is the source of truth for the UI UX Agent. It must contain the list of currently valid screens, deprecated screens, version comparisons, approval status, linked issues, linked components, preview, and annotations. The preview must be immediately viewable through an iframe or artifact renderer like Open Design, and the user must be able to leave comments on specific regions over a screen. Since Open Design provides sandboxed iframe preview, preview-element comments, a live artifact workflow, and read-only MCP access, this product should refer to it and treat design as an operatable asset that can be previewed, not a document. It is appropriate to hide deprecated screens from the default list but keep them viewable in an archive tab.
The Capabilities screen is the space that shows the skills, plugins, MCP servers, and design systems the company holds as a single registry. The important UX here is not "showing everything" but "showing only what is needed." Anthropic's skills documentation explains that a skill body is loaded into context only when actually invoked, and that skillOverrides can control on, name-only, user-invocable-only, and off. Therefore this product's capability registry should also have visibility states such as assigned, discoverable, hidden, and disabled, with the default being to show only the capabilities each role needs. Open Design's plugin registry and trust badge UX are an excellent precedent worth referencing here.
The Usage Center is the screen that must most honestly reflect the user's original requirement. Anthropic provides a Usage & Cost API and a Rate Limits API in the Admin API, and in the Claude Code / Claude products it shows session/weekly usage, usage credits, and spend/reporting through Settings > Usage and billing surfaces. OpenAI provides API rate/usage limits, remaining requests/tokens in response headers, a Usage page, a Billing page, and flexible pricing credits. However, this information varies in accuracy and freshness depending on organization/workspace permissions, project unit, product plan, and the kind of rate limit. Therefore the Usage Center should have three accuracy badges — Exact, Synced, Estimated — and must clearly tell the user "whether this figure is the provider's official remaining quota, a synced managed figure, or an internal burn-rate estimate."
The recommended implementation strategy is forking Paperclip + redefining the domain + sidecar/bridge integration of external capabilities. The reason is clear. Paperclip is already a "full control plane" with a Node.js server, a React UI, and a task/work/governance/budget/activity/adapters/plugins structure, and it provides much of the foundation for the company-style orchestration we want. By contrast, pair work goes beyond a layer placed on top of the current invariants and changes the execution-owner model, and the plugin side currently has the practical constraints of being self-hosted, single-node, and same-origin trusted UI. Therefore this product is best served by incorporating pair, design dashboard, and capability governance into the core domain, and treating Open Design, MCP, and external plugins as an optional connection layer.
The architecture is broadly divided into Control Plane API, Planner / Scheduler, Run Orchestrator, Adapter Gateway, Capability Registry, Design Sidecar Bridge, Usage Telemetry, Context Manager, and Audit / Observability. The Adapter Gateway accommodates Claude Code, Codex, other CLI agents, HTTP/Webhook Agents, and an MCP Bridge, and the Design Sidecar Bridge attaches external artifact engines such as Open Design. Paperclip already describes a structure that places Claude Code, Codex, CLI, and HTTP families under the control plane; Open Design provides headless-by-default and read-only MCP; and Anthropic subagents/skills allow independent context and tool scoping. In other words, this structure is less a new paradigm than a rearrangement of proven elements to fit the purpose.
This product's core entities are best fixed as follows.
Company: the owning unit of the organization, policies, subscription, budgets, secret store, and capability registryProject: a particular unit of work. Optionally connects a repo, tracker, design workspace, and deployment targetPlanSet:SPEC(full plan / source of truth) ·implemented/(what has been built, a per-feature tree at most 500 lines) ·TODO(what remains = SPEC − implemented). The role deliverablesDESIGN_DASHBOARDandQA_PLAYBOOKare separate. Details = "Project planning-doc methodology"Issue: an execution unit carrying a goal result, acceptance criteria, a proof surface, blockers, and linked artifactsWorkOwner:singleorpairAgentProfile: role charter, behavior prompt, model/runtime, permissions, memory policyPairGroup: two members, max rounds, stop policy, escalation policyRun/PairTurn: actual execution logs, cost, artifact diffs, stop reasonArtifact/ArtifactVersion/Annotation: documents, code, designs, reports, preview feedbackProofBundle: test results, screenshots, golden, URL, QA verdictCapability/CapabilitySource/CapabilityAssignment: registration and assignment of skills, plugins, MCP, and design systemsUsageSnapshot: usage, remaining quota, accuracy, and refresh time per provider/planContextShard/CompactionRun: charter, working memory, episodic memory, capability index, and compaction recordsDecisionRequest: a blocked object requiring user approval, a policy decision, or a product-direction choice
The core of this entity model is to still keep an Issue's assignee single, while letting that single owner be either single or pair. This is the most stable way to accommodate the requested horizontal pair work while preserving Paperclip's single-assignee simplicity.
Context management is best split into four planes. Role Charter holds the role's identity and prohibition rules; Working Memory holds the current issue and blockers; Episodic Memory holds recurring lessons; and Capability Index holds only the names and descriptions of capabilities. The Anthropic skills documentation explains that a skill body is loaded only when needed and that, via skillOverrides, a name-only or off state can be set. issueflow requires keeping the active file budget small, and hooks allow reactions to be hung before and after compaction via PreCompact/PostCompact. Therefore this product should, by default, not preload full skill bodies, archive history, or past proof, but first load only indexes and pointers and fetch on demand when needed.
The external-capability expansion layer is best split into three. First, trusted platform modules are low-level adapters or storage/secrets extensions tightly integrated with the host. Second, plugins are instance-wide additive capabilities with an out-of-process worker. Third, skills / MCP / design systems are lighter prompt+tool or data-source extensions. Paperclip's plugin spec separates platform modules from plugins and treats third-party plugins as out-of-process by default, whereas the current implementation's plugin UI warns that it is same-origin trusted code. Therefore this product should not mount third-party UI directly same-origin into the host but instead separate it via iframe/webview/typed bridge. At the same time, "safe but useful" bridge patterns like Open Design's read-only MCP can be actively leveraged.
The update model defaults not to "auto-update" but to user-triggered staged update. Open Design provides a plugin registry, trust badge, and packaged auto-update, and Paperclip's long-term plugin design targets hot install/uninstall/upgrade and capability approval. However, Paperclip is not yet cloud-ready for dynamic plugin distribution, and there is also the same-origin UI constraint. Therefore the most realistic flow for this product's V1 is to pin the upstream repo/tag after importing a capability source, and when the user clicks check updates, show the manifest diff, license diff, smoke-test results, and breaking risk, then approve apply update. The scope of reflecting to the whole company versus reflecting to only a specific Agent must also be separated.
Planning "documents" (SPEC/implemented/TODO) hold the details and are kept minimal, and above them sits a single lightweight knowledge graph — a current-state map/index that links code + plan/spec + decisions + issues (by reference) as nodes/edges. The purpose is not memory but navigation: rather than reading many documents in full, one skims the graph to pick "which documents, code, and issues in which area to look at in detail" and loads them on demand.
- Model. Nodes = features, modules, concepts, decisions, plan items, issues (by reference). Edges = implements, depends-on, relates-to, spec-of, status. Each node holds only pointers to details (a document section,
file:line, an issue ID) and does not duplicate the body (consistent with D11). - Population (derivation) & reuse of existing assets. The graph is a read index derived from authoritative sources (on mismatch, the source wins; updated event-driven / on-demand). It reuses existing edges:
issue_relations(blocks) andissue_reference_mentions(auto-extracted issue↔issue links) are absorbed as depends-on/relates-to (no parallel storage). The existingplugin-llm-wikidistillation pipeline (distilling issues, comments, and docs into pages) is reused as a graph populator. Code nodes use Graphify-style code graphing. - Replacement target (existing Paperclip role). llm-wiki's navigation layer —
index.md(flat catalog) +[[wikilink]]backlinks +projects/standup.md— is succeeded by the formal typed graph. The wiki-maintainer agent is redefined from "wiki document management" to "graph maintenance (populator)." Keyword search (company-search, trigram; no embeddings) is text matching, so it coexists as a complement (graph = structural navigation, search = text). - When the Agent uses it (touchpoints). ① MCP graph tools (
graphQuery/graphNeighbors/graphUpsert) for on-demand querying/updating — newly added because the current MCP has no search/knowledge tool. ② Injecting graph-derived "related documents, decisions, issue pointers" into heartbeat-context (the issue wake bundle) → relevant context arrives automatically on wake. ③ Updated on issue creation/completion. The Planner = queries the current state before creation (duplicates, dependencies, impact); Dev/QA = navigate related code, docs, and issues. - No conflict. The source of truth for issues is the DB/Kanban — the graph holds only ID references (no re-storing status, no dual tracking). The time axis is non-core (the immutable audit log handles "when it changed," and re-storing it would conflict with D11's non-accumulation) → an optional P3 layer if needed.
Approach: MCP sidecar/bridge (same as the external-capability layer), no preloading by default, on-demand. Backend lightweight-first — an embedded Postgres graph schema / Apache AGE + pgvector (without a new DB), with Neo4j/FalkorDB not adopted. The implementation and backend are confirmed via a P3 PoC. (Decision = DECISIONS.md D12)
As the UI/UX Agent's design engine, attach Open Design (nexu-io/open-design, Apache-2.0 — a local daemon + CLI agents as the design engine, <artifact> sandboxed iframe preview, read-only MCP, BYOK, 150 design systems · 132 skills). But not as a core fork — as a plugin (capability pack) + sidecar bridge — because the Open Design engine overlaps heavily with what Workcell already has (claude/codex adapters, skills, workspace, Run Orchestrator).
- Porting form = a Workcell plugin (
plugin-llm-wikitemplate). Not an adapter — the adapter contract (ServerAdapterModule.execute) is an "agent process runtime," whereas OD is an engine/MCP/artifact source, so it is unsuitable (and built-in adapters are locked). The plugin provides: UX Agent agent tools, the design Skills +DESIGN.mdsystem (BYOK =secrets.read-ref), the Design Dashboard (pluginpageslot, routesdesign/screens;design-guideis reserved), per-issue artifacts (detailTab/taskDetailView), region annotations = reuse of the existingcommentAnnotationslot, anddashboardWidget. - Generation is executed via the Workcell adapters/workspace/Run Orchestrator (the OD daemon is not attached as a second orchestrator) — the design skills/systems are driven by the claude/codex adapters.
- Preview = sandboxed iframe — reuse the existing iframe launcher (
/_plugins/:id/ui/*+ asset CSPsandbox); the in-process React slot loader is prohibited (generated untrusted HTML). - Artifacts = augmenting the existing
issue_work_products(type/url/reviewState/isPrimary/metadata/createdByRunId) +assets(raster/blob). The spec'sArtifact/ArtifactVersion/Annotationmap onto this rather than new core tables (annotations =commentAnnotation+issue_comments). No parallel system. - The external MCP bridge = the only net-new infrastructure (Workcell has no outbound MCP client). Two-path PoC: (a) the plugin worker
http.outbound/ a new MCP client, (b) attaching OD's read-only MCP directly to the claude/codex adapters (the CLIs are MCP-native — possible with 0 core changes). (b) is preferred, and this bridge is shared with the knowledge graph (code-graph MCP) — build it once and use it for both. - The UX Designer role already exists (
uxdesigner.md, roledesigner, "Visual-truth gate" = a mandatory actual-viewport render + screenshot) → Open Design supplies the engine that satisfies that gate. The existing role simply gets the plugin tools attached. Augmentation, not replacement (the design capability itself is greenfield). - License: Apache-2.0 — when bundling/porting skills/design systems, add
NOTICEattribution; if it is only an external sidecar execution, the footprint is light. - Sequencing: Design Dashboard base + UX agent = P2; Open Design bridge + outbound MCP + capability registry = P3.
A porting map of what to reuse and what is net-new on top of the Paperclip fork (codebase survey 2026-05-27). The new primary domain concepts — proof bundle · owner role · single/pair · design impact · decision-needed · usage burn · the
Blocked by Userrail — do not yet exist in the code (and the richer state model is not reflected inIssueStatus).
The 5 screens = a greenfield product layer + donor pages. The current UI is Paperclip's general-purpose agent-ops UI (docs/DESIGN_DASHBOARD.md states all 5 screens are unimplemented). Evolution starting points:
- Issue Workspace ←
IssueDetail.tsx(strongest donor: transcriptIssueChatThread· run/costIssueRunLedger· versioned docsIssueDocumentsSection· reviewers/approvers · attachments). net-new = proof-gated Done (the QA-role + proof-bundle condition) · classification/acceptance/non-goals/pair-turns/audit timeline. - Kanban ←
KanbanBoard.tsx+IssuesList.tsx(structure exists). net-new = natural language → Planner draft (the currentPOST .../issuesis pure CRUD with no LLM = the key Phase 1 gap) · the card chip-row (owner role · single/pair · proof · design impact · decision · usage burn) · theBlocked by Userdedicated rail. - Project Home ←
Dashboard.tsx(global) +ProjectDetail.tsx(overview), restructured around the goal experience. - Design Dashboard · Capabilities/Usage Center = greenfield (donors:
DocumentDiffModal·CommentThread/CompanySkills·Costs·PluginManager).
PairGroup = a thin orchestrator on top of a solid single-run substrate. One round = one existing adapter.execute = one heartbeat_runs row (executeRun). Reuse: agent_task_sessions (per-member sessions) · heartbeat_run_events + TranscriptEntry.diff/.result (per-round diff, feedback, cost) · cost_events/agent_runtime_state (cost) · the wakeup→claim path. The issue already has a single assigneeAgentId (= the single-owner invariant). net-new = ① a two-agent alternating round-loop orchestrator (stop: no_change_required/maxRounds=10/budget/human/blocked); ② a PairTurn ledger (round# · drafter/critic · diff · feedback · cost · stop_reason); ③ a WorkOwner indirection (resolving a single assignee → pair).
Usage Center = already ~70% implemented (a big finding). On top of internal burn (cost_events + costService) and budgets (budgetService), provider official quota sync already exists — getQuotaWindows() pulls from claude-local (Anthropic OAuth usage + Claude CLI /usage) and codex-local (codex app-server RPC + ChatGPT WHAM) (/costs/quota-windows, Costs.tsx · ProviderQuotaCard). → Badge mapping: Synced/Exact = subscription/OAuth quota sync, Estimated = adapter-reported burn; a metered API key cannot sync, so it is structurally Estimated. net-new = a formal Exact|Synced|Estimated provenance enum (currently ad-hoc labels + a quotaSource string) · an integrated Usage Center IA · (optional) UsageSnapshot history storage (current quota is a live fetch, unstored). → Evolves from the existing Costs.tsx.
Agent charter/instructions. Reuse: the agentInstructionsService file bundle (per-agent AGENTS.md, managed|external mode = NL .md editing) + agent_config_revisions (config snapshots, rollback). net-new = a two-layer split of charter (identity, prohibition rules) ↔ behavior (the prompt body) + versioning/rollback of the prompt body. AGENTS.md body is not in the snapshot (body versioning is built from scratch).
Capability registry/visibility. Currently spread across 3 systems (skills = company_skills, plugins = plugins/lifecycle, MCP/adapters = registry); assignment is stored implicitly in adapterConfig.workcellSkillSync.desiredSkills (a per-agent array of skill keys). net-new = a unified registry (skill + plugin + MCP + design system) + a visibility enum (assigned/discoverable/hidden/disabled) + an explicit scope table. Evolves from company-skills.ts.
Security trust tier. Reuse: a robust secret store (company_secrets/versions/company_secret_bindings) + audit (secret_access_events/activity_log) + the plugin capability approval gate (plugin-lifecycle.ts: adding a new capability → upgrade_pending → approval). net-new = a trusted|reviewed|unreviewed tier + an enforced bundle (no auto-invoke · disabled by default · UI isolation · secret blocking). company_skills.trustLevel is a "content risk class" (markdown/scripts/assets), not a security-review status — do not confuse the name/meaning (use a new field).
Bootstrap (mostly greenfield). Currently only manual CRUD: onboard.ts = infrastructure only, createProject/createCompany = row insertion, OnboardingWizard = a manual 4-step (1 agent + 1 issue). Company export/import is for migration (≠ bootstrap), and repo scanning exists only in skills. net-new = Planner-driven bootstrap (new = plan/anchor/backlog/proof + first wave / existing = repo · tracker · test scan → current-state + classified backlog). Evolve hook = createProject/OnboardingWizard; the scan pattern = company-skills repo-scan.
Audit/version substrate reuse: Extend install/update/approval audit and versioning with agent_config_revisions + activity_log + secret_access_events.
Entity alignment (spec → code). The issue/project/run/cost/skill/plugin spine already exists richly (Company · Project · Issue · AgentProfile = agents · Run = heartbeat_runs · part of Capability = company_skills/plugins). The collaboration + proof layer is entirely net-new: WorkOwner · PairGroup · PairTurn · ProofBundle · ContextShard · CompactionRun · UsageSnapshot · ArtifactVersion · CapabilitySource/Assignment. Since Artifact = issue_work_products + assets and Annotation = issue_comments mapping, the only new core table is ArtifactVersion. assigneeAgentId XOR assigneeUserId) — there is no pairing-schema scaffold.
Issue state model. The current 7 states (backlog · todo · in_progress · in_review · done · blocked · cancelled) → the target 10 states. net-new = In QA (the current QA is merely an execution-policy review/approval stage) · splitting Blocked → Blocked by User/System (currently 1 state + read-time derivation) · Archived (currently the hiddenAt timestamp). Draft/Ready = renames of backlog/todo. assertTransition only validates the target string) — the real workflow is a separate execution-policy stage machine. The "Blocked by User rail" is partially pre-implemented as blocked-inbox attention (issues.ts) (a derived value, unstored).
Approval/governance (DecisionRequest). Strong reuse: approvals (a generic type + payload, the board decides (assertBoard), agent wakeup on approval, issue link) = the home of DecisionRequest. + issue_execution_decisions (an in-issue reviewer/approver stage ledger, separate from the company approval queue). Of the spec's 4 kinds, only blocked-issue approval exists (request_board_approval); release sign-off · capability-install approval · plan-conflict = net-new types (in particular, skill/plugin installs currently have no approval gate). The current company approval is a board-only decision (assertBoard; reviewer/approver delegation is separate, in issue_execution_decisions) — onto this we add, as net-new, a delegated-approval mode (D18: when standing delegation is on, the assertBoard path checks the policy and the Planner Agent auto-approves).
Context assembly/compaction. Reusable donor: /issues/:id/heartbeat-context (a 12-way bundle, already loading summary documents rather than full history) + per-run contextSnapshot. session-compaction is CLI session rotation (maxSessionRuns/RawInputTokens/AgeHours), and token-window management is delegated to the adapters (claude/codex). The spec's 4-plane (Charter/Working/Episodic/Capability Index) · ContextShard/CompactionRun · index+pointer-first · on-demand are all net-new (do not confuse them).
Scheduler/heartbeat/liveness — strongest reuse. wakeup → queue → priority claim → execute is complete: queueIssueAssignmentWakeup → agent_wakeup_requests → startNextQueuedRunForAgent (per-agent lock · maxConcurrentRuns slot · dependency/priority/FIFO ordering · coalescing/idempotency) → executeRun. liveness = a periodic scheduler (index.ts) runs orphan reaping · retry promotion · stranded reassignment · the silent-run watchdog. The spec's "the planner does not stop and agents keep acting" is structurally satisfied. Evolves from heartbeat.ts + index.ts.
Update (staged) — partially implemented. Plugins: plugin-lifecycle.ts upgrade() has a manifest capability-diff + an upgrade_pending approval gate (closest to the spec). Skills: company-skills.ts has pinning (a 40-char SHA) + "check updates," but installUpdate applies immediately with no diff/approval. net-new = license diff · smoke · breaking-risk · company/agent scope + a staged-approval retrofit for skills. Evolves from plugin-lifecycle.ts:639.
Audit/observability — substrate is solid (DB-persisted). activity_log (logActivity: redact + live event + plugin event bus) and secret_access_events persist every record to the DB. Strict immutability (UPDATE/DELETE-blocking triggers and permissions) is optional later hardening (not a V1 blocker). Coverage = call-site opt-in, so only the capability-install / done-verdict logging needs to be explicitly wired. No metrics/alerting (P4).
Multi-company isolation — robust (reuse). Every table has a companyId FK + assertCompanyAccess + authorization.ts deny_company_boundary. RBAC is deliberately thin (P4): 8 PERMISSION_KEYS + roles (owner/admin/operator/viewer/member + instance_admin) + a grant/scope/manager-chain engine (authorizationService.decide). The board local is allow-all (single-tenant pragmatism), and agents are default-deny. Advanced RBAC = P4. Evolves from authorization.ts + PERMISSION_KEYS.
For the billing model, on a self-serve basis a single subscription-product structure is recommended. Expose to the user only a seat- or workspace-based subscription, and internally track provider cost, rate limits, shared credits, and burn rate separately, translating them into a platform allowance. Both Anthropic and OpenAI provide usage, credits, rate limits, spend alerts, and usage reports as official surfaces, but this structure differs by provider and the permissions are tied to the organization level. Therefore the most practical is a dual structure that simplifies the end-user pricing policy into a subscription while letting the operator screen view provider-level usage and limit signals precisely. In other words, pricing should be simplified into a subscription, and operations should be refined to be usage-aware.
The basic principle of the security model is "open up expansion, but make trust reducible." Anthropic explicitly says to use only trusted MCP servers, and warns that even though Open Design's MCP is read-only, a registered client gains read access to the local project, so only trustworthy clients should be registered. Paperclip likewise warns that its current plugin UI is trusted same-origin code. Therefore this product should have a trusted, reviewed, unreviewed trust tier per capability, and unreviewed should carry the policies of no auto-invoke, disabled by default after install, separate approval required, UI bridge isolation, and no secret access. Secret material must not be put in the capability manifest but kept only in the company-scoped secret store, and installs, updates, and permission approvals must all be left in the audit log.
A four-stage implementation roadmap is appropriate. The first stage is Project bootstrap, Planner, Kanban, Issue Workspace, single-owner execution, proof bundle, and a basic Usage Center. The second stage is PairGroup, round diff, stop policy, the blocked decision lane, the QA / QC gate, and a basic Design Dashboard. The third stage is the Open Design bridge, the capability registry, scope assignment, user-triggered update, context compaction, and visibility control. The fourth stage is enterprise hardening, which organizes adapter smoke tests, provider failure classification, alerting, backup/export, metrics, and advanced RBAC. This order has the lowest risk because it first leverages Paperclip's control plane, then layers operating discipline with the issueflow philosophy, and then expands with Open Design and external capabilities.
The MVP acceptance criteria are best fixed as follows.
- Bootstrap must be possible for both new and existing projects. The former newly creates plan/anchor/backlog/proof; the latter scans the repo and tracker to generate current state and backlog.
- When the user requests in natural language, the Planner Agent must be able to create a draft or ready issue regardless of any ongoing process.
- WorkOwner must support two kinds,
SingleAgentandPairGroup, and a PairGroup must leave a maximum of 10 rounds, a stop reason, per-round diffs, and a cost total. - The UI UX Agent must be able to generate an Open Design-based preview, and must manage current / deprecated screens distinctly in the Design Dashboard.
- The Developer Agent must take an issue-level vertical slice by default, and must be able to dispatch independent lanes in a parallel worktree manner.
- The QA / QC Auditor must not be able to mark something done without a proof bundle, and must be able to leave a qualitative quality verdict as well.
- The Capability Registry must be able to assign external skill/plugin/MCP/design system to a company or a specific agent scope, and must support user-triggered update and visibility states.
- The Usage Center must show, per provider, the recent usage, remaining quota, and warning status along with one of the accuracy badges
Exact,Synced,Estimated. PLAN_ANCHOR,CURRENT_STATE, and the capability index must be maintained without context overflow, following the compaction policy and the on-demand loading policy.- Every mutating action, approval, provider sync, capability install/update, and done verdict must be queryable as an audit trail.
If these criteria are satisfied, this product can function no longer as "a dashboard with many agents" but as a user-centered multi-agent operations platform that actually runs projects. Only then do Paperclip's control plane, issueflow's issue philosophy, Open Design's design engine, and the human-centered company model the user requested come together as one coherent product.