Atmos Specs Tech

---
name: atmos-specs-tech
description: Write or update the technical design document for an Atmos spec at `specs/<ZONE>/<ZONE>-NNN_.../TECH.md`. Use whenever the user wants to turn a PRD into a HOW — architecture, data model, API/WebSocket messages, rollout plan, risks. Trigger on "tech spec", "技术方案", "架构设计", "data model", "WebSocket message", "crate layout", or when the user asks how to build a feature the PRD has already pinned down. Respect Atmos's layered architecture (infra → core-engine → core-service → api → apps) and WebSocket-first transport. Only touch `TECH.md`.
user-invokable: true
args:
  - name: spec_id
    description: Spec identifier, e.g. `APP-006` or `APP-006_project-wiki`. Required.
    required: true
---

# Atmos Specs · TECH

Translate a PRD into an engineering plan concrete enough that another engineer could implement it without a meeting. Output: one `TECH.md` file.

## What this skill owns — and what it does not

- **Owns**: `TECH.md` in one spec directory.
- **Does not own**: BRAINSTORM, PRD, TEST, and — importantly — actual code. If you find yourself wanting to edit `crates/` or `apps/`, stop and hand off to the `atmos-specs-impl` skill.

Why: TECH is a design artifact. It should be reviewable without running the code. Editing code mid-design flow contaminates the spec with premature details.

## Read these before you write

1. `specs/AGENTS.md` — conventions.
2. The spec's own `PRD.md` — this is your contract. Every Must Have (M1, M2, …) should be addressed here.
3. The spec's `BRAINSTORM.md` for context on rejected options.
4. Root `AGENTS.md` — specifically the **Transport Rules** (WebSocket-first) and the **Backend Change Flow** (infra → core-engine → core-service → api).
5. Package-level `AGENTS.md` files for any crate/app you plan to touch:
   - `crates/infra/AGENTS.md` — DB, WebSocket, jobs.
   - `crates/core-engine/AGENTS.md` — PTY, Git, FS.
   - `crates/core-service/AGENTS.md` — business rules.
   - `crates/agent/AGENTS.md` — ACP integration.
   - `apps/api/AGENTS.md` — handlers and DTOs.
   - `apps/web/AGENTS.md` — Next.js app.
   - `packages/ui/AGENTS.md` — shared UI.
6. A comparable existing `TECH.md` for tone and depth:
   - API/WebSocket-style: `specs/APP/APP-012_remote-access/TECH.md`
   - Frontend-heavy: `specs/APP/APP-010_preview-element-select/TECH.md`
   - Protocol/integration: `specs/APP/APP-004_local-agent-integration-acp/TECH.md`

## Workflow

### 1. Anchor to the PRD

Open `PRD.md`. List every Must Have (M1, M2, …) and every resolved fork. The TECH must answer each one. If the PRD has unresolved forks tagged "decide in TECH", resolve them here — explicitly name the decision and why.

If the PRD is empty or obviously stale, pause and suggest running `atmos-specs-prd` first.

### 2. Pick the layer surface

Decide, for each Must Have, which layers need to change. The canonical flow:

```
apps/web or apps/desktop
        ↑
     apps/api (HTTP / WebSocket handlers, DTOs)
        ↑
crates/core-service (business logic)
        ↑
crates/core-engine (tech capability: Git, PTY, FS)
        ↑
crates/infra (DB, WS, Redis, jobs)
```

Rules you should apply unless explicitly overridden by the user:

- **New persistent data** → `crates/infra` (schema + DB access).
- **New capability like "apply a patch", "read a worktree"** → `crates/core-engine`.
- **New business rule like "can user X do Y to workspace Z"** → `crates/core-service`.
- **New endpoint** → `apps/api`, but **only after** asking whether it should be a WebSocket message instead. Atmos is WebSocket-first. Defend any new REST route explicitly in the Risks section.
- **New frontend feature** → start from existing API client in `apps/web/src/api/` and shared primitives in `packages/ui/`.

### 3. Decide data model before protocol

- Sketch types once, canonically. If a type exists in Rust in `crates/*`, reuse it; don't invent a parallel shape.
- Name every new table, column, and enum. Call out migrations explicitly.
- For WebSocket, name every new `WsAction` variant and the payload shape. Link to the existing enum location (`crates/infra/src/websocket/message.rs` or similar) by path.

### 4. Draft rollout steps

Order them so a reviewer can read top to bottom and get smaller, mergeable chunks:

1. Schema / migration.
2. Infra + core-engine plumbing.
3. Core-service logic.
4. Transport (WS message or REST endpoint).
5. Frontend consumption.
6. Feature flag / gradual rollout if any.

Each step should be shippable by itself (or clearly marked as "merge with step N").

### 5. Write TECH.md

Use this structure. Keep it 150–500 lines; go longer only when justified (e.g., APP-001 is a product-wide tech plan).

````markdown
# TECH · <ZONE>-NNN: <Title>

> Technical Design · HOW. Implements PRD <ZONE>-NNN: <Title>.

## Scope summary

One paragraph: what this doc covers, what it explicitly doesn't. Include the PRD Must Have items this doc addresses (e.g., "Addresses M1–M4. N1 and N2 deferred.").

## Architecture overview

High-level diagram (ASCII is fine). Name the layers and the specific crates / apps / packages touched.

```
apps/web  →  apps/api  →  crates/core-service  →  crates/core-engine  →  crates/infra
```

Call out any external dependency (GitHub API, tmux, tunnel provider, LLM provider).

## Module-by-module design

### crates/infra

- **DB schema changes**: …
- **WebSocket message additions**: `WsAction::Foo { … }` in `crates/infra/src/websocket/message.rs`.

### crates/core-engine (or agent / ai-usage / etc.)

- New capability: `fn apply_patch(...) -> Result<…>`.
- Reused capability: existing `X` from `Y`.

### crates/core-service

- New service method / trait: …
- Authorization / validation rules: …

### apps/api

- WebSocket handler: maps `WsAction::Foo` → service call. File path: `apps/api/src/...`.
- REST route **only if justified** — explain here why WS doesn't fit.

### apps/web

- New component(s) and their location under `apps/web/src/components/...`.
- Store changes in `apps/web/src/stores/...`.
- API client wiring in `apps/web/src/api/...`.

### packages/ui (if touched)

- New primitives, new variants on existing primitives.

## Data model

Types, tables, and enums in one place. Use code blocks.

```ts
interface Foo { … }
```

```rust
pub struct Foo { … }
```

```sql
CREATE TABLE foo ( … );
```

## Transport

### WebSocket messages

For each message, define the request/response shape and invariants. Prefer extending `WsAction` over adding REST.

```ts
// request
{ action: "foo_create", payload: { … } }
// response
{ action: "foo_created", payload: { … } }
```

### REST (only if justified)

Endpoint, method, auth, request/response schema. Write a one-line justification for why this isn't a WebSocket message.

## Security & permissions

- Auth requirements.
- Authorization checks (per-project, per-workspace).
- Any sensitive data handled (tokens, file contents). Note how they are stored and logged.

## Rollout plan

Ordered, small, mergeable steps.

1. DB migration `…`.
2. Add `WsAction::Foo` variant (no handler yet).
3. Implement service method + handler behind feature flag.
4. Frontend wiring, hidden behind flag.
5. Enable flag for internal dogfood.
6. Remove flag.

## Risks & tradeoffs

- **Risk**: …
- **Tradeoff**: chose X over Y because …
- **If this breaks in production, the rollback path is**: …

## Dependencies & compatibility

- Depends on spec: …
- Blocks spec: …
- Minimum Atmos version: …
- External services / binaries: `gh`, `tmux`, Tailscale, etc.

## Open questions

- [ ] …
````

## Writing rules

- **English**. Code identifiers stay as-is; comments and prose are English.
- **Use real paths**. `crates/infra/src/websocket/message.rs`, not "somewhere in infra". When you cite a symbol, include enough path that the reader can open the file in one jump.
- **Be decisive**. A TECH doc is where decisions land. When two options both work, pick one and say why in one sentence in Risks & tradeoffs.
- **Defend non-WS REST**. If you're adding a REST endpoint to an otherwise-WS flow, write the one-line reason next to it.
- **Show small before big**. Data model and transport shapes before component trees. It's easier to review a schema than a UI sketch.
- **Skip what's obvious**. Don't rehash the PRD. Don't restate what every Atmos contributor already knows.

## Done criteria

- Every PRD Must Have is visibly addressed somewhere in TECH.md (scan for M1, M2, …).
- Every new type, table, enum, WsAction, endpoint, file path is named.
- A rollout section with at least 3 ordered steps exists.
- At least one risk / tradeoff is named.
- No placeholder comments remain.

## Common mistakes to avoid

- Copying PRD prose into TECH. TECH is bulletier and more concrete.
- Designing in prose without naming file paths. The reader will want to open files.
- Silent REST addition in a WebSocket-first app. Flag it explicitly.
- Skipping the rollout section. A design with no rollout is hard to ship in small PRs.
- Writing implementation code. Pseudocode for clarity is fine; real code belongs in the impl skill.