In scope
- Derived architecture, domain/class, ERM, flow, dependency, and knowledge views.
- Worktree/session coordination, work-item board, audit explorer, and staged prompts.
- Multiple terminal/visual/prompt tabs within a workspace.
Part A — Functional specification
Problem and core scenario
Multiple coding agents, terminals, worktrees, code artifacts, infrastructure files, and audit records are currently disconnected. The product must let the operator inspect their relationships without creating a hand-maintained architecture model.
In the core scenario, a technical lead selects a domain aggregate, traces it through data/service/infrastructure relationships, identifies an affected worktree/session, inspects the audit evidence, prepares feedback, and explicitly dispatches that reviewed prompt to the intended ready session.
Explicit non-goals
- Replacing a source editor or hand-editing derived diagrams.
- Perfect extraction of dynamic relationships.
- Cloud synchronization, multi-user graph writes, or autonomous code changes.
- Selecting storage, renderer, terminal, or extractor technology before spikes.
Required user outcomes
| Story | Observable outcome |
|---|---|
| Implemented architecture | Filter, expand, and inspect code/infra relationships with provenance, confidence, and stale/failed refresh state. |
| Domain and data | Distinguish hierarchy, aggregate/entity/value-object classifications, ERM evidence, and missing/inferred joins. |
| Flow and impact | Show static and runtime flow differently; return bounded impact results with published limits and continuation. |
| Knowledge | Search and navigate source artifacts, knowledge, and audit decisions as distinct, source-backed information spaces. |
| Coordination | Show work intent separately from current evidence-derived state, session, agent, worktree, dependency, and freshness. |
| Prompt staging | Keep a revisioned rich-text draft until the user confirms an immutable revision and target session/generation. |
| Audit history | Read eligible audit entries with integrity/redaction/duration state; never turn missing information into a clean empty result. |
| Workspace tabs | Preserve tab identity/context and provide non-destructive recovery instead of silently retargeting a terminal or view. |
Conceptual domain model
The model separates Workspace Registry, Evidence and Projection, Agent Operations, Work Coordination, and Audit Reading so source-derived truth, user intent, and audit evidence cannot silently become the same thing.
| Aggregate / fact | Invariant |
|---|---|
| Workspace Registry | Canonical repository/worktree membership is unique in the workspace and rejects path-escaped membership. |
| Relationship Claim + Evidence Assertion | Every displayed relationship has attributable assertion evidence; no evidence renders as not recorded, not a claim. |
| Agent Session | An active session has at most one active worktree reference at a time and has a generation-bound readiness state. |
| Prompt Draft + Delivery Receipt | One immutable prompt revision, workspace, target session generation, and dispatch key identify one delivery outcome. |
| Work Item + Work-State Assessment | Human work intent is distinct from an evidence-derived assessment; stale, unknown, and conflicted override success-shaped status. |
| Audit Entry / Derived View | Audit records are append-only source evidence; a view is rebuildable projection and never implementation truth. |
Part B — UX specification
The primary operator is an expert working under cognitive load. The experience is dense, not cramped; calm, not passive; powerful, not opaque. Reading evidence is parallel; composing and dispatching a prompt is serial and deliberate.
Workspace
Repositories, worktrees, sessions, and health.
Explore
Architecture, Domain, Data, Flows, Dependencies, Knowledge.
Coordinate
Work board, claims, slices, conflicts.
Compose
Prompt drafts, context references, target session.
Audit
Timeline, prompts, responses, artifacts, decisions.
Every flow has an explicit recovery path: source refresh can retry, inspect provenance, or return to Explore; dispatch can revalidate, retarget, or preserve a draft and exit; coordination can show no-match/conflict/write-failure states; audit and tabs preserve identity when a source/session is unavailable.
Part C — UI specification
The shell uses the B1 Keyboard-Velocity GUI archetype because the dominant job is rapid expert navigation across many sessions and evidence views. It embeds spatial/graph and telemetry views where their jobs require them; it is not a generic equal-weight dashboard.
Archetype signature:
Type:OLTP · Arch:SPA · Layout:MasterDetail · Density:Compact ·
Nav:CommandPalette+Sidebar · Input:KeyboardFirst+PrecisionPointer ·
A11y:WCAG_2.2_AA
- Medium: Windows desktop workspace; Fluent 2 and Windows keyboard/focus conventions.
- Design system:
DESIGN.mdis a required design-gate artifact with token modes and measured AA contrast. - States: every terminal, graph, work-board, prompt, audit, filter, command, and dialog surface has loading, empty, partial/stale, unavailable, error/retry, success, and long-content behavior where applicable.
- Accessibility: keyboard-first navigation, focus restoration, semantic graph/list equivalence, accessible names/roles/value changes, no color-only states, and NVDA/automated evidence before implementation approval.
- Performance: p95 selected-view render under 2 seconds; p95 node selection under 100ms; p95 filter update under 250ms on an approved benchmark corpus.
- AI honesty: prompt transfer distinguishes acknowledgement, observed agent activity, unknown downstream result, inferred content, and verified repository fact.
Security, privacy, and verification gates
| Gate | Required control |
|---|---|
| Trust boundaries | Canonical path containment, safe terminal/renderer behavior, generation-bound prompt binding, default-deny MCP capabilities, bounded parsing, audit integrity, and dependency provenance. |
| Privacy | Workspace owner and repository-policy precedence; egress deny by default; source/audit classification before indexing; purpose-minimum retention/deletion; opaque allowlisted telemetry. |
| Indirect model egress | Session declares LocalOnly, ExternalProcessing, or UnknownProcessing. Unknown fails closed for rich prompt/context transfer; external processing requires provider/residency/retention/policy preview. |
| Verification | Versioned fixtures and deterministic oracles for every user story; red-first security/privacy/accessibility tests and benchmark results before implementation approval. |
The linked privacy review adds the LINDDUN-lite data inventory, rights/deletion path, unsafe-audit fail-closed rule, and future external-processing approval requirements.
Flagged risks and handoff
- Graph storage, extractor fidelity, terminal hosting, prompt-editor fit, audit-reader contract, and scale are spike decisions.
- Existing audit history may contain unsafe source content outside the IDE’s deletion reach.
- Independent usability evidence beyond the product-owner workflow remains outstanding.
- Implementation must attach red-first tests, mutation/benchmark evidence, a Proof Pack, component LINDDUN review, design tokens, contrast audit, review harness, and accessibility traces.
Handoff: proceed to /define-architecture only after the named
spikes are planned; no implementation choice is made by this specification.