Pre-flight implementation specs for under-specified consumer-critical issues

[kovtcharov]

Goal

Pre-flight implementation specs for consumer-critical issues that are currently under-specified for coding-agent execution. Prevents divergent agent implementations and rework.

Why this matters

Issues #887 (skill synthesis), #888 (agentskills.io format), #890 (privacy verifier) shipped with full implementation specs in their comments — dataclasses, pseudocode, acceptance criteria, failure modes. They're ready for agent assignment. Other consumer-critical issues are not.

When an agent picks up an under-specified issue, it makes architectural decisions ad-hoc. Two agents on adjacent issues will make different decisions. Result: PRs that don't compose, rework, slipped ship date.

Scope — write specs at the depth of #887/#888/#890 for these issues

Issue	Why under-specified	Spec required
#549 Agent UI MCP server	High-level scope; no API surface defined	MCP tool list (start/stop/send-message/get-state); stdio transport contract; auth model; persistence; example client
#688 Dynamic tool loading via memory	Mentions "context" without defining the trigger; no policy for which tools load when	Algorithm: how memory recall maps to tool subset; thresholds; cache strategy; integration point with agent planning loop
#702 Voice-first parity	"Parity between voice and text" is a goal not a spec	Agent-boundary voice abstraction interface; how surfaces (Agent UI, Telegram, browser-PWA) consume; codec negotiation
#719 ChatAgent prompt compression (7,400 → 4,000 tokens)	Quantified goal but no method	Specific reduction strategies (tool docstring summarization, system prompt restructure, dynamic loading via #688); regression tests for behavioral parity
M2 Mobile-responsive Agent UI	Requirements listed but no design-system spec	See A3 (separate issue) — A2 includes A3 by reference
M3 Mobile voice via browser	Cross-browser quirks listed but no codec/API decision	Concrete codec list per browser; permission UX flow; push-to-talk vs tap-to-toggle decision

Process per spec

• Read existing issue body + linked code + adjacent issues for context
• Draft spec at the depth of gh issue view 887 -c style comments
• Post as a comment on the original issue
• Tag the issue with spec-ready label (new label, see below)
• Notify orchestrator that the issue is now agent-assignable

New label

• spec-ready (color #0E8A16, green) — issue has an implementation spec adequate for agent assignment

Authorship

• Each spec can itself be drafted by a coding agent (using Skill auto-synthesis: procedural memory layer extending PR #606 #887/Adopt agentskills.io open standard for skill format compatibility #888/Privacy & telemetry audit + verification UX — make zero-telemetry a property #890 as templates), then reviewed by a human or architecture-reviewer before posting
• Estimated cost per spec: ~30-60 minutes of agent time + 15 minutes of human review

Deliverables

• 6 specs posted as comments on Agent UI MCP Server: programmatic UI control for agents #549, Dynamic tool loading based on conversation context via memory #688, Voice-first interaction: parity between voice and text as P0 enabling technology #702, perf: reduce ChatAgent system prompt from ~7,400 to ~4,000 tokens #719, M2 (Mobile-responsive Agent UI: touch targets, single-pane layout, virtual keyboard #895), M3 (Voice via mobile browser: ASR + TTS on iOS Safari + Android Chrome #896)
• spec-ready label created and applied
• AGENTS.md references this issue as the example pattern
• Updated triage rule: no consumer-critical issue is agent-assignable without spec-ready

Acceptance criteria

• All 6 issues have specs covering: dataclasses/interfaces, pseudocode for non-obvious logic, acceptance criteria → test mapping, failure modes, attribution
• A coding agent given any of these issues + the spec produces a PR that needs no architectural rework in review
• gh issue list --label spec-ready returns ≥ 6 items by end of week

Dependencies

• Blocks: agent execution on Agent UI MCP Server: programmatic UI control for agents #549, Dynamic tool loading based on conversation context via memory #688, Voice-first interaction: parity between voice and text as P0 enabling technology #702, perf: reduce ChatAgent system prompt from ~7,400 to ~4,000 tokens #719, M2, M3
• Adjacent: A1 (orchestration playbook documents this rule), A3 (mobile design-system spec — itself a sub-deliverable)
• Targets: complete by May 5, 2026 so v0.18.2 + v0.20.0 work can start with specs in hand