CortexBuild — Product Spec (v0.1, locked)¶
Locked decisions¶
| Dimension | Decision | Rationale |
|---|---|---|
| Wedge | Builder platform on existing repos; brownfield is a strength, not a ceiling. Featured surfaces: Legacy Modernisation + Backlog Burn-Down | Both have huge TAM; both leverage existing rule SSoT |
| Audience | PMs + tech-lead multiplexers (same product, different UI persona toggle) | Same workflows, just different language layer |
| Dev VM | Build on top of Daytona (v0/v1) → custom Firecracker (v3+) (planned execution runtime, Phase 1) | Daytona is OSS, devcontainer-native, fast to integrate |
| IDE strategy | Coexist — never replace. Code in git, devs use VS Code/Cursor as normal | Doesn't fight where developers already live |
| LLM provider | BYO key. Native Anthropic (Claude) + native Gemini + any OpenAI-compatible endpoint (covers OpenAI/Codex models, gateways, Ollama). Bedrock/Vertex only via an OpenAI-compatible gateway (no native adapter). | No lock-in. User controls cost. |
| Host tools | CortexBuild renders its harness INTO the AI coding tools devs run inside: Copilot, Claude Code, Codex CLI, Cursor. These are host surfaces, not LLM providers. | Meet developers in the tools they already use. |
| Per-agent model routing | Planner, Critic, Security, PR Reviewer → reasoning_heavy; Builder, Tester, Optimizer → balanced; Explore → fast_cheap. In rendered-host mode the host vendor controls the model (no tier routing). For medium+ risk tasks the Critic MUST run on an independent model (different vendor/model than Planner) — see rule-critic-gate. |
Right model for the right job; keep cost low on high-volume agents; cross-vendor Critic avoids shared blind spots. |
| Compliance posture | Generic enterprise best practices (OWASP ASVS, NIST SSDF, ISO 27001-aligned, WCAG 2.2 AA, Azure WAF) | One foundational pack covers 80% of needs |
| Industry packs | Deferred to v2 (community contribution model) | Don't fragment v1 by industry |
| Agent autonomy | User-configured per action class (15-row matrix) | Conservative defaults, full user control |
| Liability | User-monitored, AI-assisted; ToS shields platform | All actions logged; nothing irreversible without explicit approval |
| OSS strategy | Deferred until product validated | Decide at v2 |
Product surfaces¶
Surface A — Legacy Modernisation¶
Trigger: User connects a repo flagged "modernise this."
Flow: 1. Onboarding interview (15 min, chat-style): - Business goals (deprecate, scale, comply, hand off) - Risk tolerance (aggressive / balanced / conservative) - Deprecation horizon (3 months / 12 months / 3 years) 2. Codebase analysis (~10 min): - Structural scan (languages, frameworks, sizes) - Convention inference (auth patterns, error handling, naming) - Pain-point mining (git log → hotfix clusters, revert patterns) - Architecture map via graphify-style tooling 3. Roadmap synthesis: - Technical debt heatmap (file × hotfix count × age × dependency centrality) - Modernisation backlog (Linear/GitHub issues) ranked by ROI - "If we had to ship in N months, here's the critical path" 4. Execution loop: - User approves the roadmap (or edits it) - CortexBuild starts working through issues in dependency order - Each issue: Planner → Critic → Builder → (Tester ∥ Security ∥ Optimizer) → PR - User reviews PRs in normal GitHub flow; approves/rejects/comments 5. Continuous learning: - Every rejected PR → post-mortem → ledger entry - Recurrence patterns become enforced rules - User sees "agent confidence rising" graph over time
Surface B — Backlog Burn-Down¶
Trigger: User connects Linear/Jira/GitHub Issues to a repo.
Flow: 1. Triage pass: - Classify every open ticket: S/M/L/XL complexity - Required skills (frontend / backend / SQL / infra / docs) - Blast radius (touches 1 file / 1 service / multiple services) - Confidence score: can CortexBuild do this autonomously? 2. Autonomous mode (S tickets only, default): - Pick S tickets with confidence ≥ 0.85 - Run full wave model - Open PR with self-audit + screenshots/diffs - Mark ticket "in review" 3. Assisted mode (M/L tickets): - CortexBuild drafts a plan - User approves plan → CortexBuild executes - Or user rejects/edits plan → re-plan 4. Escalation (XL tickets): - CortexBuild flags as too complex for autonomous execution - Suggests breakdown into smaller tickets - Hands back to user for breakdown
Approval Matrix (Autonomy Ceiling)¶
User configures at project setup. Defaults below.
| # | Action Class | Default Level |
|---|---|---|
| 1 | Read repo / search code | Auto |
| 2 | Create branch | Auto |
| 3 | Edit files | Auto |
| 4 | Commit + push to branch | Auto |
| 5 | Open PR | Auto |
| 6 | Update PR description | Auto |
| 7 | Add labels / move ticket | Auto |
| 8 | Comment on PR / ticket | Auto |
| 9 | Install new dependency | Notify |
| 10 | Modify CI/CD config | Notify |
| 11 | Send external email / webhook | Notify |
| 12 | Merge PR to staging | Notify |
| 13 | Deploy to staging | Notify |
| 14 | Merge PR to main | Approve |
| 15 | Deploy to production | Approve |
| 16 | Spend money (cloud, APIs) | Approve |
| 17 | Modify production data | Approve |
| 18 | Rotate secrets / keys | Approve |
| 19 | Delete files / branches | Approve |
| 20 | Run any command requiring sudo |
Approve |
Levels: - Auto — performed silently; visible in audit log - Notify — performed but UI shows a banner; user can rollback within 5 min - Approve — blocking dialog in UI; agent waits for explicit yes/no
User can shift any row up (more control) or down (more autonomy). Going below default requires a confirmation dialog ("are you sure?").
What we explicitly will not build in v1¶
- New IDE
- Code editing UI (use git + your editor)
- Greenfield project generator
- Marketplace UI (rule packs distributed via GitHub for now)
- Mobile app
- Slack/Teams bot (planned for v2)
- Custom LLM training
- A debugger
- A test runner UI
Non-functional requirements¶
| NFR | Target |
|---|---|
| Latency | First CortexBuild action visible in UI < 5s of user message |
| Throughput | Single tenant: 10 parallel tasks. Cloud Team: 50 parallel tasks per tenant. |
| Availability | 99.5% (UI), 99.0% (orchestrator) in v1; 99.9% in v2 |
| Cost ceiling per task | Configurable per project; default $5 |
| Audit retention | 90 days (free), 1 year (paid), 7 years (enterprise) |
| Time to first PR after repo connect | ≤ 30 min |
| Confidence floor for autonomous PR | 0.85 (configurable) |
| PR pass-CI-on-first-try rate | ≥ 60% (v1), ≥ 80% (v2) |
| Recurrence rate (same class of bug recurring) | < 5% per project per month |
Success metrics (post-launch)¶
| Metric | Target by EOY1 |
|---|---|
| Paying projects | 250 |
| MRR | $50k |
| PRs opened per week (aggregate) | 5,000 |
| PR merge rate | ≥ 50% |
| NPS (PM persona) | ≥ 40 |
| NPS (tech-lead persona) | ≥ 50 |
| Hosted control plane p95 latency | < 500ms |