From f85faba0c7a6c366d0d55df5549d7c0426a025ad Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Wed, 30 Sep 2026 13:09:55 -0700 Subject: [PATCH] refactor(skills): rename scribe to docs and trim it --- docs/ARCHITECTURE.md | 16 +- docs/PRODUCT.md | 6 +- plugins/corbits-skills/manifest.json | 2 +- .../skills/create-issue/SKILL.md | 2 +- plugins/corbits-skills/skills/docs/SKILL.md | 32 ++ plugins/corbits-skills/skills/scribe/SKILL.md | 375 ------------------ src/agent/directors/shakespeare/package.ts | 4 +- src/telemetry/classify.ts | 2 +- 8 files changed, 48 insertions(+), 391 deletions(-) create mode 100644 plugins/corbits-skills/skills/docs/SKILL.md delete mode 100644 plugins/corbits-skills/skills/scribe/SKILL.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 447d9cae6..9c145a1b6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -312,13 +312,13 @@ Every shipped specialist is a **director package** — a prompt-first `DirectorP **Docs + QA** -| Director | Owns | -| ----------- | --------------------------------------------------------------------------------------- | -| shakespeare | Docs maintain (scribe core baked into prompt); PRODUCT/ARCHITECTURE/IMPLEMENTATION lane | -| testsmith | Test design only (what/how to test) | -| tester | Runtime verification; never fix product code | -| gauntlet | Mutation/vacuity check that named tests can actually fail | -| prober | Measure-only latency/behavior probe per family/model | +| Director | Owns | +| ----------- | ------------------------------------------------------------------------------------- | +| shakespeare | Docs maintain (docs core baked into prompt); PRODUCT/ARCHITECTURE/IMPLEMENTATION lane | +| testsmith | Test design only (what/how to test) | +| tester | Runtime verification; never fix product code | +| gauntlet | Mutation/vacuity check that named tests can actually fail | +| prober | Measure-only latency/behavior probe per family/model | **Intent → director** (`spawn_agent(intent=…)` when `agent` is omitted). implement/review (and their default directors) fail closed without non-empty `success_criteria`. @@ -468,7 +468,7 @@ Corbits Code **ships a bundled catalog** as the first-party data-only plugin `pl `discoverRepoPlugins` locates `plugins/` next to the source root, at `dist/plugins`, or at `dirname(execPath)/plugins`. It never scans the session cwd for the bundled catalog. -Primary is Skywalker. Bundled skill bodies are **how-to playbooks** (steps, done-definition) — not director personas and not fleet routers. Identity and who-does-what live on director system prompts. Default slashes: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/scribe`, `/interview`. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/scribe` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit greybeard → implement → gate → critic loop and does not steal planning from `/plan`; substantial Builder work consumes a counsel / `/plan` plan first; `/plan` authors an eng change plan and does not implement or file tickets; `/create-issue` remains the tracker command — Linear MCP when available, otherwise `ask_operator` for the platform and persists `Preferred issue tracker` in `.corbits/MEMORY.md` There is no first-party dispatch skill — Skywalker orchestrates natively. Draper and emil are closed directors via `spawn_agent(agent=…)`, not slashes. There is no catch-all worker. The operator types the slash; the primary follows the playbook. +Primary is Skywalker. Bundled skill bodies are **how-to playbooks** (steps, done-definition) — not director personas and not fleet routers. Identity and who-does-what live on director system prompts. Default slashes: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/docs`, `/interview`. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit greybeard → implement → gate → critic loop and does not steal planning from `/plan`; substantial Builder work consumes a counsel / `/plan` plan first; `/plan` authors an eng change plan and does not implement or file tickets; `/create-issue` remains the tracker command — Linear MCP when available, otherwise `ask_operator` for the platform and persists `Preferred issue tracker` in `.corbits/MEMORY.md` There is no first-party dispatch skill — Skywalker orchestrates natively. Draper and emil are closed directors via `spawn_agent(agent=…)`, not slashes. There is no catch-all worker. The operator types the slash; the primary follows the playbook. #### Discovery and precedence diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 06302e2ce..9eab5cc0d 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -20,7 +20,7 @@ That distinction sets priority. **The harness is core and cannot be swapped in later**, because everything runs inside it. Fleet events waking the director, continuous dispatch while capacity is free, unprompted reporting, aggregated health, a bound grounded in real cost rather than a turn count. This is the part no one can hand us and the part a competitor cannot copy from a directory of prompts. -**Agent personas and skills are content.** They define who gets dispatched and to what standard. They are valuable, they are swappable, and they ship as the first-party `corbits-skills` plugin — on by default, disable-able in `/plugins`. The default action set (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/scribe`, `/interview`, `/ast-grep`, `/lexicon`) is not an optional install and not something an operator has to discover. +**Agent personas and skills are content.** They define who gets dispatched and to what standard. They are valuable, they are swappable, and they ship as the first-party `corbits-skills` plugin — on by default, disable-able in `/plugins`. The default action set (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/docs`, `/interview`) is not an optional install and not something an operator has to discover. **Distribution is packaging for content**, and content is not the constraint. A catalog and an install surface matter eventually; they do not gate anything the product is actually judged on. @@ -107,7 +107,7 @@ the file path and parse details. The TUI has an extensible slash-command framework. Built-ins include `/help` (shortcut + command overlay), `/model` (models-only picker for connected accounts; **Alt+A** or `/connect` adds a provider), `/settings`, `/permissions`, `/plugins`, `/clear`, `/new`, `/compact` (fold conversation context now, optional trailing instructions to the summarizer; does not wait for the 60% occupancy governor; idle success shows the fold and does not start a new turn), `/mcp` (enable, disable, or remove servers), `/handoff [optional instructions]` (folds context through the shared operator pipeline, then immediately starts the next turn with the instructions as the inbound content — default copy when omitted; unlike `/compact`, which stops after the fold, handoff always re-infers, so the operator can pivot goals without `/clear`; a handoff issued mid-tool-batch queues behind the in-flight batch and whichever boundary fires first runs the single fold), and `/yolo` (`/yolo [on|off|toggle]`, bare `/yolo` toggles), plus a `/` command per available workflow. `/yolo` persists skip-permissions to the active settings file. That file is the user-global `~/.corbits/settings.json` by default, making the setting machine-wide; explicit `--config ` selects a different active file, and `/yolo` writes that file. An ordinary TUI launch without the same `--config` returns to the user-global source and does not modify the custom file. `--dangerously-skip-permissions` and `--yolo` are process-only aliases. Secret-guard and authz still apply. When a session starts with its active persisted setting already on, the TUI and `corbits exec` warn that permission prompts are disabled by saved settings at the active settings path and direct the operator to edit that file to re-enable them. Plugins can register additional commands. -**Default skills** exist out of the gate as first-party slash **actions**, not director names: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/scribe`, `/interview`. Each one is a how-to playbook — the slash sends the skill body to the primary, which follows the steps. Skills do not assign identity or route the fleet; that stays on director system prompts. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/scribe` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit review/build/critique loop — it does not steal planning from `/plan`. Substantial Builder work consumes a counsel / `/plan` plan first; tiny parent-DIY stays plan-optional. `/plan` authors an eng change plan (files, AC, non-goals, risks, ordered steps) and does not implement. `/create-issue` remains the tracker command: Linear MCP when available; otherwise it `ask_operator`s for the platform (GitHub etc.) and persists `Preferred issue tracker` in `.corbits/MEMORY.md` (GitHub via `gh issue create`). There is no first-party dispatch skill — Skywalker orchestrates natively. `linear-issue-workflow`, `style`, `philosophy`, `native-integration`, and `typescript` stay `use_skill` only (`user-invocable: false`); `git-worktrees` is a background library that is not listed for `use_skill`. Draper and emil are not slashes; they remain closed directors via `spawn_agent(agent=…)`. There is no catch-all worker. Slash names are also available to the model via `skill_search` (descriptions) then `use_skill` (body). Disable the catalog in `/plugins` (`corbits-skills`) if you want them gone. +**Default skills** exist out of the gate as first-party slash **actions**, not director names: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/docs`, `/interview`. Each one is a how-to playbook — the slash sends the skill body to the primary, which follows the steps. Skills do not assign identity or route the fleet; that stays on director system prompts. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit review/build/critique loop — it does not steal planning from `/plan`. Substantial Builder work consumes a counsel / `/plan` plan first; tiny parent-DIY stays plan-optional. `/plan` authors an eng change plan (files, AC, non-goals, risks, ordered steps) and does not implement. `/create-issue` remains the tracker command: Linear MCP when available; otherwise it `ask_operator`s for the platform (GitHub etc.) and persists `Preferred issue tracker` in `.corbits/MEMORY.md` (GitHub via `gh issue create`). There is no first-party dispatch skill — Skywalker orchestrates natively. `linear-issue-workflow`, `style`, `philosophy`, `native-integration`, and `typescript` stay `use_skill` only (`user-invocable: false`); `git-worktrees` is a background library that is not listed for `use_skill`. Draper and emil are not slashes; they remain closed directors via `spawn_agent(agent=…)`. There is no catch-all worker. Slash names are also available to the model via `skill_search` (descriptions) then `use_skill` (body). Disable the catalog in `/plugins` (`corbits-skills`) if you want them gone. Providers are **models-first**: there is no standalone `/login` command. `/model` opens a **models-only list** (Recent, Favorites, then connected provider/model rows) — type-to-filter owns printable keys, so Connect is never a bare letter. **Alt+A** or `/connect` opens a dedicated add-provider selector over every first-class kind (OpenAI dual-path ChatGPT OAuth or API key, xAI, OpenCode Zen, Anthropic, Google, OpenCode Go, Z.AI Coding Plan, Ollama, Custom), each annotated with its live account count and never filtered out for “already connected.” **Alt+F** toggles favorite on the highlighted model. **Alt+D** persists the highlighted pair as the default without switching the live session. Advanced provider drill-down (edit/delete/tiers) stays on the advanced surface, not a bare printable key while the model list is filtering. OAuth providers open their existing browser login with a named account step so multiple accounts per kind coexist (`codex/work`, …). API-key providers use the same named-instance step before the key (auth-only form: instance name + key + fixed catalog base URL), so personal and team keys land as distinct catalog rows (`openai/default`, `anthropic/work`, …); reusing a name re-keys that instance after confirm. Custom remains a free-form single endpoint (full manual form). Successful connect refreshes the catalog and reopens the model list focused on the new account’s default model. OpenCode Go lists models from the live `/zen/go/v1/models` catalog (packaged seed on fetch failure), routes each by its protocol metadata (chat completions, OpenAI responses, or Anthropic messages) and can show subscription usage in the status bar when active (rolling 5h / weekly / monthly windows when the usage API responds; omitted on auth or network failure). When Go returns a quota or rate-limit error — including some HTTP 400 responses that carry limit payloads — Corbits classifies them so quota aborts cleanly and short provider rate limits remain retryable. On a free-tier or subscription quota hit, wait for the window to reset or use OpenCode Zen free models. @@ -155,7 +155,7 @@ Capabilities beyond the core toolset are opt-in plugins, enabled per workspace t ## Multi-agent (fleet agents) -The primary session is always **orchestrator** (single-agent mode is gone). Its identity is **Skywalker** (product name remains Corbits Code; when asked its name, answer Skywalker): classify work, DIY tiny/single-file/one-route product edits, dispatch a **closed fleet of 20 directors** for substantial work, track the fleet, and synthesize. Product mutation tools (`write_file` / `edit_file` / `delete_file`) are mounted on the primary (CORE / `SKYWALKER_TOOLS`) — path tools are the DIY surface; spawn remains the default for substantial, multi-file, parallel, or specialist work. Shell file-writes stay denied. MCP tools are not re-filtered by a product-write deny list (that list is gone). There is no static per-package write-path declaration (CL-6952 removed it — no shipped director ever set one). A concurrent dispatch landing on the same working directory as another still-running lane is recorded as a `conflict` intervention, not blocked. Operator slash recipes (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/scribe`, `/interview`, `/ast-grep`, `/lexicon`) tell Skywalker which directors to spawn for substantial work (`/lexicon` runs on the primary and spawns nothing); tiny/bounded edits may run on the primary. +The primary session is always **orchestrator** (single-agent mode is gone). Its identity is **Skywalker** (product name remains Corbits Code; when asked its name, answer Skywalker): classify work, DIY tiny/single-file/one-route product edits, dispatch a **closed fleet of 20 directors** for substantial work, track the fleet, and synthesize. Product mutation tools (`write_file` / `edit_file` / `delete_file`) are mounted on the primary (CORE / `SKYWALKER_TOOLS`) — path tools are the DIY surface; spawn remains the default for substantial, multi-file, parallel, or specialist work. Shell file-writes stay denied. MCP tools are not re-filtered by a product-write deny list (that list is gone). There is no static per-package write-path declaration (CL-6952 removed it — no shipped director ever set one). A concurrent dispatch landing on the same working directory as another still-running lane is recorded as a `conflict` intervention, not blocked. Operator slash recipes (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/docs`, `/interview`) tell Skywalker which directors to spawn for substantial work (`/lexicon` runs on the primary and spawns nothing); tiny/bounded edits may run on the primary. | Lane | Directors | | --------- | -------------------------------------------------------------------------------------------------------- | diff --git a/plugins/corbits-skills/manifest.json b/plugins/corbits-skills/manifest.json index 6c4376a22..befe1b3d0 100644 --- a/plugins/corbits-skills/manifest.json +++ b/plugins/corbits-skills/manifest.json @@ -3,5 +3,5 @@ "name": "Corbits Skills", "kind": "command", "defaultEnabled": true, - "description": "Default operator skills and slash commands (implement, refactor, review, pull-request-review, create-issue, scribe, interview, plan)." + "description": "Default operator skills and slash commands (implement, refactor, review, pull-request-review, create-issue, docs, interview, plan)." } diff --git a/plugins/corbits-skills/skills/create-issue/SKILL.md b/plugins/corbits-skills/skills/create-issue/SKILL.md index ecc506cbe..5aa38c6b5 100644 --- a/plugins/corbits-skills/skills/create-issue/SKILL.md +++ b/plugins/corbits-skills/skills/create-issue/SKILL.md @@ -24,7 +24,7 @@ Pick the tracker before drafting. Do not skip this. ## Phase 1: Document Discovery -When the operator provides `--from-doc` or mentions a planning document, search for scribe-managed documents: +When the operator provides `--from-doc` or mentions a planning document, search for `/docs`-managed documents: 1. Look for `PRODUCT.md`, `ARCHITECTURE.md`, `IMPLEMENTATION.md` in: - Repository root diff --git a/plugins/corbits-skills/skills/docs/SKILL.md b/plugins/corbits-skills/skills/docs/SKILL.md new file mode 100644 index 000000000..76147fdda --- /dev/null +++ b/plugins/corbits-skills/skills/docs/SKILL.md @@ -0,0 +1,32 @@ +--- +name: docs +description: Maintain product, architecture, and implementation docs and detect gaps. +--- + +# Docs + +Route what the operator tells you into the right document, then find the gaps it leaves and ask about them. This is not a filing system: recording the input is half the job. + +## Documents + +Look for `PRODUCT.md`, `ARCHITECTURE.md`, and `IMPLEMENTATION.md` (case-insensitive) in the repo root and `docs/`. Prefer the root when both exist. Create missing ones in the root after confirming with `ask_operator`. + +| Document | Holds | Signals | +| -------------- | --------------------------------------------------------------------------------------- | ------------------------------------------ | +| Product | What we build and why: users, value, goals | "users can", needs, benefits, no mechanism | +| Architecture | Structure: components, interfaces, data and control flow, technology-agnostic decisions | parts and how they interact | +| Implementation | Concrete choices: technologies, protocols, formats, config, deployment | "uses", "built on", named libraries | + +Read the existing documents first. Their vocabulary beats the general signals above: a term the architecture doc already owns routes to architecture. + +## Steps + +1. **Read** the existing documents for terms, patterns, and similar entries to copy. +2. **Classify** the input. When it is clear, go to step 3. When it is ambiguous or spans documents, do not ask "which document?". Name the product, architecture, and implementation aspects you see and ask targeted questions that separate them. +3. **Update** the target document in its own voice and level of detail. If the new content contradicts existing content, ask whether to replace, keep both with clarification, or merge. +4. **Check consistency** across the other documents and fix or flag what the change makes stale. +5. **Find gaps** (significant updates only): concepts referenced but not explained, thin sections, missing failure modes or limits, decisions without rationale. Ask 2 to 4 probing questions in one batch with options drawn from the documents. Update with the answers. If the operator declines, move on. + +## Asking + +Use `ask_operator` with batched questions and context-aware options (reference similar documented features, earlier answers, and project terms). Fall back to general options only when the documents are empty. diff --git a/plugins/corbits-skills/skills/scribe/SKILL.md b/plugins/corbits-skills/skills/scribe/SKILL.md deleted file mode 100644 index 5de607edb..000000000 --- a/plugins/corbits-skills/skills/scribe/SKILL.md +++ /dev/null @@ -1,375 +0,0 @@ ---- -name: scribe -description: Maintain product, architecture, and implementation docs and detect gaps. ---- - -# Scribe - -Use this skill to maintain documentation across multiple documents that represent different levels of abstraction. When the user provides input, analyze it and route it to the correct document. Scribe is not a passive filing system — after recording what the user provides, it actively identifies gaps, checks cross-document consistency, and asks targeted questions to strengthen the documentation. - -## Document Discovery - -Before processing input, locate the documentation files: - -1. Search for existing files matching `PRODUCT.md`, `ARCHITECTURE.md`, and `IMPLEMENTATION.md` (case-insensitive) in: - - Repository root - - `docs/` directory - -2. If documents exist, use their locations. If multiple matches exist for the same type, prefer the repository root. - -3. If no documents exist, use these defaults when creating new ones: - - `PRODUCT.md` in repository root - - `ARCHITECTURE.md` in repository root - - `IMPLEMENTATION.md` in repository root - -## Document Types - -**Product** - Product-level documentation -- What we're building and why -- User-facing value propositions -- Vision and goals -- Target users and use cases -- Business justification - -**Architecture** - System architecture documentation -- How the system is structured -- Components and their relationships -- Abstractions and interfaces -- Data flow and control flow -- Design decisions that are technology-agnostic - -**Implementation** - Implementation documentation -- Specific technology choices -- Protocols and formats -- Libraries and frameworks -- Concrete technical details -- Configuration and deployment specifics - -## Using the Question Tool - -Throughout this skill, you will use the `ask_operator` tool to interact with the user. `ask_operator` allows you to present multiple questions with predefined options to the user. - -**Key mechanics:** -- You can present multiple questions in a single tool call (as an array of questions) -- Each question has a header, question text, and multiple options -- Each option has a label and description -- Users can select one or multiple options (if `multiple: true`) -- The tool automatically includes a "Type your own answer" option by default -- Questions are answered together as a batch, but you should make options context-aware based on information you already have - -**When to provide context-aware options:** -- Reference similar features, patterns, or components already documented -- Suggest options based on answers from previous interactions in the session -- Use project-specific terminology from existing documents -- When no patterns exist (empty/minimal documents), provide general options as fallbacks - -**Example invocation:** - -```json -{ - "questions": [ - { - "header": "Document classification", - "question": "Is 'fast and reliable' a user-facing promise or a system design requirement?", - "options": [ - { - "label": "User-facing promise", - "description": "Add to PRODUCT.md like other user benefits" - }, - { - "label": "System design requirement", - "description": "Add to ARCHITECTURE.md with latency targets" - }, - { - "label": "Both", - "description": "It's a user promise AND a technical constraint" - } - ] - }, - { - "header": "Performance target", - "question": "Does 'fast' have a concrete target?", - "options": [ - { - "label": "Under 5 seconds", - "description": "Similar to report generation target" - }, - { - "label": "Different target", - "description": "Specify a different performance goal" - }, - { - "label": "No specific target", - "description": "Keep it qualitative for now" - } - ] - } - ] -} -``` - -The tool returns the selected options as an array of labels (e.g., `["Both", "Under 5 seconds"]`). - -## Execution Steps - -### Step 0: Document Discovery and Reading - -Before classifying input, locate and read the existing documentation files to learn project-specific vocabulary and patterns. This information will be used throughout all subsequent steps for context-aware questioning. - -1. Search for existing files matching `PRODUCT.md`, `ARCHITECTURE.md`, and `IMPLEMENTATION.md` (case-insensitive) in repository root and `docs/` directory -2. Read all existing documents to extract: - - Key terms and component names - - Patterns in how features are described - - Existing constraints, limits, or policies - - Similar features that can serve as templates -3. If documents are empty or minimal, note that general options will be needed instead of context-aware ones - -### Step 1: Analyze Input - -Read the user's input and determine which category it falls into. Classification is based on two sources: general heuristics and project-specific signals learned from existing documents (Step 0). - -**General heuristics:** - -*Product signals:* -- Describes user needs or problems -- Explains value or benefits -- Discusses market or competitive positioning -- Uses language like "users can", "enables", "provides value" -- Talks about goals without specifying how - -*Architecture signals:* -- Describes components or modules -- Explains how parts interact -- Defines abstractions or interfaces -- Discusses system properties without naming specific technologies -- Technology-agnostic design decisions - -*Implementation signals:* -- Names specific technologies, protocols, or formats -- Describes wire formats or API specifications -- Specifies configuration details -- Uses language like "uses", "built on", "implemented with" -- Concrete technical choices - -**Project-specific signals:** - -Read the existing documents to learn the project's vocabulary. Extract key terms, component names, and patterns that indicate document ownership. For example: -- If the architecture document discusses "the kernel" and "agents", mentions of these terms suggest architectural content -- If the implementation document discusses "SMTP" and "IMAP", mentions of email protocols suggest implementation content -- If the product document discusses "wallets" as a user-facing feature, wallet mentions in a value context suggest product content - -Use these learned signals alongside general heuristics. Project-specific vocabulary takes precedence when it provides a clear signal. - -### Step 2: Classify and Deepen - -If the categorization is clear, proceed to update the appropriate document. - -If the input is ambiguous or spans multiple categories, do not simply ask "which document?" Instead, use the `ask_operator` tool to interview the user and decompose the input into distinct claims that can each be routed precisely: - -1. Explain what makes the input ambiguous — identify the product, architecture, and/or implementation aspects you see in it. -2. Use the `ask_operator` tool to ask targeted questions that separate those aspects. Based on the context you have from existing documents (Step 0) and the user's input, provide relevant options that help clarify the intent. - -**If documents have content with patterns to reference:** - - When user mentions "fast and reliable", reference existing performance promises or design constraints: - - "User-facing promise (add to PRODUCT.md like [similar feature])" - - "System design requirement (add to ARCHITECTURE.md with latency targets)" - - "Both - it's a user promise AND a technical constraint" - - When user mentions a component name, reference similar components: - - "[Component] is user-facing (like [similar component] in PRODUCT.md)" - - "[Component] is an internal abstraction (add to ARCHITECTURE.md)" - -**If documents are empty/minimal (no patterns to reference):** - - Provide general options without specific references: - - "User-facing promise (add to PRODUCT.md)" - - "System design requirement (add to ARCHITECTURE.md)" - - "Both - it's a user promise AND a technical constraint" - -3. Route each extracted piece to its appropriate document. A single user statement may result in updates to multiple documents. - -### Step 3: Update Document - -Read the target document to understand its current structure and content. - -Determine where in the document the new content belongs: -- Does it extend an existing section? -- Does it require a new section? -- Does it modify existing content? - -Make the update, maintaining the document's existing style and structure. - -After updating, assess whether the change is **significant**. A change is significant if it: -- Introduces a new concept, component, or section -- Contradicts or substantially revises existing content -- Adds a top-level capability or design decision - -If the change is minor — extending an existing section with more detail, fixing wording, adding a clarification — skip Steps 4 and 5 and proceed directly to Step 6. - -### Step 4: Cross-Document Consistency - -*Only for significant updates.* - -Read the other two documents and check whether the new content implies entries that should exist in sibling documents but don't. Common patterns to look for: - -- A new architecture component with no corresponding product justification -- A new product capability with no architectural description of how it works -- An implementation detail referencing a component not described in architecture -- A product goal with no implementation approach mentioned - -If gaps are found, use the `ask_operator` tool to present them as a batch of 2-4 questions. Based on the context from existing documents (Step 0) and the change just made, provide specific, relevant options. - -**Example with existing patterns:** - -If you just added an export service to ARCHITECTURE.md, and PRODUCT.md has no mention of exports: - -> I updated ARCHITECTURE.md with the export service. I noticed some potential gaps in other documents. - -Use the `ask_operator` tool with: -- Question 1: "Should PRODUCT.md describe data export as a user-facing capability?" - - **If PRODUCT.md has similar features**: "Add export as data access capability (like reports feature)" / "Add as part of reporting feature" - - **If PRODUCT.md is minimal**: "Yes, add as new user-facing capability" / "No, exports are internal only" -- Question 2: "How should IMPLEMENTATION.md describe export generation?" - - **If IMPLEMENTATION.md describes other services**: "Similar to [existing service], using [library]" / "Different approach (specify details)" - - **If IMPLEMENTATION.md is minimal**: "Specify library/technology used" / "Defer implementation details for now" - -For each question the user answers, update the corresponding document before proceeding. - -### Step 5: Gap Detection and Completeness - -*Only for significant updates.* - -Scan the updated document for weaknesses: -- Concepts referenced but not elaborated -- Sections that are thin relative to their importance -- Missing failure modes, edge cases, or constraints -- Decisions stated without rationale - -Use the `ask_operator` tool to present 2-4 probing questions as a batch. Focus on non-obvious gaps — things the user might not think to document unprompted. Based on the content just added, questions already answered in this session, and patterns from existing documentation, provide specific, contextual options. - -**Example with existing patterns:** - -If you just added an export service to ARCHITECTURE.md: - -- Question 1: "What happens when an export fails mid-generation?" - - **If other services have retry logic**: "Automatic retry (like [existing service])" / "User must re-trigger" / "Saved as partial export for resume" - - **If no retry patterns exist**: "Automatic retry" / "User must re-trigger" / "Partial export saved for resume" -- Question 2: "Are there size or rate limits on exports?" - - **If similar features have limits**: "Same limits as [similar feature]" / "Different limits (specify)" / "No hard limits - best effort" - - **If no limits documented**: "10k rows / 100MB max" / "No hard limits - best effort" / "To be determined" -- Question 3: "Who has permission to trigger exports?" - - **If docs mention role-based access**: "Any authenticated user" / "Only admin/owner roles" / "Configurable per workspace" - - **If auth not documented**: "Any authenticated user" / "Role-restricted (specify roles)" / "To be determined" - -Update the document with any answers the user provides. If the user declines to answer, move on without pressing. - -**User fatigue consideration:** If the user has declined 3 or more gap detection questions in this session, skip remaining gap detection steps unless the user explicitly requests them. - -### Step 6: Report - -Briefly confirm what was changed and in which document. If Steps 4 or 5 resulted in additional updates, summarize those as well: - -> Updated ARCHITECTURE.md: added export service component under "Data Pipeline" section. -> Also updated PRODUCT.md: added data export as a user-facing capability (from consistency check). - -## Examples - -These examples demonstrate how classification and the active documentation steps work. The specific terms will vary by project. - -### Classification - -**Input:** "Users can export their data in multiple formats" -**Classification:** Product (describes user-facing capability) - -**Input:** "The export service validates permissions before generating files" -**Classification:** Architecture (describes component responsibility and interaction) - -**Input:** "Exports are generated as CSV using the fast-csv library" -**Classification:** Implementation (names specific format and library) - -### Depth Elicitation (Step 2) - -**Input:** "Data export is fast and reliable" -**Classification:** Ambiguous — has both product and architecture aspects. - -Instead of asking "which document?", use the `ask_operator` tool to decompose. After reading existing docs (Step 0) and seeing that PRODUCT.md already mentions "reports" as a user-facing feature and ARCHITECTURE.md discusses latency targets for other services: - -Use the `ask_operator` tool: -- Question 1: "Is 'fast and reliable' a promise to users or a system design requirement?" - - Option 1: "User-facing promise (add to PRODUCT.md like other user benefits)" - - Option 2: "System design requirement (add to ARCHITECTURE.md with latency targets)" - - Option 3: "Both - it's a user promise AND a technical constraint" -- Question 2: "Does 'fast' have a concrete target?" - - Option 1: "Yes - under 5 seconds (similar to report generation target)" - - Option 2: "Yes - but different target (specify)" - - Option 3: "No specific target yet" - -If the user selects "Both" and "under 5 seconds", this produces two updates: -- **PRODUCT.md:** Data export completes in under 5 seconds for typical datasets (up to 10k rows). -- **ARCHITECTURE.md:** The export pipeline must meet a 5-second latency target for datasets up to 10k rows. - -### Cross-Document Consistency (Step 4) - -**Scenario:** User adds "The notification service delivers messages through email, SMS, and push" to ARCHITECTURE.md. - -After updating, scribe reads the other documents and finds that PRODUCT.md has no mention of notifications as a user-facing feature, but does mention "alerts" in a different context. IMPLEMENTATION.md describes other third-party integrations using specific provider names. - -Use the `ask_operator` tool: -- Question 1: "Should PRODUCT.md describe notifications as a user-facing capability?" - - Option 1: "Yes - add as new notifications feature (users receive updates via email/SMS/push)" - - Option 2: "Yes - integrate with existing 'alerts' feature (notifications are how alerts are delivered)" - - Option 3: "No - notifications are internal only, not user-facing" -- Question 2: "Should IMPLEMENTATION.md specify the notification providers?" - - Option 1: "Yes - using [provider] (similar to how we document other integrations)" - - Option 2: "Yes - but different providers (specify which)" - - Option 3: "Not yet - still evaluating options" - -### Gap Detection (Step 5) - -**Scenario:** User adds a new "Authentication" section to ARCHITECTURE.md describing token-based auth with refresh tokens. - -After updating, scribe scans the section and identifies gaps. From reading ARCHITECTURE.md (Step 0), scribe notices other sections mention security constraints and timeout values. IMPLEMENTATION.md describes storage mechanisms for other sensitive data. - -Use the `ask_operator` tool: -- Question 1: "What happens when a refresh token is revoked?" - - Option 1: "User signed out immediately (like session invalidation elsewhere in the system)" - - Option 2: "User signed out at next request (deferred enforcement)" - - Option 3: "Configurable per deployment" -- Question 2: "Is there a maximum session duration?" - - Option 1: "Yes - 30 days (similar to other timeout values in the docs)" - - Option 2: "Yes - but different duration (specify)" - - Option 3: "No hard limit - refresh tokens last indefinitely until revoked" -- Question 3: "How are tokens stored on the client side?" - - Option 1: "Same as [other sensitive data] - in secure storage" - - Option 2: "Different approach (specify storage mechanism)" - - Option 3: "Client implementation decision - not specified in architecture" - -## Error Handling - -### Document does not exist - -If the target document does not exist, use the `ask_operator` tool to ask the user if they want to create it, with context about what type of document it is: - -Question: "The [DOCUMENT].md file does not exist. Should I create it?" -Options: -- "Yes, create [DOCUMENT].md (will contain [brief description based on document type])" -- "No, use a different document instead" - -### Content conflicts - -If the new content contradicts existing content, use the `ask_operator` tool to flag it with specific options: - -Question: "This conflicts with existing content in [DOCUMENT].md: '[existing content]'. How should I resolve this?" -Options based on the nature of the conflict: -- "Replace old content with new (new information supersedes old)" -- "Keep both with clarification (they represent different aspects/contexts)" -- "Merge the two (combine into comprehensive description)" - -### Unclear scope - -If the input is too broad or vague to place in a specific document, use the `ask_operator` tool to narrow it down: - -Question: "I'm not sure where '[user input]' belongs. Can you help me place it?" -Options based on what aspects you can detect: -- "PRODUCT.md ([specific user-facing aspect you detected])" -- "ARCHITECTURE.md ([specific structural aspect you detected])" -- "IMPLEMENTATION.md ([specific technical aspect you detected])" -- "Multiple documents (it spans several concerns)" diff --git a/src/agent/directors/shakespeare/package.ts b/src/agent/directors/shakespeare/package.ts index bd5d28ddd..5bf21267a 100644 --- a/src/agent/directors/shakespeare/package.ts +++ b/src/agent/directors/shakespeare/package.ts @@ -3,7 +3,7 @@ import { DOCS_TOOLS } from "../tool-sets.js"; /** * Shakespeare worker (CL-7029). - * Docs maintenance — PRODUCT / ARCHITECTURE / IMPLEMENTATION only; scribe core baked in. + * Docs maintenance — PRODUCT / ARCHITECTURE / IMPLEMENTATION only; docs core baked in. * Package id/path stays `shakespeare` (global rename is out of scope). */ export const shakespearePackage: DirectorPackage = { @@ -30,7 +30,7 @@ BLINDERS ON: Stay on the brief's success_criteria and the P/A/I docs. Do not wan **IMPLEMENTATION.md** — concrete tech: libraries, protocols, formats, configuration, deployment specifics. -# Workflow (scribe core) +# Workflow (docs core) ## 0. Document discovery diff --git a/src/telemetry/classify.ts b/src/telemetry/classify.ts index f3f2a2dc3..757e66fa1 100644 --- a/src/telemetry/classify.ts +++ b/src/telemetry/classify.ts @@ -84,6 +84,7 @@ const BUILT_IN_AGENT_NAMES: ReadonlySet = new Set([ // name. const FIRST_PARTY_SKILL_NAMES: ReadonlySet = new Set([ "create-issue", + "docs", "git-worktrees", "implement", "interview", @@ -93,7 +94,6 @@ const FIRST_PARTY_SKILL_NAMES: ReadonlySet = new Set([ "pull-request-review", "refactor", "review", - "scribe", "style", "typescript", ]);