Add design.md

design.md

@@ -0,0 +1,105 @@
+# 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 ✅
+
+- **Issue nodes:** title, description, status, labels, assignee, timestamps
+- **Decomposition tree:** strict parent→child hierarchy, single root per project
+- **Lateral links:** blocks, blocked_by, relates_to, duplicates
+- **Untyped nodes:** depth = abstraction level, labels = orthogonal classification
+- **Single project** (no cross-project features)
+
+### Views ✅
+
+- **Layered overview:** rows by depth, parent→child edges visible, lateral links as overlay, collapse/expand, filtering
+- **Focus widget:** selected node + parent + children, detail panel, quick actions, lateral links shown
+- **Flat list/board:** Kanban columns by status, sorting, grouping, bulk actions, search
+
+### Policy Engine ✅
+
+- **Full granular engine underneath:** 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 (can be minimal UI)
+- **Resolution order:** direct > role, deny > allow, narrow > broad, default deny
+- **Reparenting warnings:** surface when moving a node changes permission boundaries
+
+### Agent API ✅
+
+- **Authentication:** API tokens tied to agent actor accounts
+- **Read operations:** get node, children, subtree, parent, links, path, root
+- **Write operations:** add comment, change status
+- **Queries:** filter by status, assignee, labels, unblocked
+- **Permission-aware responses:** include effective permissions, opaque link targets
+- **Webhooks:** node.status_changed, node.comment_added, node.created, node.link_created
+
+### Entry Experience ✅
+
+- New project → auto-create root node → Focus Widget on root → prompt to add children
+- Clean, fast onboarding: create root, add first children, start working
+
+## v0.1 Scope: What's Deferred
+
+### v0.2: Expand Agent Capabilities + Cross-Project
+
+- [ ] Agent can create child nodes (task decomposition)
+- [ ] Agent can create lateral links
+- [ ] Agent can propose reparenting
+- [ ] Cross-project lateral links
+- [ ] Cross-project views
+- [ ] Permission model for cross-project boundaries
+- [ ] Import from Linear, Jira, GitHub Issues (with hierarchy inference)
+- [ ] Export to standard formats
+- [ ] MCP server compatibility
+
+### v0.3: Collaboration & Intelligence
+
+- [ ] Agent self-assignment (autonomous task pickup)
+- [ ] Sprint/iteration planning view
+- [ ] Time tracking
+- [ ] Notifications and subscriptions
+- [ ] Activity feed per node/subtree
+- [ ] Agent marketplace (pre-built agent configurations)
+- [ ] Graph analytics (bottleneck detection, progress heatmaps)
+- [ ] AI-suggested decomposition (assistant mode: "break this into tasks")
+
+### v0.4+: Platform
+
+- [ ] Custom fields on nodes
+- [ ] Workflow automation (status change triggers)
+- [ ] Git integration (link commits to nodes)
+- [ ] CI/CD integration (agent reports build status)
+- [ ] Public API for third-party integrations
+- [ ] Multi-workspace / organization support
+- [ ] Mobile app
+
+## Open Questions
+
+1. **Graph rendering library:** What to use for the layered overview? Options include D3.js, Cytoscape.js, or a custom SVG renderer. D3 offers the most control; Cytoscape has built-in graph layouts.
+
+2. **Real-time collaboration:** Do we need real-time updates in v0.1 (WebSocket) or is polling acceptable? Real-time matters more once agents are actively changing things.
+
+3. **Offline support:** Is this needed for v0.1? Probably not — web-first is fine for the target audience.
+
+4. **Hosting model:** SaaS-first? Self-hosted option for teams that want it? Open-source core?
+
+5. **Node depth limits:** Should we enforce a maximum tree depth? Too deep gets unwieldy. A soft limit of 5-6 levels with a warning might work.
+
+6. **Bulk operations in the graph view:** How do you multi-select in a graph? The flat list handles this, but power users might want it in the layered view too.
+
+7. **History/undo:** How far back can you undo? Is there version history per node? Per graph structure? This matters for agent trust — if an agent messes up, how do you roll back?
+
+## Success Metrics (v0.1)
+
+- **Adoption:** Team uses Non-Linear as primary tracker for 2+ weeks
+- **Graph usage:** Users spend >30% of time in graph views (not just flat list)
+- **Agent integration:** At least one agent connected and actively reading/commenting
+- **Retention signal:** Team continues using after initial trial without reverting to previous tool
+- **Structural depth:** Average project tree depth >2 (indicating real decomposition, not flat usage)