Refresh quickstart around operator chat and quiet agent onboarding - #84
Merged
Merged
Conversation
The README had grown to 437 lines of reference material, with the quickstart buried under install variants and hook internals and the native event delivery section stranded below the License heading. Restructure it to 183 lines: the pitch, a screenshot of tt chat, then the quickstart as the first real section, followed by session flow, waking, a command overview, install/update, customization, storage and development. Add a chat syntax table so the console is usable from the README alone. Move the full command surface, messaging semantics, native event delivery, chat details, install behavior, identity resolution, design notes and storage into docs/reference.md rather than dropping them, and link to it from each summarized section. Fix what was stale or overclaimed while moving it: - the chat footer mockup still showed a member count the footer no longer renders, and a paragraph described reserved suggestion rows that no longer exist - the fencing-token bullet implied lease fencing protects arbitrary workspace edits; it fences Talking Stick's own state - drop --dangerously-skip-permissions from the quickstart The screenshot is resized to 1600px and quantized, 1.2MB to 231KB, because package.json ships docs/ in the npm tarball.
Review caught overclaims, some inherited from the old README and moved verbatim into the reference: - next-tool-boundary steering is operator-only; the service requires a human:% sender for it, so the wake table no longer implies a peer can steer a working session - not every wake carries the message; cmux and oversized payloads fall back to a body-free pull notice - the single-writer line said "guarantees", which reads as enforcement; it is protocol authority, matching the fencing-token caveat - directed messages are filtered from other agents' default waits, so "not private" needed to mean readable via audit views rather than delivered to everyone - messages were called ephemeral and priced at six round-trips; they are recorded in the event log and the cost claim was unsupported - the instruction-tiering table still described wake hooks as fixed warning text, predating native envelopes - tt ack was missing from the list of things that close an unread batch Also: the quickstart console pane now cds into the repo first, since the room follows the working directory; --no-guard needs an explicit harness or --all; @everyone is scoped to agents that have joined; and a jump link sits above the hero image so the quickstart is reachable without scrolling past it.
Two behavior defaults, plus the quickstart that teaches them. Invoking the skill is not a task. Previously an agent pointed at the skill with no work would join and start the loop, which in a room with peers can hand it a turn it has nothing to do with, or leave it asking the operator for direction in a harness prompt nobody is reading. Now a taskless invocation joins, reports in, and enters standby, waiting for the task to arrive in chat. Sessions that cannot self-wake keep one parked wait instead, so they stay reachable without claiming. An explicit task given alongside the skill still runs the normal loop. Agents also kept repeating operator messages to each other. An operator's room message already reaches every joined agent, so echoing it doubles the console; a directed message was scoped deliberately, so forwarding it widens a scope the operator chose. Both the skill and the default instructions now say not to relay, while keeping agents talking about their own actions, findings and disagreements, which is the coordination the room exists for. The README quickstart now mirrors the console layout: agents stacked left, tt chat right, each agent prompted only to load the skill, and the task typed once into the console.
mostlydev
changed the title
The room already emits a join event, and the operator console prints it unconditionally: chat-format.ts renders "codex joined" outside the show_turn_events gate. An agent that also sends "joined, idle, listening" to the room therefore announces itself twice in the console, which is the duplicate noise this branch set out to remove. Agents now join and go idle without a room ping, and introduce themselves when the operator asks rather than on launch, matching the screenshot's flow where the intros answer a chat message.
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
1 participant
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.
The README mixed setup with stale implementation notes, and the setup asked users to repeat a task in every harness. This makes the quickstart match the screenshot: agent panes on the left, tt chat on the right, invoke the skill in each agent, then introduce the agents and give the task once through chat.
The skill and bundled instructions now treat a taskless invocation as join once and stand by, retaining a parked listener when native wake is unavailable. Agents report their own plans and findings without routinely relaying operator messages or widening directed-message scope. Existing explicit-task invocations continue to work.
The shorter README places the screenshot and quickstart link near the top. Detailed command, install, identity, and delivery information lives in docs/reference.md, with stale claims corrected against source.
Validation: full suite 646 passed and typecheck passed during preparation. Final refinements passed the instructions suite (10), typecheck, and build. Independent source review, relative-link/anchor checks, and screenshot inspection passed. Draft pending operator review of the revised quickstart.