> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase25-session08-claude-code-parity-responsive-e2e/spec.md).

# Session Specification

**Session ID**: `phase25-session08-claude-code-parity-responsive-e2e` **Phase**: 25 - Hermes Mission Control Activation **Status**: Not Started **Created**: 2026-06-08

***

## 1. Session Overview

This session proves the upgraded Mission Control surface works as one shared contract across the Hermes and Claude Code presentations. Sessions 03 through 07 restored safe planning prompts, preview-to-commit writes, multi-goal authoring, full prompt and briefing copy, active mission progress, and archive reactivation. The remaining implementation gap before final documentation is route parity and responsive confidence.

The work is intentionally hardening-focused. It should not add new Mission Control product features, bridge endpoints, storage paths, or Claude-specific spawn/shell/workspace capabilities. The goal is to sweep the existing Hermes and Claude Code presentations, fix any copy, layout, accessibility, or contract drift, and add browser coverage that exercises the full assembled Mission Control layout on desktop and mobile.

The most important user-visible outcome is that long planning prompts, per-goal `/goal` copy, human briefings, drawers, active mission rail, optimized preview, and archive list remain usable without horizontal overflow. The same read and admin write boundaries must hold in both routes, with Claude Code differing only by presentation copy and route shell.

***

## 2. Objectives

1. Verify and correct Hermes and Claude Code Mission Control presentation parity across copy, layout, controls, route shell, and contract boundaries.
2. Add Playwright coverage for copied prompt wrapping, mobile drawer behavior, no horizontal overflow, and full Mission Control assembly on both routes.
3. Strengthen route and component tests so Claude Code cannot drift into Claude-specific bridge calls or route-only mutation behavior.
4. Preserve the existing admin-gated, hook-mediated Mission Control read/write architecture while documenting any residual responsive or parity risks.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase25-session03-safe-planning-prompt-authorized-write` - provides the safe planning prompt and authorized optimize path.
* [x] `phase25-session04-multi-goal-authoring-preview-ui` - provides multi-goal authoring and preview-to-commit UI.
* [x] `phase25-session05-full-prompt-drawer-copy-briefings` - provides per-goal copy and human briefing drawers.
* [x] `phase25-session06-active-mission-rail-progress` - provides the active mission rail and milestone progress behavior.
* [x] `phase25-session07-mission-archive-actions` - provides archive reactivation actions and set-active contract coverage.
* [x] `phase23-session01-claude-code-agent-route` - provides the Claude Code route shell that reuses Mission Control.

### Required Tools/Knowledge

* Bun 1.3.14 project toolchain.
* React 19, TypeScript 6, TanStack Query, Tailwind CSS 4, and existing Hermes page primitives.
* Playwright route mocking, viewport testing, DOM overflow checks, and accessibility-oriented locator conventions.
* Existing route tests in `src/routes/__tests__/agents.test.tsx`.
* Existing e2e route coverage in `tests/e2e/hermes-agent.spec.ts`.
* Existing Mission Control presentation contract in `src/components/hermes/hermes-mission-control.tsx`.

### Environment Requirements

* Work from the repository root.
* No live Hermes credentials are required; browser tests should use mocked bridge responses and seeded local browser state.
* Generated private Hermes data, `.env*`, logs, real tokens, local mission files, screenshots, traces, and Playwright reports remain out of git unless a committed fixture is explicitly planned.

***

## 4. Scope

### In Scope (MVP)

* Operators get identical Mission Control capabilities on `/agents/hermes` and `/agents/claude-code` - verify authoring, optimize preview, commit, per-goal copy, human briefing drawer, active rail, clear/tick controls, archive markers, and set-active affordances.
* Operators can read and copy long prompts safely - ensure mission prompts, `/goal` copy, and human briefings wrap or scroll inside their containers without document-level horizontal overflow.
* Operators can use Mission Control on mobile - validate drawer open/close, focus behavior, touch-size action targets, active rail, optimized preview, and archive list at narrow widths.
* Operators can trust the Claude Code boundary - prove it reuses Hermes read and admin bridge endpoints and does not introduce Claude-specific spawn, shell, git, workspace, or local execution calls.
* Test authors get deterministic browser fixtures - share long mission and admin-disabled fixtures across Hermes and Claude Code e2e coverage.
* Route state remains explicit - loading, empty/setup-required, error, offline, token-failure, demo, admin-disabled, and admin-ready copy stays bounded and route-appropriate.

### Out of Scope (Deferred)

* New Mission Control features - Reason: Session 08 hardens existing behavior only.
* New bridge capabilities - Reason: read/write contracts were added in prior sessions and final contract docs land in Session 09.
* Rebranding AI OS around Claude Code - Reason: Claude Code remains a local-agent presentation that reuses Hermes bridge boundaries.
* Documentation closeout - Reason: Session 09 owns final contract docs, considerations, security posture, and release validation.
* Live destructive smoke testing - Reason: this session should use mocked browser routes and not mutate a real local Hermes home.

***

## 5. Technical Approach

### Architecture

Keep Mission Control as the shared product component. `HermesMissionControl` owns presentation variants through its existing `missionControlAgent` prop and should remain the only component that encodes agent-specific Mission Control copy. `ClaudeCodeMissionPage` stays a route shell that wires `useHermes` and `useHermesAdmin` into the same Mission Control contract; it should not parse raw bridge payloads, call Claude-specific endpoints, or introduce route-only write behavior.

Add a shared Playwright fixture module under `tests/e2e/fixtures/` for Mission Control bridge mocks. The fixture should expose realistic long mission data: multiple goals, long `full_prompt` content, a human briefing payload, archived missions, admin-disabled state, and safe paths that cannot resemble real local secrets. Hermes and Claude Code e2e specs should consume the same fixture so parity assertions exercise the same contract.

Use Playwright for layout facts that unit tests cannot prove: no document-level horizontal overflow, mobile drawer usability, long copied prompt wrapping, and full layout assembly. Use component and route tests for faster contract assertions: labels, presentation copy, route metadata, shared bridge call boundaries, and fallback state rendering.

### Design Patterns

* Shared contract, variant copy: Hermes and Claude Code differ through presentation strings and route chrome only.
* Browser facts in browser tests: overflow, viewport, focus, drawer, and wrapping checks belong in Playwright.
* Component facts in component tests: labels, callbacks, state branches, and route-specific copy stay in Vitest/Testing Library.
* Deterministic fixtures: e2e bridge mocks use committed, bounded payloads with no private paths, tokens, or local operator details.
* No new write paths: Session 08 may test write controls but must not add new bridge endpoints or mutation semantics.
* Accessibility-first locators: prefer roles, labels, headings, and named regions over brittle CSS selectors.
* Responsive constraints: fixed-format Mission Control surfaces use stable dimensions, wrapping, clipping, or scroll containers instead of viewport-wide text expansion.

### Technology Stack

* TypeScript 6.0.3.
* React 19.
* TanStack Query 5 through existing Hermes hooks.
* Tailwind CSS 4 plus route-scoped CSS in `src/styles.css`.
* Testing Library and Vitest 4.1.6 for component and route tests.
* Playwright 1.60 for desktop and mobile browser coverage.

***

## 6. Deliverables

### Files to Create

| File                                                                                             | Purpose                                                                                          | Est. Lines |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------- |
| `tests/e2e/fixtures/hermes-mission-control.ts`                                                   | Shared mocked bridge payloads and helpers for Hermes and Claude Code Mission Control e2e checks. | \~260      |
| `tests/e2e/claude-code-agent.spec.ts`                                                            | Claude Code Mission Control route parity, drawer, mobile, and overflow e2e coverage.             | \~220      |
| `.spec_system/specs/phase25-session08-claude-code-parity-responsive-e2e/implementation-notes.md` | Implementation decisions, command output, manual checks, and known follow-ups.                   | \~80       |
| `.spec_system/specs/phase25-session08-claude-code-parity-responsive-e2e/security-compliance.md`  | Session security review for parity testing, mocked fixtures, and unchanged bridge boundaries.    | \~80       |

### Files to Modify

| File                                                              | Changes                                                                                                               | Est. Lines |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------- |
| `tests/e2e/hermes-agent.spec.ts`                                  | Reuse shared Mission Control fixtures and add Hermes prompt/drawer/mobile overflow assertions.                        | \~180      |
| `src/components/hermes/hermes-mission-control.tsx`                | Fix any presentation drift, add stable accessible labels/selectors, and harden long prompt/drawer containers.         | \~160      |
| `src/components/hermes/claude-code-mission-page.tsx`              | Align Claude Code route shell, support banners, and state projections with the shared Mission Control contract.       | \~100      |
| `src/components/hermes/__tests__/hermes-mission-control.test.tsx` | Extend component parity coverage for labels, drawer copy, archive actions, active rail, and Claude Code presentation. | \~160      |
| `src/routes/__tests__/agents.test.tsx`                            | Extend route tests for Claude Code bridge reuse and absence of Claude-specific execution endpoints.                   | \~120      |
| `src/styles.css`                                                  | Add or adjust route-scoped responsive, drawer, prompt, rail, archive, and overflow hardening styles.                  | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Hermes and Claude Code Mission Control presentations expose the same authoring, preview, commit, per-goal copy, briefing drawer, rail, tick, clear, archive, and set-active capabilities.
* [ ] Claude Code route copy is route-appropriate without adding Claude-specific bridge, spawn, shell, git, or workspace calls.
* [ ] Long planning prompts, `/goal` prompts, and human briefings wrap or scroll inside their intended containers on desktop and mobile.
* [ ] Mobile drawer open, close, copy, and focus behavior is usable and tested.
* [ ] The assembled Mission Control layout renders in the intended order: header/support state, empty or authoring actions, optimized preview, active mission rail/grid, and archive list.
* [ ] The document has no horizontal overflow on tested desktop, tablet, or mobile viewports for both routes.
* [ ] Loading, setup-required/empty, error, offline, token-failure, demo, admin-disabled, and admin-ready route states remain explicit and bounded.
* [ ] Existing admin-gated writes remain hook-mediated and no new bridge capability is introduced.

### Testing Requirements

* [ ] Component tests cover Hermes and Claude Code presentation parity for title, prompt copy labels, drawer labels, rail labels, archive labels, and set-active copy.
* [ ] Route tests prove Claude Code uses the existing Hermes bridge and does not call Claude-specific execution endpoints.
* [ ] Playwright tests cover Hermes Mission Control no-overflow and long prompt/drawer behavior.
* [ ] Playwright tests cover Claude Code Mission Control parity, mobile drawer behavior, and no horizontal overflow.
* [ ] Playwright fixtures use bounded safe data and no generated private paths, tokens, or operator-specific local files.

### Non-Functional Requirements

* [ ] No new endpoint, storage path, mission schema field, local execution path, or third-party transfer is introduced.
* [ ] Admin gate strength is unchanged; writes stay loopback, token, admin-mode, non-demo, and hook-mediated.
* [ ] Browser-visible route state contains no token, auth header, local path, raw bridge error detail, or generated private mission file path.
* [ ] Route CSS remains scoped to Hermes and Claude Code skins.
* [ ] UI remains dense, scannable, keyboard reachable, touch friendly, and consistent with the local-agent operator console.
* [ ] Text never overlaps incoherently or creates document-level horizontal overflow on supported viewports.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests pass.
* [ ] Playwright Hermes and Claude Code specs pass.
* [ ] `bun run typecheck` passes.
* [ ] `bun run typecheck:scripts` passes.
* [ ] `bun run lint` passes.

***

## 8. Implementation Notes

### Key Considerations

* The session should start by auditing existing parity rather than assuming drift. Any code changes should be limited to discovered copy, layout, accessibility, or testability gaps.
* Playwright should assert browser layout facts using viewport sizes and DOM measurements instead of relying only on screenshots.
* Long prompts should be realistic enough to exercise wrapping while remaining committed-safe and free of private operator context.
* Existing browser tests already include Hermes route mocks. Extracting shared fixtures should reduce duplication without weakening current Hermes coverage.
* Claude Code must continue to reuse Hermes bridge endpoints. A test that rejects `__claude`, `spawn`, `shell`, `git`, and `workspace` calls should remain part of route or e2e coverage.

### Potential Challenges

* E2e fixture extraction could accidentally weaken existing Hermes assertions: keep current route coverage and add parity checks incrementally.
* Drawer and prompt locators may be ambiguous after route copy changes: add stable accessible names or labels where the UI needs them.
* Mobile overflow can come from nested fixed-width controls, prompt text, rail labels, or archive action rows: inspect computed scroll width after each major Mission Control section.
* Playwright timing can become flaky around query loading and tab activation: wait for route-specific headings and mocked mission text before measuring.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: This session must test bridge reuse without adding or weakening write boundaries.
* \[P17] **Reuse existing hook contracts for write surfaces**: Any parity fix should extend existing `useHermes` and `useHermesAdmin` behavior rather than adding direct route fetches.
* \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Keep Mission Control prop-driven and route-neutral.
* \[P23] **Hermes hook reuse for related agent routes**: Claude Code should remain a presentation variant over the same Mission Control hooks.
* \[P23] **Do not hand-edit generated route trees**: Route coverage changes should not manually edit `src/routeTree.gen.ts`.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Long copied prompts or briefings could create horizontal overflow that unit tests miss.
* Claude Code could accidentally gain route-specific bridge calls or write behavior outside the shared Hermes admin hook.
* Drawer or confirmation state could keep focus trapped or stale after mobile open/close cycles.

***

## 9. Testing Strategy

### Unit and Component Tests

* Extend Mission Control component tests for presentation labels, drawer copy, active rail labels, archive labels, set-active copy, and route-specific prompt wording.
* Extend route tests for Claude Code metadata, bridge reuse, mode/admin state projections, demo fallback, and absence of Claude-specific execution calls.

### Integration and E2E Tests

* Add shared e2e bridge fixtures with long mission data and admin-disabled state.
* Extend Hermes e2e coverage for Mission tab assembly, long prompt/drawer behavior, and mobile no-overflow.
* Add Claude Code e2e coverage for live route parity, mobile drawer behavior, archive visibility, and no horizontal overflow.

### Manual Testing

* Inspect `/agents/hermes` and `/agents/claude-code` at desktop, tablet, and mobile widths with mocked or demo mission data.
* Confirm long prompt text, rail controls, archive rows, and drawers remain readable and do not overlap.
* Confirm no route visibly exposes bridge tokens, local paths, or raw private error details.

### Edge Cases

* No active mission with archived missions present.
* Active mission with very long title, binary outcome, and full prompt.
* Human briefing drawer with long paragraphs and labels.
* Claude Code demo mode with live bridge unavailable.
* Token failure or admin-disabled state while Mission Control actions are visible but disabled.
* Mobile viewport around 390px wide and desktop viewport around 1024px wide.

***

## 10. Dependencies

### External Libraries

* None. Use existing Playwright, React, TanStack Query, Testing Library, Vitest, Tailwind CSS, and local UI primitives.

### Internal Dependencies

* `src/components/hermes/hermes-mission-control.tsx`
* `src/components/hermes/claude-code-mission-page.tsx`
* `src/components/hermes/hermes-read-only-page.tsx`
* `src/hooks/use-hermes.ts`
* `src/hooks/use-hermes-admin.ts`
* `src/lib/hermes-admin-types.ts`
* `src/lib/hermes-types.ts`
* `tests/e2e/hermes-agent.spec.ts`

### Other Sessions

* **Depends on**: `phase25-session03-safe-planning-prompt-authorized-write`, `phase25-session04-multi-goal-authoring-preview-ui`, `phase25-session05-full-prompt-drawer-copy-briefings`, `phase25-session06-active-mission-rail-progress`, `phase25-session07-mission-archive-actions`
* **Depended by**: `phase25-session09-documentation-validation-release`

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase25-session08-claude-code-parity-responsive-e2e/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.