doc/plans/2026-03-13-features.md
The repo already has onboard, doctor, run, deployment modes, and even agent-oriented onboarding text/skills endpoints, but there are also current onboarding/auth validation issues and an open “onboard failed” report. That means this is not just polish; it is product-critical. (GitHub)
Replace “configuration-first onboarding” with interview-first onboarding.
On first run, show an interview:
type OnboardingProfile = {
useCase: "startup" | "agency" | "internal_team";
companySource: "new" | "existing";
deployMode: "local_solo" | "shared_private" | "shared_public";
autonomyMode: "hands_on" | "hybrid" | "full_auto";
primaryRuntime: "claude_code" | "codex" | "openclaw" | "other";
};
Questions:
Then Paperclip should:
detect installed CLIs/providers/subscriptions
recommend the matching deployment/auth mode
generate a local onboarding.txt / LLM handoff prompt
offer a button: “Open this in Claude / copy setup prompt”
create starter objects:
GET /api/onboarding/recommendationGET /api/onboarding/llm-handoff.txtThere is a real tension here: the transcript says users want “chat with my CEO,” while the public product definition says Paperclip is not a chatbot and V1 communication is tasks + comments only. At the same time, the repo is already exploring plugin infrastructure and even a chat plugin via plugin SSE streaming. The clean resolution is: make the core surface conversational, but keep the data model task/thread-centric; reserve full chat as an optional plugin. (GitHub)
Build a Command Composer backed by issues/comments/approvals, not a separate chat subsystem.
Add a global composer with modes:
type ComposerMode = "ask" | "task" | "decision";
type ThreadScope = "company" | "project" | "issue" | "agent";
Examples:
strategy issue/thread scoped to the company.Add issue kinds:
type IssueKind = "task" | "strategy" | "question" | "decision";
Prefer extending existing issues rather than creating chats:
issues.kindissues.scopeissues.target_agent_idcomment.intent = hint | correction | board_question | board_decisionThe core product promise is already visibility and governance, but right now the transcript makes clear that the UI is still too close to raw agent execution. The repo already has org charts, activity, heartbeat runs, costs, and agent detail surfaces; the missing piece is the explanatory layer above them. (GitHub)
Default the UI to human-readable operational summaries, with raw logs one layer down.
Company page:
Agent page:
Run page:
Generate a run view model from current run/activity data:
type RunSummary = {
runId: string;
headline: string;
objective: string | null;
currentStep: string | null;
completedSteps: string[];
delegatedTo: { agentId: string; issueId?: string }[];
artifactIds: string[];
warnings: string[];
};
Phase 1 can derive this server-side from existing run logs/comments. Persist only if needed later.
This gap is already showing up in the repo. Storage is present, attachment endpoints exist, but current issues show that attachments are still effectively image-centric and comment attachment rendering is incomplete. At the same time, your transcript wants plans, docs, files, and generated web pages surfaced cleanly. (GitHub)
Introduce a first-class Artifact model that unifies:
type ArtifactKind = "attachment" | "workspace_file" | "preview" | "report_link";
interface Artifact {
id: string;
companyId: string;
issueId?: string;
runId?: string;
agentId?: string;
kind: ArtifactKind;
title: string;
mimeType?: string;
filename?: string;
sizeBytes?: number;
storageKind: "local_disk" | "s3" | "external_url";
contentPath?: string;
previewUrl?: string;
metadata: Record<string, unknown>;
}
Issue page gets a Deliverables section:
Project page gets a Files tab:
For HTML/static outputs:
.md, .txt, .json, .csv, .pdf, and .html.The repo already has a clear deployment story in docs: local_trusted, authenticated/private, and authenticated/public, plus Tailscale guidance. The roadmap explicitly calls out cloud agents like Cursor / e2b. That means the next step is not inventing a deployment model; it is making the shared/cloud path canonical and production-usable. (GitHub)
Make shared/private deploy and public/cloud deploy first-class supported modes, and add remote runtime drivers for cloud-executed agents.
Separate control plane from execution runtime more explicitly:
type RuntimeDriver = "local_process" | "remote_sandbox" | "webhook";
interface ExecutionHandle {
externalRunId: string;
status: "queued" | "running" | "completed" | "failed" | "cancelled";
previewUrl?: string;
logsUrl?: string;
}
First remote driver: remote_sandbox for e2b-style execution.
canonical deploy recipes:
runtime health page
adapter/runtime capability matrix
one official reference deployment path
New “Deployment” settings page:
doctor catches missing public/private config and gives concrete fixes.This is the biggest deliberate departure from the current V1 spec. Publicly, V1 still says “single human board operator” and puts role-based human granularity out of scope. But the transcript is right that shared use is necessary if Paperclip is going to be real for teams. The key is to do a minimal collaboration model, not a giant permission system. (GitHub)
Ship coarse multi-user company memberships, not fine-grained enterprise RBAC.
type CompanyRole = "owner" | "admin" | "operator" | "viewer";
interface CompanyMembership {
userId: string;
companyId: string;
role: CompanyRole;
invitedByUserId: string;
createdAt: string;
}
Stretch goal later:
This is a product behavior issue, not a UI nicety. If agents cannot keep working or accept course correction without restarting, the autonomy model feels fake.
Make auto mode and mid-run interruption first-class runtime semantics.
type RunState =
| "queued"
| "running"
| "waiting_approval"
| "waiting_input"
| "paused"
| "completed"
| "failed"
| "cancelled";
Add board interjections as resumable input events:
interface RunMessage {
runId: string;
authorUserId: string;
mode: "hint" | "correction" | "hard_override";
body: string;
resumeCurrentSession: boolean;
}
Buttons on active run:
Interrupt opens a small composer that explicitly says:
This is probably the most important immediate workstream. The transcript says token burn is the highest pain, and the repo currently has active issues around budget enforcement evidence, onboarding/auth validation, and circuit-breaker style waste prevention. Public docs already promise hard budgets, and the issue tracker is pointing at the missing operational protections. (GitHub)
Treat this as a P0 runtime contract, not a nice-to-have.
Do cheap, explicit work detection before invoking an LLM.
type WakeReason =
| "new_assignment"
| "new_comment"
| "mention"
| "approval_resolved"
| "scheduled_scan"
| "manual";
Rules:
Keep the existing public promise, but make it undeniable:
Add per-agent runtime guards:
interface CircuitBreakerConfig {
enabled: boolean;
maxConsecutiveNoProgress: number;
maxConsecutiveFailures: number;
tokenVelocityMultiplier: number;
}
Trip when:
Split current orchestration into modules:
Mandatory automated proofs for:
This is the right way to resolve the code-workflow debate. The repo already has worktree-local instances, project workspaceStrategy.provisionCommand, and an RFC for adapter-level git worktree isolation. That is the correct architectural direction: project execution policies and workspace isolation, not built-in PR review. (GitHub)
Paperclip should manage the issue → workspace → preview/PR → review handoff lifecycle, but leave diffs/review/merge to external tools.
Prefer repo-local project config:
# .paperclip/project.yml
execution:
workspaceStrategy: shared | worktree | ephemeral_container
deliveryMode: artifact | preview | pull_request
provisionCommand: "pnpm install"
teardownCommand: "pnpm clean"
preview:
command: "pnpm dev --port $PAPERCLIP_PREVIEW_PORT"
healthPath: "/"
ttlMinutes: 120
vcs:
provider: github
repo: owner/repo
prPerIssue: true
baseBranch: main
deliveryMode=artifactdeliveryMode=previewdeliveryMode=pull_requestprPerIssue=true, one issue maps to one isolated branch/worktreeIssue page shows:
workspace link/status
preview URL if available
PR URL if created
“Reopen preview” button with TTL
lifecycle:
todoin_progressin_reviewdoneThe roadmap already includes plugins, GitHub discussions are active around it, and there is an open issue proposing an SSE bridge specifically to enable streaming plugin UIs such as chat, logs, and monitors. This is exactly the right place for optional surfaces. (GitHub)
Keep the control-plane core thin; put optional high-variance experiences into plugins.
interface PluginManifest {
id: string;
version: string;
requestedPermissions: (
| "read_company"
| "read_issue"
| "write_issue_comment"
| "create_issue"
| "stream_ui"
)[];
surfaces: ("company_home" | "issue_panel" | "agent_panel" | "sidebar")[];
workerEntry: string;
uiEntry: string;
}
Given the repo state and the transcript, I would sequence it like this:
P0
P1 5. Board command surface 6. Visibility/explainability layer 7. Auto mode + interrupt/resume 8. Minimal multi-user collaboration
P2 9. Project workspace / preview / PR lifecycle 10. Plugin system + optional chat plugin 11. Template/preset expansion for startup vs agency vs internal-team onboarding
Why this order: the current repo is already getting pressure on onboarding failures, auth/onboarding validation, budget enforcement, and wasted token burn. If those are shaky, everything else feels impressive but unsafe. (GitHub)
The best synthesis is:
That keeps the repo’s current product direction intact while solving almost every pain surfaced in the transcript.