Add Dialogue feature specification + deferred-specs policy#281
Merged
kirich1409 merged 10 commits intomainfrom Apr 18, 2026
Merged
Add Dialogue feature specification + deferred-specs policy#281kirich1409 merged 10 commits intomainfrom
kirich1409 merged 10 commits intomainfrom
Conversation
Commits the authoritative specification for the Dialogue feature (EPIC #250) to docs/architecture/ as durable documentation — the research worktree can be removed, while the spec continues to live on main and guides implementation whenever it is picked up. Adds two new architecture documents: - dialogue.md — feature spec: problem, user stories, architecture, session surface model, UX live-feel patterns, external dependency decisions, risk register, MVP acceptance criteria, out-of-MVP list. - dialogue-events.md — Claude Code stream-json event catalog with wire-level detail, UI mapping, dedup rules, edge cases. Parser contract for D-8 / D-10. Amends CLAUDE.md Documentation Maintenance section with a new "Deferred feature specs" subsection: specifies that any feature decomposed into an epic but deferred from immediate implementation MUST commit its full spec to docs/architecture/. Research artefacts in swarm-report/ are ephemeral; docs/architecture/ is durable. Updates Architecture Documents index to include the two new files. Closes #254
kirich1409
added
dialogue
There was a problem hiding this comment.
Pull request overview
Adds durable, version-controlled specifications for the deferred “Dialogue” feature (including a wire-level event catalog) and codifies a policy requiring deferred epics to commit their specs under docs/architecture/ before cleaning up ephemeral research worktrees.
Changes:
- Add
docs/architecture/dialogue.mdas the Dialogue feature specification. - Add
docs/architecture/dialogue-events.mdas the Claude Codestream-jsonevent catalog / parser contract. - Update
CLAUDE.mdto index the new docs and introduce a “Deferred feature specs” documentation maintenance policy.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/architecture/dialogue.md | Introduces the Dialogue feature spec (problem, architecture, dependencies, MVP criteria, risks). |
| docs/architecture/dialogue-events.md | Defines the stream-json event catalog, schemas, UI mapping, dedup rules, and edge cases. |
| CLAUDE.md | Adds doc index entries and formalizes a policy for committing deferred feature specs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Deferred specs are snapshots in time — the codebase moves while the spec sleeps, and picking up an epic months later risks implementing against a stale design. A mandatory status banner makes the drift risk visible at the top of every deferred doc and forces re-verifi- cation on the first implementation PR. Changes: - dialogue.md + dialogue-events.md — add the mandatory status banner with snapshot date, link to EPIC #250, and the re-verify obligation. - CLAUDE.md Deferred-specs subsection — codifies: - required banner format (copy-paste template), - re-verify step on the first child-task PR, - status transitions (Deferred → Implemented → Archived), - retirement policy for abandoned specs.
Major fixes: - Correct the dependency graph: `apple/swift-markdown` sits beside `DesignSystem` under `AgentChatUI`, not below `DesignSystem`. Keeps ISP boundary intact (DS stays markdown-free). - MVP AC #2 no longer names a specific markdown library — references the Dependencies table and the current plan (`apple/swift-markdown` + own renderer) instead. - Replace remaining stale Textual references with the actual chosen path (`apple/swift-markdown`) across TL;DR, recommendation, and risks. Textual remains explicitly called out as rejected in the Dependencies table with rationale. - Prerequisites section now notes that `DSCardModifier` and `StatusBadge` already exist in DesignSystem — only `BlockCodeContainer` is genuinely new. Child issues #251 (D-1) and #252 (D-2) annotated with re-verify-before-implement banners. - `dialogue-events.md` banner restored to the CLAUDE.md template; the catalog-specific re-verify note (re-fetch Anthropic docs before D-8) is a separate subsection below the banner, preserving the policy shape. Minor fixes: - `AgentChat` package row clarifies that `TerminalAbstraction` dependency is for a new `rawStdout` hook added in D-5. - Pre-flight risk row clarifies that `ClaudeEnvironment` whitelist is an extension of the existing module, not an existing API. - Architecture Documents index entries tagged with snapshot date + deferred status. - Worktree cleanup rule adds a pre-removal audit step.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Addresses the two remaining issues from the second review pass: 1. Line 156 of dialogue.md (architecture section — "Изменения существующих пакетов") was not updated in parallel with the Prerequisites section during round 1. It now acknowledges that DSCardModifier and StatusBadge already exist in DesignSystem, and only BlockCodeContainer is genuinely new. ISP note no longer names Textual (which was rejected in round 1). 2. Permission-mode inconsistency: dialogue.md used `acceptEdits` throughout (safer — auto-accept edits, pair with --allowedTools list for Bash/etc.), while dialogue-events.md §7 and D-20 child issue used `bypassPermissions` (blanket skip — less safe). Aligned all three on `acceptEdits + --allowedTools`, matching the MVP strategy described in the Risks section of dialogue.md.
- MVP AC #1 in dialogue.md now includes the `--allowedTools` whitelist alongside `--permission-mode acceptEdits`, matching the rest of the spec where the two flags always appear as a pair. - events.md §6.8 (user interrupt) flips the MVP recommendation: plain SIGINT is primary; streaming-input via `--input-format stream-json` moves to a Post-MVP enhancement, since the flag is undocumented (Anthropic issue #24594) — matches dialogue.md approaches section. - events.md §7 CLI launch block drops `--input-format stream-json` from the MVP command line; kept as a commented-out post-MVP hint. - Corresponding updates to child issue bodies: D-20 (#270) expected flag count from 7 to 6, D-9 (#259) interrupt implementation reframed as SIGINT-primary with the streaming-input path explicitly deferred.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Addresses the last remaining major finding — the Architecture section of dialogue.md (Новые пакеты + Изменения существующих пакетов + AgentChatSession protocol) described future state without calling out that none of it exists on main yet. While the deferred-spec banner at the top covers this semantically, a reader jumping to the Architecture section could miss it. Adds an inline callout at the top of the Architecture section listing every symbol that is planned (not present), with an explicit re-verification reminder. Implementers starting on D-1 will now see the status marker right next to the design they're about to build. Also addresses two clarifying minors from the same review: - AgentInput enum shape added inline in the AgentChatSession protocol example — MVP = .text(String), .attachment post-MVP. - `--bare` flag in events.md §7 annotated with "publicly undocumented, re-verify behaviour before D-20" — matches the re-verify obligation already established for Anthropic CLI flags.
- Approach A description now includes the `--allowedTools` whitelist next to `--permission-mode acceptEdits`, matching every other MVP context. The section is now self-contained. - CLAUDE.md §Rules adds an explicit exception pointer to §Deferred feature specs — an agent reading the general "Docs describe what IS" rule won't mistakenly flag a deferred spec as a policy violation.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- "принимать SessionSurface" → "добавить параметр surface: SessionSurface" — aligns verb choice with other planned-state bullets in the same section and reinforces that the param is new. - --bare flag gets the same "publicly undocumented, re-verify" footnote in dialogue.md Approach A description that already exists in events.md §7 — keeps the warning consistent across both docs.
- D-21 note: refactoring AgentSessionFeature.State replaces the existing `terminal: TerminalFeature.State` field with a `presentation: Presentation` enum — it's a breaking State restructure, not an additive change. Flag it so the implementer does regression coverage across all existing Action cases. - D-5 note: RemoteTerminalSession gRPC inbound loop runs outside @mainactor. `rawStdout` emission should use nonisolated continuation forwarding — same pattern already used for TerminalViewDelegate methods (see CLAUDE.md §Gotchas). No `Task { @mainactor in }` hop on the hot path.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Fixes inconsistencies Copilot caught that earlier review agents missed
(they trusted the narrative, Copilot inspects raw text):
Naming consistency — major:
- `.agentChat(...)` → `.agentDialogue(...)` (SessionSurface case) —
matches top-of-doc code identifiers.
- `AgentChatView` → `DialogueView`, `ChatMarkdownView` →
`DialogueMarkdownView`, `ChatInputView` → `DialogueInputView` —
user-facing view names now align with the Dialogue feature name.
- `.chat(AgentChatFeature.State)` → `.dialogue(AgentChatFeature.State)`
in the Presentation enum case.
- Added an Organizing convention section that explains the deliberate
two-layer split: `Dialogue*` for user-facing surface, `AgentChat*`
for generic agent-chat domain reusable by future agents (Codex, ACP).
Technical fixes — Copilot raw-text catches:
- Typo: `bulit-in` → `built-in`.
- "bus factor 0" replaced with "maintained by Apple, no single-
maintainer risk" (the numeric phrasing read as its opposite).
- apple/swift-markdown version column: "snapshot (active, updated
daily)" is not actionable — now says "pin specific commit SHA,
update via explicit PR" matching Apple's un-tagged branch policy.
- ACP adapter name standardised to `zed-industries/claude-agent-acp`
across both docs (was `claude-code-acp` in one place).
- events.md §7 bash block: inline comments after line-continuation
backslashes are syntax errors in shell. Moved all comments above
the command, quoted the `{UUID}` / `{worktree path}` placeholders
as real variable expansions.
CLAUDE.md policy:
- Banner placement wording: "at the very top (before any other
content)" → "immediately after the H1 title" — matches where the
banner actually lives and is standard markdown doc style.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Commits the Dialogue feature specification to
docs/architecture/as durable, version-controlled documentation. EPIC #250 and its 30 child issues (D-1 … D-30) reference these files;swarm-report/research artefacts remain gitignored / ephemeral.Also adds a Deferred feature specs subsection to
CLAUDE.md→ Documentation Maintenance — codifies the policy that any epic deferred from immediate implementation must ship its spec todocs/architecture/before the research worktree is cleaned up.What changes
Why
After decomposition of the Dialogue feature (EPIC #250) into 30 tasks, implementation is deferred to a later time. The research that produced the spec lived in `swarm-report/` (gitignored) inside a throw-away worktree. To avoid losing the spec when the worktree is removed, it moves to `docs/architecture/` and becomes the long-term source of truth. Future work (any of the 30 child tasks) reads from these committed docs, not from research artefacts.
The CLAUDE.md addition makes this the project convention — not a one-off.
Closes
Closes #254 (D-4: Commit Dialogue spec to docs/architecture/).
Test plan
🤖 Generated with Claude Code