Legionis: Definitive Execution Plan

Version: 3.0 (supersedes execution-plan.md V2.2) Date: 2026-02-13 Owner: Yohay Etsion Status: GO — the build guide Aligned To: PRD V1.5, Architecture Stack V1.4, System Prompt Deep Dive, Vercel Constraints Deep Dive

How to Use This Document

This is the step-by-step build plan. Each phase has a clear entry gate, specific deliverables, file-level implementation tasks, test criteria, and an exit gate. Open this before every build session, check off what's done, pick up where you left off.

Builder: Yohay + Claude Code (backend, architecture, integration) + Cursor (frontend UI, rapid iteration) Pace: ~15-20 hrs/week Total MVP: 8-10 weeks

Architecture Summary (Reference)

Layer	Technology	Package
Frontend	Next.js 14+ (App Router)	`next`
Styling	Tailwind CSS 4 + Radix UI	`tailwindcss`, `@radix-ui/*`
Client State	Zustand	`zustand`
Server State	TanStack Query	`@tanstack/react-query`
Agent Runtime	Vercel AI SDK v6	`ai`, `@ai-sdk/anthropic`, `@ai-sdk/openai`
Database	PostgreSQL 16 (Neon)	`@neondatabase/serverless`, `drizzle-orm`
ORM	Drizzle	`drizzle-orm`, `drizzle-kit`
Auth	Clerk	`@clerk/nextjs`
Payments	Stripe	`stripe`, `@stripe/stripe-js`
Cloud Storage	Google Drive API v3	`googleapis`
Search	Typesense	`typesense`
Object Storage	Cloudflare R2	`@aws-sdk/client-s3` (S3-compatible)
Monitoring	Sentry	`@sentry/nextjs`
Analytics	PostHog	`posthog-js`

Hosting: Vercel (single deployment — frontend + API routes) Monthly infra: ~$162

Pre-Development: Project Setup (Day 0)

P0.1 — Repository & Scaffold

npx create-next-app@latest legionis \
  --typescript --tailwind --app --src-dir \
  --import-alias "@/*"
cd legionis
git init && git add -A && git commit -m "Initial scaffold"

Directory structure (target):

legionis/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── (auth)/             # Auth pages (sign-in, sign-up)
│   │   ├── (dashboard)/        # Main app (workspace, chat, settings)
│   │   ├── api/                # API routes
│   │   │   ├── chat/           # Agent/skill execution endpoint
│   │   │   ├── drive/          # Google Drive proxy routes
│   │   │   ├── webhooks/       # Stripe, Clerk webhooks
│   │   │   └── health/         # Health check
│   │   └── layout.tsx          # Root layout
│   ├── components/             # React components
│   │   ├── chat/               # Chat UI components
│   │   ├── explorer/           # File explorer components
│   │   ├── shared/             # Shared/common components
│   │   └── ui/                 # Radix-based primitives
│   ├── lib/                    # Core libraries
│   │   ├── agent/              # Agent runtime (Vercel AI SDK wrappers)
│   │   ├── db/                 # Drizzle schema + queries
│   │   ├── drive/              # Google Drive client
│   │   ├── prompt/             # Prompt compilation + caching
│   │   ├── stripe/             # Stripe helpers
│   │   └── utils/              # Shared utilities
│   ├── tools/                  # Custom AI SDK tool definitions
│   │   ├── read-file.ts
│   │   ├── write-file.ts
│   │   ├── edit-file.ts
│   │   ├── glob-files.ts
│   │   ├── grep-content.ts
│   │   ├── list-directory.ts
│   │   └── spawn-agent.ts
│   ├── personas/               # Compiled agent personas (build output)
│   └── middleware.ts           # Clerk auth middleware
├── scripts/
│   ├── compile-prompts.ts      # SKILL.md → compiled persona JSON
│   ├── seed-skills.ts          # Seed skill metadata into DB
│   └── migrate.ts              # DB migration runner
├── drizzle/                    # Migration files
├── os-source/                  # Git submodules for OS content
│   ├── product-org-os/         # PUBLIC submodule: 13 agents, 61 skills, 9 knowledge packs
│   └── extension-teams/        # PRIVATE submodule: 68 agents, 34 knowledge packs, 15 integrations
├── public/
├── .env.local                  # Local env vars (not committed)
├── drizzle.config.ts
├── next.config.ts
├── tailwind.config.ts
└── tsconfig.json

P0.2 — External Service Accounts

Create accounts and collect credentials before writing code:

Service	Action	Env Var(s)	Status
Vercel	Create project, link repo	Auto-configured via `vercel link`	✅ Done
Neon	Create project + database	`DATABASE_URL`	✅ Done
Clerk	Create application (Google + MS + LinkedIn + email)	`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`	✅ Done
Stripe	Create products + prices ($10/$7/$5/$25) + trial config	`STRIPE_SECRET_KEY`, `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`, `STRIPE_WEBHOOK_SECRET`, 4x `STRIPE_*_PRICE_ID`	✅ Done (test mode)
Google Cloud	Create OAuth 2.0 client (Drive API scopes)	`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`	✅ Done
Cloudflare R2	Create bucket	`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`	Pending (Week 4)
Typesense	Create cloud cluster	`TYPESENSE_HOST`, `TYPESENSE_API_KEY`	Pending (Week 8)
Sentry	Create Next.js project	`SENTRY_DSN`	Pending (Week 8)
PostHog	Create project	`NEXT_PUBLIC_POSTHOG_KEY`	Pending (Week 8)

5 of 9 services configured (Feb 14). Remaining 4 are not needed until later phases.

>

Vercel env vars complete (Feb 16): All 16 production env vars added to Vercel dashboard (Production + Preview + Development). Includes: Clerk (7), Neon (1), Stripe (7), Google Drive (3 + ENCRYPTION_KEY). GCP redirect URI also added to OAuth client.

P0.3 — OS Source Integration ✅

Both content sources are integrated as git submodules (open core model):

os-source/
├── product-org-os/           ← PUBLIC submodule (yohayetsion/product-org-os @ v3.0.1)
│   └── product-org-plugin/
│       ├── skills/           # 13 OS agent personas + 61 skill templates
│       ├── rules/            # 22 rules files
│       ├── reference/knowledge/  # 9 knowledge packs
│       └── integrations/     # 6 integration templates
└── extension-teams/          ← PRIVATE submodule (yohayetsion/extension-teams)
    ├── {9 team dirs}/        # 68 Extension Team agent SKILL.md files
    ├── reference/knowledge/  # 34 knowledge packs
    └── integrations/         # 15 integration templates

Update workflow: cd os-source/ && git pull && cd ../.. && git add os-source/ && git commit

Status: ✅ Done (Feb 15). Submodules pinned, 81 total agents available for compile-prompts.

P0.4 — Initial Deploy ✅

Push scaffold to Vercel. Verify https://legionis.vercel.app (or custom domain) shows the default Next.js page. This is the "it deploys" checkpoint.

Completed Feb 13 — commit 2348bec. legionis.vercel.app live. Auto-deploys on push.

Exit gate: Repo exists, deploys to Vercel, all external accounts created with env vars in .env.local and Vercel project settings.

Substantially met. 5/9 services configured, all deployed to Vercel (Feb 16). Remaining 4 (R2, Typesense, Sentry, PostHog) not needed until later phases.

Phase 1: Foundation (Weeks 1-2)

Week 1: Auth + Database + Billing

Goal: User can sign up, see a dashboard, subscribe, and hit a billing wall. No AI yet.

1.1 Database Schema (Neon + Drizzle)

Create src/lib/db/schema.ts:

// Core tables — define with drizzle-orm
users               // Clerk user ID, email, created_at, subscription_status
workspaces          // id, user_id, name, drive_folder_id, drive_access_token (encrypted), created_at
api_keys            // id, user_id, provider (anthropic|openai), encrypted_key, last_four, validated_at
conversations       // id, workspace_id, title, created_at, updated_at
messages            // id, conversation_id, role (user|assistant|system|tool), content, metadata, created_at
context_entries     // id, workspace_id, type (decision|bet|feedback|learning), entry_id (DR-YYYY-NNN), title, content, metadata (JSON), created_at
file_references     // id, workspace_id, drive_file_id, path, name, mime_type, context_entry_id (optional)
subscriptions       // id, user_id, stripe_customer_id, stripe_subscription_id, plan, status, trial_ends_at, current_period_end

Tasks:

✓ Define Drizzle schema in src/lib/db/schema.ts

✓ Generate initial migration: drizzle-kit generate

✓ Run migration against Neon: drizzle-kit migrate

✓ Create src/lib/db/index.ts — Neon serverless client + Drizzle instance

✓ Create src/lib/db/queries/ — typed query helpers per table

Completed Feb 14 — commit c78bd8d. 8 tables: users, workspaces, api_keys, conversations, messages, context_entries, file_references, subscriptions. Migration 0000_whole_wonder_man.sql.

1.2 Authentication (Clerk)

Tasks:

✓ Install @clerk/nextjs

✓ Add to root layout

✓ Create src/middleware.ts — protect /dashboard/* routes, allow /sign-in, /sign-up, /api/webhooks

✓ Create src/app/(auth)/sign-in/[[...sign-in]]/page.tsx

✓ Create src/app/(auth)/sign-up/[[...sign-up]]/page.tsx

✓ Create src/app/api/webhooks/clerk/route.ts — sync user creation to users table

✓ Test: sign up with email, sign up with Google, verify session persistence

Completed Feb 14 — commit c78bd8d. Svix signature verification on webhook. User CRUD in src/lib/db/queries/users.ts. Root page auth-aware redirect. Tested: Google sign-in → dashboard → Neon user row verified.

1.3 Billing (Stripe)

Tasks:

✓ Create Stripe products: "Legionis Individual" ($10/mo), "Legionis Team" ($7/seat/mo, min 3), "Add-on Team" (+$5/mo), "Full Organization" ($25/mo)

✓ Configure 1-month free trial on all products

✓ Create src/app/api/webhooks/stripe/route.ts — handle checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed

✓ Create src/lib/stripe/checkout.ts — create checkout session

✓ Create src/lib/stripe/portal.ts — create billing portal session

☐ Create subscription gating middleware: check subscriptions.status before agent execution

✓ Create src/app/dashboard/settings/billing/page.tsx + billing-client.tsx — plan display, trial countdown, upgrade CTA

☐ Test: sign up → 30-day trial active → trial expiry → read-only state → subscribe → active

Completed Feb 14 — commit ac749da. Stripe account "Legionis" (test mode). 4 products created via API. Webhook endpoint registered at https://legionis.vercel.app/api/webhooks/stripe. Full billing UI with plan cards, status badges, checkout buttons, portal link. Price IDs: individual price_1T0lKDCzBUEHrjdqtWL8qlKl, team price_1T0m4eCzBUEHrjdqpARE8Ym2, addon price_1T0m4nCzBUEHrjdqynA3See4, full-org price_1T0m4xCzBUEHrjdqbxtseHCp.

>

Note: Pricing updated from plan's $10/$8 to actual Agent Catalog pricing: $10/$7/$5/$25. Subscription gating middleware deferred — will implement when chat API route is built (Week 2).

>

~~Action needed: Add 7 Stripe env vars to Vercel dashboard.~~ ✅ Done (Feb 16).

1.4 Dashboard Shell

Tasks:

✓ Create src/app/dashboard/layout.tsx — sidebar + main content area

✓ Sidebar: workspace selector (Radix DropdownMenu), conversation list (Radix ScrollArea), file explorer (placeholder with "Soon" label), settings link

✓ Create src/app/dashboard/page.tsx — personalized greeting from DB, QuickAction cards

✓ Create src/app/dashboard/settings/page.tsx + layout.tsx — settings layout with tabbed nav (Profile, API Keys, Billing, Storage) using lucide-react icons

✓ Install and configure Radix UI primitives: DropdownMenu, ScrollArea (Dialog, Tooltip, Tabs available but not yet used)

✓ Dark theme by default (Tailwind dark mode — zinc-900 palette)

Completed Feb 14 — commit ce76779. Also created: settings/api-keys/page.tsx (Anthropic + OpenAI cards, disabled), settings/storage/page.tsx (Drive connection placeholder). Clerk UserButton integrated in sidebar. lucide-react installed for icons.

Week 1 Exit Gate:

✓ User can sign up (email or Google)

✓ User lands on dashboard with sidebar

✓ Stripe trial is active (30 days)

☐ Subscription gating works (read-only after trial without payment) — deferred to Week 2 chat API

✓ Settings page shows billing status

✓ Database has correct schema, migrations run cleanly

✓ Deploys to Vercel successfully

Week 1 substantially complete. One exit gate item (subscription gating) deferred to Week 2 — it requires the chat API route to gate against.

Week 2: Agent Runtime Core + Custom Tools

Goal: A single agent (PM) can receive a message, use tools to read/write files in memory, and stream a response. No Google Drive yet — local/mock storage first.

2.1 Prompt Compiler (`compile-prompts.ts`)

The build script that transforms OS source into SaaS-ready prompts. This is the bridge between the open-source plugin and the SaaS product.

Input: os-source/product-org-os/product-org-plugin/skills//SKILL.md + os-source/extension-teams//SKILL.md + os-source/product-org-os/product-org-plugin/rules/*.md Output: src/personas/compiled-personas.json + src/personas/compiled-rules.json

Three-layer architecture (from system prompt deep dive):

Layer	Content	Tokens	Caching
L1: Core Protocol	Compiled rules (response format, routing, V2V, context, delegation, principles, meeting mode, no-fabrication)	~1,500	Global cache (all users, all agents)
L2: Agent Persona	Compressed SKILL.md (identity, how-I-think, RACI, deliverables, collaboration, skills, V2V phase)	~500	Per-agent cache (shared across users)
L3: Domain Rules	Conditional rules (decision-system, strategy, roadmaps, GTM, requirements, maturity, auto-context, context-graph) + knowledge packs	~300-500	Per-task (loaded based on skill/domain)

Tasks:

☐ Create scripts/compile-prompts.ts
☐ Parse YAML frontmatter from SKILL.md files (extract name, description, skills list, allowed-tools)
☐ Extract agent-specific sections (Identity, How I Think, RACI, Key Deliverables, Collaboration, Primary Skills, V2V Phase)
☐ Strip shared boilerplate (Response Format, Sub-Agent Spawning, Context Awareness, Feedback Capture sections — these go into L1)
☐ Compile L1 core protocol from Tier 1 rules (10 files → single compressed document, ~1,500 tokens)
☐ Compile L2 per-agent personas (39 agents → 39 compressed persona objects, ~500 tokens each)
☐ Compile L3 domain rules (Tier 2 rules → 8 conditional modules, ~300-500 tokens each)
☐ Compile knowledge packs (22 packs → indexed by agent domain)
☐ Output: compiled-personas.json with structure:

  {
    "coreProtocol": "...(L1 text)...",
    "agents": {
      "product-manager": { "persona": "...(L2)", "skills": [...], "primaryPhases": [...], "emoji": "📝", "displayName": "Product Manager" },
      ...
    },
    "domainRules": {
      "decisions": "...(L3 conditional)...",
      "strategy": "...",
      ...
    },
    "knowledgePacks": {
      "prioritization": "...",
      "pricing-frameworks": "...",
      ...
    },
    "skillTemplates": {
      "prd": { "description": "...", "template": "...", "phase": 3 },
      ...
    }
  }

☐ Add compile-prompts to package.json scripts — runs as prebuild step
☐ Test: output validates, token counts match expectations

2.2 Agent Runtime (`src/lib/agent/`)

The core engine that executes agents using Vercel AI SDK.

src/lib/agent/runtime.ts — Main agent execution:

// Core function signature
async function executeAgent(params: {
  agentKey: string;           // "product-manager", "vp-product", etc.
  userMessage: string;        // User's input
  conversationHistory: Message[];
  workspace: Workspace;       // Drive connection, file context
  apiKey: string;             // User's decrypted API key
  provider: 'anthropic' | 'openai';
  model: string;              // "claude-sonnet-4-5-20250929", etc.
  onStream?: (chunk: string) => void;
}): Promise

Tasks:

☐ Create src/lib/agent/runtime.ts — main executeAgent() function
☐ Implement system prompt assembly: L1 (core) + L2 (agent persona) + L3 (domain rules, conditional on task)
☐ Implement Anthropic prompt caching: cache_control: { type: "ephemeral" } on L1 and L2 blocks
☐ Create src/lib/agent/provider-factory.ts — create provider instance from user's API key:

  // Per-request provider creation (BYOT)
  function createProvider(apiKey: string, provider: 'anthropic' | 'openai') {
    if (provider === 'anthropic') return createAnthropic({ apiKey });
    if (provider === 'openai') return createOpenAI({ apiKey });
  }

☐ Create src/lib/agent/tools.ts — register all custom tools with the agent
☐ Implement generateText() call with maxSteps: 15 and tool definitions
☐ Implement streamText() variant for streaming responses
☐ Implement onStepFinish hook for tool call logging
☐ Implement onFinish hook for usage tracking and ROI calculation
☐ Test: PM agent receives "create a PRD outline for authentication" → streams response with persona header

2.3 Custom Tool Definitions (`src/tools/`)

These replace Claude Code's built-in Read, Write, Edit, Glob, Grep. In MVP, they operate on an in-memory file system (Week 4 swaps to Google Drive).

src/tools/read-file.ts:

export const readFileTool = tool({
  description: 'Read a file from the workspace',
  parameters: z.object({
    path: z.string().describe('File path relative to workspace root'),
  }),
  execute: async ({ path }, { workspace }) => {
    return await workspace.readFile(path);
  }
});

Tasks:

☐ Create src/tools/read-file.ts — read file contents by path
☐ Create src/tools/write-file.ts — create or overwrite file at path
☐ Create src/tools/edit-file.ts — find-and-replace in file (old_string → new_string)
☐ Create src/tools/glob-files.ts — list files matching glob pattern
☐ Create src/tools/grep-content.ts — search file contents with regex
☐ Create src/tools/list-directory.ts — list directory contents
☐ Create src/tools/spawn-agent.ts — spawn a sub-agent (nested generateText() call)
☐ Create src/lib/workspace/memory-fs.ts — in-memory file system for testing (Week 4 replaces with Drive)
☐ Test: agent can read, write, edit, search files. Tool calls appear in response stream.

2.4 Chat API Route

src/app/api/chat/route.ts:

export async function POST(req: Request) {
  // 1. Auth check (Clerk)
  // 2. Get workspace + API key for user
  // 3. Determine agent (from @mention or auto-route)
  // 4. Assemble system prompt (L1 + L2 + L3)
  // 5. Call streamText() with tools
  // 6. Return SSE stream via .toDataStreamResponse()
}

Tasks:

☐ Create src/app/api/chat/route.ts
☐ Auth middleware: verify Clerk JWT, get user_id
☐ Subscription gate: verify trial active or paid subscription
☐ API key decryption: retrieve and decrypt user's API key
☐ Agent selection: parse @agent mention or apply auto-routing
☐ System prompt assembly with caching markers
☐ streamText() call with all tools registered
☐ Return .toDataStreamResponse() for SSE streaming
☐ Error handling: invalid API key, rate limits, model errors
☐ Test: POST to /api/chat with PM agent → streamed response

Week 2 Exit Gate:

☐ compile-prompts.ts produces valid compiled output from OS source
☐ PM agent responds in character ("📝 Product Manager: ...")
☐ Agent can use file tools (read, write, edit, search) on in-memory FS
☐ Streaming works — tokens appear progressively
☐ API key validation works (rejects bad keys with clear error)
☐ Prompt caching headers set correctly for L1/L2

Phase 2: Core Product (Weeks 3-4)

Week 3: Chat UI + Skill Dispatch + Persona System

Goal: Working chat interface where a user can type messages, invoke skills with /, mention agents with @, and see streaming responses with agent identity.

3.1 Chat Interface (`src/components/chat/`)

Tasks:

☐ Create src/components/chat/chat-container.tsx — main chat area with message list + input
☐ Create src/components/chat/message.tsx — individual message rendering (user vs assistant)
☐ Create src/components/chat/agent-message.tsx — agent-styled message with emoji + display name header
☐ Create src/components/chat/streaming-message.tsx — renders tokens as they arrive via useChat hook
☐ Create src/components/chat/tool-call-indicator.tsx — inline "📁 Reading file..." indicators
☐ Create src/components/chat/input.tsx — text input with submit button, keyboard shortcuts (Cmd+Enter)
☐ Create src/components/chat/meeting-mode.tsx — PLT/gateway multi-agent response display (collapsible sections, alignment/tension/synthesis)
☐ Integrate useChat from ai/react for streaming
☐ Markdown rendering in messages (tables, code blocks, headers, lists)
☐ Auto-scroll to bottom on new content
☐ Test: type message → see streaming response with agent header

3.2 Skill Palette

Tasks:

☐ Create src/components/chat/skill-palette.tsx — command palette triggered by / key
☐ Load all 61 skills from compiled personas (name, description, argument-hint)
☐ Fuzzy search filtering (as user types after /)
☐ Skill categories: group by V2V phase
☐ Tooltip on hover: description + example usage
☐ Select skill → insert into input: /prd with cursor positioned for argument
☐ Test: type / → palette appears → filter to "de" → see decision-record, decision-charter → select → inserted

3.3 Agent Selector

Tasks:

☐ Create src/components/chat/agent-selector.tsx — selector triggered by @ key
☐ Show all 39 agents grouped: OS Agents (13), Design Team (6), Architecture Team (6), Marketing Team (14)
☐ Each entry: emoji + display name + short description
☐ Gateways at top: @product, @plt, @design, @architecture, @marketing
☐ Select agent → insert into input: @pm with cursor positioned
☐ Test: type @ → selector appears → filter to "biz" → see @bizops, @bizdev → select

3.4 Skill Dispatch System

When user invokes /prd authentication, the system must:

Parse the skill name

Load the skill template

Inject the template as a specialized system prompt addition

Execute with the agent runtime

Tasks:

☐ Create src/lib/agent/skill-dispatcher.ts:

- Parse /skill-name [arguments] from user input - Look up skill template from compiled personas - Determine owning agent (from SKILL.md frontmatter) - Inject skill template into system prompt as additional context - Execute via executeAgent() with skill context

☐ Create src/lib/agent/auto-router.ts:

- Parse user input for domain keywords - Match against routing table (from compiled personas) - Return recommended agent key - Support explicit @agent override

☐ Test: /prd authentication → executes as PM with PRD template → produces PRD output

3.5 All 39 Agent Personas

Tasks:

☐ Verify compile-prompts.ts correctly processes all 39 SKILL.md files:

- 13 OS agents: pm, cpo, vp-product, pm-dir, pmm-dir, pmm, product-mentor, bizops, bizdev, ci, prod-ops, ux-lead, value-realization - 6 Design: design-dir, ui-designer, visual-designer, interaction-designer, user-researcher, motion-designer - 6 Architecture: chief-architect, api-architect, data-architect, security-architect, cloud-architect, ai-architect - 14 Marketing: marketing-dir, content-strategist, copywriter, seo-specialist, cro-specialist, paid-media, email-marketer, social-media, growth-hacker, market-researcher, video-producer, pr-specialist, analytics-specialist, brand-strategist

☐ Test 5 representative agents end-to-end: @pm, @vp-product, @ci, @ui-designer, @copywriter
☐ Verify each responds with correct emoji + display name
☐ Verify each stays in character and domain

Week 3 Exit Gate:

☐ Chat UI renders user and assistant messages with streaming
☐ / triggers skill palette with fuzzy search across 61 skills
☐ @ triggers agent selector with 39 agents + 5 gateways
☐ Skill dispatch executes correct skill template via correct agent
☐ Auto-routing matches domain keywords to agents
☐ 5 representative agents tested end-to-end
☐ Markdown renders correctly in messages (tables, code blocks, headers)

Week 4: Google Drive Integration

Goal: Replace in-memory filesystem with real Google Drive. User connects Drive, selects workspace folder, and all agent file operations go through Drive API.

4.1 OAuth Flow

Tasks:

☐ Create src/app/api/drive/auth/route.ts — initiate OAuth flow
☐ Create src/app/api/drive/callback/route.ts — handle OAuth callback, exchange code for tokens
☐ Scopes: https://www.googleapis.com/auth/drive.file (access to files created/opened by app)
☐ Store encrypted access + refresh tokens in workspaces table
☐ Implement token refresh logic (auto-refresh before expiry)
☐ Create src/app/(dashboard)/onboarding/drive/page.tsx — "Connect Google Drive" UI
☐ Test: click connect → Google consent screen → redirect back → tokens stored

4.2 Workspace Initialization

Tasks:

☐ Create src/lib/drive/client.ts — Google Drive API client wrapper
☐ Create src/lib/drive/workspace.ts — workspace initialization:

- List user's Drive folders for selection - Create new folder option - Create V2V context structure inside selected folder:

    [Selected Folder]/
    ├── context/
    │   ├── decisions/
    │   ├── bets/
    │   ├── feedback/
    │   ├── learnings/
    │   ├── interactions/
    │   ├── portfolio/
    │   ├── documents/
    │   ├── assumptions/
    │   ├── handoffs/
    │   ├── roi/
    │   └── index.json        # Structured context index
    └── deliverables/

- Store folder_id as workspace root in database

☐ Create src/app/(dashboard)/onboarding/workspace/page.tsx — folder selection UI
☐ Test: select folder → structure created → workspace saved with folder_id

4.3 Drive-Backed File Tools

Swap in-memory FS with real Drive API calls in all tools:

Tasks:

☐ Create src/lib/drive/operations.ts:

- readFile(folderId, path) — resolve path to file ID → download content - writeFile(folderId, path, content) — create or update file at path - editFile(folderId, path, oldStr, newStr) — download, replace, re-upload - listDirectory(folderId, path) — list files in subfolder - globFiles(folderId, pattern) — search by name pattern - grepContent(folderId, pattern, path?) — download + search content - getFileById(fileId) — direct ID-based access

☐ Implement path-to-fileId resolution: walk folder hierarchy, cache file ID mappings
☐ Implement file ID caching in file_references table (avoid repeated Drive lookups)
☐ Update all tools in src/tools/ to use Drive operations instead of memory FS
☐ Implement error handling: token expired → auto-refresh → retry
☐ Test: agent creates a file → appears in user's Google Drive → agent reads it back

4.4 File Explorer

Tasks:

☐ Create src/components/explorer/file-tree.tsx — tree view of workspace
☐ Create src/components/explorer/file-item.tsx — individual file/folder node
☐ Create src/components/explorer/file-preview.tsx — markdown preview panel
☐ Load tree from Drive API on workspace open (cache in memory)
☐ Context folders prominently displayed at top (decisions, bets, feedback...)
☐ Real-time refresh: when an agent creates a file, tree updates
☐ Click file → markdown preview in right panel
☐ Markdown renderer: tables, code blocks, headers, lists, horizontal rules
☐ Test: workspace loads → file tree shows → click file → preview renders

~~Action needed: Add GOOGLE_REDIRECT_URI=https://legionis.vercel.app/api/drive/callback to Vercel dashboard env vars.~~ ✅ Done (Feb 16). Also added https://legionis.vercel.app/api/drive/callback as authorized redirect URI in Google Cloud Console. When app.legionis.ai goes live, add that URL too.

Week 4 Exit Gate:

☐ Google Drive OAuth flow works end-to-end
☐ Workspace folder created with V2V context structure
☐ All 6 file tools operate on real Google Drive
☐ File operations are reliable (read, write, edit, list, glob, grep)
☐ File explorer shows tree view with Drive files
☐ Markdown preview renders correctly
☐ Agent creates a document → it appears in Drive AND file explorer
☐ Token refresh works (no auth failures during extended sessions)

Phase 3: Agent System (Weeks 5-6)

Week 5: BYOT + Full Agent Roster + Context Layer

Goal: All 39 agents operational with BYOT key routing. Context layer (save, recall, feedback) works against Drive storage.

5.1 API Key Management (BYOT)

Tasks:

☐ Create src/lib/crypto/envelope.ts — envelope encryption for API keys:

- Master key in env var (ENCRYPTION_MASTER_KEY) - Per-key DEK (data encryption key) generated on save - AES-256-GCM encryption

☐ Create src/app/(dashboard)/settings/api-keys/page.tsx:

- Add Anthropic API key field - Add OpenAI API key field (optional) - Show only last 4 chars after save - Validate key on save (test API call) - Clear error messages for invalid keys

☐ Create src/lib/agent/key-router.ts:

- Per-request key lookup: decrypt user's key → create provider - Model selection: user chooses default model in settings - Fallback: if Anthropic key invalid, try OpenAI (if configured)

☐ Integrate key routing into /api/chat/route.ts
☐ Create onboarding step: "Connect your API key" with link to Anthropic console
☐ Test: add key → validated → invoke agent → uses user's key → Anthropic dashboard shows usage

5.1b Quality/Efficiency Model Routing

Goal: Users control the quality-cost tradeoff with a global setting that overrides per-agent model defaults.

Three-position setting: Maximum Quality (always top-tier models) | Balanced (default — uses SKILL.md model per agent) | Maximum Efficiency (always cheapest sufficient model).

Current compiled persona model distribution: 12 agents use "sonnet" (OS agents), 69 agents use "opus" (Extension Teams). provider-factory.ts already resolves abstract model names via MODEL_MAP. The toggle intercepts agentModel before resolveModel().

Tasks:

☐ Add quality_preference column to workspaces table: enum('maximum_quality', 'balanced', 'maximum_efficiency'), default 'balanced'
☐ Create src/lib/agent/quality-override.ts:

- applyQualityPreference(preference, agentModel) → returns overridden model - maximum_quality → always returns "opus" - balanced → returns agentModel unchanged (SKILL.md default) - maximum_efficiency → always returns "haiku"

☐ Wire into executeAgent() in runtime.ts: call applyQualityPreference() before resolveModel()
☐ Create src/app/(dashboard)/settings/ai-config/page.tsx:

- Segmented control: Efficiency / Balanced (selected) / Quality - Live cost indicator below toggle: updates per position - "Customize per agent" disclosure link (expandable, initially collapsed) — shows agent list with per-agent model override dropdown (post-launch enhancement, stub only for now)

☐ Update settings layout: rename/restructure settings nav to: Profile | API Keys | AI Configuration | Connections (placeholder) | Storage | Billing
☐ Test: set Quality → all agents use opus. Set Balanced → OS agents use sonnet, ET agents use opus. Set Efficiency → all agents use haiku.

5.2 All 81 Agents Operational

Tasks:

☐ Batch test all 13 OS agents with a standard prompt: "Introduce yourself and explain your role"

- Verify emoji + display name header - Verify first-person voice - Verify domain-appropriate response

☐ Batch test all 68 Extension Team agents with same prompt
☐ Fix any persona compilation issues
☐ Verify auto-routing for 10 test prompts:

- "How should we price the enterprise tier?" → @bizops - "Write user stories for checkout" → @pm - "Analyze our competitor landscape" → @ci - "Review the API design" → @api-architect (Extension) - "Write landing page copy" → @copywriter (Extension) - (5 more domain-specific prompts)

☐ Document any routing failures and adjust routing table weights

5.3 Context Layer Implementation

The context layer is the "organizational memory" that persists across sessions. Stored in the user's Google Drive workspace.

Tasks:

☐ Create src/lib/context/manager.ts — context layer operations:

- saveDecision(workspace, decision) → write to context/decisions/YYYY/ + update index - saveBet(workspace, bet) → write to context/bets/YYYY/ + update index - saveFeedback(workspace, feedback) → write to context/feedback/YYYY/ + update index - saveLearning(workspace, learning) → write to context/learnings/index.md - recallByTopic(workspace, topic) → search index.json topicIndex - getPortfolioStatus(workspace) → read context/portfolio/active-bets.md - logInteraction(workspace, interaction) → append to daily log + update index.json

☐ Create src/lib/context/index-manager.ts:

- Read/write context/index.json (structured JSON index with topic, product, phase, status indexes) - Auto-generate IDs: DR-YYYY-NNN, SB-YYYY-NNN, FB-YYYY-NNN, etc. - Cross-reference management: link decisions ↔ bets ↔ feedback ↔ learnings

☐ Create src/lib/context/auto-inject.ts:

- Before agent produces a deliverable, query index for relevant context - Inject up to 5 relevant items as "Auto-Context" section in prompt - Skip for retrieval operations (/context-recall, /feedback-recall)

☐ Integrate context tools into agent runtime:

- /context-save → calls saveDecision or saveBet - /context-recall → calls recallByTopic - /feedback-capture → calls saveFeedback - /feedback-recall → searches feedback index - /portfolio-status → reads portfolio state

☐ Test: save a decision → recall it by topic → verify cross-references work

5.4 Legionis Tokens (Managed Token Plan)

Goal: Users who don't want to manage their own API keys can opt into Legionis Tokens — platform-provided AI at a 30% markup over provider costs. BYOT remains the default and recommended path.

Architecture: When a user selects "Managed Tokens", requests route through Legionis's pooled API keys instead of the user's own keys. Every request is metered for billing.

Tasks:

☐ Create src/lib/tokens/managed-provider.ts:

- Platform API key pool: Legionis-owned Anthropic + OpenAI keys (env vars: LEGIONIS_ANTHROPIC_KEY, LEGIONIS_OPENAI_KEY) - Provider selection logic: pick provider based on agent model + user preference - Per-request cost calculation: track input/output tokens, apply provider pricing, add 30% markup

☐ Create DB table usage_events:

  usage_events: id, user_id, workspace_id, conversation_id, agent_key, model, provider,
                input_tokens, output_tokens, provider_cost_micros, markup_micros, total_cost_micros,
                quality_preference, token_source (byot|managed), created_at

☐ Create src/lib/tokens/metering.ts:

- Log every managed-token request to usage_events table - Provider cost lookup table: current rates for all models (claude-opus, claude-sonnet, claude-haiku, gpt-4o, gpt-4o-mini) - Calculate: provider_cost = (input_tokens × input_rate) + (output_tokens × output_rate) - Calculate: markup = provider_cost × 0.30 - Calculate: total_cost = provider_cost + markup

☐ Create src/lib/tokens/spend-tracking.ts:

- Real-time spend dashboard data: daily/weekly/monthly aggregates - Spend alerts: configurable threshold (default: warn at $50/month) - Optional monthly spending cap (hard stop when reached)

☐ Update src/lib/agent/provider-factory.ts:

- Check user's token_source setting: 'byot' or 'managed' - If BYOT: use user's decrypted key (existing flow) - If Managed: use LEGIONIS_ANTHROPIC_KEY or LEGIONIS_OPENAI_KEY, enable metering

☐ Update settings UI — new "AI Configuration" page:

- Token source toggle: "Bring Your Own Keys" (default, recommended) vs "Use Legionis Tokens" - If BYOT selected: show existing API key fields - If Managed selected: show spend dashboard with current balance, usage history, cost breakdown - Clear cost comparison: "Your cost: provider rate + 30%. Example: Claude Sonnet at $3/$15 per MTok → $3.90/$19.50 with Legionis Tokens"

☐ Update billing integration:

- Managed token users: metered billing via Stripe Usage Records API - Create Stripe metered price for token consumption - Daily usage report: aggregate usage_events → report to Stripe - Monthly invoice includes: platform subscription + token usage

☐ Update onboarding flow:

- After signup, present choice as two side-by-side cards: - Card 1: "Bring Your Own Keys" — "Lower cost, full transparency. Paste your Anthropic or OpenAI API key." (recommended badge) - Card 2: "Use Legionis Tokens" — "No setup needed. 30% service fee included in your usage."

☐ Provision operational prerequisites:

- Create Legionis Anthropic account (separate from personal) with spending limits - Create Legionis OpenAI account (separate from personal) with spending limits - Store keys as LEGIONIS_ANTHROPIC_KEY and LEGIONIS_OPENAI_KEY in Vercel env vars

☐ Test: switch to managed tokens → invoke agent → see cost tracked in usage_events → see spend dashboard → verify 30% markup applied correctly → verify Stripe usage record created

5.5 Conversation Persistence

Tasks:

☐ Save messages to messages table after each turn
☐ Load conversation history on page load
☐ Create conversation list in sidebar
☐ Create new conversation button
☐ Rename and delete conversations
☐ Test: have a conversation → refresh page → conversation restored → continue chatting

Week 5 Exit Gate:

☐ BYOT key management works (add, validate, encrypt, use per-request)
☐ Quality/Efficiency toggle works: Quality → opus, Balanced → SKILL.md default, Efficiency → haiku
☐ Legionis Tokens: managed provider routes through platform keys with 30% markup metered
☐ Token source toggle: users can switch between BYOT and Managed in settings
☐ All 81 agents respond correctly to test prompts
☐ Auto-routing correctly matches 8/10 test prompts
☐ Context layer: save decision → recall by topic → returns result
☐ Cross-references: save decision mentioning a bet → link created
☐ Auto-context: invoke /prd on a topic with existing decisions → decisions surfaced
☐ Conversations persist across page refreshes

Week 6: Sub-Agents + Skill Execution + Delegation

Goal: Agents can spawn sub-agents, invoke skills, and collaborate using the 4 delegation patterns. Full skill execution pipeline works for all 61 skills.

6.1 Sub-Agent Spawning

The spawnAgent tool allows an agent to create a child agent (nested generateText() call).

Tasks:

☐ Implement src/tools/spawn-agent.ts:

- Accept: agentKey, task, context - Assemble child agent system prompt (L1 + L2 for target agent) - Execute generateText() (not streaming — parent agent consumes result) - Enforce max depth: 3 levels - Return child agent's response to parent

☐ Implement depth tracking: pass current depth through tool context, reject at depth > 3
☐ Implement delegation pattern detection:

- Parse [CONSULTATION], [DELEGATION], [REVIEW], [DEBATE] prefixes in spawn prompts - Tag child agent response with pattern type for attribution

☐ Test: @pm creates PRD → needs competitive context → spawns @ci → integrates response

6.2 Full Skill Execution Pipeline

Tasks:

☐ Verify all 61 skills are loaded in compiled personas
☐ Test skill execution for one skill per category:

- Phase 1: /strategic-intent or /market-analysis - Phase 2: /decision-record or /pricing-strategy - Phase 3: /prd or /user-story - Phase 4: /campaign-brief or /sales-enablement - Phase 5: /value-realization-report - Phase 6: /outcome-review or /retrospective - Context: /context-save, /context-recall, /feedback-capture

☐ Verify Document Intelligence modes:

- CREATE mode: /prd authentication → creates new PRD - UPDATE mode: /prd update auth PRD with MFA scope → updates existing - FIND mode: /prd find authentication → lists related PRDs

☐ Verify each skill writes output to correct workspace location:

- Decisions → context/decisions/YYYY/ - PRDs → deliverables/ (or user-specified path) - Context entries → appropriate context subfolder

☐ Test auto-registration: skill produces strategic document → auto-registered in context/documents/index.md

6.3 ROI Tracking

Tasks:

☐ Create src/lib/roi/calculator.ts:

- Map skills/agents to baseline times (from reference/roi-baselines.md) - Assess complexity: simple (0.5×), standard (1.0×), complex (1.5×), enterprise (2.0×) - Calculate: base time × complexity factor - Track elapsed time per operation

☐ Create src/lib/roi/tracker.ts:

- Per-session accumulator - Write session log to context/roi/session-log.md in workspace - Update monthly history in context/roi/history/YYYY-MM.md

☐ Display ROI line after every skill/agent completion in chat UI
☐ Format: ⏱️ ~X hrs/min saved in Ys using Nk tokens (vs. manual equivalent)
☐ Include token count (input + output) in every ROI line — users need cost transparency
☐ Test: invoke /prd → see ROI line with token count → invoke /decision-record → see updated session total

Week 6 Exit Gate:

☐ Sub-agent spawning works with depth limit (3 levels)
☐ Delegation patterns (Consultation, Delegation, Review, Debate) detected and routed
☐ At least 7 skills tested end-to-end across all V2V phases
☐ Document Intelligence (Create/Update/Find) works
☐ Skills write to correct workspace locations
☐ Auto-registration of strategic documents works
☐ ROI displayed after skill/agent completions
☐ One full workflow tested: /strategic-intent → /decision-record → /prd → context persists between all three

Phase 4: Multi-Agent & Gateway Orchestration (Weeks 7-8)

Week 7: Gateway System + PLT Meeting Mode

Goal: @product and @plt gateways work. PLT spawns 3-4 agents in parallel, displays individual perspectives with alignment/tension/synthesis.

7.1 Gateway Engine

Tasks:

☐ Create src/lib/agent/gateway.ts:

- Parse gateway invocation (@product, @plt, @design, @architecture, @marketing) - Analyze request to determine ownership complexity (SINGLE / PRIMARY+ / MULTI) - Select agents based on RACI mapping + domain analysis - For SINGLE: spawn one agent, pass through response - For PRIMARY+: spawn lead + supporting agents - For MULTI: spawn all needed agents in parallel

☐ Create src/lib/agent/parallel-executor.ts:

- Accept array of agent configs - Execute all generateText() calls concurrently (Promise.allSettled) - Collect responses with timing data - Handle partial failures (some agents succeed, some fail) - Enforce max parallel: 4 agents - Stagger start times by 500ms to reduce rate limit risk

☐ Implement @product gateway logic (from SKILL.md):

- V2V phase detection - RACI-based agent selection - Complexity assessment (route to PLT if cross-functional)

☐ Implement @plt gateway logic:

- Always spawns 3-4 agents based on topic - Composition varies: VP Product always included, others by domain - Meeting Mode output format mandatory

☐ Implement Extension Team gateways (@design, @architecture, @marketing):

- Route to team leader + relevant specialists

☐ Test: @plt should we prioritize webhooks or SDK? → spawns VP Product + PM + PMM Dir → individual responses + synthesis

7.2 Meeting Mode UI

Tasks:

☐ Create src/components/chat/meeting-mode.tsx:

- Header: topic + "Present: 📈 VP Product, 📝 PM, 📣 Dir PMM" - Individual sections: collapsible, each with emoji + Display Name header - Agent responses in first person (verbatim from agent output) - Divider between agents - Alignment section: bullet points of agreement - Tension section: bullet points of disagreement - Synthesis section: senior agent's synthesis - Aggregate ROI at bottom

☐ Progressive rendering: show each agent's section as it completes (don't wait for all)
☐ Loading states: "📈 VP Product is thinking..." while agents work
☐ Test: PLT session → see 3-4 agents' perspectives individually → alignment → tension → synthesis

7.3 Aggregate ROI for Multi-Agent

Tasks:

☐ After gateway completes, calculate aggregate ROI:

- Sum per-agent savings - Show total + per-agent breakdown - Format: ⏱️ Total: ~X hrs saved (vs. manual equivalent) └─ 📈 VP: ~A min | 📝 PM: ~B min | 📣 Dir PMM: ~C min

☐ Log multi-agent operation as single ROI entry in session log

Week 7 Exit Gate:

☐ @product gateway routes correctly (SINGLE/PRIMARY+/MULTI)
☐ @plt spawns 3-4 agents in parallel
☐ Meeting Mode displays individual voices → alignment → tension → synthesis
☐ Progressive rendering: agents appear as they complete
☐ Extension Team gateways (@design, @architecture, @marketing) work
☐ Aggregate ROI displays correctly
☐ PLT session completes in <60s (p95) with 300s Fluid Compute headroom

Week 8: Onboarding + Settings + Polish

Goal: Complete onboarding flow, settings page, and polish for beta readiness. Everything works end-to-end.

8.1 Onboarding Flow

First-time user experience:

Sign up → Connect API Key → Connect Google Drive → Select/Create Workspace → Guided First Interaction

Tasks:

☐ Create src/app/(dashboard)/onboarding/page.tsx — stepper component:

1. "Welcome to Legionis" — brief value prop 2. "Connect Your AI" — API key setup with link to Anthropic console 3. "Connect Your Storage" — Google Drive OAuth 4. "Create Your Workspace" — folder selection/creation 5. "Try Your First Skill" — guided /prd or /decision-record invocation

☐ Track onboarding progress in user record
☐ Skip completed steps on return
☐ Progressive disclosure: recommend 5 starter skills based on common roles
☐ Time-to-value target: user produces first meaningful output in <5 minutes
☐ Test: fresh signup → complete onboarding → first skill produces output → <5 min total

8.2 Settings Page

Tasks:

☐ settings/profile — name, email, avatar (from Clerk)
☐ settings/api-keys — add/update/delete API keys (Anthropic, OpenAI)
☐ settings/storage — Google Drive connection status, disconnect/reconnect, workspace selection
☐ settings/billing — current plan, trial countdown, upgrade button, Stripe portal link
☐ settings/model — default model selection (Haiku/Sonnet/Opus), display cost implications
☐ settings/about — version info, prompt cost efficiency display ("Prompt caching saves ~90%")

8.3 Search (Typesense)

Tasks:

☐ Create src/lib/search/client.ts — Typesense client
☐ Index workspace files on creation/update (title, content, type, path)
☐ Index context entries (decisions, bets, feedback, learnings) with metadata
☐ Create search UI: Cmd+K global search across files and context
☐ /context-recall uses Typesense for fast full-text search
☐ Test: create 10 context entries → search by keyword → results in <200ms

8.4 Error Handling & Edge Cases

Tasks:

☐ API key errors: clear message + link to key management page
☐ Rate limiting: per-user limits (10 agent calls/minute, 2 PLT sessions/minute)
☐ Drive token expiry: auto-refresh, fallback to re-auth prompt
☐ Model errors: retry with exponential backoff (3 attempts)
☐ Large response handling: truncation with "view full document in explorer" link
☐ Conversation too long: context window management, summarization strategy
☐ Network errors: offline indicator, retry buttons
☐ Subscription expired: read-only mode with clear upgrade CTA

8.5 Monitoring & Analytics

Tasks:

☐ Sentry: capture all unhandled errors, add breadcrumbs for agent execution
☐ PostHog: track key events:

- user_signed_up, trial_started, trial_converted, subscription_cancelled - skill_invoked (which skill, agent, duration) - agent_spawned (which agent, duration, tool_calls) - plt_session (agents involved, duration) - file_created, context_saved, context_recalled - onboarding_step_completed, onboarding_completed

☐ Health check endpoint: GET /api/health → DB connection, Drive API, Anthropic API status
☐ Better Stack: uptime monitoring for /api/health

Week 8 Exit Gate:

☐ Onboarding flow works end-to-end (<5 min to first output)
☐ Settings page fully functional (profile, keys, storage, billing, model)
☐ Cmd+K search works across workspace
☐ Error handling covers all major failure modes
☐ Sentry captures errors, PostHog tracks events
☐ Health check endpoint responds correctly
☐ No P0 bugs

Phase 5: Beta & Launch (Weeks 9-10)

Week 9: Beta Testing

Goal: 5-10 beta users test the full product. Identify and fix P0/P1 bugs.

9.1 Beta User Recruitment

Tasks:

☐ Identify 5-10 beta users (product leaders, PMs, CPOs from network)
☐ Create beta invite system: unique signup codes
☐ Prepare beta onboarding doc: what to test, how to report issues
☐ Set up feedback channel (Slack, email, or in-app)

9.2 Beta Test Plan

Each beta user should test:

Area	Test Script
Onboarding	Sign up → connect API key → connect Drive → create workspace → first skill
Skills	Invoke 5 different skills, verify output quality and file creation
Agents	Spawn 3 different agents, verify persona + domain accuracy
PLT	Run 1 PLT session, verify Meeting Mode display
Context	Save 3 decisions → recall by topic → verify cross-references
File Explorer	Browse workspace, preview files, verify Drive sync
Billing	View trial status, check billing page

9.3 Bug Triage

Tasks:

☐ Establish triage process: P0 (blocks usage) → fix immediately, P1 (degrades experience) → fix before launch, P2 (minor) → fix post-launch
☐ Daily bug review during beta week
☐ Performance benchmarking against PRD targets:

- Skill <5s p95 - Agent <15s p95 - PLT <60s p95 - Search <200ms p95

☐ Fix all P0 and P1 bugs

Week 9 Exit Gate:

☐ 5+ beta users completed test plan
☐ 0 P0 bugs remaining
☐ All P1 bugs fixed or have workarounds
☐ Performance targets met
☐ Beta user feedback documented

Week 10: Launch Preparation

Goal: Production-ready. Domain configured, landing page live, monitoring active.

10.1 Production Setup

Tasks:

☐ Configure custom domain: app.legionis.ai
☐ SSL certificate verified
☐ Production environment variables set in Vercel
☐ Database production branch on Neon
☐ Stripe in live mode (not test mode)
☐ Google OAuth production credentials (not development)
☐ Rate limiting configured for production load
☐ CDN and caching headers optimized

10.2 Landing Page

Tasks:

☐ Landing page at legionis.ai:

- Hero: "Your AI Product Organization" + CTA "Start Free Trial" - Feature sections: 39 agents, 61 skills, Meeting Mode, context layer - Pricing: $10/mo individual, $8/seat/mo team, 1-month free trial - BYOT explanation: "Your keys, your costs, your control" - Demo/video: Meeting Mode in action

☐ SEO basics: meta tags, OG tags, sitemap
☐ Analytics tracking on landing page

10.3 Legal & Compliance

Tasks:

☐ Privacy policy (data handling, BYOT, Google Drive scope)
☐ Terms of service
☐ Cookie policy (if applicable)
☐ GDPR data handling documentation

10.4 Launch Checklist

Run through PRD Section 12 launch checklist:

Technical:

☐ All 61 skills execute successfully
☐ All 39 agents respond in character
☐ PLT Meeting Mode works correctly
☐ Delegation protocol works (4 patterns)
☐ System prompt caching active (>80% hit rate)
☐ Context layer CRUD works
☐ API key encryption validated
☐ Row-level security enforced
☐ Performance targets met
☐ No P0 bugs

Business:

☐ Stripe billing configured (trial + paid plans)
☐ Landing page live
☐ Onboarding tested with beta users
☐ Support channel active
☐ Privacy policy + ToS published
☐ Analytics tracking configured

Week 10 Exit Gate: LAUNCH

Post-Launch: Growth Phase (Weeks 11-20)

After launch, focus shifts to retention, enrichment, expansion, and external tool integrations.

Weeks 11-12: External Tool Integration Framework + First Wave

Goal: Users can connect external tools (Jira, Slack, GitHub, Figma, etc.) via OAuth. Agents use connected tools to perform real operations. Graceful fallback when tools aren't connected.

11.1 Integration Framework (Week 11)

The framework provides a generic OAuth + API call pipeline that all integrations share. Individual integrations are configuration on top of this framework.

Architecture: Hybrid OAuth model. Users click "Connect [Tool]" → standard OAuth 2.0 flow → Legionis stores encrypted tokens in tool_connections table → agents call tool APIs directly using stored tokens. The OS integration templates inform what API calls to make; the platform provides the authenticated HTTP client. No MCP servers needed in production.

DB Schema:

tool_connections:
  id, user_id, workspace_id,
  service (jira|slack|github|figma|...),
  provider_config (JSON: instance_url, project_key, etc.),
  encrypted_oauth_tokens (access_token, refresh_token, expiry),
  scopes,
  status (connected|expired|error),
  connected_at, last_used_at

Tasks:

☐ Create tool_connections table (Drizzle migration)
☐ Create src/lib/integrations/oauth.ts — generic OAuth 2.0 framework:

- initiateOAuth(service, scopes) → redirect URL - handleCallback(service, code) → exchange for tokens → encrypt → store - refreshToken(connectionId) → auto-refresh before expiry - Support both OAuth 2.0 Authorization Code (most tools) and API key (simpler tools)

☐ Create src/lib/integrations/registry.ts — integration registry:

- Map service names → OAuth config (client_id, auth_url, token_url, scopes) - Map service names → API client factory - Map OS integration templates → executable API operations - Runtime check: isConnected(userId, service) → boolean

☐ Create src/lib/integrations/api-client.ts — authenticated HTTP client:

- Wraps fetch with OAuth token injection - Auto-refresh on 401 - Rate limiting and retry logic - Audit logging (all external API calls logged)

☐ Create src/tools/external-tool.ts — agent-facing tool:

- Agent calls: { service: "jira", operation: "create_issue", params: {...} } - Tool checks: user has service connected? - If yes: execute API call with stored tokens → return result - If no: return graceful fallback ("Jira is not connected. Here are the issues to create manually: [list]")

☐ Create src/app/(dashboard)/settings/connections/page.tsx — Connections settings page:

- Marketplace-style grid of available integrations (3 columns desktop, 1 mobile) - Each card: tool logo, name, connection status (green dot / "Connect" button) - "Used by X agents" indicator per integration - Connect → OAuth flow → redirect back → status updates - Disconnect button with confirmation - Group by category: Project Management, Communication, Design, Code, Analytics, Finance, Legal, IT

☐ Create OAuth callback route: src/app/api/integrations/callback/route.ts
☐ Test: connect mock OAuth → token stored → agent invokes tool → API call succeeds → graceful fallback when disconnected

11.2 Wave 1 Integrations: Project Management + Communication (Week 11)

Priority integrations for launch-adjacent value. These cover the most common "where does the output go?" question.

Jira / Atlassian (Operations, Product):

☐ OAuth config: Atlassian OAuth 2.0 (3LO), scopes: read:jira-work, write:jira-work, read:jira-user
☐ API client: src/lib/integrations/services/jira.ts

- searchIssues(jql) — POST /rest/api/3/search/jql - getIssue(key) — GET /rest/api/3/issue/{key} - createIssue(project, type, summary, description) — POST /rest/api/3/issue - getBoard(id) — GET /rest/agile/1.0/board/{id} - getSprint(id) — GET /rest/agile/1.0/sprint/{id}

☐ Agent mapping: @program-manager, @project-manager, @operations-dir, @pm (cross-team)
☐ Test: @pm creates PRD → user stories auto-created as Jira tickets

Slack (Communication, all teams):

☐ OAuth config: Slack OAuth 2.0, scopes: chat:write, channels:read, channels:history
☐ API client: src/lib/integrations/services/slack.ts

- postMessage(channel, text) — POST /api/chat.postMessage - listChannels() — GET /api/conversations.list - getHistory(channel) — GET /api/conversations.history

☐ Agent mapping: All agents (post updates, share deliverables), @pr-comms-specialist, @social-media-manager
☐ Test: gateway session completes → synthesis posted to #product-decisions channel

GitHub (Architecture):

☐ OAuth config: GitHub OAuth App, scopes: repo, read:org
☐ API client: src/lib/integrations/services/github.ts

- listPRs(repo), getPR(repo, number), createIssue(repo, title, body) - getSecurityAlerts(repo), searchCode(query)

☐ Agent mapping: @chief-architect, @api-architect, @security-architect, @cloud-architect
☐ Test: @security-architect reviews codebase → creates GitHub issues for findings

Linear (Project Management alternative):

☐ OAuth config: Linear OAuth 2.0
☐ API client: GraphQL-based (src/lib/integrations/services/linear.ts)

- searchIssues(query), createIssue(team, title, description), getCycles(team)

☐ Agent mapping: Same as Jira (alternative PM tool)

11.3 Wave 2 Integrations: Design + Marketing (Week 12)

Figma (Design Team):

☐ Auth: Figma Personal Access Token (API key, not OAuth)
☐ API client: src/lib/integrations/services/figma.ts

- getFile(fileKey), getComponents(fileKey), getStyles(fileKey), getComments(fileKey)

☐ Agent mapping: @design-dir, @ui-designer, @visual-designer, @interaction-designer, @user-researcher, @motion-designer
☐ Workflows: design review, component audit, brand consistency check

Google Analytics (GA4) (Marketing Team):

☐ Auth: Google OAuth 2.0 (Analytics scope) or service account
☐ API client: src/lib/integrations/services/analytics.ts

- runReport(property, metrics, dimensions, dateRange) - runRealtimeReport(property) - runFunnelReport(property, steps)

☐ Agent mapping: @cro-specialist, @growth-marketer, @paid-media-manager, @marketing-dir
☐ Workflows: conversion analysis, channel attribution, funnel optimization

Mailchimp / SendGrid / HubSpot Email (Marketing Team):

☐ Auth: API key (Mailchimp, SendGrid) or OAuth 2.0 (HubSpot)
☐ API client: src/lib/integrations/services/email-platform.ts

- getCampaignStats(id), getListInfo(id), createCampaign(params), getDeliverability()

☐ Agent mapping: @email-marketer, @copywriter, @cro-specialist, @growth-marketer
☐ Workflows: campaign creation with A/B testing, lifecycle automation, channel health

SEO Tools — Google Search Console (Marketing Team):

☐ Auth: Google OAuth 2.0 (Webmasters scope)
☐ API client: src/lib/integrations/services/search-console.ts

- queryAnalytics(site, dateRange, dimensions), listSitemaps(site), getIndexStatus(site)

☐ Agent mapping: @seo-specialist, @content-strategist, @growth-marketer
☐ Workflows: keyword performance, indexation health, content gap analysis

Weeks 13-14: Wave 3 Integrations: Finance + Legal + IT + Corp Dev

Xero / QuickBooks (Finance Team):

☐ Auth: OAuth 2.0 (both use OAuth with tenant/realm ID)
☐ API client: src/lib/integrations/services/accounting.ts

- getProfitLoss(period), getBalanceSheet(date), getCashFlow(period) - getInvoices(status, dateRange), getBankTransactions(dateRange)

☐ Agent mapping: @financial-controller, @fpa-analyst, @treasury-analyst
☐ Workflows: financial health review, cash flow analysis, expense categorization
☐ Read-only access only — agents never create/modify/delete financial records

Stripe Billing (Finance Team):

☐ Auth: API key (Stripe secret key — may reuse existing Stripe integration)
☐ API client: src/lib/integrations/services/stripe-billing.ts

- getSubscriptions(status), getRevenue(period), getCustomers(params) - getMRR(), getChurnRate(period), getInvoices(status)

☐ Agent mapping: @revenue-analyst, @fpa-analyst, @cfo
☐ Workflows: SaaS metrics dashboard, revenue model validation, cohort analysis

DocuSign / PandaDoc (Legal Team):

☐ Auth: DocuSign OAuth 2.0 + JWT; PandaDoc API key or OAuth 2.0
☐ API client: src/lib/integrations/services/contract-management.ts

- searchAgreements(query), getAgreement(id), getAuditTrail(id) - listTemplates(), getEnvelopeStatus(id)

☐ Agent mapping: @contracts-counsel, @legal-dir, @general-counsel
☐ Workflows: contract review, portfolio analysis, obligation tracking
☐ Agents never execute contracts or approve signatures

Vanta / Drata (Legal Team):

☐ Auth: API key
☐ API client: src/lib/integrations/services/compliance.ts

- getTests(framework), getFrameworkStatus(), getVendors(), getEvidence(testId)

☐ Agent mapping: @compliance-officer, @general-counsel, @privacy-counsel
☐ Workflows: audit preparation, compliance posture review, vendor risk assessment

ServiceNow / Jira Service Management (IT Governance Team):

☐ Auth: OAuth 2.0 + instance credentials (ServiceNow); Atlassian OAuth (JSM)
☐ API client: src/lib/integrations/services/itsm.ts

- getIncidents(query), createIncident(params), getChanges(query) - getCMDB(ciType), getSLAStatus(), getKnowledgeArticles(query)

☐ Agent mapping: @it-dir, @it-security-policy, @enterprise-systems
☐ Workflows: incident analysis, change risk assessment, service level review

Okta / Microsoft Entra ID (IT Governance Team):

☐ Auth: Okta API token or OAuth 2.0; Entra ID uses Microsoft Graph OAuth 2.0 with admin consent
☐ API client: src/lib/integrations/services/identity.ts

- listUsers(filter), getUser(id), listGroups(), getGroupMembers(id) - listApplications(), getSignInLogs(dateRange), getPrivilegedRoles()

☐ Agent mapping: @it-security-policy, @cio, @it-dir, @security-architect (cross-team)
☐ Workflows: access review, privileged access audit, authentication policy review
☐ Data marked as highly sensitive — audit all queries

Salesforce / HubSpot CRM (Corp Dev Team):

☐ Auth: Salesforce OAuth 2.0 connected app; HubSpot OAuth 2.0
☐ API client: src/lib/integrations/services/crm.ts

- queryRecords(soql), getRecord(type, id), createRecord(type, data) - getPipeline(id), getDeals(stage), getActivities(recordId)

☐ Agent mapping: @head-corpdev, @ma-analyst, @strategic-partnerships, @bizdev (cross-team)
☐ Workflows: M&A pipeline, partnership tracking, customer health

PitchBook / Crunchbase (Corp Dev Team):

☐ Auth: API key
☐ API client: src/lib/integrations/services/research-data.ts

- searchCompanies(query), getCompany(id), getFundingRounds(companyId) - getInvestors(companyId), getComparables(criteria)

☐ Agent mapping: @ma-analyst, @corporate-venture, @head-corpdev, @ci (cross-team)
☐ Workflows: target identification, comparable analysis, market mapping

Notion / Confluence (Operations Team):

☐ Auth: Notion OAuth 2.0; Confluence via Atlassian OAuth 2.0
☐ API client: src/lib/integrations/services/knowledge-base.ts

- searchPages(query), getPage(id), createPage(parent, title, content) - queryDatabase(id, filter), updatePage(id, content)

☐ Agent mapping: @process-engineer, @operations-dir, @program-manager
☐ Workflows: SOP creation, knowledge base audit, process documentation

Miro (Operations Team):

☐ Auth: Miro OAuth 2.0
☐ API client: src/lib/integrations/services/miro.ts

- getBoards(), getBoard(id), createStickyNote(boardId, content) - createShape(boardId, shape), createConnector(boardId, start, end)

☐ Agent mapping: @process-engineer, @operations-dir, @program-manager
☐ Workflows: process mapping, workshop facilitation, visual collaboration

Integration Summary (All Waves)

Wave	Week	Integrations	Teams Served	Platforms
1	11	Project Mgmt + Communication + Code	Operations, Product, Architecture	Jira, Slack, GitHub, Linear
2	12	Design + Marketing	Design, Marketing	Figma, GA4, Mailchimp/SendGrid/HubSpot, Search Console
3	13-14	Finance + Legal + IT + Corp Dev + Knowledge	Finance, Legal, IT, Corp Dev, Operations	Xero/QBO, Stripe, DocuSign/PandaDoc, Vanta/Drata, ServiceNow/JSM, Okta/Entra, Salesforce/HubSpot CRM, PitchBook/Crunchbase, Notion/Confluence, Miro

Total: ~30 platforms across 15 integration categories serving all 9 teams + Product Org.

Exit Gate (Week 14):

☐ Integration framework handles OAuth connect/disconnect/refresh for any service
☐ At least 8 integrations connected and tested end-to-end
☐ Graceful fallback works: unconnected tools produce text with manual action items
☐ Connections settings page shows all available integrations with status
☐ Agent in-chat nudge: "I can do this directly if you connect [tool]"
☐ All external API calls logged for audit
☐ Token refresh works (no auth failures during extended sessions)

Weeks 15-20: Enrichment + Expansion

Focus	Deliverable	Week
Per-agent model override	Users can set Opus vs Sonnet per agent in settings. Stored in `user_agent_preferences` table. Enhances the global Quality/Efficiency toggle from Week 5.1b with per-agent granularity. Settings UI: agent grid with model dropdown.	15
Knowledge packs	All 43 packs loaded conditionally per agent domain	15
Team personalities	Each of the 10 teams has a configurable personality tagline. Stored in `team_config` table. Injected into L2 persona layer. Default taglines ship; workspace admins can customize.	16
File explorer v2	Create, rename, delete, drag-drop, bulk operations	16
Additional model providers	Google Gemini via `@ai-sdk/google`, Mistral via `@ai-sdk/mistral`	17
Voice input	Push-to-talk, transcription via Whisper API	18
OneDrive integration	Microsoft Graph API OAuth + file operations (cloud storage, not tool integration)	19
Dropbox integration	Dropbox API v2 OAuth + file operations	20
Advanced onboarding	Role-based skill recommendations, example workspaces	20

Appendix A: Key Technical Decisions (Pre-Made)

These decisions are MADE. Do not re-litigate during build.

Decision	Choice	Rationale	Reference
Agent runtime	Vercel AI SDK v6	Pure API, multi-model, BYOT, unlimited subagents	`sdk-comparison-presentation.html`
Backend	Next.js API Routes (not separate Hono)	Single deployment, native AI SDK integration	Architecture Stack V1.4
Storage	Google Drive first (not local FS)	Stable file IDs, cloud-native, cross-device	Architecture Stack V1.4
Prompt architecture	3-layer cached (L1+L2+L3)	87% token reduction, ~$0.71/mo user cost	System Prompt Deep Dive
Auth	Clerk	Pre-built UI, social login, org support	Architecture Stack V1.4
Database	Neon PostgreSQL + Drizzle	Serverless, branching, scale-to-zero, type-safe ORM	Architecture Stack V1.4
Billing	Stripe	1-month trial, $10/mo individual, $8/seat/mo team	PRD V1.5
PLT timeout	300s Fluid Compute (default)	5x headroom vs 60s target	Vercel Constraints Deep Dive
Subagent depth	Max 3 levels	Prevents runaway chains, sufficient for delegation	PRD V1.5
Model default	Claude Sonnet 4.5	Best balance of quality and speed	Architecture Stack V1.4
Token plan	BYOT default + Managed Tokens at 30% markup	BYOT preserves transparency USP; managed tokens reduce onboarding friction	Gateway meeting 2026-02-18
Model routing	3-tier global toggle (Quality/Balanced/Efficiency)	Users control cost-quality tradeoff; intercepted before `resolveModel()`	Gateway meeting 2026-02-18
Tool integrations	Hybrid OAuth (not MCP in production)	Standard OAuth UX; direct API calls; OS templates inform operations	Gateway meeting 2026-02-18
Integration rollout	3 waves post-launch (Weeks 11-14)	Not a launch blocker; graceful fallback already works	Gateway meeting 2026-02-18

Appendix B: Environment Variables

Auth (Clerk)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
CLERK_WEBHOOK_SECRET=whsec_...
Database (Neon)
DATABASE_URL=postgresql://...
Stripe
STRIPE_SECRET_KEY=sk_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_INDIVIDUAL_PRICE_ID=price_...
STRIPE_TEAM_PRICE_ID=price_...
Google Drive
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=https://app.legionis.ai/api/drive/callback
Encryption
ENCRYPTION_MASTER_KEY=...
Cloudflare R2
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=legionis-storage
R2_ENDPOINT=https://...r2.cloudflarestorage.com
Typesense
TYPESENSE_HOST=...
TYPESENSE_API_KEY=...
TYPESENSE_PORT=443
TYPESENSE_PROTOCOL=https
Monitoring
SENTRY_DSN=https://...
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
App
NEXT_PUBLIC_APP_URL=https://app.legionis.ai
Legionis Tokens (Managed Plan) — Week 5.4
LEGIONIS_ANTHROPIC_KEY=sk_ant_...
LEGIONIS_OPENAI_KEY=sk_...
STRIPE_METERED_PRICE_ID=price_...          # Metered price for token consumption
OAuth — External Tool Integrations (Weeks 11-14)
Per-service OAuth client IDs/secrets added as integrations are built
JIRA_CLIENT_ID=...
JIRA_CLIENT_SECRET=...
SLACK_CLIENT_ID=...
SLACK_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
Additional service OAuth creds added per wave

Appendix C: Weekly Session Template

Start each build session by:

Open this document

Find current week

Check remaining unchecked tasks

Pick the next task

Work with Claude Code / Cursor

Check off completed items

Note any blockers or deviations

End each session by:

Commit and push

Verify Vercel preview deployment

Update checked items in this doc

Note any carry-over items for next session

Document Status: V3.0 — Definitive Build Guide Supersedes: execution-plan.md V2.2 Start Condition: This document is ready to execute. All architectural decisions are made, all dependencies are available, all service accounts need creation.

Legionis: Definitive Execution Plan

How to Use This Document

Architecture Summary (Reference)

Pre-Development: Project Setup (Day 0)

P0.1 — Repository & Scaffold

P0.2 — External Service Accounts

P0.3 — OS Source Integration ✅

P0.4 — Initial Deploy ✅

Phase 1: Foundation (Weeks 1-2)

Week 1: Auth + Database + Billing

1.1 Database Schema (Neon + Drizzle)

1.2 Authentication (Clerk)

1.3 Billing (Stripe)

1.4 Dashboard Shell

Week 2: Agent Runtime Core + Custom Tools

2.1 Prompt Compiler (compile-prompts.ts)

2.2 Agent Runtime (src/lib/agent/)

2.3 Custom Tool Definitions (src/tools/)

2.4 Chat API Route

Phase 2: Core Product (Weeks 3-4)

Week 3: Chat UI + Skill Dispatch + Persona System

3.1 Chat Interface (src/components/chat/)

3.2 Skill Palette

3.3 Agent Selector

3.4 Skill Dispatch System

3.5 All 39 Agent Personas

Week 4: Google Drive Integration

4.1 OAuth Flow

4.2 Workspace Initialization

4.3 Drive-Backed File Tools

4.4 File Explorer

Phase 3: Agent System (Weeks 5-6)

Week 5: BYOT + Full Agent Roster + Context Layer

5.1 API Key Management (BYOT)

5.1b Quality/Efficiency Model Routing

5.2 All 81 Agents Operational

5.3 Context Layer Implementation

5.4 Legionis Tokens (Managed Token Plan)

5.5 Conversation Persistence

Week 6: Sub-Agents + Skill Execution + Delegation

6.1 Sub-Agent Spawning

6.2 Full Skill Execution Pipeline

6.3 ROI Tracking

Phase 4: Multi-Agent & Gateway Orchestration (Weeks 7-8)

Week 7: Gateway System + PLT Meeting Mode

7.1 Gateway Engine

7.2 Meeting Mode UI

7.3 Aggregate ROI for Multi-Agent

Week 8: Onboarding + Settings + Polish

8.1 Onboarding Flow

8.2 Settings Page

8.3 Search (Typesense)

8.4 Error Handling & Edge Cases

8.5 Monitoring & Analytics

Phase 5: Beta & Launch (Weeks 9-10)

Week 9: Beta Testing

9.1 Beta User Recruitment

9.2 Beta Test Plan

9.3 Bug Triage

Week 10: Launch Preparation

10.1 Production Setup

10.2 Landing Page

10.3 Legal & Compliance

10.4 Launch Checklist

Post-Launch: Growth Phase (Weeks 11-20)

Weeks 11-12: External Tool Integration Framework + First Wave

11.1 Integration Framework (Week 11)

11.2 Wave 1 Integrations: Project Management + Communication (Week 11)

11.3 Wave 2 Integrations: Design + Marketing (Week 12)

Weeks 13-14: Wave 3 Integrations: Finance + Legal + IT + Corp Dev

Integration Summary (All Waves)

Weeks 15-20: Enrichment + Expansion

Appendix A: Key Technical Decisions (Pre-Made)

Appendix B: Environment Variables

Auth (Clerk)

Database (Neon)

Stripe

Google Drive

Encryption

Cloudflare R2

2.1 Prompt Compiler (`compile-prompts.ts`)

2.2 Agent Runtime (`src/lib/agent/`)

2.3 Custom Tool Definitions (`src/tools/`)

3.1 Chat Interface (`src/components/chat/`)