AgentCompany/docs/01-project-manager-scope.md

Phase 1: ProjectManager Scope And Milestones

Product Frame

• Product working name: AgentCompany
• Product type: cross-platform Electron desktop application
• Platform target: macOS, Windows, Linux
• Primary mode: local-first single-operator control plane
• Product goal: run a multi-agent company from one desktop application with explicit control over connectors, workspaces, tasks, runs, approvals, budgets, logs, and recovery

Scope Source

• Existing Paperclip concept from doc/GOAL.md, doc/PRODUCT.md, doc/SPEC-implementation.md
• Rebuild constraints and product direction from /Users/zacharyzhang/Documents/Github/paperclip/PRD.md

Supported MVP Domains

• Local profile with backup and restore
• Multi-company local data model
• Connector registry with capability matrix
• Agent registry and org tree
• Goals, projects, tasks, lineage
• Run orchestration with session persistence and live console
• Approval queue and governance actions
• Cost tracking and budget hard-stop behavior
• Activity timeline and run diagnostics
• Workspace and repository management
• Secret management with OS-backed encryption where available
• Packaging, signing configuration, updater wiring, and crash-safe recovery hooks

Explicit Platform Decision

AgentCompany targets all three desktop platforms in the first implementation.

Platform-specific constraints that must be handled intentionally:

• macOS:
  • standard traffic-light window controls
  • Cmd modifiers in menus and shortcuts
  • notification permission behavior
  • notarization and Developer ID signing requirements
  • safeStorage may block while Keychain access is resolved
• Windows:
  • NSIS installer target
  • Ctrl modifiers in menus and shortcuts
  • AppUserModelID and toast notification expectations
  • code signing certificate requirement for trusted distribution
• Linux:
  • AppImage target with optional deb/rpm later
  • tray behavior differs by desktop environment
  • safeStorage backend may degrade to basic_text, so fallback vault behavior must stay explicit

Delivery Milestones

1. Architecture Freeze

Feature scope:

• final process model
• profile/storage layout
• IPC contract surface
• connector capability model
• initial screen map

Dependencies:

• PRD audit
• Electron security research
• platform packaging research

Acceptance criteria:

• architecture docs complete
• privileged boundaries defined
• no renderer-to-Node direct access

2. Interactive Prototype

Feature scope:

• shell window
• top nav + sidebar + utility drawer
• onboarding flow
• fake local data rendered from real repositories/services

Dependencies:

• design system
• typed preload bridge
• renderer route skeleton

Acceptance criteria:

• navigable desktop shell
• keyboard navigation baseline
• console drawer and inspector patterns established

3. Internal Alpha

Feature scope:

• local SQLite profile
• connectors registry and environment checks
• agents/tasks/approvals/workspaces CRUD
• utility-process orchestrator
• real run launch for supported local connectors

Dependencies:

• repository layer
• connector host
• activity logging

Acceptance criteria:

• launch first task run from onboarding
• view live logs
• persist app state across restart

4. Cross-Platform Validation

Feature scope:

• window/menu differences
• path handling
• notifications
• backup/restore
• crash recovery path

Dependencies:

• packaged test builds
• platform QA checklist

Acceptance criteria:

• app boots and navigates on macOS, Windows, Linux
• core workflows verified on each target

5. Signed Beta Build

Feature scope:

• electron-builder config
• signing env handling
• updater channel wiring
• production logging paths

Dependencies:

• build pipeline
• signing assets

Acceptance criteria:

• signed distributables generated
• updater checks optional and disableable
• release metadata generated

6. Release Candidate

Feature scope:

• performance pass
• memory/resource leak pass
• e2e coverage for critical flows
• security audit fixes

Dependencies:

• alpha feedback
• perf instrumentation

Acceptance criteria:

• no known critical security issue
• no crash in scripted happy path flows
• startup and live console remain responsive under load

7. Production Release Readiness

Feature scope:

• release checklist
• support docs
• backup guidance
• known limitations register

Dependencies:

• verification results
• signing and packaging validation

Acceptance criteria:

• typecheck/build/tests pass or deviations are explicitly recorded
• security and packaging docs complete
• final manual QA checklist complete

Feature Sequencing Rules

• Connector execution begins only after IPC and orchestration boundaries are documented.
• Renderer implementation begins only after screen structure and state ownership are defined.
• Packaging config begins early, but signing and updater activation stay behind environment gating.
• Kimi support is tracked explicitly. If its runtime contract remains lower capability than other first-class connectors, the UI must declare the downgrade rather than hiding it.