non-linear-docs/06-SCOPE-AND-ROADMAP.md

Non-Linear: Scope & Roadmap

Milestone Structure

Milestone	Purpose
v0.1-alpha	Minimum viable validation — see 06a-ALPHA-SCOPE.md
v0.1-full	Complete v0.1 vision (this document) — ships after alpha validates the thesis
v0.2	Expand agent capabilities + cross-project
v0.3+	Integrations & intelligence

v0.1-full Validation Goal

Can a team of 3-5 people use this to run an actual project for two weeks without falling back to another tool?

If yes, the core thesis holds. If they keep opening Linear or a spreadsheet for certain tasks, those gaps tell us what v0.2 needs.

v0.1-full Scope: What Ships (after alpha validates)

Core Data Model

• Two node types (alpha): components (skeleton, map to code) and issues (work, flow through statuses). Artifacts (Layer 4) are introduced post-alpha.
• Decomposition tree: strict parent→child hierarchy, single root per project
• Lateral links: blocks, blocked_by, relates_to, duplicates, depends_on (inter-component)
• Component health: derived from children's statuses (no status field on components)
• Single project (no cross-project features)
• Complete change history: every mutation is a stored event with actor + timestamp

Alpha note: Alpha ships blocks and relates_to only. duplicates and depends_on (Layer 3) are post-alpha.

Repository Integration

• Multi-repo support: connect multiple GitHub/GitLab repos to one project
• Repo ↔ component linking: each repo or subdirectory maps to a component node
• Monorepo support: one repo → multiple components (per package/service)
• Skeleton inference (fast-start): connect repos → scan structure → AI proposes component tree → user adjusts → skeleton committed
• Automatic commit/PR association: code activity auto-surfaces in the right component's feed
• New directory detection: suggest adding new components when code structure changes

Views

• Layered overview: rows by depth, edges visible, lateral links as overlay, collapse/expand, filtering, backlink count badges, component vs. issue visual distinction
• Focus widget: node + parent + children, detail panel, quick actions, backlinks, breadcrumbs, change history, repo link info for components
• Flat list/board: Kanban by status (issues only), sorting, grouping, bulk actions, search
• Cycle view: current cycle issues, grouped by component or status

Interaction Model

• Keyboard-first: every action has a shortcut, graph navigation via Alt+↑/↓/←/→
• Command palette (Cmd+K): fuzzy search across nodes, actions, views; context-aware
• Natural language node creation: parse tree path, labels, assignment from text
• Plan-then-apply: structural changes show preview of consequences before committing

Triage

• Rootless inbox: issues without a parent land here
• Smart triage: system suggests which component an issue belongs to based on keywords, file paths, or related commits
• Triage = assigning a parent, placing the issue in the tree
• Agents can triage via API

Cycles

• Cycle: named set of issue references + date range
• Cycle membership shown as color highlight/tag in all views
• Only issues join cycles (not components)
• Agent scoping: policies can restrict agents to "current cycle only"

Notifications

• Scoped watching: single node, subtree, or project-wide
• Event type filters: status changes, comments, new children, link changes, agent actions, code activity
• Defaults: watch nodes you created or are assigned to
• Mute: temporarily silence a subtree

Code Integration

• Node ID format: short, typeable (NL-42 for issues, NL-C12 for components)
• Commit message parsing: fixes NL-42 triggers status change
• PR linkage: PR appears in relevant node's activity feed (auto via component path, or explicit via ID)
• Branch naming support: feature/NL-42-login-flow
• Webhooks from GitHub/GitLab trigger node updates

Policy Engine

• Full granular engine: policy = actor + action + resource scope + effect
• Three resource scopes: global, subtree, single node
• Three default presets: owner, member, agent-reader (all editable)
• Custom role creation: via settings panel
• Resolution order: direct > role, deny > allow, narrow > broad, default deny

Agent API

• Authentication: API tokens tied to agent actor accounts
• Read operations: node, children, subtree, parent, links, backlinks, path, history, root, inbox, component repo info
• Write operations: comment, change status, triage (assign parent)
• Queries: filter by status, assignee, labels, unblocked, cycle, node type
• Permission-aware responses: include effective permissions, opaque link targets
• Webhooks: node.status_changed, node.comment_added, node.created, node.link_created, node.reparented, node.cycle_added, repo.commit_associated

Entry Experience — Three Paths

1. Connect your code (new): OAuth to GitHub/GitLab → select repos → AI scans and proposes component skeleton → user adjusts → start adding issues
2. Clean start: Create project → root node → add components and issues manually
3. Import from tracker (v0.2+): Import from Linear/Jira/GitHub Issues → infer hierarchy

What's Deferred

v0.2: Expand Agent Capabilities + Cross-Project

• Agent creates child nodes (task decomposition)
• Agent creates lateral links
• Agent proposes reparenting (submit as "plan" for human review)
• Cross-project lateral links
• Cross-project agent scoping
• Multi-root projects
• Import from Linear / Jira / GitHub Issues (infer tree levels)
• Dependency inference from code (import graphs → depends_on links)

v0.3+: Integrations & Intelligence

• Auto-link external signals (Sentry/PagerDuty errors → right component subtree)
• MCP server exposure
• Agent autonomous task pickup (self-assign from backlog)
• Time tracking
• Custom views / saved filters
• Export (PDF, CSV)

Deliberately Not Building

• Rich document blocks (Notion-style) — stay focused on tracking
• Multiplayer presence / cursors — overkill for small teams
• Canvas sketch-to-structure — cool demo, unclear daily value

Open Questions

1. Graph rendering library: D3 vs Cytoscape vs custom WebGL?
2. Real-time updates: WebSocket via FastAPI or dedicated service (Centrifugo)?
3. Cycle UX: How to add/remove issues from cycles?
4. Natural language parsing: LLM-powered or rule-based for v0.1?
5. Git integration depth: Webhook-only, or GitHub App with deeper permissions?
6. Skeleton inference depth: How deep should auto-scan go? Top-level packages only, or nested modules?
7. Component health aggregation: Simple ratios, or weighted by priority/blockers?

Success Metrics

• Adoption: Team uses Non-Linear as sole tracker for 2+ weeks
• Retention: No fallback to Linear/spreadsheet for any workflow
• Repo connection rate: >50% of projects connect at least one repo
• Agent utility: Agent produces at least 1 useful action per day
• Graph value: Users create trees with 3+ depth levels
• Speed: Command palette action <200ms, view transitions <100ms