# Non-Linear: v0.1 Scope & Roadmap

## v0.1 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 Scope: What Ships

### Core Data Model

- **Two node types:** components (skeleton, map to code) and issues (work, flow through statuses)
- **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

### 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