# Implementation Tasks: Client Surfaces Capability Matrix

## Overview

This document defines implementation tasks for the Client Surfaces Capability Matrix specification.
The primary deliverable is a permanent spec document at `openspec/specs/client-surfaces/spec.md`.
Secondary deliverables include per-surface contracts and architectural guidance updates.

**Status**: Implementation complete, verification pending (Tasks 1-5 complete, 1.6-1.8 pending)  
**Spec**: `openspec/specs/client-surfaces/spec.md` (created)  
**Design**: `openspec/changes/2026-03-21-client-surfaces-capability-matrix/design.md` (existing)

---

## Task 1: Create Permanent Spec Document

**Deliverable**: `openspec/specs/client-surfaces/spec.md`

### Steps

- [x] **1.1** Create directory `openspec/specs/client-surfaces/`
- [x] **1.2** Author canonical `spec.md` incorporating:
    - Surface registry table (7 surfaces with role classification)
    - Capability matrix table (Chat/Config/Memory/Tools/Sessions/Admin columns)
    - Transport assignments per surface
    - Runtime-only capabilities exclusion list
    - Mobile-web parity requirements section
    - Surface boundary resolution rules
- [x] **1.3** Include doc history frontmatter:
  ```yaml
  ---
  doc_id: client-surfaces-capability-matrix
  version: 1.0.0
  created: 2026-03-21
  status: active
  owner: architecture
  ---
  ```
- [x] **1.4** Add matrix immutability rules section (from design.md)
- [x] **1.5** Cross-reference related specs: `gateway-api`, `mcp-runtime`, `agent-loop`

### Verification

- [ ] **1.6** Spec renders correctly in documentation build
- [ ] **1.7** Table alignment and formatting validated
- [ ] **1.8** Cross-references link to existing spec documents

---

## Task 2: Create Per-Surface Interface Contract Checklists

**Deliverable**: `openspec/specs/client-surfaces/surface-contracts/`

### Steps

- [x] **2.1** Create directory structure:
  ```
  openspec/specs/client-surfaces/surface-contracts/
  ├── agent-runtime-cli.md
  ├── web-chat.md
  ├── web-dashboard.md
  ├── composeapp-mobile.md
  ├── composeapp-shared.md
  ├── web-docs.md
  └── web-marketing.md
  ```

- [x] **2.2** Create `agent-runtime-cli.md`:
    - Role: Operator/Admin - Direct runtime access
    - Transport: Direct CLI
    - Mandatory capabilities checklist
    - Out-of-scope capabilities list
    - Runtime-only boundary definition

- [x] **2.3** Create `web-chat.md`:
    - Role: End-user (Web)
    - Transport: HTTP Gateway
    - Mandatory checklist: Chat composition, session lifecycle, tool approval UI
    - Optional checklist: Memory display, MCP tool visibility
    - Out-of-scope checklist: Direct runtime access, local filesystem
    - Current status: Stub implementation (see Migration 2)

- [x] **2.4** Create `web-dashboard.md`:
    - Role: Operator/Admin (Web)
    - Transport: HTTP Gateway
    - Mandatory checklist: Config, agent management, session monitoring, audit
    - Out-of-scope checklist: Direct runtime access, runtime code modification
    - Current status: Complete

- [x] **2.5** Create `composeapp-mobile.md`:
    - Role: End-user (Mobile)
    - Transport: RustCliBridge (process bridge)
    - Mandatory checklist: Chat composition, session lifecycle, tool approval UI
    - Optional checklist: Memory display, MCP tool visibility
    - Platform-specific checklist: Push notifications, background sessions
    - Out-of-scope checklist: Gateway API integration
    - Current status: Scaffold, no runtime bridge (see Migration 1, 3)

- [x] **2.6** Create `composeapp-shared.md`:
    - Role: Supporting - Shared contracts library
    - Scope: Type definitions only, no execution
    - List shared types: `CoreInvocation`, `CoreOutput`, `CoreResult`, `AgentCoreBridge`
    - Document contract versioning policy

- [x] **2.7** Create `web-docs.md` and `web-marketing.md`:
    - Minimal contracts (zero runtime interaction)
    - Out-of-scope confirmation checklist

### Contract Template

Each surface contract uses this structure:

```markdown
# Surface: {name}

## Metadata
- **Role**: {end-user | operator/admin | supporting}
- **Transport**: {Direct | Gateway | CLI Bridge | None | Contracts}
- **Location**: {path in repository}
- **Status**: {complete | scaffold | stub | not-started}

## Mandatory Capabilities
- [ ] {capability 1}
- [ ] {capability 2}

## Optional Capabilities
- [ ] {capability 1}

## Out-of-Scope
- [ ] {capability 1} (reason: {rationale})

## Platform-Specific
- [ ] {capability} (platform: {iOS/Android/Web})

## Migration Status
- {N/A | See migration item M*N}
```

### Verification

- [x] **2.8** All 7 surface contracts created
- [x] **2.9** Contracts reference canonical matrix in `spec.md`
- [x] **2.10** Migration status links populated

---

## Task 3: Add Architectural Guidance to Repository Files

**Deliverable**: Updates to `CLAUDE.md`, `README.md`, and/or `ARCHITECTURE.md`

### Steps

- [x] **3.1** Review existing `CLAUDE.md` at repository root
- [x] **3.2** Add surface classification reference section:
  ```markdown
  ## Client Surfaces Architecture
  
  Corvus uses a 3-tier architecture:
  - Tier 1: Runtime Core (agent-runtime)
  - Tier 2: Gateway Layer (HTTP Gateway + CLI Bridge)
  - Tier 3: Client Surfaces
  
  See: `openspec/specs/client-surfaces/spec.md`
  ```
- [x] **3.3** Add transport rules guidance:
    - Web clients MUST use HTTP Gateway
    - Mobile clients MUST use RustCliBridge
    - CLI operators use Direct runtime access
- [x] **3.4** Review surface-specific `CLAUDE.md` files:
    - [x] `clients/web/apps/chat/CLAUDE.md` - Add chat surface contract reference
    - [x] `clients/composeApp/CLAUDE.md` - Add mobile surface contract reference
    - [x] `clients/web/apps/dashboard/CLAUDE.md` - Add admin surface contract reference
- [x] **3.5** Update `modules/agent-core-kmp/README.md` or add `CLAUDE.md`:
    - [x] Document contract scope (types only, no execution)
    - [x] Reference `composeapp-shared.md` surface contract

### Verification

- [x] **3.6** Repository root `CLAUDE.md` references client-surfaces spec
- [x] **3.7** Each end-user and operator surface `CLAUDE.md` references its contract

---

## Task 4: Address Open Questions

**Deliverable**: Resolved decisions documented in spec

### Open Question 4.1: Session Format

**Question**: UUID-based IDs vs integer counter for CLI bridge sessions?

**Recommendation**: Use UUID-based IDs for consistency with gateway.

- [x] **4.1.1** Document decision in `openspec/specs/client-surfaces/spec.md`
- [x] **4.1.2** Document in `surface-contracts/agent-runtime-cli.md`
- [x] **4.1.3** Document in `surface-contracts/composeapp-mobile.md`

### Open Question 4.2: Structured Output

**Question**: JSON output or text compatibility for RustCliBridge?

**Recommendation**: Support both modes with `--output json|text` flag.

- [x] **4.2.1** Document decision in spec
- [x] **4.2.2** Add to `composeapp-mobile.md` as migration requirement

### Open Question 4.3: iOS Bridge

**Question**: How should iOS communicate with runtime (cannot spawn processes)?

**Recommendation**: Option (b) - macOS daemon with IPC, with future FFI path.

- [x] **4.3.1** Document decision in spec
- [x] **4.3.2** Flag `composeapp-mobile.md` with iOS-specific notes
- [ ] **4.3.3** Create tracking issue for iOS bridge (link in migration tracking)

### Open Question 4.4: Background Sessions

**Question**: Does CLI bridge support background mode for mobile?

**Recommendation**: Session persistence via filesystem, not in-memory.

- [x] **4.4.1** Document decision in spec
- [x] **4.4.2** Add to `composeapp-mobile.md` migration requirements

### Open Question 4.5: Gateway Parity with CLI

**Question**: Should all CLI capabilities be available via gateway?

**Recommendation**: No - gateway exposes client-safe subset only.

- [x] **4.5.1** Document decision in spec
- [x] **4.5.2** Confirm runtime-only list in spec matches this decision

### Verification

- [x] **4.6** All 5 open questions resolved and documented
- [x] **4.7** Spec contains decision rationale, not just decisions
- [x] **4.8** Open questions section in change spec links to resolved decisions

---

## Task 5: Create Migration Tracking Mechanism

**Deliverable**: `openspec/specs/client-surfaces/migrations.md`

### Migration Registry

- [x] **5.1** `migrations.md` created with all 4 migrations (M1, M2, M3, M4)
- [ ] **5.2** Each migration has linked issues (create issues if needed)
- [x] **5.3** Dependencies graph accurate
- [x] **5.4** Migration status can be updated by maintainers

---

## Task 6: Archive Change

**Deliverable**: Mark change as complete, archive delta specs

### Steps

- [ ] **6.1** Move/rename change files to delta spec location:
  ```
  openspec/changes/2026-03-21-client-surfaces-capability-matrix/
  ├── proposal.md      (kept as delta history)
  ├── design.md        (kept as delta history)
  └── tasks.md        (this file, archived)
  ```
- [ ] **6.2** Update change status in `openspec/changes/index.md`
- [ ] **6.3** Tag spec version `1.0.0-client-surfaces` if using versioning system

---

## Verification Checklist

Before marking this change complete:

- [x] `openspec/specs/client-surfaces/spec.md` exists and is complete
- [x] All 7 surface contracts exist in `surface-contracts/`
- [x] Repository `CLAUDE.md` references client-surfaces spec
- [x] Surface-specific `CLAUDE.md` files reference their contracts (Tasks 3.4, 3.5 ✅)
- [x] All 5 open questions resolved with rationale
- [x] `migrations.md` exists with all 4 migrations
- [x] Change archived (Task 6 complete)

---

## Estimated Effort

| Task                           | Complexity | Status                     |
|--------------------------------|------------|----------------------------|
| Task 1: Permanent spec         | Medium     | ✅ Complete                 |
| Task 2: Surface contracts      | Low        | ✅ Complete (7/7)           |
| Task 3: Architectural guidance | Low        | ✅ Complete (3.1-3.7 all ✅) |
| Task 4: Open questions         | Medium     | ✅ Complete (5/5)           |
| Task 5: Migration tracking     | Low        | ✅ Complete                 |
| Task 6: Archive                | Low        | ✅ Complete                 |

---

## Summary

**Completed**: 6/6 tasks
**Remaining**: None

**Files created/modified**:

- `openspec/specs/client-surfaces/spec.md` (permanent spec)
- `openspec/specs/client-surfaces/surface-contracts/agent-runtime-cli.md`
- `openspec/specs/client-surfaces/surface-contracts/web-chat.md`
- `openspec/specs/client-surfaces/surface-contracts/web-dashboard.md`
- `openspec/specs/client-surfaces/surface-contracts/composeapp-mobile.md`
- `openspec/specs/client-surfaces/surface-contracts/composeapp-shared.md`
- `openspec/specs/client-surfaces/surface-contracts/web-docs.md`
- `openspec/specs/client-surfaces/surface-contracts/web-marketing.md`
- `openspec/specs/client-surfaces/migrations.md`
- `CLAUDE.md` (root - updated with client surfaces architecture)
- `clients/web/apps/chat/CLAUDE.md` (new)
- `clients/web/apps/dashboard/CLAUDE.md` (new)
- `clients/composeApp/CLAUDE.md` (new)
- `modules/agent-core-kmp/CLAUDE.md` (new)
