diff --git a/.github/skills/excalidraw-diagram/SKILL.md b/.github/skills/excalidraw-diagram/SKILL.md new file mode 100644 index 0000000..9df9894 --- /dev/null +++ b/.github/skills/excalidraw-diagram/SKILL.md @@ -0,0 +1,552 @@ +--- +name: excalidraw-diagram +description: Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts. +--- + +# Excalidraw Diagram Creator + +Generate `.excalidraw` JSON files that **argue visually**, not just display information. + +**Setup:** If the user asks you to set up this skill (renderer, dependencies, etc.), see `README.md` for instructions. + +## Customization + +**All colors and brand-specific styles live in one file:** `references/color-palette.md`. Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything. + +To make this skill produce diagrams in your own brand style, edit `color-palette.md`. Everything else in this file is universal design methodology and Excalidraw best practices. + +--- + +## Core Philosophy + +**Diagrams should ARGUE, not DISPLAY.** + +A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning. + +**The Isomorphism Test**: If you removed all text, would the structure alone communicate the concept? If not, redesign. + +**The Education Test**: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples. + +--- + +## Depth Assessment (Do This First) + +Before designing, determine what level of detail this diagram needs: + +### Simple/Conceptual Diagrams +Use abstract shapes when: +- Explaining a mental model or philosophy +- The audience doesn't need technical specifics +- The concept IS the abstraction (e.g., "separation of concerns") + +### Comprehensive/Technical Diagrams +Use concrete examples when: +- Diagramming a real system, protocol, or architecture +- The diagram will be used to teach or explain (e.g., YouTube video) +- The audience needs to understand what things actually look like +- You're showing how multiple technologies integrate + +**For technical diagrams, you MUST include evidence artifacts** (see below). + +--- + +## Research Mandate (For Technical Diagrams) + +**Before drawing anything technical, research the actual specifications.** + +If you're diagramming a protocol, API, or framework: +1. Look up the actual JSON/data formats +2. Find the real event names, method names, or API endpoints +3. Understand how the pieces actually connect +4. Use real terminology, not generic placeholders + +Bad: "Protocol" → "Frontend" +Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()" + +**Research makes diagrams accurate AND educational.** + +--- + +## Evidence Artifacts + +Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams. + +**Types of evidence artifacts** (choose what's relevant to your diagram): + +| Artifact Type | When to Use | How to Render | +|---------------|-------------|---------------| +| **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) | +| **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) | +| **Event/step sequences** | Protocols, workflows, lifecycles | Timeline pattern (line + dots + labels) | +| **UI mockups** | Showing actual output/results | Nested rectangles mimicking real UI | +| **Real input content** | Showing what goes IN to a system | Rectangle with sample content visible | +| **API/method names** | Real function calls, endpoints | Use actual names from docs, not placeholders | + +**Example**: For a diagram about a streaming protocol, you might show: +- The actual event names from the spec (not just "Event 1", "Event 2") +- A code snippet showing how to connect +- What the streamed data actually looks like + +**Example**: For a diagram about a data transformation pipeline: +- Show sample input data (actual format, not "Input") +- Show sample output data (actual format, not "Output") +- Show intermediate states if relevant + +The key principle: **show what things actually look like**, not just what they're called. + +--- + +## Multi-Zoom Architecture + +Comprehensive diagrams operate at multiple zoom levels simultaneously. Think of it like a map that shows both the country borders AND the street names. + +### Level 1: Summary Flow +A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram. + +*Example*: `Input → Processing → Output` or `Client → Server → Database` + +### Level 2: Section Boundaries +Labeled regions that group related components. These create visual "rooms" that help viewers understand what belongs together. + +*Example*: Grouping by responsibility (Backend / Frontend), by phase (Setup / Execution / Cleanup), or by team (User / System / External) + +### Level 3: Detail Inside Sections +Evidence artifacts, code snippets, and concrete examples within each section. This is where the educational value lives. + +*Example*: Inside a "Backend" section, you might show the actual API response format, not just a box labeled "API Response" + +**For comprehensive diagrams, aim to include all three levels.** The summary gives context, the sections organize, and the details teach. + +### Bad vs Good + +| Bad (Displaying) | Good (Arguing) | +|------------------|----------------| +| 5 equal boxes with labels | Each concept has a shape that mirrors its behavior | +| Card grid layout | Visual structure matches conceptual structure | +| Icons decorating text | Shapes that ARE the meaning | +| Same container for everything | Distinct visual vocabulary per concept | +| Everything in a box | Free-floating text with selective containers | + +### Simple vs Comprehensive (Know Which You Need) + +| Simple Diagram | Comprehensive Diagram | +|----------------|----------------------| +| Generic labels: "Input" → "Process" → "Output" | Specific: shows what the input/output actually looks like | +| Named boxes: "API", "Database", "Client" | Named boxes + examples of actual requests/responses | +| "Events" or "Messages" label | Timeline with real event/message names from the spec | +| "UI" or "Dashboard" rectangle | Mockup showing actual UI elements and content | +| ~30 seconds to explain | ~2-3 minutes of teaching content | +| Viewer learns the structure | Viewer learns the structure AND the details | + +**Simple diagrams** are fine for abstract concepts, quick overviews, or when the audience already knows the details. **Comprehensive diagrams** are needed for technical architectures, tutorials, educational content, or when you want the diagram itself to teach. + +--- + +## Container vs. Free-Floating Text + +**Not every piece of text needs a shape around it.** Default to free-floating text. Add containers only when they serve a purpose. + +| Use a Container When... | Use Free-Floating Text When... | +|------------------------|-------------------------------| +| It's the focal point of a section | It's a label or description | +| It needs visual grouping with other elements | It's supporting detail or metadata | +| Arrows need to connect to it | It describes something nearby | +| The shape itself carries meaning (decision diamond, etc.) | Typography alone creates sufficient hierarchy | +| It represents a distinct "thing" in the system | It's a section title, subtitle, or annotation | + +**Typography as hierarchy**: Use font size, weight, and color to create visual hierarchy without boxes. A 28px title doesn't need a rectangle around it. + +**The container test**: For each boxed element, ask "Would this work as free-floating text?" If yes, remove the container. + +--- + +## Design Process (Do This BEFORE Generating JSON) + +### Step 0: Assess Depth Required +Before anything else, determine if this needs to be: +- **Simple/Conceptual**: Abstract shapes, labels, relationships (mental models, philosophies) +- **Comprehensive/Technical**: Concrete examples, code snippets, real data (systems, architectures, tutorials) + +**If comprehensive**: Do research first. Look up actual specs, formats, event names, APIs. + +### Step 1: Understand Deeply +Read the content. For each concept, ask: +- What does this concept **DO**? (not what IS it) +- What relationships exist between concepts? +- What's the core transformation or flow? +- **What would someone need to SEE to understand this?** (not just read about) + +### Step 2: Map Concepts to Patterns +For each concept, find the visual pattern that mirrors its behavior: + +| If the concept... | Use this pattern | +|-------------------|------------------| +| Spawns multiple outputs | **Fan-out** (radial arrows from center) | +| Combines inputs into one | **Convergence** (funnel, arrows merging) | +| Has hierarchy/nesting | **Tree** (lines + free-floating text) | +| Is a sequence of steps | **Timeline** (line + dots + free-floating labels) | +| Loops or improves continuously | **Spiral/Cycle** (arrow returning to start) | +| Is an abstract state or context | **Cloud** (overlapping ellipses) | +| Transforms input to output | **Assembly line** (before → process → after) | +| Compares two things | **Side-by-side** (parallel with contrast) | +| Separates into phases | **Gap/Break** (visual separation between sections) | + +### Step 3: Ensure Variety +For multi-concept diagrams: **each major concept must use a different visual pattern**. No uniform cards or grids. + +### Step 4: Sketch the Flow +Before JSON, mentally trace how the eye moves through the diagram. There should be a clear visual story. + +### Step 5: Generate JSON +Only now create the Excalidraw elements. **See below for how to handle large diagrams.** + +### Step 6: Render & Validate (MANDATORY) +After generating the JSON, you MUST run the render-view-fix loop until the diagram looks right. This is not optional — see the **Render & Validate** section below for the full process. + +--- + +## Large / Comprehensive Diagram Strategy + +**For comprehensive or technical diagrams, you MUST build the JSON one section at a time.** Do NOT attempt to generate the entire file in a single pass. This is a hard constraint — Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that in one shot. Even if it didn't, generating everything at once leads to worse quality. Section-by-section is better in every way. + +### The Section-by-Section Workflow + +**Phase 1: Build each section** + +1. **Create the base file** with the JSON wrapper (`type`, `version`, `appState`, `files`) and the first section of elements. +2. **Add one section per edit.** Each section gets its own dedicated pass — take your time with it. Think carefully about the layout, spacing, and how this section connects to what's already there. +3. **Use descriptive string IDs** (e.g., `"trigger_rect"`, `"arrow_fan_left"`) so cross-section references are readable. +4. **Namespace seeds by section** (e.g., section 1 uses 100xxx, section 2 uses 200xxx) to avoid collisions. +5. **Update cross-section bindings** as you go. When a new section's element needs to bind to an element from a previous section (e.g., an arrow connecting sections), edit the earlier element's `boundElements` array at the same time. + +**Phase 2: Review the whole** + +After all sections are in place, read through the complete JSON and check: +- Are cross-section arrows bound correctly on both ends? +- Is the overall spacing balanced, or are some sections cramped while others have too much whitespace? +- Do IDs and bindings all reference elements that actually exist? + +Fix any alignment or binding issues before rendering. + +**Phase 3: Render & validate** + +Now run the render-view-fix loop from the Render & Validate section. This is where you'll catch visual issues that aren't obvious from JSON — overlaps, clipping, imbalanced composition. + +### Section Boundaries + +Plan your sections around natural visual groupings from the diagram plan. A typical large diagram might split into: + +- **Section 1**: Entry point / trigger +- **Section 2**: First decision or routing +- **Section 3**: Main content (hero section — may be the largest single section) +- **Section 4-N**: Remaining phases, outputs, etc. + +Each section should be independently understandable: its elements, internal arrows, and any cross-references to adjacent sections. + +### What NOT to Do + +- **Don't generate the entire diagram in one response.** You will hit the output token limit and produce truncated, broken JSON. Even if the diagram is small enough to fit, splitting into sections produces better results. +- **Don't use a coding agent** to generate the JSON. The agent won't have sufficient context about the skill's rules, and the coordination overhead negates any benefit. +- **Don't write a Python generator script.** The templating and coordinate math seem helpful but introduce a layer of indirection that makes debugging harder. Hand-crafted JSON with descriptive IDs is more maintainable. + +--- + +## Visual Pattern Library + +### Fan-Out (One-to-Many) +Central element with arrows radiating to multiple targets. Use for: sources, PRDs, root causes, central hubs. +``` + ○ + ↗ + □ → ○ + ↘ + ○ +``` + +### Convergence (Many-to-One) +Multiple inputs merging through arrows to single output. Use for: aggregation, funnels, synthesis. +``` + ○ ↘ + ○ → □ + ○ ↗ +``` + +### Tree (Hierarchy) +Parent-child branching with connecting lines and free-floating text (no boxes needed). Use for: file systems, org charts, taxonomies. +``` + label + ├── label + │ ├── label + │ └── label + └── label +``` +Use `line` elements for the trunk and branches, free-floating text for labels. + +### Spiral/Cycle (Continuous Loop) +Elements in sequence with arrow returning to start. Use for: feedback loops, iterative processes, evolution. +``` + □ → □ + ↑ ↓ + □ ← □ +``` + +### Cloud (Abstract State) +Overlapping ellipses with varied sizes. Use for: context, memory, conversations, mental states. + +### Assembly Line (Transformation) +Input → Process Box → Output with clear before/after. Use for: transformations, processing, conversion. +``` + ○○○ → [PROCESS] → □□□ + chaos order +``` + +### Side-by-Side (Comparison) +Two parallel structures with visual contrast. Use for: before/after, options, trade-offs. + +### Gap/Break (Separation) +Visual whitespace or barrier between sections. Use for: phase changes, context resets, boundaries. + +### Lines as Structure +Use lines (type: `line`, not arrows) as primary structural elements instead of boxes: +- **Timelines**: Vertical or horizontal line with small dots (10-20px ellipses) at intervals, free-floating labels beside each dot +- **Tree structures**: Vertical trunk line + horizontal branch lines, with free-floating text labels (no boxes needed) +- **Dividers**: Thin dashed lines to separate sections +- **Flow spines**: A central line that elements relate to, rather than connecting boxes + +``` +Timeline: Tree: + ●─── Label 1 │ + │ ├── item + ●─── Label 2 │ ├── sub + │ │ └── sub + ●─── Label 3 └── item +``` + +Lines + free-floating text often creates a cleaner result than boxes + contained text. + +--- + +## Shape Meaning + +Choose shape based on what it represents—or use no shape at all: + +| Concept Type | Shape | Why | +|--------------|-------|-----| +| Labels, descriptions, details | **none** (free-floating text) | Typography creates hierarchy | +| Section titles, annotations | **none** (free-floating text) | Font size/weight is enough | +| Markers on a timeline | small `ellipse` (10-20px) | Visual anchor, not container | +| Start, trigger, input | `ellipse` | Soft, origin-like | +| End, output, result | `ellipse` | Completion, destination | +| Decision, condition | `diamond` | Classic decision symbol | +| Process, action, step | `rectangle` | Contained action | +| Abstract state, context | overlapping `ellipse` | Fuzzy, cloud-like | +| Hierarchy node | lines + text (no boxes) | Structure through lines | + +**Rule**: Default to no container. Add shapes only when they carry meaning. Aim for <30% of text elements to be inside containers. + +--- + +## Color as Meaning + +Colors encode information, not decoration. Every color choice should come from `references/color-palette.md` — the semantic shape colors, text hierarchy colors, and evidence artifact colors are all defined there. + +**Key principles:** +- Each semantic purpose (start, end, decision, AI, error, etc.) has a specific fill/stroke pair +- Free-floating text uses color for hierarchy (titles, subtitles, details — each at a different level) +- Evidence artifacts (code snippets, JSON examples) use their own dark background + colored text scheme +- Always pair a darker stroke with a lighter fill for contrast + +**Do not invent new colors.** If a concept doesn't fit an existing semantic category, use Primary/Neutral or Secondary. + +--- + +## Modern Aesthetics + +For clean, professional diagrams: + +### Roughness +- `roughness: 0` — Clean, crisp edges. Use for modern/technical diagrams. +- `roughness: 1` — Hand-drawn, organic feel. Use for brainstorming/informal diagrams. + +**Default to 0** for most professional use cases. + +### Stroke Width +- `strokeWidth: 1` — Thin, elegant. Good for lines, dividers, subtle connections. +- `strokeWidth: 2` — Standard. Good for shapes and primary arrows. +- `strokeWidth: 3` — Bold. Use sparingly for emphasis (main flow line, key connections). + +### Opacity +**Always use `opacity: 100` for all elements.** Use color, size, and stroke width to create hierarchy instead of transparency. + +### Small Markers Instead of Shapes +Instead of full shapes, use small dots (10-20px ellipses) as: +- Timeline markers +- Bullet points +- Connection nodes +- Visual anchors for free-floating text + +--- + +## Layout Principles + +### Hierarchy Through Scale +- **Hero**: 300×150 - visual anchor, most important +- **Primary**: 180×90 +- **Secondary**: 120×60 +- **Small**: 60×40 + +### Whitespace = Importance +The most important element has the most empty space around it (200px+). + +### Flow Direction +Guide the eye: typically left→right or top→bottom for sequences, radial for hub-and-spoke. + +### Connections Required +Position alone doesn't show relationships. If A relates to B, there must be an arrow. + +--- + +## Text Rules + +**CRITICAL**: The JSON `text` property contains ONLY readable words. + +```json +{ + "id": "myElement1", + "text": "Start", + "originalText": "Start" +} +``` + +Settings: `fontSize: 16`, `fontFamily: 3`, `textAlign: "center"`, `verticalAlign: "middle"` + +--- + +## JSON Structure + +```json +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [...], + "appState": { + "viewBackgroundColor": "#ffffff", + "gridSize": 20 + }, + "files": {} +} +``` + +## Element Templates + +See `references/element-templates.md` for copy-paste JSON templates for each element type (text, line, dot, rectangle, arrow). Pull colors from `references/color-palette.md` based on each element's semantic purpose. + +--- + +## Render & Validate (MANDATORY) + +You cannot judge a diagram from JSON alone. After generating or editing the Excalidraw JSON, you MUST render it to PNG, view the image, and fix what you see — in a loop until it's right. This is a core part of the workflow, not a final check. + +### How to Render + +```bash +cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py +``` + +This outputs a PNG next to the `.excalidraw` file. Then use the **Read tool** on the PNG to actually view it. + +### The Loop + +After generating the initial JSON, run this cycle: + +**1. Render & View** — Run the render script, then Read the PNG. + +**2. Audit against your original vision** — Before looking for bugs, compare the rendered result to what you designed in Steps 1-4. Ask: +- Does the visual structure match the conceptual structure you planned? +- Does each section use the pattern you intended (fan-out, convergence, timeline, etc.)? +- Does the eye flow through the diagram in the order you designed? +- Is the visual hierarchy correct — hero elements dominant, supporting elements smaller? +- For technical diagrams: are the evidence artifacts (code snippets, data examples) readable and properly placed? + +**3. Check for visual defects:** +- Text clipped by or overflowing its container +- Text or shapes overlapping other elements +- Arrows crossing through elements instead of routing around them +- Arrows landing on the wrong element or pointing into empty space +- Labels floating ambiguously (not clearly anchored to what they describe) +- Uneven spacing between elements that should be evenly spaced +- Sections with too much whitespace next to sections that are too cramped +- Text too small to read at the rendered size +- Overall composition feels lopsided or unbalanced + +**4. Fix** — Edit the JSON to address everything you found. Common fixes: +- Widen containers when text is clipped +- Adjust `x`/`y` coordinates to fix spacing and alignment +- Add intermediate waypoints to arrow `points` arrays to route around elements +- Reposition labels closer to the element they describe +- Resize elements to rebalance visual weight across sections + +**5. Re-render & re-view** — Run the render script again and Read the new PNG. + +**6. Repeat** — Keep cycling until the diagram passes both the vision check (Step 2) and the defect check (Step 3). Typically takes 2-4 iterations. Don't stop after one pass just because there are no critical bugs — if the composition could be better, improve it. + +### When to Stop + +The loop is done when: +- The rendered diagram matches the conceptual design from your planning steps +- No text is clipped, overlapping, or unreadable +- Arrows route cleanly and connect to the right elements +- Spacing is consistent and the composition is balanced +- You'd be comfortable showing it to someone without caveats + +### First-Time Setup +If the render script hasn't been set up yet: +```bash +cd .claude/skills/excalidraw-diagram/references +uv sync +uv run playwright install chromium +``` + +--- + +## Quality Checklist + +### Depth & Evidence (Check First for Technical Diagrams) +1. **Research done**: Did you look up actual specs, formats, event names? +2. **Evidence artifacts**: Are there code snippets, JSON examples, or real data? +3. **Multi-zoom**: Does it have summary flow + section boundaries + detail? +4. **Concrete over abstract**: Real content shown, not just labeled boxes? +5. **Educational value**: Could someone learn something concrete from this? + +### Conceptual +6. **Isomorphism**: Does each visual structure mirror its concept's behavior? +7. **Argument**: Does the diagram SHOW something text alone couldn't? +8. **Variety**: Does each major concept use a different visual pattern? +9. **No uniform containers**: Avoided card grids and equal boxes? + +### Container Discipline +10. **Minimal containers**: Could any boxed element work as free-floating text instead? +11. **Lines as structure**: Are tree/timeline patterns using lines + text rather than boxes? +12. **Typography hierarchy**: Are font size and color creating visual hierarchy (reducing need for boxes)? + +### Structural +13. **Connections**: Every relationship has an arrow or line +14. **Flow**: Clear visual path for the eye to follow +15. **Hierarchy**: Important elements are larger/more isolated + +### Technical +16. **Text clean**: `text` contains only readable words +17. **Font**: `fontFamily: 3` +18. **Roughness**: `roughness: 0` for clean/modern (unless hand-drawn style requested) +19. **Opacity**: `opacity: 100` for all elements (no transparency) +20. **Container ratio**: <30% of text elements should be inside containers + +### Visual Validation (Render Required) +21. **Rendered to PNG**: Diagram has been rendered and visually inspected +22. **No text overflow**: All text fits within its container +23. **No overlapping elements**: Shapes and text don't overlap unintentionally +24. **Even spacing**: Similar elements have consistent spacing +25. **Arrows land correctly**: Arrows connect to intended elements without crossing others +26. **Readable at export size**: Text is legible in the rendered PNG +27. **Balanced composition**: No large empty voids or overcrowded regions diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index a948ca8..15224d4 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -6,6 +6,7 @@ on: - main paths: - docs/** + - slides/** - mkdocs.yml - requirements-docs.txt - .github/workflows/deploy-pages.yml @@ -41,7 +42,11 @@ jobs: run: python -m pip install --upgrade pip && pip install -r requirements-docs.txt - name: Build site - run: mkdocs build --strict --site-dir site + run: | + mkdocs build --strict --site-dir site + cp -R slides site/slides + mkdir -p site/docs + cp -R docs/assets site/docs/assets - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 diff --git a/.squad/agents/bender/history.md b/.squad/agents/bender/history.md index 109269d..e5d2618 100644 --- a/.squad/agents/bender/history.md +++ b/.squad/agents/bender/history.md @@ -97,3 +97,7 @@ - Hermes completed the semantic cleanup, not just file removal: plugin metadata now advertises the guide + agent surface, repo docs no longer teach repo-local skill installation, and late Part 4 numbering is contiguous again. - Live filesystem and `rg` checks satisfied the main acceptance criteria: no top-level `skills/`, no `skills-lock.json`, and one canonical image copy under `docs/assets/`. - Remaining gap is environmental, not yet a content failure: strict MkDocs build still cannot be executed here because `mkdocs` is not installed. + +### 2026-06-17: Token Recommendation Placement Review — Approved + +- Hermes placed RTK Windows cautions, VS Code extension/profile cleanup, custom-agent cost control, model-switch risk, and Copilot CLI AIC value framing in natural locations without overstating hidden internals or exact billing math. diff --git a/.squad/agents/hermes/history.md b/.squad/agents/hermes/history.md index ccf2f27..690a0ac 100644 --- a/.squad/agents/hermes/history.md +++ b/.squad/agents/hermes/history.md @@ -9,6 +9,20 @@ ## Learnings +### 2026-06-19: Governance Cohorts and FinOps Automation + +- Updated `docs/12-enterprise-governance.md` with spend-cohort guidance: export historical Copilot billing/usage CSVs, upload to Copilot Billing Preview, then map power/high/baseline/low usage cohorts to budget defaults and review paths. +- Added `amgdy/copilot-finops-automation` as an admin-scale option for Copilot FinOps-as-code: reviewed YAML config, schema validation, dry runs, idempotent budget apply, cost-center membership sync, audit reports, and private-config caveat. +- Made a tiny `README.md` guide-summary update so Enterprise Governance mentions spend cohorts and FinOps-as-code automation. + + +### 2026-06-17: Placement for Tool, Profile, Model-Switch, and AIC Recommendations + +- Added RTK Windows caveat beside existing RTK setup, not as a new technique. Readers need the warning where they copy commands. +- Extension/profile cleanup belongs with MCP/tool costs and practical agent setup because extension-injected tools behave like hidden context surface. +- Model mid-chat switching belongs in model-pricing anti-patterns with careful cache/history wording; avoid claiming fixed implementation internals. +- Copilot CLI AIC counter fits habit-building/monthly maintenance: value framing is a behavior loop, not a setup prerequisite. + ### 2026-04-14: Wrote TOKEN-OPTIMIZATION-GUIDE.md (v1) - 1107 lines. Followed Leela's outline (5 parts), filled with Farnsworth's data. diff --git a/.squad/decisions.md b/.squad/decisions.md index 985f422..8444116 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -196,6 +196,13 @@ - Cleanup stays semantic, not just structural: docs and plugin metadata must stop advertising shipped installable skills. - Validation target stays bounded: live `rg` and filesystem checks must pass; strict MkDocs build remains desirable but may be blocked if `mkdocs` is unavailable. +### 2026-06-17: Token Recommendations Placement + +**Author:** Hermes | **Status:** Active | **Requested by:** Marco Olivo + +- Placed RTK Windows caution in MCP/tool-cost sections, VS Code extension/profile and custom-agent guidance in MCP/practical setup, model-switch cache risk in model-pricing anti-patterns, and Copilot CLI AIC value-framing in habit-building maintenance. +- Each recommendation now sits beside the mechanism it affects, avoiding a new page and keeping README changes limited to high-impact quick-start nudges. + ## Governance - All meaningful changes require team consensus diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..0be68ef --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,15 @@ +{ + "workbench.colorCustomizations": { + "activityBar.background": "#580D3B", + "titleBar.activeBackground": "#7B1252", + "titleBar.activeForeground": "#FFFCFD", + "titleBar.inactiveBackground": "#580D3B", + "titleBar.inactiveForeground": "#FFFCFD", + "statusBar.background": "#580D3B", + "statusBar.foreground": "#FFFCFD", + "statusBar.debuggingBackground": "#580D3B", + "statusBar.debuggingForeground": "#FFFCFD", + "statusBar.noFolderBackground": "#580D3B", + "statusBar.noFolderForeground": "#FFFCFD" + } +} \ No newline at end of file diff --git a/README.md b/README.md index bdfee06..12db265 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,19 @@ --- -## Quick Start — 11 Things to Do Right Now +## Presentations + +- [Concise practitioner briefing (18 slides)](slides/briefing.html) +- [Full customer workshop (8 hours)](slides/index.html) + +## Quick Start — 15 Things to Do Right Now > **June 1, 2026 — Usage-Based Billing (UBB) is live.** GitHub Copilot now bills real tokens (input + output + cached) drawn from pooled AI credits ($30/seat Business, $70/seat Enterprise) instead of request counters. Every technique in this guide translates directly into credit savings — and cache-friendly habits matter more than ever. See [Enterprise Governance](docs/12-enterprise-governance.md) for customer guardrails and [Model Selection & Pricing](docs/11-models-and-pricing.md) for model-cost guidance. > **Output tokens cost much more than input tokens.** That's the most important pricing fact in this guide. Anthropic's public pricing makes the asymmetry concrete ($1/$5 Haiku, $3/$15 Sonnet, $5/$25 Opus per MTok input/output). Copilot's exact per-model UBB pricing table is not public yet, but UBB still makes verbose output disproportionately expensive. Most input tokens come from file context, history, and tool schemas — not from what you type. Your typed prompt is a tiny fraction of total input. Start with output control, then tackle structural input wins. +![Token cost anatomy: input tokens include hidden context, output tokens are the visible answer, and stable cached tokens get cheaper.](docs/assets/diagrams/token-cost-anatomy.svg) + Don't have time to read the full guide? Do these today and cut your token usage: | # | Action | Primary Effect | Time to Set Up | @@ -21,20 +28,26 @@ Don't have time to read the full guide? Do these today and cut your token usage: | 1 | **Request code-only responses** — add `Code only, no explanation.` to `copilot-instructions.md`. Highest per-token ROI: output costs 5× more than input, and this cuts 40-70% of output on every code task, permanently | Shrinks response length | 0 minutes | | 2 | **Constrain output format by default** — add `Bullets over paragraphs. No explanations unless asked.` to `copilot-instructions.md` | Keeps answers terse | 0 minutes | | 3 | **Shrink your always-on context** — compress `copilot-instructions.md` AND prune `AGENTS.md` to landmines only. Every token in either file is billed on every interaction (and every agent step). Strip filler, delete anything the agent discovers by reading code, delete LLM-generated `/init` boilerplate | Reduces always-on input/context | 15 minutes | -| 4 | **Default to Auto model selection** — use Auto as the baseline because it chooses from the supported Auto pool and gives a paid-plan discount. Pin higher-cost models manually when a task clearly justifies them. See [Model Selection & Pricing](docs/11-models-and-pricing.md) | Lowers billed rate on eligible usage | 0 minutes | +| 4 | **Default to Auto model selection + protect cache stability** — use Auto as the baseline because it chooses from the supported Auto pool and gives a paid-plan discount. In long expensive threads, keep the model, reasoning effort, loaded skills, MCP/tool set, and agent/profile stable. Changing any of these can discard the cached prefix, so start a fresh chat with a short handoff summary instead. See [Model Selection & Pricing](docs/11-models-and-pricing.md) | Lowers billed rate on eligible usage and preserves cached-input discounts | 0 minutes | | 5 | **Use Ask Mode for simple questions** — reserve Agent Mode for multi-step tasks | Avoids agent overhead | 0 minutes (just choose the right mode) | | 6 | **Scope context with `applyTo:` paths** — split one large instructions file into small scoped ones that load only when relevant | Reduces always-on input/context | 15 minutes | | 7 | **Be precise in your prompts** — "Add null check to `getUser()`" not "Can you please look at this and maybe add some error handling?" Note: your typed prompt is a small fraction of total input; precision matters more for quality than for raw token savings | Improves task targeting | 0 minutes | | 8 | **Retune prompts to the target model** — provider prompting guides change by model/version. Paste the official guide URL into Copilot and ask it to adapt `.github/copilot-instructions.md`, agent profiles, or app prompts for the model you actually use | Reduces rework | 10 minutes per model change | -| 9 | **Audit your MCP servers** — disable servers you're not using; each costs ~100-500 tokens per agent step | Removes tool/schema overhead | 5 minutes | -| 10 | **Run `/chronicle improve` weekly** (**Copilot CLI only**, experimental) — this slash command works in interactive Copilot CLI sessions, not as a general Copilot Chat feature. It finds recurring confusion in your CLI session history and generates custom-instruction fixes so the same misread intent stops costing tokens forever | Cuts recurring rework | 2 minutes per run | -| 11 | **Try CodeAct for long tool chains** (**Copilot CLI only**, optional external plugin) — [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) collapses multi-step tool chains into one sandboxed execution, which can reduce repeated replay of system prompt, prior messages, and tool definitions | Reduces tool-loop replay | 10-15 minutes | +| 9 | **Audit your MCP servers and injected tools** — disable unused MCP servers and VS Code extensions that add skills/tools; use a clean coding profile or focused custom agent for repeat workflows. Each MCP tool costs ~100-500 tokens per agent step. If shell output is still large after that, evaluate one output filter such as [RTK](https://github.com/rtk-ai/rtk) or [`snip`](https://github.com/edouard-claude/snip) | Removes tool/schema overhead and noisy command output | 5-10 minutes | +| 10 | **Convert rich files to Markdown before AI work** — `.docx`, `.pdf`, `.pptx`, `.xlsx`, HTML, images, audio, video, and ZIPs carry format tax. [Marc Bara's writeup](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) shows the cost; use [Microsoft MarkItDown](https://github.com/microsoft/markitdown) before chat, agent, or RAG ingestion | Reduces noisy input context | 5 minutes | +| 11 | **Run `/chronicle cost tips` and `/chronicle improve` weekly** (**Copilot CLI only**, experimental) — these slash commands work in interactive Copilot CLI sessions (not VS Code), not as a general Copilot Chat feature. `cost tips` analyzes your token spend and suggests reductions; `improve` finds recurring confusion in your CLI session history and generates custom-instruction fixes so the same misread intent stops costing tokens forever | Cuts recurring rework and direct token spend | 2 minutes per run | +| 12 | **Use [Tokentop](https://github.com/tokentopapp/tokentop) for live token visibility** — its local terminal dashboard shows session, model, token, cost, and burn-rate data for Copilot CLI and other supported agents. Set budget alerts before optimizing | Makes token waste and cost spikes visible; does not compress prompts or output | 5 minutes | +| 13 | **Try CodeAct for long tool chains** (**Copilot CLI only**, optional external plugin) — [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) collapses multi-step tool chains into one sandboxed execution, which can reduce repeated replay of system prompt, prior messages, and tool definitions | Reduces tool-loop replay | 10-15 minutes | +| 14 | **Plan first, then execute in a fresh session** — use plan mode (CLI) or Ask mode (VS Code) to agree the approach with a strong model, save the plan to `plan.md` or an issue, then run the execution from that plan in a clean session — often with a cheaper model. Reaching the right outcome the first time avoids the expensive rework of an agent coding in the wrong direction. See [Plan First, Then Execute §2.5.9](docs/06-workflow-optimization.md#259-plan-first-then-execute-and-route-the-phases) and [Outcome per Token](docs/13-outcome-per-token.md) | Avoids wrong-direction rework; cheaper execution lane | 0 minutes (just sequence the work) | +| 15 | **Build a persistent codebase graph with Graphify** (optional, VS Code + Copilot CLI) — [`graphify`](https://github.com/Graphify-Labs/graphify) maps the repo once with tree-sitter AST and writes `graphify-out/graph.json`; agents query the graph instead of re-reading project files each session. Best for large repos where orientation reads dominate agent input. Install: `uv tool install graphifyy` | Reduces repeated file-read input | 5-10 minutes | **Looking at this from an enterprise or customer-governance angle instead of an individual setup angle?** Start with [Enterprise Governance](docs/12-enterprise-governance.md). That chapter covers AI-credit budgets, per-user tightening, model-access policy, org instructions, and separate-organization tradeoffs. *Figures above are scoped to the mechanism named in each row, are not additive, and do not equal total bill reduction.* -Output control (#1, #2) pays off immediately and compounds — set it once, save on every call. Structural input control (#3, #6) compounds across every interaction. Model routing (#4, #5) reduces cost at the billing tier. Model-specific prompt tuning (#8) cuts waste by improving first-pass quality. MCP audit (#9) eliminates thousands of hidden tokens per agent task. +Output control (#1, #2) pays off immediately and compounds — set it once, save on every call. Structural input control (#3, #6) compounds across every interaction. Model routing (#4, #5) reduces cost at the billing tier. Model-specific prompt tuning (#8) cuts waste by improving first-pass quality. MCP audit (#9) eliminates thousands of hidden tokens per agent task; RTK/snip-style output filters address the separate cost of verbose shell results. Markdown conversion (#10) removes DOCX/PDF/HTML layout noise before the model ever sees it. Graph-based navigation (#15) front-loads codebase orientation once, then reuses it across agent sessions. + +![Plan first, execute cheaply: use a strong model for planning, save the plan, then execute in a fresh cheaper lane and verify acceptance criteria.](docs/assets/diagrams/plan-execute-cheaply.svg) --- @@ -60,7 +73,7 @@ Data-backed comparison: English is the most token-efficient language in these ex #### [2.3 Context Management](docs/04-context-management.md) -Compress system instructions, compress memory files, scope context with `applyTo`, close unused editor tabs, configure Content Exclusion (Business/Enterprise admins), start fresh conversations. Control what gets sent to the model. +Compress system instructions, compress memory files, scope context with `applyTo`, close unused editor tabs, convert non-text files to Markdown before AI work, configure Content Exclusion (Business/Enterprise admins), start fresh conversations. Control what gets sent to the model. #### [2.4 Output Control](docs/05-output-control.md) @@ -76,7 +89,7 @@ Research on LLM-generated context files suggests they often hurt agent correctne #### [2.7 MCP & Tool Costs](docs/08-mcp-tool-costs.md) -The hidden token tax: each MCP tool costs 100-500 tokens per agent step. 15 servers × 15 steps = 265K tokens of overhead. Audit guide included. +The hidden token tax: each MCP tool costs 100-500 tokens per agent step. 15 servers × 15 steps = 265K tokens of overhead. Covers MCP audit, Copilot harness baseline, RTK, snip, minimal-context-tools, and adjacent output/context-compression tools. --- @@ -96,19 +109,27 @@ Step-by-step: configure Copilot, optimize the Coding Agent, configure agent mode --- -### Part 4.2: Model Selection & Pricing +### Companion: Model Selection & Pricing Dedicated page on models, PRU-era multiplier history, current Auto guidance, plan availability, and where vendor input/output token pricing fits while Copilot's exact per-model UBB table remains unpublished. Includes links to the official GitHub Docs pages for Auto model selection, billing, and plan/model availability. -→ **[Read Part 4.2](docs/11-models-and-pricing.md)** +→ **[Read the companion](docs/11-models-and-pricing.md)** + +--- + +### Companion: Enterprise Governance + +Dedicated chapter for customer-facing admin guidance: usage-based billing guardrails, AI-credit budgets, spend cohorts, FinOps-as-code automation, model-access policy, org-level instructions, and separate-organization tradeoffs. + +→ **[Read the companion](docs/12-enterprise-governance.md)** --- -### Part 4.3: Enterprise Governance +### Companion: Outcome per Token -Dedicated chapter for customer-facing admin guidance: usage-based billing guardrails, AI-credit budgets, per-user tightening, model-access policy, org-level instructions, and when separate organizations are worth the overhead. +Dedicated chapter for the shift from token minimization to value per token: plan-first execution, prompt-skill progression, model routing, benchmark caveats, and day-to-day model choices under usage-based billing. -→ **[Read Part 4.3](docs/12-enterprise-governance.md)** +→ **[Read the companion](docs/13-outcome-per-token.md)** --- @@ -123,10 +144,12 @@ Ranked by cost impact. Output first — it costs 5× more per token than input. 1. **Output control** — "Code only, no explanation" + terse default in `copilot-instructions.md`. 40-70% output savings on code tasks, 30-60% across all interactions. One instruction, permanent. 2. **Shrink always-on context** (`copilot-instructions.md` + `AGENTS.md`) — compress filler, prune to landmines only, delete LLM-generated boilerplate. Compounds on every interaction and agent step; 20-23% agent-task reduction plus better correctness 3. **Ask Mode for simple questions** — 60-90% savings by avoiding Agent overhead -4. **Audit MCP servers** — disable unused servers, save 5K-190K tokens per agent task +4. **Audit MCP servers and injected tools** — disable unused servers/extensions, or use a clean coding profile/custom agent, to save 5K-190K tokens per agent task 5. **Auto model selection** — lower-cost default routing plus paid-plan discount on eligible usage, zero effort -6. **Retune prompts to the target model** — better first-pass output reduces repeated clarification turns -7. **Precise prompts** — 20-40% of user-prompt input tokens; more important for quality than raw savings +6. **Convert rich files to Markdown first** — avoid paying for Word/PDF/HTML layout noise in chat, agent, and RAG workflows +7. **Build a persistent codebase graph** — use Graphify on large repos so agents query `graph.json` instead of re-reading structural files every session +8. **Retune prompts to the target model** — better first-pass output reduces repeated clarification turns +9. **Precise prompts** — 20-40% of user-prompt input tokens; more important for quality than raw savings --- diff --git a/docs/01-why-tokens-matter.md b/docs/01-why-tokens-matter.md index 79825b2..4da9c12 100644 --- a/docs/01-why-tokens-matter.md +++ b/docs/01-why-tokens-matter.md @@ -49,23 +49,7 @@ Every token you send or receive has a cost. Here's how: Understanding what Copilot does behind the scenes helps you optimize: -```text -┌─────────────────────────────────────────────────┐ -│ Context Window │ -│ │ -│ ┌──────────────────┐ ┌─────────────────────┐ │ -│ │ INPUT TOKENS │ │ OUTPUT TOKENS │ │ -│ │ │ │ │ │ -│ │ System prompt │ │ The response │ │ -│ │ + copilot- │ │ you receive │ │ -│ │ instructions │ │ │ │ -│ │ + file context │ │ │ │ -│ │ + conversation │ │ │ │ -│ │ history │ │ │ │ -│ │ + YOUR prompt │ │ │ │ -│ └──────────────────┘ └─────────────────────┘ │ -└─────────────────────────────────────────────────┘ -``` +![Token cost anatomy: input tokens include hidden context, output tokens are the visible answer, and stable cached tokens get cheaper.](assets/diagrams/token-cost-anatomy.svg) - **System prompt:** Copilot's own instructions (you can't control this) - **`copilot-instructions.md`:** Your project-level instructions — loaded on **every** interaction diff --git a/docs/02-prompt-compression.md b/docs/02-prompt-compression.md index dc3de6b..a8c5b1e 100644 --- a/docs/02-prompt-compression.md +++ b/docs/02-prompt-compression.md @@ -8,6 +8,8 @@ The single most effective token optimization technique. Drop the linguistic scaffolding that adds tokens without adding information. +![Prompt compression ladder: verbose text compresses through lite, full, and ultra forms while preserving technical terms and constraints.](assets/diagrams/prompt-compression-ladder.svg) + **What to drop:** - Articles: a, an, the diff --git a/docs/04-context-management.md b/docs/04-context-management.md index d3d915e..8251a6b 100644 --- a/docs/04-context-management.md +++ b/docs/04-context-management.md @@ -45,7 +45,7 @@ Code/commits/PRs: normal. Off: "stop caveman" / "normal mode". ## 2.3.2 Memory File Compression -Beyond `copilot-instructions.md` / `AGENTS.md` (which are the same file under two names, see note above), many projects accumulate other memory files that become context: `CLAUDE.md`, project notes, coding guidelines, `.cursorrules`. These are all loaded as context, and all burn tokens on every call. Consolidate duplicates before you start compressing. +Beyond `copilot-instructions.md` / `AGENTS.md` (distinct conventions that can both be loaded; see note above), many projects accumulate other memory files that become context: `CLAUDE.md`, project notes, coding guidelines, `.cursorrules`. These are all loaded as context, and all burn tokens on every call. Consolidate duplicates before you start compressing. **Before (~40 tokens):** @@ -93,15 +93,47 @@ What actually reduces auto-included context (per-developer levers that work ever - Vendor directories - Data files (CSVs, JSON fixtures) - Archived documentation +- Rich document formats (`.docx`, `.pdf`, `.pptx`, `.xlsx`, HTML exports, scanned images, audio/video transcripts) Every file that enters context costs tokens. Be intentional about what's open and what's referenced with `#file`. +### Normalize non-text inputs to Markdown first + +When the source is a Word file, PDF, PowerPoint, spreadsheet, image, audio file, or exported HTML, do not paste the rich format directly into an AI workflow if you can avoid it. Convert it to clean Markdown first, then send the Markdown. + +![Format tax pipeline: rich formats create layout noise, MarkItDown normalizes them to clean Markdown, and rich delivery formats are generated only at the end.](assets/diagrams/format-tax-pipeline.svg) + +Marc Bara calls this the **format tax** in [Your .docx Is Wasting 33% of Your AI Budget](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042): Word, PDF, and HTML carry font data, XML, page-positioning metadata, layout artifacts, embedded objects, and tag soup that models must process but rarely need. The article cites a concrete example where a 10-page report extracted from PDF used roughly 12,400 tokens, while the same content as clean Markdown used about 8,350 tokens — a 33% reduction with the same information. HTML exports can be even worse because semantic content gets wrapped in long tags, classes, IDs, and layout scaffolding. + +The rule: use Markdown as the **working format** for AI interaction, and treat Word/PDF/PowerPoint as delivery formats. Draft, review, summarize, chunk, and retrieve from Markdown. Generate `.docx` or `.pdf` at the end only when a client, regulator, or internal process needs that artifact. + +[Microsoft MarkItDown](https://github.com/microsoft/markitdown) is the practical bridge. It is a Python tool for converting files and office documents to Markdown for LLM and text-analysis pipelines. It preserves useful structure such as headings, lists, tables, links, and extracted metadata, while avoiding high-fidelity visual layout noise. Current converters include PDF, Word, PowerPoint, Excel, images with EXIF/OCR support, audio with transcription support, HTML, CSV/JSON/XML, ZIP contents, YouTube URLs, EPUBs, and more. + +Fast path: + +```bash +pip install 'markitdown[all]' +markitdown report.docx -o report.md +markitdown deck.pptx -o deck.md +markitdown source.pdf > source.md +``` + +Use narrower extras when you control the workflow and want fewer dependencies: + +```bash +pip install 'markitdown[pdf,docx,pptx,xlsx]' +``` + +Security note: MarkItDown reads files, streams, and URLs with the privileges of the current process. For untrusted inputs, validate paths and URLs first, and prefer the narrowest conversion API that fits the workflow. + ## 2.3.4 Scope Context Intentionally — Conditional Over Always-On Most context files are loaded on **every** interaction. That's a tax you pay even when the file isn't relevant — your React component questions don't need your database migration guidelines. The fix: prefer **conditional context** over always-on context. +![Context loading boundaries: keep the always-on core tiny, move path-specific guidance to scoped instructions, and load skills on demand.](assets/diagrams/context-loading-boundaries.svg) + ### Use `applyTo:` paths in custom instructions Custom instruction files in `.github/instructions/*.instructions.md` accept an `applyTo` frontmatter field that scopes the file to matching paths. Copilot only loads it when the conversation involves files matching the glob. @@ -140,14 +172,80 @@ Most teams have it inverted — everything in always-on. Flipping the ratio cuts The cheapest token is the one the platform doesn't have to re-process. Modern Copilot interactions cache stable portions of context (system prompt, instruction files, recently-loaded files) so they don't pay the full input-token cost on every turn. +In long sessions, this is often the biggest single cost lever. When most of your input is cache-hit input, effective input cost can drop dramatically (commonly cited as up to ~90% discount on cached input, depending on provider/model/surface billing rules). + You can lean into this. Two practical patterns: +![Cache stability: stable threads reuse the same model, MCP set, and agent profile; cache-busted threads switch controls mid-session and should use a fresh handoff instead.](assets/diagrams/cache-stability.svg) + **1. Stable instructions at the top, volatile work at the bottom.** Cached context only works if the prefix of your conversation is stable. Don't reshuffle your `copilot-instructions.md` or rotate which files are open between every prompt — keep the stable layer stable, and let only the most recent message change. **2. Reuse named context via slash commands and saved snippets.** When you frequently ask about the same domain, define it once and reference it. For example: keep a short customers-schema note or slash-command snippet, load it once for the session, then keep follow-up prompts anchored to that shared summary instead of re-pasting the schema every time. +**3. Don't churn the cacheable prefix mid-session.** The cached prefix is the *front* of every request — system prompt, tool/MCP definitions, and instruction files (the always-loaded `System/Tools` baseline; see [MCP & Tool Costs §2.7](08-mcp-tool-costs.md)). Changing any of it mid-conversation forces a full re-encode and forfeits the savings: + +| Mid-session change | Effect on cache & context | +|--------------------|---------------------------| +| **Switch model or reasoning effort** | Caches are typically per-model, and changing model configuration can discard the cached prefix. The carried history may then be billed again at standard input rates in the new lane. Pick both before work starts; see [Model-switch rule](11-models-and-pricing.md#anti-patterns). | +| **Switch custom agent** | Swaps the system prompt, tool set, and instructions — the prefix changes, so the cache is invalidated and the prior accumulated context becomes pollution under the new agent. | +| **Toggle MCP servers, tools, or loaded skills** | Changes the harness and its tool/instruction definitions in the prefix — cache invalidated, plus you add or remove always-loaded tokens on every later turn. | +| **Churn large context** | Attaching/detaching big files or pasting large blobs reshuffles context and undercuts prefix stability. Choose your files and context up front. | + +The pattern: **decide model, agent, and tool set before you start; if you genuinely need a different one, start a fresh session** with only the relevant summary and files rather than mutating a long one. (Billing implementation varies by surface and plan, so treat this as risk control rather than guaranteed repricing math.) + Caching gains are real and dual-purpose: **it's faster** (cached prefixes skip re-encoding) **and cheaper** (most platforms bill cached input tokens at a fraction of the standard rate). Designing your context layout for cache stability is one of the lowest-effort wins available. +```text +Cache-stable long thread + +Turn 1 Turn 2 Turn 3 Turn 4 +| | | | +v v v v +[same model + same reasoning effort + same skills/MCP set + same agent/profile] +[stable prompt prefix reused from cache ] -> lower effective input cost +[only newest user request changes ] + +Cache-busted long thread + +Turn 1 Turn 2 Turn 3 +| | | +v v v +[model A + MCP set A + agent A] +[cached prefix builds ] + | + v + switch model / reasoning effort / skills / MCP / agent + | + v +[large prefix invalidated or repriced] -> cache discount lost; start fresh instead +``` + +### Protect the cache: avoid cache-busting changes mid-thread + +In expensive long-running chats, treat cache stability as a hard constraint. The most common cache-busters are: + +- **Switching models mid-thread** (for example, moving from one Claude/GPT tier to another) +- **Changing reasoning effort mid-thread** on a supported reasoning model +- **Enabling or disabling MCP servers mid-thread** (tool definitions sit near the top of context; changing them invalidates large prefixes) +- **Loading or unloading skills mid-thread** when they change the session's instructions or tools +- **Switching agent/profile mode mid-thread** (default agent ↔ custom agent, or one custom agent ↔ another) + +Practical rule: keep this tuple fixed for the whole long thread: + +```text +{ model, reasoning effort, loaded skills, active MCP/tool set, agent/profile } +``` + +If you need to change any item in that tuple, start a fresh conversation with a compact handoff summary instead of changing it in place. + +### Safe handoff pattern when a switch is required + +1. Summarize current thread in 5-10 bullets (decisions, constraints, open tasks). +2. Start a new chat with the new model/agent/MCP setup. +3. Paste only the summary + required files, not the entire old transcript. + +This preserves cache efficiency in the original thread and prevents dragging stale context into a new cost lane. + ## 2.3.6 Start Fresh Conversations Conversation history accumulates. After 20+ messages, you might have 50K+ tokens of history sent with every new message. @@ -161,6 +259,51 @@ Conversation history accumulates. After 20+ messages, you might have 50K+ tokens **How to preserve continuity:** Summarize key decisions in your new prompt. "Continuing from auth refactor — we chose JWT over sessions. Now implement refresh tokens." +## 2.3.7 Persistent Graphs — Replace Per-Session File Reads + +The per-session codebase-read pattern is a hidden input cost: every new agent session starts from scratch, re-reading the same structural files to understand imports, call paths, and component layout. On large repos, orientation reads can burn thousands of tokens before the agent makes one useful edit. + +[Graphify](https://github.com/Graphify-Labs/graphify) attacks that cost differently from prompt compression. It parses the repo once with tree-sitter AST, writes a persistent `graphify-out/graph.json`, and lets agents query that graph instead of repeatedly reading source files for structure. + +![Persistent graph navigation: Graphify builds a shared graph once, then agents query paths and explanations instead of rereading broad file sets.](assets/diagrams/graphify-navigation.svg) + +```bash +uv tool install graphifyy + +# Build or update the graph in the repo +graphify . + +# Query targeted structure instead of reading broad files +graphify query "where is auth middleware?" +graphify explain "UserService" +graphify path "Router" "Database" +``` + +Core outputs: + +```text +graphify-out/ +├── graph.json queryable graph for agents +├── graph.html interactive visual explorer +└── GRAPH_REPORT.md human-readable communities, god nodes, and suggested questions +``` + +**When this helps most:** + +- large codebases where agents routinely start by reading 5-10 files for orientation +- repeated agent sessions over the same repo +- cross-file questions where a path/query answer is cheaper than broad file reads +- teams that can share the same graph build across developers or agents + +**When to skip:** tiny repos where the agent reads two files and finishes. The one-time graph build is overhead if there is no repeated navigation cost to amortize. + +**Caveats:** + +- Code extraction is local and deterministic for the AST pass; optional semantic/deep extraction over docs, PDFs, images, or media may use a configured AI backend. +- The graph can go stale after large refactors. Rebuild it or use Graphify's update/watch/hook flows where appropriate. +- `GRAPH_REPORT.md` is generated output. Treat it as a map, not the source of truth. +- Graphify complements RTK or snip. Graphify reduces repeated codebase-navigation input; shell-output filters compress verbose command results. + --- **Next:** [Output Control →](05-output-control.md) diff --git a/docs/06-workflow-optimization.md b/docs/06-workflow-optimization.md index ca89e33..44132cc 100644 --- a/docs/06-workflow-optimization.md +++ b/docs/06-workflow-optimization.md @@ -61,6 +61,8 @@ This is one of the higher-leverage savings opportunities in the guide. **Ask Mode** is a single call. One question, one answer. +![Copilot mode decision tree: use Ask for questions, Edit for single-file changes, Agent for clear multi-file work, and clarify vague work before execution.](assets/diagrams/mode-decision-tree.svg) + | Task | Right Mode | Why | |------|-----------|-----| | "What does this function do?" | Ask | Single-shot answer. No tool use needed | @@ -95,11 +97,11 @@ When not to use it: Keep the claim bounded: this guide is **not** benchmarking CodeAct itself. The plugin README reports lower token use on its own benchmark prompts, including MCP-loaded cases, but that is plugin-reported task data, not a universal savings baseline. -### Complementary: RTK for tool output compression +### Complementary: RTK or snip for tool output compression -CodeAct reduces the *number* of tool calls. [**RTK (Rust Token Killer)**](https://github.com/rtk-ai/rtk) reduces the *size* of each tool call's result. They address different sides of the same problem and can be used together. +CodeAct reduces the *number* of tool calls. [**RTK (Rust Token Killer)**](https://github.com/rtk-ai/rtk) and [`snip`](https://github.com/edouard-claude/snip) reduce the *size* of each shell tool result. They address different sides of the same problem and can be used together. -RTK is a CLI proxy that intercepts `git`, `cargo test`, `grep`, `ls`, and 100+ other dev commands and compresses their output before it reaches the agent — 60–90% savings per command. Unlike CodeAct, RTK works in all Copilot surfaces (VS Code, CLI, and other AI tools), not just Copilot CLI. See [MCP & Tool Costs §2.7.7](08-mcp-tool-costs.md#277-compress-tool-output-at-the-source-rtk) for setup and the full command list. +These tools intercept `git`, test runners, `grep`, `ls`, and other dev commands and compress their output before it reaches the agent — often 60–90% savings on verbose command output. Unlike CodeAct, this is not about Copilot CLI only; it can help anywhere the shell hook is reliable. Treat Windows and preview hook paths as pilots, not default rollouts. See [MCP & Tool Costs §2.7.7](08-mcp-tool-costs.md#277-compress-tool-output-at-the-source-rtk) and [§2.7.8](08-mcp-tool-costs.md#278-rtk-alternative-snip) for setup. ## 2.5.4 Default to Auto Model Selection @@ -113,6 +115,22 @@ The model picker is one of the highest-cost control surfaces in Copilot. Pinning Teams that switch their default from "always Sonnet" or "always Opus" to "Auto, override when needed" generally reduce spend because they stop defaulting every interaction into the higher-cost lane. +### Cache-aware model workflow + +Model routing and caching must work together. In long expensive sessions, avoid changing your cost/control surface mid-thread: + +- do not switch model unless the task clearly changes +- do not toggle MCP servers unless the task truly requires different tools +- do not switch agent/profile mode in the same long thread + +Why: those controls live in the high, stable prefix of context. Changing them can invalidate cached prefixes and force reprocessing of large input blocks. + +Practical pattern: + +1. Pick lane at session start: `{model, agent/profile, MCP set}`. +2. Keep lane stable while working that thread. +3. If lane must change, start a fresh chat with a concise handoff summary. + ## 2.5.5 Retune Prompts to the Target Model This is not prompt compression. It may not reduce tokens per request. It reduces total token use by improving first-pass quality, which cuts follow-up turns, repeated clarifications, and agent rework. @@ -188,21 +206,32 @@ A well-designed terse prompt template or agent profile can handle this automatic Token waste isn't only in any one prompt — it's in the **patterns** you don't notice. The same misread intent costing 5K extra tokens per session, every session. Copilot ships a built-in feedback loop for this: the [`/chronicle`](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/chronicle) slash command analyzes your local session history and tells you where Copilot got confused, where you went in circles, and how to fix it. -> **Scope:** Full `/chronicle` (all subcommands) is available in **Copilot CLI** interactive sessions, backed by local session history in `~/.copilot/session-state/`. The `tips` subcommand is also available in **VS Code** as `/chronicle:tips`. +> **Scope:** `/chronicle` is a **Copilot CLI** feature, backed by local session history in `~/.copilot/session-state/`. It runs in Copilot CLI interactive sessions — and inside **JetBrains IDEs** via interactive Copilot CLI sessions. It is **not** available in **VS Code**; for VS Code usage analytics, see [AI Engineering Coach](#258-vs-code-usage-analytics-ai-engineering-coach) below. > > **Availability:** `/chronicle` is currently experimental. Enable it with `/experimental on` in an interactive Copilot CLI session, or pass `--experimental` on the command line. -Three subcommands, ranked by token-saving impact: +The full subcommand set is `standup`, `tips`, `cost tips`, `search`, `improve`, and `reindex`. The three with the most token-saving impact: | Command | What it does | Token-saving payoff | |---------|--------------|---------------------| -| **`/chronicle improve`** | Scans session history for back-and-forth, misunderstood intent, and repeated corrections — then **generates custom-instruction snippets** to prevent the pattern next time | Highest. Cuts off recurring waste at the source. Each fix compounds across every future session in that repo. | -| **`/chronicle tips`** (CLI) / **`/chronicle:tips`** (VS Code) | Personalized coaching based on how you actually use Copilot — surfaces features and workflow improvements you're missing | Medium. Often suggests Ask Mode, model routing, or context scoping changes worth real tokens. | +| **`/chronicle cost tips`** | Analyzes your token spend across recent sessions — prompt length, tool-call frequency, continuation steps — and suggests concrete ways to cut cost | Highest, and the most on-topic for this guide. Targets token spend directly. | +| **`/chronicle improve`** | Scans session history for back-and-forth, misunderstood intent, and repeated corrections — then **generates custom-instruction snippets** to prevent the pattern next time | High. Cuts off recurring waste at the source. Each fix compounds across every future session in that repo. | +| **`/chronicle tips`** | Personalized coaching based on how you actually use Copilot — surfaces features and workflow improvements you're missing | Medium. Often suggests Ask Mode, model routing, or context scoping changes worth real tokens. | | **`/chronicle standup`** | Generates a standup summary from your session data (branches, PRs, status) | Indirect — saves the 10 minutes you'd spend reconstructing yesterday, not direct token spend. | +### The `cost tips` workflow + +The most direct fit for this guide. Run it weekly to see where your tokens actually go. + +```text +/chronicle cost tips +``` + +Copilot CLI analyzes your token usage across recent sessions — looking at patterns like prompt length, tool-call frequency, and continuation steps — and surfaces specific, usage-grounded ways to reduce spend. Unlike generic advice, these recommendations are tied to your real session data, so they tend to point at the few habits costing you the most. + ### The `improve` workflow -This is the one that matters for token optimization. Run it weekly, or any time you catch yourself thinking *"why does it keep getting this wrong?"* +This is the one that generates lasting fixes. Run it weekly, or any time you catch yourself thinking *"why does it keep getting this wrong?"* ```text /chronicle improve @@ -214,21 +243,17 @@ Copilot CLI reads your recent CLI sessions, identifies recurring confusion (e.g. ### The `tips` workflow -Run every week or two. Command varies by surface: +Run every week or two: ```text -# Copilot CLI /chronicle tips - -# VS Code -/chronicle:tips ``` Treat the suggestions like a code review — not all are worth adopting, but the ones that match your actual workflow are usually high-ROI. Common tips that overlap with this guide: switching to Ask Mode for explanation requests, scoping instruction files with `applyTo`, disabling unused MCP servers. ### Where this fits in the workflow -- **Weekly:** `/chronicle tips` (CLI) or `/chronicle:tips` (VS Code) — catch missed habits. +- **Weekly:** `/chronicle cost tips` — see where tokens go, and `/chronicle tips` — catch missed habits. - **When something feels repetitive:** `/chronicle improve` — turn the friction into a one-time fix. - **Daily standup (optional):** `/chronicle standup last 24 hours` — for the human ritual, not for tokens. @@ -262,6 +287,58 @@ Then `Cmd+Shift+P` → **AI Engineer Coach: Open Dashboard**. **How it complements `/chronicle`:** `/chronicle` acts on CLI session history to generate instruction fixes. AI Engineering Coach acts on VS Code session history to score your practice and flag structural issues (context bloat, unused MCPs, instruction-file gaps). Use both: chronicle to patch recurring prompt failures; AI Engineering Coach to audit the broader VS Code setup and track trend lines. +## 2.5.9 Plan First, Then Execute (and Route the Phases) + +The most expensive tokens are the ones spent reaching a *wrong* outcome: an agent that codes for twenty steps in the wrong direction, then gets unwound and redone. Separating **planning** from **execution** is one of the highest-leverage habits for cutting that waste. + +**The two-phase pattern:** + +![Plan first, execute cheaply: use a strong model for planning, save the plan, then execute in a fresh cheaper lane and verify acceptance criteria.](assets/diagrams/plan-execute-cheaply.svg) + +1. **Plan in plan mode (or Ask mode) first.** Use Copilot CLI's plan mode (or VS Code Ask mode) to think through the approach *before* any code is written — files to touch, order of changes, edge cases, acceptance criteria. Planning is cheap: it's mostly reasoning, no large diffs, no repeated tool loops. This is where a stronger model earns its cost, because a good plan prevents expensive rework downstream. +2. **Save the plan, then execute it.** Write the agreed plan to a file (e.g. `plan.md`) or a tracked issue, then start a **fresh session** and prompt the execution against that saved plan. A clean session keeps the cacheable prefix stable (see [Caching §2.3.5](04-context-management.md#235-caching-store-and-reuse-context-within-prompts)) and avoids dragging the whole planning conversation forward as input tokens on every execution turn. + +**Why this saves tokens:** + +- **Fewer wasted steps.** A concrete, pre-agreed plan means the agent doesn't explore, guess requirements, or backtrack. Each avoided agent step is one full context reload saved (see [Minimizing Agent Steps §4.5.3](10-practical-setup.md#453-minimizing-agent-steps)). +- **Cheaper execution lane.** Once the hard thinking is done and captured as explicit steps, execution is often mechanical — a cheaper model (Auto or an included model) can carry it out. Reserve the premium model for the planning phase where reasoning quality moves the outcome. See [Model Routing §4.5](10-practical-setup.md#step-5-mix-models-by-task-model-routing). +- **A clean execution context.** Starting execution from a saved plan, rather than a long plan-then-build mega-session, keeps history short and the prefix cache-friendly — input cost per turn stays low. + +**Rule of thumb:** plan with the strong model, execute with the cheap one, and put the plan on disk in between. The outcome is reached in fewer total tokens *and* is usually higher quality, because the plan was reviewed before a single line was written. + +For the fuller outcome-per-token frame, skill taxonomy, benchmark caveats, and current model routing matrix, see [Outcome per Token](13-outcome-per-token.md). + +## 2.5.10 Layer Tooling on Top of the Copilot Harness + +Copilot CLI and VS Code Copilot already optimize parts of the agent loop. Treat that as the baseline before adding external tools: + +![MCP and tooling stack: scope MCP schemas, use CodeAct for long tool chains, filter command output with RTK or snip, and use Graphify for repeated orientation.](assets/diagrams/mcp-tooling-stack.svg) + +- **Prompt/cache layer:** keep `{model, active MCP set, active agent/profile}` stable so cached prefixes stay reusable. +- **Tool-schema layer:** prefer built-in tools and scoped MCPs; Copilot can defer or route some tool definitions, but extra servers and extensions still add surface area. +- **Transport/session layer:** WebSocket reuse and automatic compaction help long agent runs, but compaction summarizes what the agent already saw. +- **Terminal-output layer:** built-in truncation is a safety net, not a semantic filter. + +Add third-party tools only for the layer they actually improve: + +| Layer | Tooling | What it reduces | +|-------|---------|-----------------| +| Workflow turns | CodeAct | Repeated replay from many small tool calls in Copilot CLI | +| Command output | RTK or snip | Verbose `git`, test, grep, build, and infra command output | +| Command choice | minimal-context-tools | Broad file reads and iterative searching by steering toward `rg`, `fd`, `jq`, `ast-grep` | +| Codebase orientation | Graphify | Repeated structural file reads across sessions | +| Visibility/audit | [Tokentop](https://github.com/tokentopapp/tokentop), Tokalator, token-optimizer | Tokentop gives live local session, model, token, cost, and burn-rate visibility; monitoring does not compress by itself | + +**Rule:** one tool per layer. Combining CodeAct with RTK or snip can make sense because one reduces turn count and the other reduces output size. Running RTK and snip on the same command path usually does not — it can double-truncate output and make failures harder to inspect. + +Use this order when tuning a session: + +1. Pick the Copilot lane once: model, mode, active MCP/tool set, and agent/profile. +2. Disable unused MCP servers and extension-provided tools. +3. Use skills or focused agent instructions to make tool calls precise. +4. Add one shell-output filter if command output is still large. +5. Start a fresh session when changing lanes instead of mutating a long thread. + --- **Next:** [The AGENTS.md Problem →](07-agents-md-problem.md) diff --git a/docs/08-mcp-tool-costs.md b/docs/08-mcp-tool-costs.md index 731e4cb..7ee670f 100644 --- a/docs/08-mcp-tool-costs.md +++ b/docs/08-mcp-tool-costs.md @@ -8,6 +8,8 @@ Most context waste hides in things you never examine. Before tuning MCP servers or instruction files, check what's actually in your context window. +![MCP and tooling stack: separate fixes reduce schema cost, turn count, shell output, repeated orientation reads, and visibility gaps.](assets/diagrams/mcp-tooling-stack.svg) + **Copilot CLI:** run `/context` mid-session to get a real breakdown: ```text @@ -18,7 +20,7 @@ Free Space: 55.3k (28%) Buffer: 40.4k (20%) ``` -**VS Code Copilot:** no equivalent command, but you can estimate your `System/Tools` baseline by counting active MCP servers × tools × ~200 tokens average (see §2.7.2). +**VS Code Copilot:** no equivalent command, but you can estimate your `System/Tools` baseline by counting active MCP servers × tools × ~200 tokens average (see §2.7.2). Also audit extensions that add skills, agents, MCP servers, or tool surfaces. If an extension injects tools you do not need for coding, disable it for that workspace or move coding work into a VS Code profile with only the essentials enabled. **The critical distinction — always-loaded vs. on-demand:** @@ -32,6 +34,8 @@ Buffer: 40.4k (20%) Skills stored in `.copilot/skills/` — even hundreds of kilobytes on disk — contribute **zero** to the `System/Tools` baseline. Optimizing skills improves individual agent spawn speed, not context headroom. MCP plugins and instruction files are the levers that move the `System/Tools` number. +> **Set this baseline before you start — don't change it mid-session.** Because `System/Tools` sits at the front of every request, it's also the cacheable prefix. Toggling MCP servers/tools or switching the custom agent mid-conversation rewrites that prefix, forfeits the cached savings, and leaves prior context as pollution under the new tool set. Choose your MCP/tool and agent set up front; if you genuinely need a different one, start a fresh session. See [Caching §2.3.5](04-context-management.md#235-caching-store-and-reuse-context-within-prompts). + > Dina Berry (Microsoft/GitHub content contributor) measured a real Copilot CLI production setup and found a single Azure plugin loading ~27K tokens per message — invisible until she ran `/context`. [Full writeup →](https://dfberry.github.io/2026-05-06-tuning-up-copilot-context) --- @@ -151,6 +155,8 @@ Don't enable every MCP server globally. Use workspace-level configuration: **The rule:** If you don't need it for the current task, disable it. You can always re-enable it later. Every idle MCP server costs tokens on every agent step. +**VS Code extensions count too.** MCP servers are the obvious source of tool schemas, but some extensions also add skills, chat participants, agent profiles, or tool surfaces that can appear in the AI context. For cost-sensitive coding sessions, keep a lean VS Code profile: core language tooling, GitHub Copilot, and only the MCP/tools needed for that repo. Disable everything else at the workspace or profile level. + ## 2.7.6 Practical Guidance 1. **Audit your MCP servers** — run through your enabled servers. Do you actually use all of them? Disable the rest @@ -160,12 +166,16 @@ Don't enable every MCP server globally. Use workspace-level configuration: 5. **Custom instructions help** — add "Minimize tool calls. Read files only when necessary." to reduce call frequency 6. **Use skills instead of MCPs for occasional capabilities** — MCP tool schemas load on every step whether used or not. Skills load only title and description upfront; the full content pulls on demand. If a capability is used in fewer than half your sessions, a skill is cheaper. See [Practical Setup §4.2](10-practical-setup.md#mcps-vs-skills-eager-vs-lazy-context-loading) for the full comparison 7. **Optional, Copilot CLI only: try CodeAct for long tool chains** — external plugin [`copilot-codeact-plugin`](https://github.com/jsturtevant/copilot-codeact-plugin) collapses many small tool hops into one sandboxed execution. That does not shrink any one server's schema, but it can reduce how often the full tool catalog gets replayed on CLI-heavy tasks -8. **Compress tool output at the source with RTK** — [RTK (Rust Token Killer)](https://github.com/rtk-ai/rtk) is a CLI proxy that filters the *results* of shell commands before they reach the agent. Confirmed to work well in VS Code Copilot (repo-by-repo setup). Reductions are real but vary by command and project output volume. See §2.7.7 +8. **Use a focused custom agent for repeat coding workflows** — a custom agent can carry a narrow tool list and stable instructions, so the same coding workflow starts with the same active surface instead of whatever the default chat currently exposes. Where your Copilot surface supports model selection in agent/profile files, pin the intended model there too +9. **Compress tool output at the source with RTK or snip** — [RTK (Rust Token Killer)](https://github.com/rtk-ai/rtk) and [`snip`](https://github.com/edouard-claude/snip) are CLI proxies that filter the *results* of shell commands before they reach the agent. Reductions are real but vary by command, project output volume, and hook reliability. See §2.7.7 and §2.7.8 +10. **Use minimal-context skills before adding more tools** — [`minimal-context-tools`](https://github.com/SebastienDegodez/copilot-instructions/tree/main/plugins/minimal-context-tools) packages skills for `rg`, `fd`, `jq`, `yq`, `ast-grep`, and related CLIs. The pattern is cheap because it steers the agent toward precise one-shot commands before any large output exists. Pair it with RTK/snip when shell output is still noisy. ## 2.7.7 Compress Tool Output at the Source: RTK MCP schema overhead is the cost *before* any work. Separately, every shell command the agent runs produces output that becomes input tokens on the next step. A failing `cargo test` or `git diff` on a large PR can return 10,000–25,000 tokens of raw text — passing test lines, unchanged diff context, build noise — that the agent reads in full. +Copilot already has harness-level savings: prompt caching, deferred tool schemas, WebSocket transport, context compaction, and large-output caps. Those features do not replace output filters. VS Code's terminal tool uses a hard head/tail-style output limit; Copilot CLI also warns the model to limit output and filter with `head`, `tail`, `grep`, or `awk`. That is useful safety net behavior, not semantic parsing. RTK and snip act earlier: they turn verbose command output into a smaller domain-specific summary before the harness has to truncate it. + [**RTK (Rust Token Killer)**](https://github.com/rtk-ai/rtk) is a CLI proxy that sits between the shell and the agent. It runs the original command, captures the output, applies per-command filters (noise removal, keeping only failing tests, deduplicating log lines, grouping file listings), and returns the compressed result. The agent sees smaller output; its behavior is otherwise unchanged. **How it works, step by step:** @@ -198,17 +208,21 @@ brew install rtk curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh ``` -**Setting up for VS Code Copilot — per-repo:** +**Windows caveat:** RTK is strongest today on Unix-like shell paths. On Windows, shell-hook behavior and path handling can be brittle, especially across PowerShell, Git Bash, WSL, and VS Code agent execution. Treat it as a pilot, not a default recommendation: test it on the exact repo and shell your team uses, and skip it if the setup causes command failures or noisy behavior. -For VS Code Copilot, RTK installs a PreToolUse hook scoped to the current repository. Run this once inside each repo where you want RTK active: +**Setting up for Copilot:** + +For Copilot, RTK installs a PreToolUse hook and awareness instructions. Project-scoped setup writes into `.github/`; newer RTK builds also document a global Copilot install under `~/.copilot/` / `$COPILOT_HOME`. Validate on your Copilot surface before rolling it out because hook contracts move faster than static docs. ```bash cd your-repo rtk init --copilot -# Restart VS Code + +# Optional global Copilot setup where supported by your RTK version: +rtk init -g --copilot ``` -This is a per-repo setup — there is no single global install that covers all VS Code workspaces. Once enabled in a repo, the hook is transparent: your terminal commands are unchanged; only the agent's Bash tool calls are intercepted. +Once enabled, the hook is transparent: your terminal commands are unchanged; only the agent's Bash tool calls are intercepted. If your environment does not support the global Copilot hook path reliably, keep the per-repo setup and document it for each team workspace. **Other AI tools (global install available):** @@ -223,7 +237,74 @@ rtk init --agent cline # Cline / Roo Code (project-level) **Pairs with MCP reduction:** Schema audit (§2.7.4–2.7.6) cuts the definition cost that reloads every step. RTK cuts what each tool call *returns*. Both address different parts of the token budget and work together. -## 2.7.8 Case Study: Scoping a Large Plugin — Azure MCP +## 2.7.8 RTK Alternative: snip + +[`snip`](https://github.com/edouard-claude/snip) solves the same class of problem as RTK: shell commands still run normally, but the agent receives a filtered result instead of raw noisy output. The main difference is extensibility. RTK ships a compiled Rust command registry; snip uses declarative YAML filters that users and teams can add without touching Go code. + +**When snip is most attractive:** + +- you want custom filters for project-specific tools +- you want local savings stats via `snip gain` +- you prefer YAML filter contribution over compiled command rules +- you need Copilot CLI hook support and can validate the hook path in your environment + +**Install:** + +```bash +brew install edouard-claude/tap/snip +# or +go install github.com/edouard-claude/snip/cmd/snip@latest +``` + +**Copilot setup:** + +```bash +snip init --agent copilot +``` + +At the time of writing, snip's Copilot path writes a `preToolUse` hook for Copilot CLI. VS Code Copilot agent hooks are still a moving surface, so treat VS Code setup as a pilot unless your team has validated the exact version and workspace configuration. + +**Filter model:** + +```yaml +name: "git-log" +match: + command: "git" + subcommand: "log" +pipeline: + - action: "head" + n: 20 +``` + +Snip supports pipeline actions such as keeping or removing matching lines, head/tail truncation, ANSI stripping, JSON extraction, regex extraction, grouping, deduplication, aggregation, and templates. Project-local filters require trust approval, which is the right default for teams: output filters influence what the model sees, so they should be reviewed like tool configuration. + +**RTK vs. snip:** + +| Choice | Pick when | +|--------|-----------| +| RTK | You want a single Rust binary, broad agent support, and compiled defaults | +| snip | You want YAML filters, local stats, and easier project/team customization | + +Do not stack RTK and snip on the same command path by default. Pick one output-filter layer per agent surface, then measure. Stacking can double-truncate output and make debugging harder. + +## 2.7.9 Adjacent Ecosystem: What Else Belongs in the Mental Model + +Not every token tool is a direct RTK/snip alternative. Keep these categories separate: + +| Tool | Category | Use it for | Caveat | +|------|----------|------------|--------| +| [`snip-ai/snip`](https://github.com/snip-ai/snip) | Claude Code-focused output filter | Read/Bash/Grep/Glob optimization with AST-aware code handling | Different project from `edouard-claude/snip`; no Copilot path verified | +| [Redcon / ContextBudget](https://github.com/natiixnt/ContextBudget) | Context packing + command compression | Team workflows that want command compressors plus CI quality gates | License and product boundary should be reviewed before rollout | +| [Headroom](https://github.com/headroomlabs-ai/headroom) | Full-stack compression wrapper | Broader file, command, memory, and MCP compression experiments | Validate `headroom wrap copilot` before documenting as standard setup | +| [Tokentop](https://github.com/tokentopapp/tokentop) | Local token and cost visibility | Live session, model, token, cost, and burn-rate dashboard for Copilot CLI and other supported agents | Monitoring only; does not compress | +| [Tokalator](https://github.com/vfaraji89/tokalator) | VS Code token visibility | Budget dashboards, model/context-window awareness, instruction-file scans | Monitoring only; does not compress | +| [token-optimizer](https://github.com/alexgreensh/token-optimizer) | Context audit/status tooling | Auditing stale memory, configs, compaction loss, and model routing | PolyForm Noncommercial license | +| [Caveman](https://github.com/JuliusBrussee/caveman) | Model-output compression | Shorter assistant responses and terse style packs | Does not reduce shell-command input; prompt overhead matters | +| [ACON](https://github.com/microsoft/acon) | Research framework | Academic grounding for long-horizon context compression | Not a drop-in developer tool | + +The practical stack is: keep Copilot's harness stable, reduce always-loaded MCP/schema overhead, steer the agent toward precise commands, then use one semantic output filter where command output is still large. + +## 2.7.10 Case Study: Scoping a Large Plugin — Azure MCP A single plugin can dominate your `System/Tools` budget. Dina Berry (Microsoft/GitHub content contributor) audited her Copilot CLI setup with `/context` and found the Azure MCP plugin loading **~27K tokens per message** by default — more than all her other MCP servers combined. diff --git a/docs/09-comparisons-data.md b/docs/09-comparisons-data.md index 206a950..37f9631 100644 --- a/docs/09-comparisons-data.md +++ b/docs/09-comparisons-data.md @@ -74,6 +74,8 @@ The complete comparison of every technique covered in this guide: | C2 | Compressed instructions file | 40-60% of file | — | None | Low | Every repo | | C3 | Progressive on-demand guidance | 60-90% of optional guidance | — | Positive | High | Teams with reusable prompt files | | C4 | Start new conversations | 80%+ | — | Lose context | Low | Long sessions | +| C5 | Convert non-text files to Markdown first | ~33% on cited PDF example; higher for noisy HTML | — | Improves structure | Low | DOCX, PDF, PPTX, XLSX, images, audio, RAG ingestion | +| C6 | Precompute codebase graph with [Graphify](https://github.com/Graphify-Labs/graphify) | 6.8×-71.5× claimed for structural navigation tasks | — | Improves targeting | Medium | Large codebases; repeated cross-file agent navigation | | **Output Control** | | D1 | Code-only responses | — | 40-70% | Good | Low | Code generation | | D2 | Structured output (JSON/tables) | — | 30-60% | Depends | Low | Data tasks | @@ -105,17 +107,27 @@ The complete comparison of every technique covered in this guide: | J2 | Per-workspace MCP config | Variable | — | None | Medium | Multi-project setups | | J3 | Minimize tool calls (instructions) | 10-30% | — | Neutral | Low | Agent mode | | J4 | Compress tool output with [RTK](https://github.com/rtk-ai/rtk) | 60-90% of shell cmd output | — | None | Low | Agent / Coding Agent — any AI tool | +| J5 | Compress tool output with [snip](https://github.com/edouard-claude/snip) | 60-90% of shell cmd output; command-specific examples report higher | — | None | Low | Copilot CLI / agent shells where hook path is validated | +| J6 | Use minimal-context skills before more tools | 70-95% on targeted search/query patterns (tool-reported) | — | Improves targeting | Medium | Agent workflows that repeatedly search/read too broadly | +| J7 | Evaluate broad compression wrappers (Redcon / Headroom) | Tool-reported; varies by command/context pack | — | Depends | Medium | Teams willing to validate external wrappers and licenses | | **Agent Mode Configuration** | | K1 | Precise prompts + acceptance criteria | 30-60% | — | Improves | Low | Agent tasks | | K2 | Plan files for complex tasks | 15-40% | — | Improves | Medium | Multi-step agent tasks | | K3 | Cap agent maxRequests | Variable | — | Risk truncation | Low | All agent tasks | | K4 | Mode selection (Ask/Edit/Agent) | 60-90% | — | Good | Low | Every interaction | +| K5 | CodeAct for long Copilot CLI tool chains | 49-69% input tokens in plugin benchmarks | — | Depends | Medium | Copilot CLI exploration/audit sessions | > †A1/A2 output savings require system-level terse output instructions (see B5). Writing terse prompts alone saves input tokens; output tokens are only reduced if the model is instructed to respond tersely. +> C5 source: Marc Bara's [Your .docx Is Wasting 33% of Your AI Budget](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042). Use [Microsoft MarkItDown](https://github.com/microsoft/markitdown) when non-text files need to enter an AI workflow. + +> C6 source: [Graphify benchmarks](https://github.com/Graphify-Labs/graphify/blob/main/BENCHMARKS.md) and project documentation. Treat the high-end 71.5× number as structural-navigation best case on large codebases, not a universal savings guarantee. + +> J5-J7/K5 sources are external project-reported numbers, not independent guide benchmarks. Treat them as candidates to pilot, not universal bill-reduction guarantees. Do not stack multiple shell-output filters on the same command path without measuring for lost detail. + ### The Big Winners -If you do nothing else, do these six. Ranked by impact-to-effort ratio: +If you do nothing else, do these eight. Ranked by impact-to-effort ratio: 1. **Caveman-speak** — 30-50% input token savings; combine with B5 for 40-55% output savings 2. **Precise prompts** — 30-60% savings, just a habit change @@ -123,7 +135,9 @@ If you do nothing else, do these six. Ranked by impact-to-effort ratio: 4. **Shrink always-on context** (`copilot-instructions.md` + `AGENTS.md`) — compress filler, prune to landmines only, delete LLM-generated boilerplate. Compounds on every interaction and agent step; 20-23% agent-task reduction plus better correctness 5. **Ask Mode for simple questions** — 60-90% savings by avoiding Agent overhead 6. **Audit MCP servers** — disable unused servers, save 5K-190K tokens per agent task -7. **Retune prompts to target model guide** — not a per-request shrink; improves first-pass quality and avoids rework after model changes +7. **Convert non-text files to Markdown first** — avoid the DOCX/PDF/HTML format tax before content enters chat, agents, or RAG +8. **Precompute codebase graphs with Graphify** — replace repeated orientation reads with targeted graph queries on large repos +9. **Retune prompts to target model guide** — not a per-request shrink; improves first-pass quality and avoids rework after model changes ## 3.4 Quality Impact Assessment diff --git a/docs/10-practical-setup.md b/docs/10-practical-setup.md index 20be55c..dbb2c7a 100644 --- a/docs/10-practical-setup.md +++ b/docs/10-practical-setup.md @@ -86,6 +86,22 @@ GitHub Copilot pricing depends on model choice and billing mode. Pick the model **Never burn a high-effort model on a "what's the syntax for X" question** — you pay the higher token rate for an answer the cheapest model would have given you correctly. +### Cache-protection rule for long sessions + +After you choose the lane for a long thread, keep it stable: + +```text +{ model, reasoning effort, loaded skills, active MCP/tool set, agent/profile } +``` + +Do not change those controls in the middle of an expensive conversation unless required. Model, reasoning-effort, skill, or harness changes can invalidate the cached prefix and make its context bill again at standard input rates. + +If a switch is required, do this instead: + +1. Capture a short handoff summary (decisions, constraints, next actions). +2. Start a new chat with the new lane. +3. Paste only the summary and required files. + ### Step 5: Mix Models by Task (Model Routing) One useful cost lever: **use different models for different subtasks** within the same workflow. The detailed pricing context, historical multiplier references, plan availability, and official GitHub Docs links now live in [Model Selection & Pricing](11-models-and-pricing.md). Keep this section focused on the practical routing habit. @@ -183,6 +199,31 @@ If you are guiding an organization or enterprise rollout, stop here and read [En Use this page for practitioner setup. Use the enterprise chapter for customer governance decisions. +### Step 8: Convert Non-Text Inputs Before AI Work + +When a workflow starts from `.docx`, `.pdf`, `.pptx`, `.xlsx`, HTML exports, images, audio, video, or ZIP archives, add a conversion step before the content reaches Copilot or a RAG pipeline. Rich formats carry layout and metadata that inflate input tokens without improving the model's understanding. + +[Marc Bara's format-tax writeup](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) gives the operating principle: Markdown should be the working format for AI, while Word/PDF remain output formats when a human process requires them. The article cites a 10-page PDF example dropping from roughly 12,400 tokens to 8,350 after clean Markdown conversion — about 33% less input for the same content. + +[Microsoft MarkItDown](https://github.com/microsoft/markitdown) is the default tool to try first. It converts PDF, Word, PowerPoint, Excel, images, audio, HTML, CSV/JSON/XML, ZIP contents, YouTube URLs, EPUBs, and more into Markdown for LLM and text-analysis workflows. + +```bash +pip install 'markitdown[all]' + +markitdown report.docx -o report.md +markitdown slides.pptx -o slides.md +markitdown spreadsheet.xlsx -o spreadsheet.md +markitdown source.pdf > source.md +``` + +For production pipelines, install only the needed extras when possible: + +```bash +pip install 'markitdown[pdf,docx,pptx,xlsx]' +``` + +Then send the `.md` file to the model, chunk/index the `.md` file for retrieval, and regenerate `.docx` or `.pdf` only at the final delivery step. For untrusted uploads, validate paths and URLs first; MarkItDown performs I/O with the privileges of the running process. + ## 4.2 Keep Reusable Guidance Outside Always-On Context This repo no longer ships installable workflow packs. Keep the same habit, though: put occasional workflow guidance outside the always-on prompt and pull it in only when the task needs it. @@ -213,6 +254,12 @@ Skills behave differently: only the **title and description** load upfront. The **Rule:** Use MCPs for capabilities needed on most interactions. Use skills for occasional capabilities — you pay the full schema cost per turn with MCPs, but only per invocation with skills. If a tool is used in 1 in 10 conversations, a skill is roughly 10× cheaper in context overhead. +### Optional: minimal-context-tools + +[`minimal-context-tools`](https://github.com/SebastienDegodez/copilot-instructions/tree/main/plugins/minimal-context-tools) packages this idea as skills for common low-token CLI patterns: `fd` for file discovery, `rg` for targeted text search, `jq`/`yq` for structured data, `ast-grep` for syntax-aware code queries, and `tokei` for code statistics. + +Use it as a behavior layer, not as another always-on MCP server. The point is to make the agent ask narrower questions before any output filter runs. It pairs well with RTK or snip: skills reduce how much the agent requests; RTK/snip reduce how much comes back. + ## 4.3 GitHub Coding Agent Considerations The Coding Agent runs autonomous sessions that can last minutes to hours. Token savings compound over those long sessions. @@ -272,7 +319,9 @@ Mock: external services only. No impl mocking. Coverage: branch coverage ≥80%. ``` -Focused agents carry less instruction overhead than a general-purpose instruction set. +Focused agents carry less instruction overhead than a general-purpose instruction set. They also give you a stable control surface: the same task profile can declare the tools it is allowed to use, the instructions it carries, and, where your Copilot surface supports it, the model it should use. For repeat coding workflows, prefer a focused custom agent over the default agent when you care about predictable cost. The default agent inherits more of the current environment: active tools, extension-provided surfaces, and whatever model is currently selected. + +Keep the tool list narrow. This repo's `agents/token-saver.agent.md` is the pattern: built-in `bash`, `edit`, and `view`; no duplicate filesystem MCP; terse output rules; explicit tool minimization. ### 4.3.6 Compress Shell Command Output with RTK @@ -290,12 +339,106 @@ rtk init --copilot # Restart VS Code ``` -RTK installs a PreToolUse hook into the current repository. Repeat per repo — there is no global VS Code Copilot install. Once active, the hook is transparent: your terminal is unchanged; only the agent's Bash tool calls are intercepted. +RTK installs a PreToolUse hook into the current repository. Newer RTK builds also document a global Copilot hook path; validate that path on your Copilot surface before making it a team default. Once active, the hook is transparent: your terminal is unchanged; only the agent's Bash tool calls are intercepted. + +On Windows, validate RTK before recommending it to a team. The hook path can be more fragile across PowerShell, Git Bash, WSL, and VS Code agent execution. If RTK adds setup friction or command failures, skip it and focus first on clean profiles, fewer MCP servers, precise prompts, and shorter command output. Commands with verbose output (test failures, large diffs) see the biggest reductions. Short-output commands see smaller gains. Actual savings depend on your project's output volume. Combine with `copilot-setup-steps.yml` (§4.3.2) and precise issue descriptions (§4.3.3) for maximum session efficiency. Full setup, command list, and other AI tool support: [MCP & Tool Costs §2.7.7](08-mcp-tool-costs.md#277-compress-tool-output-at-the-source-rtk). +### 4.3.7 Compress Shell Command Output with snip + +[`snip`](https://github.com/edouard-claude/snip) is the closest practical alternative to RTK for Copilot-oriented shell-output compression. It runs commands normally, filters the output through declarative YAML pipelines, and can track local savings with `snip gain`. + +Install: + +```bash +brew install edouard-claude/tap/snip +# or: +go install github.com/edouard-claude/snip/cmd/snip@latest +``` + +Set up Copilot CLI: + +```bash +snip init --agent copilot +``` + +Use snip when you want project-specific or team-maintained filters without recompiling a tool. A filter can match a command/subcommand and apply actions like `head`, `tail`, `keep_lines`, `remove_lines`, `json_extract`, `regex_extract`, `group_by`, `dedup`, or `aggregate`. + +Example filter shape: + +```yaml +name: "my-test-summary" +match: + command: "my-test-runner" +pipeline: + - action: "keep_lines" + pattern: "FAIL|ERROR|expected|actual" + - action: "head" + n: 80 +``` + +**Team rollout:** start with one repo and one shell surface. Validate that failed tests, diffs, and build errors still preserve enough detail for the agent to fix the problem. Do not enable RTK and snip on the same command path by default; choose one filter layer and measure. + +### 4.3.8 Build a Persistent Knowledge Graph with Graphify + +RTK and snip compress what shell commands return. [Graphify](https://github.com/Graphify-Labs/graphify) addresses a different cost: tokens spent reading project files to understand structure before the agent can act. + +Install once: + +```bash +uv tool install graphifyy +``` + +Build or update the graph in the repo: + +```bash +graphify . +``` + +Then query targeted structure: + +```text +graphify query "where is error handling for the API layer?" +graphify path "AuthService" "Database" +graphify explain "QueueWorker" +``` + +The graph lives in `graphify-out/graph.json`. The human-readable map is `graphify-out/GRAPH_REPORT.md`; the visual explorer is `graphify-out/graph.html`. + +**Biggest gains:** Coding Agent and agent-mode sessions on large repos where the first several steps are file reads for orientation. Graphify front-loads that structural scan once and amortizes it across later sessions. + +**Team choice:** decide whether to commit `graphify-out/graph.json` and `GRAPH_REPORT.md` so agents share the same map, or `.gitignore` `graphify-out/` and let each developer build locally. Do not commit graphs that expose sensitive source relationships if your repo policy treats them as restricted metadata. + +**Combine with:** + +- `copilot-setup-steps.yml` (§4.3.2) so the agent environment is deterministic before graph queries matter +- precise issue descriptions (§4.3.3) so the agent queries the right subgraph, not the whole repo map +- fresh execution sessions ([Outcome per Token](13-outcome-per-token.md)) so the graph supplements a short plan instead of a long transcript + +Note: code parsing is local for the AST pass. Optional semantic/deep extraction over docs, PDFs, images, or media may use a configured AI backend. Review that boundary before enabling extras on proprietary codebases. + +### 4.3.9 Use a Session Harness Checklist + +A "harness" is not a separate install here. It is the stable set of controls around an agent session: + +```text +model + reasoning effort + mode + agent/profile + loaded skills + active MCP/tools + output filter + repo instructions +``` + +Before a long agent run, set those once and keep them stable. Changing the model, reasoning effort, loaded skills, or other harness controls mid-session can invalidate cached prefixes and make the agent carry stale context under a new setup. + +Use this checklist: + +1. Pick the mode: Ask/Edit/Agent/Coding Agent. +2. Pick the model lane or Auto and reasoning effort. +3. Disable unused MCP servers, skills, and extension-provided tools. +4. Pick one command-output filter if needed: RTK or snip. +5. Use Graphify if repeated codebase orientation dominates. +6. Start a fresh session if you need to change the model, effort, skill, or harness. + ## 4.4 Building the Habit ### Start Small @@ -310,8 +453,10 @@ Combine with `copilot-setup-steps.yml` (§4.3.2) and precise issue descriptions - Review your `copilot-instructions.md` — has it grown? Compress it back down - Check if any memory files have gotten verbose — compress them back down - Audit which files are habitually open in your editor — close ones you're not working on (open tabs auto-feed context) +- Audit VS Code profiles and extensions — disable extensions that inject AI skills, agents, MCP servers, or tools unless the current repo needs them - (Business/Enterprise) Review repository / org **Content Exclusion** settings for new sensitive paths - Check your model usage — are you pinning high-effort models for tasks Auto would route to a cheaper tier? +- In Copilot CLI, watch the bottom-right **AIC** counter. Divide by 100 for the approximate dollar value, then ask whether the output saved more time or cost than it consumed. If spend is high for weak output, treat that as feedback on prompt scope, context size, tool count, or model choice - Review budgets, user-level caps, and model policies before expanding premium access further - When default model changes, retune prompts/instructions against that provider's current prompting guide - Check token usage by user/team — are agents and power users driving outsized consumption? See [Enterprise Governance](12-enterprise-governance.md) @@ -344,28 +489,7 @@ Each mode has a fundamentally different token cost profile: Understanding the loop helps you minimize steps: -```text -Step 1: Load context - ├── System prompt (~500 tokens) - ├── copilot-instructions.md (~50-1500 tokens) - ├── Tool definitions (~2,000-20,000 tokens) - ├── Conversation history (growing) - └── YOUR prompt - → Send to LLM → Get response - -Step 2: LLM decides to call a tool - ├── Tool call (function + params) → output tokens - ├── Tool result → input tokens (next step) - └── Reasoning about result → output tokens - -Step 3: Another tool call (or generate response) - ├── ALL of Step 1's context reloaded - ├── + Step 2's tool call and result - └── + growing conversation - → Send to LLM again - -... repeat 5-25 times -``` +![Agent mode cost loop: load context, choose a tool, ingest the tool result, replay prior context, and repeat until the task is complete.](assets/diagrams/agent-cost-loop.svg) **Key insight:** Context grows with every step. Step 15 carries all the context from steps 1-14 plus the original prompt. This is why long agent sessions get expensive fast. @@ -436,6 +560,8 @@ Relevant settings that affect agent token usage: **`maxRequests`** caps how many tool-call requests the agent can make. Lower = fewer tokens, but the agent might not finish complex tasks. Start at 10-15, increase only when needed. +For repeat workflows, pair this with a custom agent profile and a clean VS Code profile. Disable extensions that inject skills, agents, MCP servers, or tool surfaces you do not need for coding. The most predictable setup is boring: one focused agent, one intended model, and only the tools required for the repo. + ### 4.5.5 Custom Instructions for Agent Efficiency Add to `.github/copilot-instructions.md`: @@ -450,20 +576,7 @@ These directives reduce unnecessary tool calls. Each skipped tool call saves 100 ### 4.5.6 Decision Framework: When to Use Each Mode -```text -Question about code/syntax/concept? - → Ask Mode (1 call, ~500-2,000 tokens) - -Change to a single file? - → Edit Mode (1-2 calls, ~1,000-4,000 tokens) - -Multi-file change with clear scope? - → Agent Mode with precise prompt (~5-10 steps, ~15,000-50,000 tokens) - -Vague "fix this" or "improve that"? - → DON'T use Agent Mode yet. Clarify scope first in Ask Mode. - → Then switch to Agent with precise prompt. -``` +![Copilot mode decision tree: choose Ask, Edit, Agent, or clarify first based on whether code changes are needed and whether scope is clear.](assets/diagrams/mode-decision-tree.svg) **A costly pattern:** Using Agent Mode for a vague prompt, watching it explore for 20 steps, then realizing it misunderstood and starting over. That can double token use without improving the result. @@ -481,4 +594,4 @@ That chapter owns: --- -**Next:** [Enterprise Governance →](12-enterprise-governance.md) +**Next:** [Model Selection & Pricing →](11-models-and-pricing.md) diff --git a/docs/11-models-and-pricing.md b/docs/11-models-and-pricing.md index 811ba5c..06d5b64 100644 --- a/docs/11-models-and-pricing.md +++ b/docs/11-models-and-pricing.md @@ -122,11 +122,22 @@ This is especially relevant when comparing a cheap reasoning-capable model at `m ### Anti-patterns - Leaving an expensive premium model pinned for the whole session +- Changing models mid-chat in a long session without thinking about accumulated context. Prior messages, tool results, and cacheable prefixes can still be part of the next request; switching into a higher-cost lane can make that carried context more expensive than starting fresh +- Enabling/disabling MCP servers mid-thread in long sessions. Tool-surface changes often invalidate stable cached prefixes +- Switching default/custom agent profiles mid-thread during expensive runs. Agent/profile changes can break cache continuity for the same conversation - Assuming Auto will escalate to Opus when a task gets hard - Using vendor API prices and Copilot pricing signals as if they were the same metric - Recommending a model without checking whether the plan includes it - Turning on every premium model for the whole org before checking who actually needs it +**Cache-protection rule:** choose the lane before work starts and hold it stable in long sessions: + +```text +{ model, reasoning effort, loaded skills, active MCP/tool set, agent/profile } +``` + +If you must change the lane or harness (for example cheap/Auto to premium, `medium` to `high` reasoning effort, or a different skill/tool set), start a fresh chat with only the relevant summary and files. This preserves cache-friendly stability in the original session and avoids dragging long low-value history into a higher-cost request. The exact billing implementation can change by surface and plan, so treat cache loss as a risk to avoid rather than a guaranteed repricing calculation. + ## Org Rollout Rule: Review Before Enablement For teams, model choice is a governance problem as much as a prompt problem. diff --git a/docs/12-enterprise-governance.md b/docs/12-enterprise-governance.md index 06a1eb7..c7e10bf 100644 --- a/docs/12-enterprise-governance.md +++ b/docs/12-enterprise-governance.md @@ -16,6 +16,8 @@ Three levers matter most: Prompt compression still matters, but it is a usage-efficiency lever. It is not an admin billing control. +![Enterprise governance control plane: budgets, user-level budgets, and model access feed usage reports, cohorts, and review loops.](assets/diagrams/enterprise-governance-control-plane.svg) + One timing rule matters: June 1, 2026 is the cutoff. After that, Business and Enterprise governance shifts to AI-credit usage under usage-based billing. Treat premium requests as legacy transition context, not as the main planning model. ## 1. Set Budgets First @@ -30,6 +32,10 @@ Key points from GitHub docs for Business and Enterprise after June 1: That budget system is the direct spend cap for AI-credit usage at enterprise, organization, cost-center, and user scope. +If budget and cost-center segmentation becomes hard to manage by hand, look at [`amgdy/copilot-finops-automation`](https://github.com/amgdy/copilot-finops-automation). It treats Copilot FinOps as code: one version-controlled YAML config defines AI-credit spend policies and team-to-cost-center mappings, then GitHub Actions validates the config, previews changes with dry runs, applies budgets idempotently, syncs team membership into cost centers, and writes audit/current-state reports. + +Why admins should care: reviewed pull requests beat ad hoc console edits, dry runs reduce mutation risk, scheduled reconciliation catches drift, and cost-center or user-level budget materialization gives tighter segmentation for teams with different spend patterns. Use a private repo or private fork for live enterprise config; keep real enterprise slugs, teams, cost centers, user logins, budget numbers, reports, logs, and tokens out of public branches. + Important caveat: budgets do **not** make prompts smaller. They do **not** reduce tokens per prompt. They cap AI-credit spend. Practical default: @@ -53,6 +59,15 @@ Practical pattern: 2. power users get more only with clear job need 3. monthly review: downgrade users whose usage does not justify the extra cost +Build cohorts from actual spend, not guesswork: + +1. download historical Copilot billing or usage CSVs from GitHub +2. upload the CSV to [Copilot Billing Preview](https://copilot-billing-preview.github.com/) +3. inspect the usage bands it surfaces, such as power users, high-usage users, baseline users, and low-usage users +4. map those cohorts to different budget defaults, review cadence, and escalation paths + +Why this matters: admins should not give every developer the same AI-credit ceiling when the spend profile is visibly different. Cohorts let you keep broad access for normal users, protect budget for people doing real agent-heavy work, and catch inactive or low-value usage before it becomes a pooled-budget surprise. + Post-June 1 admin tips: 1. watch long chat and agent sessions because repeated turns now accumulate AI-credit cost directly @@ -136,18 +151,25 @@ Supplemental benchmarking can help when comparing model quality and price postur If you are preparing customers for the June 1 shift, do this first: 1. move admin guidance from request counters to AI-credit budgets -2. decide which users need tight user-level budgets and which teams can share a broader pooled budget -3. review model availability before frontier models become direct AI-credit spend -4. remind teams that code completions and next edit suggestions stay outside AI-credit billing -5. watch long chat and agent workflows first because they become the fastest spend amplifiers +2. build spend cohorts from historical CSVs before assigning user-level or pooled budgets +3. decide which users need tight user-level budgets and which teams can share a broader pooled budget +4. review model availability before frontier models become direct AI-credit spend +5. remind teams that code completions and next edit suggestions stay outside AI-credit billing +6. watch long chat and agent workflows first because they become the fastest spend amplifiers ## Recommended Enterprise Default 1. use Auto as the default model path 2. set budgets before broad rollout -3. use user-level AI credit budgets when you need tighter per-user control -4. review premium models before enablement -5. keep repo instructions small so IDE workflows inherit the right defaults -6. use separate org segmentation only if cost-center boundaries already support it +3. segment users into spend cohorts from historical CSVs, then tune budget defaults by cohort +4. use user-level AI credit budgets when you need tighter per-user control +5. consider FinOps-as-code automation when manual cost-center and budget edits become risky +6. review premium models before enablement +7. keep repo instructions small so IDE workflows inherit the right defaults +8. use separate org segmentation only if cost-center boundaries already support it This is boring on purpose. Cheap defaults first. Premium access by exception. Measurement before expansion. + +--- + +**Next:** [Outcome per Token →](13-outcome-per-token.md) diff --git a/docs/13-outcome-per-token.md b/docs/13-outcome-per-token.md new file mode 100644 index 0000000..4a8c28d --- /dev/null +++ b/docs/13-outcome-per-token.md @@ -0,0 +1,452 @@ +# Outcome per Token + +[← Back to Guide](index.md) + +--- + +Token optimization is not the real goal. The real goal is **more accepted work per token spent**: merged pull requests, closed bugs, passing tests, clean reviews, and fewer wrong-direction agent loops. + +Raw token minimization can even be the wrong move. A short prompt that causes the agent to guess, edit the wrong files, fail tests, and backtrack is more expensive than a longer plan that gets the first implementation right. + +## Why Outcome per Token Matters + +Usage-based billing makes tokens visible, but engineering teams do not buy tokens. They buy outcomes. + +Tomasz Tunguz describes this as the shift to intelligence per dollar: the application layer competes on the cost of a closed ticket, shipped PR, or resolved support case, not the cheapest raw token.[^tunguz] That maps directly to Copilot work. The useful metric is: + +```text +outcome per token = verified work completed / total tokens spent +``` + +For agentic coding, cost behaves differently than in simple chat. The Microsoft/Stanford paper "How Do AI Agents Spend Your Money?" reports that agentic coding tasks consume roughly **1,000×** more tokens than code chat, runs on the same task can vary by up to **30×**, and higher token usage does not reliably improve accuracy.[^agent-costs] + +### What the research shows + +| Finding | Why it matters | +|---|---| +| Agentic coding can consume roughly **1,000×** more tokens than code chat | Do not extrapolate chat-cost intuition to agent sessions | +| Same task can vary by up to **30×** across runs | Budget with margin; one run is not a stable cost estimate | +| Higher token usage does not reliably improve accuracy | More exploration is not automatically better work | +| Accuracy often peaks at intermediate cost and then saturates | Defaulting to the biggest model for every step can waste money | +| Input tokens dominate agentic cost | Context hygiene matters as much as output terseness | +| Models underestimate their own token use | Do not trust an agent's pre-task cost guess; use budgets and stop rules | +| Token efficiency varies by model independent of pass rate | Compare outcome and cost together, not benchmark score alone | + +The implication is simple: optimize the loop, not the sentence. + +## The Outcome-per-Token Loop + +High outcome per token comes from six habits: + +![Outcome-per-token loop: pick the task shape, plan before code, route the model, target context, verify evidence, and close cleanly.](assets/diagrams/outcome-per-token-loop.svg) + +1. pick the right task shape +2. plan before implementation +3. route the right model to the right phase +4. preserve clean context and cache boundaries +5. verify before claiming done + +Low outcome per token usually has the opposite shape: vague prompt, huge context, expensive model pinned too long, no acceptance criteria, agent edits before planning, tests run late, then a rework session starts from scratch. + +## Prompt Skills as Superpowers + +The community project [`obra/superpowers`](https://github.com/obra/superpowers) popularizes a useful framing: treat repeatable agent practices as skills, not one-off prompts.[^superpowers] It is not an official GitHub product, but its skill categories map well to Copilot cost control. + +This chapter uses that idea as a practical taxonomy. + +| Skill | What it does | Token effect | +|---|---|---| +| Brainstorming | Explore multiple approaches before choosing | Prevents early lock-in and wrong-direction code | +| Planning | Converts intent into file-level steps and checks | Reduces guessing during execution | +| Greenness | Keeps tests passing through the work | Avoids debugging unknown baseline failures | +| Verification before completion | Requires evidence before "done" | Prevents false completion and rework | +| Impeccable close | Finishes cleanly with criteria, tests, and PR summary aligned | Prevents review churn and follow-up agent sessions | +| Branch-close discipline | Ends branch/session cleanly after merge | Prevents stale context from leaking into next task | + +The skills below are patterns. The public libraries that follow are example implementations of those patterns, not mandatory dependencies. + +## Skill Libraries Worth Borrowing From + +Community skill libraries can improve outcome per token when they make the next agent action more precise: clearer requirements, safer tool use, better tests, cleaner handoff, or stronger final review. Treat them as reusable practice, not official GitHub or Microsoft guidance. Most claims are qualitative and experience-based; use them because they encode good workflow discipline, not because they prove a universal benchmark gain. + +| Library | Best borrowed skill | Use when | Caveat | +|---|---|---|---| +| [`obra/superpowers`](https://github.com/obra/superpowers) | TDD, planning, verification, branch finish | Need broad agent SDLC discipline | Community framework | +| [`softaworks/agent-toolkit`](https://github.com/softaworks/agent-toolkit) | Planning orchestration, handoff, entropy reduction | Complex features, long sessions, bloated instruction files | Personal toolkit; qualitative claims | +| [`catpilotai/catpilot-ai-guardrails`](https://github.com/catpilotai/catpilot-ai-guardrails) | Security and tool-loop guardrails | Agents touch secrets, cloud, DB, Docker, or supply chain | Guidance, not runtime enforcement | +| [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) | Snapshot, wait, and evidence discipline | Agents test browser UIs | Browser-specific; installed CLI content is authoritative | +| [`vercel-labs/writing-guidelines`](https://github.com/vercel-labs/writing-guidelines) | Plan-as-prompt, output review, AI-tell detection | Docs, PR descriptions, specs, generated prose | Editorial guidance, not measured token reduction | +| [`mattpocock/skills`](https://github.com/mattpocock/skills) | TDD, bug diagnosis, code review, domain modeling | Engineering tasks need sharper loops | Examples skew Claude and TypeScript workflows | +| [`PramodDutta/qaskills`](https://github.com/PramodDutta/qaskills) | QA and test-generation skills | Need Playwright, API, BDD, security, accessibility, or bug-report depth | Large skill files; early project | + +### Skill Library Star History + +[![Skill library Star History Chart](https://api.star-history.com/svg?repos=obra/superpowers,softaworks/agent-toolkit,catpilotai/catpilot-ai-guardrails,vercel-labs/agent-browser,vercel-labs/writing-guidelines,mattpocock/skills,PramodDutta/qaskills&type=timeline)](https://www.star-history.com/#obra/superpowers&softaworks/agent-toolkit&catpilotai/catpilot-ai-guardrails&vercel-labs/agent-browser&vercel-labs/writing-guidelines&mattpocock/skills&PramodDutta/qaskills&timeline) + +Star history is an adoption signal, not a quality benchmark. Use it to understand community attention, then judge each library by whether it changes the next agent action. + +### `obra/superpowers`: Baseline Agent SDLC Discipline + +Use Superpowers as the reference pattern: skills are small, named operating procedures. The value is not the brand name; the value is turning "be careful" into concrete moves the agent can follow.[^superpowers] + +- Borrow the TDD, planning, verification, and branch-finish habits. +- Convert team norms into small reusable prompts or skill files. +- Prefer skills that force evidence: test output, file-level plan, acceptance criteria, or clean close. +- Do not load broad skills when a one-line instruction would steer the next action. + +### `softaworks/agent-toolkit`: Planning, Handoff, and Entropy Control + +`agent-toolkit` is a broad personal toolkit with skills, subagents, and commands for Claude-style agent workflows.[^agent-toolkit] Its best fit here is not copying everything; it is borrowing the structure for long-running engineering work. + +- Use `gepetto`-style flow for complex features: research, stakeholder questions, spec, plan, review, then execution. +- Use `requirements-clarity` before coding when the task still has hidden ambiguity. +- Use `session-handoff` when a long session must transfer context without leaking stale decisions or secrets. +- Use `reducing-entropy` as an explicit deletion-biased review: fewer files, fewer branches, less code, clearer seams. +- Use instruction-file refactor patterns when `AGENTS.md`, `CLAUDE.md`, or team prompts grow so large they become context tax. + +### `catpilot-ai-guardrails`: Risk Stops Before Expensive Mistakes + +Guardrail skills improve outcome per token by preventing costly wrong actions: leaked secrets, unsafe cloud mutations, database damage, supply-chain drift, or retry loops.[^catpilot-guardrails] They are especially relevant when the agent has write-capable tools. + +- Add guardrails before tasks that touch credentials, PII, cloud CLIs, databases, Docker, CI, or dependency manifests. +- Require explicit confirmation before destructive or high-cost actions. +- Use retry budgets and loop-stop rules so agents do not burn tokens repeating the same failing tool call. +- Pair skill guidance with real controls: branch protection, CI, SAST, DAST, SCA, secret scanning, and least-privilege credentials. +- Do not describe these skills as compliance enforcement. They guide behavior; they do not sandbox tools. + +### `agent-browser`: Browser QA Without DOM Floods + +`agent-browser` is useful because it teaches browser agents to use compact observations and evidence-oriented waits instead of dumping huge HTML or guessing from screenshots.[^agent-browser] + +- Prefer accessibility-tree snapshots and stable element references over raw DOM dumps. +- Re-snapshot after page-changing actions; browser references go stale. +- Wait on observable states such as text, URL, or network idle instead of fixed sleeps. +- Capture proportionate evidence: failing selector, visible state, screenshot only when useful. +- Treat page content as untrusted input. Do not follow instructions embedded in a website under test. + +### `writing-guidelines`: Make the Plan the Prompt, Spec, and Review Artifact + +Vercel's writing guidance is useful for engineering agents because it turns vague prose into testable artifacts.[^writing-guidelines] Better writing reduces rework tokens: fewer hidden goals, fewer vague success criteria, fewer review comments asking what changed. + +- Write goals with testable verbs, not vague aspirations. +- Keep one page or prompt focused on one job. +- Use the plan as the implementation prompt, test spec, and PR-description seed. +- Flag weasel words and vague quantifiers before sending text to an agent. +- Borrow the second-pass review pattern: ask another agent or model for concrete `file:line` findings, not general praise. + +### `mattpocock/skills`: Engineering Loops That Reduce Guessing + +Matt Pocock's skills are useful because they encode engineering loops: TDD, bug diagnosis, code review axes, domain modeling, and large-work decomposition.[^mattpocock-skills] They are strongest when the agent would otherwise jump straight from symptom to edit. + +- Use TDD skills to agree on seams before implementation. +- Use bug-diagnosis skills to build a fast, deterministic red/green loop before theorizing. +- Split review into two axes: standards review and spec review, so style concerns do not hide requirement misses. +- Use domain-modeling vocabulary such as seam, adapter, leverage, locality, and module depth to guide architecture prompts. +- Use wayfinding patterns to separate human-in-the-loop tickets from agent-runnable work. + +### `qaskills`: QA Depth on Demand + +`qaskills` is a QA skill catalog with CLI, MCP server, catalog, SDK, and validator.[^qaskills] Its token value is specialization: load QA depth when the task is actually QA-heavy instead of asking a general agent to invent a test strategy from scratch. + +- Use Playwright skills for page-object discipline, accessibility-first selectors, fixtures, and anti-pattern checks. +- Use test-plan skills for risk matrices, traceability, equivalence partitioning, and entry/exit criteria. +- Use bug-report skills when the outcome is a reproducible issue with severity, priority, environment, and evidence. +- Use BDD/Cucumber skills when acceptance criteria should become executable Given/When/Then scenarios. +- Use OWASP, visual-regression, axe-core, k6, and API-testing skills only when those checks are part of the task. + +### Do Not Install Every Skill + +Skills are context too. Install only the ones that change the next agent action. + +| Task | Load | +|---|---| +| Test design, QA automation, bug reports | QA skills | +| Browser UI investigation | Browser snapshot/wait/evidence skills | +| Cloud, database, Docker, secrets, dependencies | Guardrail skills | +| Specs, docs, PR descriptions | Writing and review skills | +| Long sessions, complex features, handoff | Planning and handoff skills | + +If a skill is not likely to change the next edit, command, test, or review, leave it out. The best skill selection is still context selection. + +### Do Not Over-Optimize the Skill Stack + +Skill research can become its own token sink. Chasing the perfect library, the perfect subagent, or the "best of the best" workflow often produces no shipped work. The practical ceiling arrives early: a clear plan plus one hard challenge pass is already strong for most tasks. + +Use a simple `plan + grill-me` loop before adding more machinery: + +1. write the plan with acceptance criteria, likely files, risks, and verification command +2. ask a second pass to grill the plan: missing edge cases, wrong assumptions, cheaper path, and failure modes +3. revise once, then execute + +Add specialized skills only when they change the next action. If the task is not security-heavy, browser-heavy, QA-heavy, or handoff-heavy, more skill loading is probably context tax. + +### Brainstorming Skill + +Use this before the first edit when requirements are ambiguous. + +```text +Before coding, list three implementation approaches. +For each: files likely touched, risks, test strategy, and token/cost risk. +Do not edit files. +``` + +This spends a small number of reasoning tokens to avoid a much larger rework loop. + +### Planning Skill + +Planning turns "build X" into executable steps. + +Use the official VS Code [Plan agent](https://code.visualstudio.com/docs/agents/planning) when available. It can be selected from the agent dropdown or invoked with `/plan`, generates a high-level plan plus implementation and verification steps, and supports separate model settings for planning and implementation through `chat.planAgent.defaultModel` and `github.copilot.chat.implementAgent.model`.[^plan-agent] + +For GitHub.com tasks, Copilot cloud agent supports a research, plan, iterate flow: ask it to research the repo, iterate on a plan, then implement the agreed plan only when ready.[^cloud-plan] + +Important caveats: + +- VS Code Plan agent session memory is cleared when the conversation ends. Save important plans externally before closing the session.[^plan-agent] +- Copilot cloud agent planning and iteration before creating a PR are GitHub.com capabilities; integrations such as Azure Boards, JIRA, Linear, Slack, or Teams support direct PR creation only.[^cloud-agent] +- Cloud agent sessions have a 59-minute hard limit. Break large work into smaller tasks.[^cloud-agent] +- Business and Enterprise users need the relevant admin policy enabled before using cloud agent.[^cloud-agent] + +### Greenness Skill + +"Greenness" is this guide's label for a simple discipline: keep the test baseline green. + +Before asking an agent to modify code: + +1. know whether tests pass now +2. tell the agent the baseline +3. ask it to preserve that baseline +4. run tests before accepting completion + +If tests start red and the agent does not know that, it spends tokens debugging pre-existing failures. If tests go red during the task and the agent keeps editing, it compounds uncertainty. + +Green baseline first. Then change. + +### Verification-before-Completion Skill + +Do not accept "done" without evidence. + +```text +Before you report completion, run the targeted tests or build, +state the exact command, and confirm each acceptance criterion. +``` + +This costs a little at the end. It saves a lot when it prevents false completion, review churn, and a second agent session. + +### Impeccable Close Skill + +"Impeccable close" is this guide's label for closing the loop cleanly. The term is not an official Copilot concept; the practice is the important part. + +A good close includes: + +1. accepted criteria checked +2. tests/build run where relevant +3. no accidental scope creep +4. no stale TODOs or commented-out attempts +5. PR summary matches the actual diff +6. next step named only if one is truly needed + +This is outcome-per-token discipline. A sloppy close moves cost from implementation into review, follow-up prompts, and hotfixes. + +### Branch-Close Discipline + +After merge, close the branch and any long-running agent session. Do not keep using the same context for the next unrelated task. + +Stale sessions accumulate decisions, tool output, file reads, and abandoned approaches. Every later prompt may drag that history forward as input tokens. A clean close keeps the next task from paying for the previous one. + +## Plan First, Then Execute Cheaply + +The strongest pattern is two separate phases: + +![Plan first, execute cheaply: plan with a strong reasoning model, save acceptance criteria, execute in a fresh cheaper session, then verify or revise the plan.](assets/diagrams/plan-execute-cheaply.svg) + +GitHub's [Optimize AI Usage](https://docs.github.com/en/copilot/tutorials/optimize-ai-usage) guidance makes the same point: defaulting to the most capable model can increase token usage without improving the outcome, and overusing reasoning models in execution-heavy tasks can reduce quality by making the model overthink or introduce unnecessary changes.[^optimize-ai] The same page gives the practical rule: plan with a strong reasoning model, then implement with a cheaper model. + +Why fresh session matters: + +- the planning conversation does not get re-sent on every execution turn +- the execution context starts clean +- the plan becomes a stable, cache-friendly prefix +- model routing is deliberate instead of accidental + +This is the expanded version of [Plan First, Then Execute §2.5.9](06-workflow-optimization.md#259-plan-first-then-execute-and-route-the-phases). + +### Official Three-Tier Framework + +GitHub's official tutorial separates work into three model lanes.[^optimize-ai] + +| Tier | Best for | Outcome-per-token rule | +|---|---|---| +| Reasoning models | Architecture decisions, complex debugging, system design, deep analysis | Use for planning and hard judgment | +| Mid-tier models | Clear plans that need efficient implementation | Use for execution once ambiguity is removed | +| Lighter models | Refactoring, formatting, documentation, routine scoped changes | Use for bounded mechanical work | + +Do not pay for frontier reasoning after the hard thinking is already captured in the plan. + +## Day-to-Day Model Guidance + +Model advice changes quickly. Treat this table as routing guidance, not permanent truth. Check the official [supported models](https://docs.github.com/en/copilot/reference/ai-models/supported-models), [model comparison](https://docs.github.com/en/copilot/reference/ai-models/model-comparison), and [models and pricing](https://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing) pages before publishing customer-specific guidance.[^supported-models][^models-pricing] + +| Work | Good default | Tier | Typical input cost / 1M tokens | Why | +|---|---|---|---:|---| +| Quick lookup, syntax, tiny bounded edit | Auto, GPT-5.6 Luna, MAI-Code-1-Flash, Claude Haiku 4.5 | Lightweight | $0.75-$1.00 | Fast and low-cost enough for small tasks | +| Normal implementation after a clear plan | Auto, GPT-5.6 Terra, MAI-Code-1-Flash, Claude Sonnet 5 | Versatile / Lightweight | $0.75-$2.50 | Balanced execution without paying maximum reasoning cost | +| Agentic coding with moderate uncertainty | GPT-5.6 Terra, GPT-5.4 nano, Claude Sonnet 5 | Versatile / Lightweight | $0.20-$2.50 | Good lane when edits need tools but not frontier reasoning | +| Hard architecture, multi-file debugging, long-horizon planning | GPT-5.6 Sol, GPT-5.5, Claude Opus 4.7/4.8, Claude Fable 5 | Powerful | $5.00-$10.00 | Pay premium where reasoning quality changes the outcome | +| Open-weight / cost-conscious coding | Kimi K2.7 Code | Versatile | $0.95 | Useful option, but review enterprise policy and security requirements | +| Visual, multimodal, research-heavy work | Gemini 3.1 Pro (Public Preview), Claude Sonnet 5, GPT-5 mini where supported | Powerful / Versatile | $0.25-$2.00 | Pick for modality and research fit, not raw benchmark rank | +| Subagents for focused subtasks | Cheaper/lightweight model | Lightweight | varies | Subagents do not inherit the whole main conversation, so cheaper models often suffice | + +### Practical Defaults + +For most teams: + +1. **Auto first** for unknown everyday work. GitHub documents Auto as a task-aware router and gives paid plans a 10% AI credit discount when using it in supported surfaces.[^auto] +2. **Luna / MAI / Haiku** for tiny, bounded work. +3. **Terra / Sonnet / mid-tier** for normal implementation. +4. **Sol / GPT-5.5 / Opus / Fable** for planning, architecture, and hard debugging. +5. **Fresh session when changing lanes.** Switching models mid-session can invalidate cache and drag accumulated context into a more expensive request.[^optimize-ai] + +### Important Model Caveats + +- GPT-5.6 Sol is the powerful lane; do not leave it pinned for routine edits. +- Kimi K2.7 is an open-weight model in Copilot and may require admin opt-in for Business/Enterprise. Treat it as a policy decision, not just a price decision.[^kimi] +- MAI-Code-1-Flash is documented as a continuously improving model; behavior may evolve as checkpoints change.[^mai] +- Claude Sonnet 5 promotional pricing was documented through August 31, 2026. Recheck after that date before publishing pricing guidance.[^supported-models] +- Claude Fable 5 has a data-retention caveat in GitHub docs: Anthropic retains prompts and outputs to operate safety classifiers. Business/Enterprise admins should review terms before enabling it.[^supported-models] +- FedRAMP and EU DR (Data Residency) enforcement add a 10% AI credit surcharge, and available models can differ by region and compliance boundary.[^fedramp-eu-dr] +- Legacy annual subscribers may not receive access to new models and features such as GPT-5.6 family, Claude Fable 5, Claude Sonnet 5, or Kimi K2.7 under old billing.[^models-pricing] +- Extended capabilities such as 1M context and configurable reasoning are documented for VS Code and Copilot CLI only. Use regular context and regular reasoning by default.[^supported-models] +- Code completions and next edit suggestions are not billed in AI credits on paid plans. Do not treat every Copilot surface as the same cost bucket.[^usage-billing] + +## Benchmarks: Useful, Not Decisive + +Benchmarks help choose lanes. They do not replace measurement on your repo. + +| Benchmark | Measures | Why it matters | Caveat | +|---|---|---|---| +| [SWE-bench Verified](https://www.swebench.com/verified.html) | 500 human-verified Python GitHub issues | Classic software-engineering proxy | Python-heavy, static, possible contamination risk | +| [SWE-bench Pro](https://labs.scale.com/leaderboard/swe_bench_pro_public) | Harder professional repo tasks | Shows enterprise difficulty cliff | Scores depend on scaffold and current live leaderboard | +| [SWE-bench Live](https://swe-bench-live.github.io/) | Continuously updated issues | Reduces saturation and memorization | Dynamic scores shift over time | +| [DeepSWE](https://github.com/datacurve-ai/deep-swe) | 113 original long-horizon tasks across several languages | Good coding-agent and cost-per-task lens | Small task count; reasoning tier changes results | +| [Terminal-Bench](https://www.tbench.ai/) | Terminal and shell workflows | Maps to build/test/devops agent work | Small task count; terminal skill is not all coding skill | +| [Artificial Analysis](https://artificialanalysis.ai/methodology) | Intelligence, pricing, latency, provider comparison | Good cost/intelligence scatter plot | Composite scores may not match coding-only needs | + +### Score Snapshot + +| Benchmark | Model / condition | Score | Confidence | +|---|---|---:|---| +| SWE-bench Verified | Top models at SWE-bench Pro paper-era cross-reference | >70% | Verified from Scale AI Pro page | +| SWE-bench Pro public | GPT-5, paper-era | 23.3% | Verified | +| SWE-bench Pro public | Claude Opus 4.1, paper-era | 23.1% | Verified | +| SWE-bench Pro private | GPT-5, paper-era | 14.9% | Verified | +| Terminal-Bench 2.0 | Frontier models | <65% | Verified from benchmark abstract | +| DeepSWE | GPT-5.6 Sol `[max]` | 72.7% | Directional; third-party mirror and reasoning-tier dependent | +| DeepSWE | Top-three spread | <3.1 points | Directional; third-party mirror and reasoning-tier dependent | + +Use benchmark numbers with labels: + +- **Verified**: source directly read from primary leaderboard or paper. +- **Directional**: aggregator or secondary source. +- **Anecdotal**: Reddit, Discord, social media, single-session reports. + +The Reddit post that motivated this chapter is useful as a hypothesis generator: it highlights a real practitioner pattern around Pareto frontiers, DeepSWE cost-per-task, and GPT-5.6 tier routing. Do not treat its exact cost/task ladder as stable guide data unless rechecked against current DeepSWE, Artificial Analysis, and official Copilot pricing. + +## Why Harness Matters + +A model score is rarely just a model score. It includes: + +- agent scaffold +- tool access +- retrieval strategy +- reasoning effort +- cache pricing assumptions +- task language mix +- benchmark version +- whether the run is single-attempt or multi-attempt + +SWE-bench itself notes that versions using different action formats are not directly comparable. DeepSWE entries often include reasoning level in the model name, such as `[max]`. Artificial Analysis may answer a different question: broad intelligence per dollar, not pure coding-agent pass rate.[^swebench][^deepswe][^artificial-analysis] + +Use benchmarks to pick candidates. Use your own repo tasks to pick defaults. + +## A Practical Decision Checklist + +Before starting an expensive agent session: + +1. **Is the task actually agentic?** If not, use Ask mode or inline completion. +2. **Is the baseline green?** If not, fix or record it first. +3. **Is the plan written?** If not, plan first. +4. **Can execution run on a cheaper model?** If yes, do that in a fresh session. +5. **Is context targeted?** Attach only the plan and relevant files. +6. **Are acceptance criteria explicit?** If not, write them before execution. +7. **Is verification defined?** Name the test/build/check command up front. +8. **Will a model switch invalidate cache?** If yes, start fresh instead. +9. **Is the model policy allowed for this org/customer?** Check admin and compliance constraints. +10. **Will the close be clean?** Require test evidence and a concise summary. + +## What Not to Include Yet: Govify + +The name "Govify" appears to refer to multiple unrelated things: a local-government HR/recruiting SaaS, an old OpenGov Foundation PDF converter, and a cloud rewrite of that converter. Research found no verified connection to GitHub Copilot, token optimization, AI developer governance, or outcome-per-token workflows. + +Do not use Govify as a case study in this guide unless a primary source is provided. A weak mention would create confusion rather than value. + +## Cross-References + +- [Workflow Optimization §2.5.9](06-workflow-optimization.md#259-plan-first-then-execute-and-route-the-phases) — shorter version of the plan-first habit +- [Context Management](04-context-management.md) — cache and context hygiene +- [Output Control](05-output-control.md) — output token reduction +- [Practical Setup](10-practical-setup.md) — setup and operating habits +- [Model Selection & Pricing](11-models-and-pricing.md) — model and pricing surfaces +- [Enterprise Governance](12-enterprise-governance.md) — budgets, model policy, and admin rollout + +## References + +[^agent-costs]: Longju Bai et al., ["How Do AI Agents Spend Your Money? Analyzing and Predicting Token Consumption in Agentic Coding Tasks"](https://arxiv.org/abs/2604.22750), arXiv:2604.22750. + +[^tunguz]: Tomasz Tunguz, ["Intelligence Per Dollar"](https://tomtunguz.com/tokens-per-result). + +[^superpowers]: [`obra/superpowers`](https://github.com/obra/superpowers), community agentic-skills framework. + +[^agent-toolkit]: [`softaworks/agent-toolkit`](https://github.com/softaworks/agent-toolkit), community agent skill toolkit. + +[^catpilot-guardrails]: [`catpilotai/catpilot-ai-guardrails`](https://github.com/catpilotai/catpilot-ai-guardrails), community security guardrail skills. + +[^agent-browser]: [`vercel-labs/agent-browser` agent browser skill](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md). + +[^writing-guidelines]: [`vercel-labs/writing-guidelines`](https://github.com/vercel-labs/writing-guidelines), practitioner writing and review guidance. + +[^mattpocock-skills]: [`mattpocock/skills`](https://github.com/mattpocock/skills), community engineering skill collection. + +[^qaskills]: [`PramodDutta/qaskills`](https://github.com/PramodDutta/qaskills), QA skill catalog and tooling. + +[^plan-agent]: VS Code Docs, ["Planning with Copilot"](https://code.visualstudio.com/docs/agents/planning). + +[^cloud-plan]: GitHub Docs, ["Use Copilot agents: Research, plan, iterate"](https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents/research-plan-iterate). + +[^cloud-agent]: GitHub Docs, ["About Copilot cloud agent"](https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent). + +[^optimize-ai]: GitHub Docs, ["Optimize AI Usage"](https://docs.github.com/en/copilot/tutorials/optimize-ai-usage). + +[^supported-models]: GitHub Docs, ["Supported AI models in Copilot"](https://docs.github.com/en/copilot/reference/ai-models/supported-models) and ["Model comparison"](https://docs.github.com/en/copilot/reference/ai-models/model-comparison). + +[^models-pricing]: GitHub Docs, ["Models and Pricing"](https://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing). + +[^auto]: GitHub Docs, ["Auto model selection"](https://docs.github.com/en/copilot/concepts/models/auto-model-selection). + +[^kimi]: GitHub Changelog, ["Kimi K2.7 now available for Copilot Business and Enterprise"](https://github.blog/changelog/2026-07-07-kimi-k2-7-now-available-for-copilot-business-and-enterprise/). + +[^mai]: GitHub Changelog, ["MAI-Code-1-Flash is now available for GitHub Copilot"](https://github.blog/changelog/2026-06-02-mai-code-1-flash-is-now-available-for-github-copilot/). + +[^fedramp-eu-dr]: GitHub Docs, ["FedRAMP models"](https://docs.github.com/en/copilot/concepts/models/fedramp-models) and ["GitHub Copilot with data residency"](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/github-copilot-with-data-residency). + +[^usage-billing]: GitHub Docs, ["Usage-based billing for individuals"](https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-individuals). + +[^swebench]: [SWE-bench Verified](https://www.swebench.com/verified.html). + +[^deepswe]: [DeepSWE](https://github.com/datacurve-ai/deep-swe). + +[^artificial-analysis]: [Artificial Analysis methodology](https://artificialanalysis.ai/methodology). + +--- + +**Next:** [Back to Home →](index.md) diff --git a/docs/assets/diagrams/agent-cost-loop.png b/docs/assets/diagrams/agent-cost-loop.png new file mode 100644 index 0000000..adc4beb Binary files /dev/null and b/docs/assets/diagrams/agent-cost-loop.png differ diff --git a/docs/assets/diagrams/agent-cost-loop.svg b/docs/assets/diagrams/agent-cost-loop.svg new file mode 100644 index 0000000..d6c6fdc --- /dev/null +++ b/docs/assets/diagrams/agent-cost-loop.svg @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + +Agent mode cost loop +Every tool step replays more context than the previous one. + + + + + + +1. Load context +system + instructions ++ tools + history + +2. Model decides +which tool to call + +3. Tool result +becomes next input + +4. Replay all prior +context + result + +history + +5. Repeat +5-25 times if task is +broad +Avoided step = one full context reload saved. + \ No newline at end of file diff --git a/docs/assets/diagrams/cache-stability.png b/docs/assets/diagrams/cache-stability.png new file mode 100644 index 0000000..290e0b3 Binary files /dev/null and b/docs/assets/diagrams/cache-stability.png differ diff --git a/docs/assets/diagrams/cache-stability.svg b/docs/assets/diagrams/cache-stability.svg new file mode 100644 index 0000000..8b42282 --- /dev/null +++ b/docs/assets/diagrams/cache-stability.svg @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + +Cache stability +Keep the control surface fixed; switch lanes in a fresh session. + + + + + +Stable thread + +Turn 1 +same model + MCP + agent + +Turn 2 +cached prefix reused + +Turn 3 +only newest request changes +Cache-busted thread + +Turn 1 +model A + MCP set A + +Mid-thread switch +model/MCP/agent changes + +Turn 3 +prefix reprocessed + stale history + +Better: +handoff summary, +then fresh session + \ No newline at end of file diff --git a/docs/assets/diagrams/context-loading-boundaries.png b/docs/assets/diagrams/context-loading-boundaries.png new file mode 100644 index 0000000..02507ae Binary files /dev/null and b/docs/assets/diagrams/context-loading-boundaries.png differ diff --git a/docs/assets/diagrams/context-loading-boundaries.svg b/docs/assets/diagrams/context-loading-boundaries.svg new file mode 100644 index 0000000..2d7f557 --- /dev/null +++ b/docs/assets/diagrams/context-loading-boundaries.svg @@ -0,0 +1,40 @@ + + + + + + + + + + + + + +Context loading boundaries +Always-on is a tax; scoped and on-demand context loads only when useful. +prune +defer + +ALWAYS-ON +loaded every turn + +• repo instructions +• AGENTS.md/CLAUDE.md +• active MCP schemas + +SCOPED +loads by path + +.github/instructions/*.md + +applyTo: src/api/** + +ON-DEMAND +loads when invoked + +skills, checklists, +prompt snippets +Target shape: tiny core + narrow scoped slices + +occasional skills. + \ No newline at end of file diff --git a/docs/assets/diagrams/enterprise-governance-control-plane.png b/docs/assets/diagrams/enterprise-governance-control-plane.png new file mode 100644 index 0000000..fc25fe4 Binary files /dev/null and b/docs/assets/diagrams/enterprise-governance-control-plane.png differ diff --git a/docs/assets/diagrams/enterprise-governance-control-plane.svg b/docs/assets/diagrams/enterprise-governance-control-plane.svg new file mode 100644 index 0000000..fc33db0 --- /dev/null +++ b/docs/assets/diagrams/enterprise-governance-control-plane.svg @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +Enterprise governance control plane +Spend control is budgets + cohorts + model policy, not prompt compression alone. + + + + + + +monthly review loop + +Budgets +enterprise/org/cost +center +stop usage when needed + +User-level budgets +$0 blocks usage-based +features + +Model access policy +enable premium +narrowly + +Usage reports +billing CSVs +AI-credit consumption +agent workflow spend + +Spend cohorts +baseline / power users +review cadence + +Value justifies +spend? + +Expand, rollback, +or retune policy + \ No newline at end of file diff --git a/docs/assets/diagrams/format-tax-pipeline.png b/docs/assets/diagrams/format-tax-pipeline.png new file mode 100644 index 0000000..5fc35ed Binary files /dev/null and b/docs/assets/diagrams/format-tax-pipeline.png differ diff --git a/docs/assets/diagrams/format-tax-pipeline.svg b/docs/assets/diagrams/format-tax-pipeline.svg new file mode 100644 index 0000000..a4b0051 --- /dev/null +++ b/docs/assets/diagrams/format-tax-pipeline.svg @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + + + + + + + + + +Format tax pipeline +Convert rich files to Markdown before they enter AI context. + + + + +working format + +DOCX / PDF / HTML +slides / media + +Format noise +fonts, XML, +layout, +positioning, tags + +MarkItDown +normalize +structure + +Clean Markdown +headings, +lists, +tables, links + +Pay for semantic +content, +not page decoration. + +Generate rich delivery +format +only at the end. + \ No newline at end of file diff --git a/docs/assets/diagrams/graphify-navigation.png b/docs/assets/diagrams/graphify-navigation.png new file mode 100644 index 0000000..6d46276 Binary files /dev/null and b/docs/assets/diagrams/graphify-navigation.png differ diff --git a/docs/assets/diagrams/graphify-navigation.svg b/docs/assets/diagrams/graphify-navigation.svg new file mode 100644 index 0000000..c430a08 --- /dev/null +++ b/docs/assets/diagrams/graphify-navigation.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + +Persistent graph navigation +Front-load codebase orientation once; query the map across sessions. + + + + + + +Repo files +code + docs + +Graphify build +AST + optional +semantic extraction + +graphify- +out/graph.json +shared map + +query +where is auth? + +path +Router → DB + +explain +QueueWorker +Agents stop rereading broad file sets for the same +orientation questions. + \ No newline at end of file diff --git a/docs/assets/diagrams/mcp-tooling-stack.png b/docs/assets/diagrams/mcp-tooling-stack.png new file mode 100644 index 0000000..b3c4ba5 Binary files /dev/null and b/docs/assets/diagrams/mcp-tooling-stack.png differ diff --git a/docs/assets/diagrams/mcp-tooling-stack.svg b/docs/assets/diagrams/mcp-tooling-stack.svg new file mode 100644 index 0000000..94d067a --- /dev/null +++ b/docs/assets/diagrams/mcp-tooling-stack.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + +MCP and tooling stack +Reduce schema cost, turn count, command output, and repeated orientation separately. + + + +Graphify +Coach / chronicle + +Tool schemas +MCP servers, extensions + +Turn loop +model ↔ tool ↔ model + +Command output +tests, git, grep, build + +Orientation reads +same files every session + +Visibility/audit +measure what loads + +Fix: scope MCPs +prefer built-ins + +Fix: CodeAct +for long tool chains + +Fix: RTK or snip +one filter layer + \ No newline at end of file diff --git a/docs/assets/diagrams/mode-decision-tree.png b/docs/assets/diagrams/mode-decision-tree.png new file mode 100644 index 0000000..71266d2 Binary files /dev/null and b/docs/assets/diagrams/mode-decision-tree.png differ diff --git a/docs/assets/diagrams/mode-decision-tree.svg b/docs/assets/diagrams/mode-decision-tree.svg new file mode 100644 index 0000000..822b170 --- /dev/null +++ b/docs/assets/diagrams/mode-decision-tree.svg @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +Copilot mode decision tree +Pick the smallest mode that can finish the job. +no +yes +no +yes +no/vague +yes + +Need code changes? + +ASK +questions + +explanations + +Single file +clear target? + +Multi-file +clear scope? + +EDIT +1-2 calls +targeted change + +CLARIFY FIRST +plan / ask mode +then execute + +AGENT +5-25 steps +multi-file work + \ No newline at end of file diff --git a/docs/assets/diagrams/outcome-per-token-loop.png b/docs/assets/diagrams/outcome-per-token-loop.png new file mode 100644 index 0000000..d5074d8 Binary files /dev/null and b/docs/assets/diagrams/outcome-per-token-loop.png differ diff --git a/docs/assets/diagrams/outcome-per-token-loop.svg b/docs/assets/diagrams/outcome-per-token-loop.svg new file mode 100644 index 0000000..7a5ecb5 --- /dev/null +++ b/docs/assets/diagrams/outcome-per-token-loop.svg @@ -0,0 +1,47 @@ + + + + + + + + + + + + + + + + + + + + + + +Outcome-per-token loop +The goal is fewer wrong turns, not merely fewer words. + + + + + + + +Pick task shape + +Plan before code + +Route model by +phase + +Target context + +Verify evidence + +Close cleanly + +High outcome +per token + \ No newline at end of file diff --git a/docs/assets/diagrams/plan-execute-cheaply.png b/docs/assets/diagrams/plan-execute-cheaply.png new file mode 100644 index 0000000..61366c4 Binary files /dev/null and b/docs/assets/diagrams/plan-execute-cheaply.png differ diff --git a/docs/assets/diagrams/plan-execute-cheaply.svg b/docs/assets/diagrams/plan-execute-cheaply.svg new file mode 100644 index 0000000..4383ae4 --- /dev/null +++ b/docs/assets/diagrams/plan-execute-cheaply.svg @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + +Plan first, execute cheaply +Spend premium reasoning before code; run mechanical execution in a clean lane. +capture +fresh session + +yes +no + +PHASE 1: PLAN +strong reasoning +model +Ask / Plan / +research + +Saved plan +steps +acceptance criteria +verification +command + +PHASE 2: EXECUTE +fresh session +cheaper/mid model + +Acceptance +criteria met? + +Verified +implementation + +Revise plan +before more code + \ No newline at end of file diff --git a/docs/assets/diagrams/prompt-compression-ladder.png b/docs/assets/diagrams/prompt-compression-ladder.png new file mode 100644 index 0000000..7ff8c44 Binary files /dev/null and b/docs/assets/diagrams/prompt-compression-ladder.png differ diff --git a/docs/assets/diagrams/prompt-compression-ladder.svg b/docs/assets/diagrams/prompt-compression-ladder.svg new file mode 100644 index 0000000..482d16c --- /dev/null +++ b/docs/assets/diagrams/prompt-compression-ladder.svg @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + + + + + + + + +Prompt compression ladder +Drop filler, keep technical substance exact. + + + +remove +preserve +clarify + +Verbose +"Could you please help +me refactor..." + +Lite +remove filler + +Full +fragments OK + +Ultra +arrows + abbrev + +Articles +pleasantries +hedging + +Technical terms +file names +code unchanged + +Scope +acceptance criteria +exact constraints +Visual rule: compression is a funnel, not a shredder. +Meaning must survive. + \ No newline at end of file diff --git a/docs/assets/diagrams/token-cost-anatomy.png b/docs/assets/diagrams/token-cost-anatomy.png new file mode 100644 index 0000000..20cc98b Binary files /dev/null and b/docs/assets/diagrams/token-cost-anatomy.png differ diff --git a/docs/assets/diagrams/token-cost-anatomy.svg b/docs/assets/diagrams/token-cost-anatomy.svg new file mode 100644 index 0000000..014b233 --- /dev/null +++ b/docs/assets/diagrams/token-cost-anatomy.svg @@ -0,0 +1,43 @@ + + + + + + + + + + + + + +Token cost anatomy +Most input is hidden context; output is small but premium-priced. + + + + + +INPUT TOKENS + +System prompt + repo instructions + +File context + open tabs + imports + +Conversation history grows every turn + +MCP/tool schemas: loaded per step + +Your typed prompt + +OUTPUT TOKENS +visible answer +5x pricing +intuition + +CACHED TOKENS +stable prefix gets +cheaper +Optimize first: +constrain responses + \ No newline at end of file diff --git a/docs/diagrams/agent-cost-loop.excalidraw b/docs/diagrams/agent-cost-loop.excalidraw new file mode 100644 index 0000000..4614db6 --- /dev/null +++ b/docs/diagrams/agent-cost-loop.excalidraw @@ -0,0 +1,689 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Agent mode cost loop", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Agent mode cost loop", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Every tool step replays more context than the previous one.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Every tool step replays more context than the previous one.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 460, + "y": 265, + "width": 100, + "height": -50, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 55, + 0 + ], + [ + 55, + -50 + ], + [ + 100, + -50 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 880, + "y": 215, + "width": 100, + "height": 50, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 55, + 0 + ], + [ + 55, + 50 + ], + [ + 100, + 50 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 1145, + "y": 325, + "width": -40, + "height": 240, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 135, + 0 + ], + [ + 135, + 240 + ], + [ + -40, + 240 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 770, + "y": 565, + "width": -100, + "height": 0, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -100, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 350, + "y": 545, + "width": -200, + "height": -260, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -230, + 0 + ], + [ + -230, + -260 + ], + [ + -200, + -260 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 150, + "y": 205, + "width": 310, + "height": 120, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 150, + "y": 226.57, + "width": 310, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "1. Load context\nsystem + instructions\n+ tools + history", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "1. Load context\nsystem + instructions\n+ tools + history", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 570, + "y": 155, + "width": 310, + "height": 120, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 570, + "y": 189.38, + "width": 310, + "height": 52.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "2. Model decides\nwhich tool to call", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "2. Model decides\nwhich tool to call", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 990, + "y": 205, + "width": 310, + "height": 120, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 990, + "y": 239.38, + "width": 310, + "height": 52.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "3. Tool result\nbecomes next input", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "3. Tool result\nbecomes next input", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 780, + "y": 500, + "width": 310, + "height": 125, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 780, + "y": 524.07, + "width": 310, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "4. Replay all prior\ncontext + result +\nhistory", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "4. Replay all prior\ncontext + result +\nhistory", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 350, + "y": 500, + "width": 310, + "height": 125, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 350, + "y": 524.07, + "width": 310, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "5. Repeat\n5-25 times if task is\nbroad", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "5. Repeat\n5-25 times if task is\nbroad", + "lineHeight": 1.22 + }, + { + "id": "txt_105", + "type": "text", + "x": 220, + "y": 708.7, + "width": 1010, + "height": 37.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1105, + "version": 1, + "versionNonce": 2105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Avoided step = one full context reload saved.", + "fontSize": 30, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Avoided step = one full context reload saved.", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/cache-stability.excalidraw b/docs/diagrams/cache-stability.excalidraw new file mode 100644 index 0000000..1a8548d --- /dev/null +++ b/docs/diagrams/cache-stability.excalidraw @@ -0,0 +1,828 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Cache stability", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Cache stability", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Keep the control surface fixed; switch lanes in a fresh session.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Keep the control surface fixed; switch lanes in a fresh session.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 350, + "y": 310, + "width": 0, + "height": 40, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 40 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 350, + "y": 440, + "width": 0, + "height": 40, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 40 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 1065, + "y": 310, + "width": 0, + "height": 40, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 40 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 1065, + "y": 440, + "width": 0, + "height": 40, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 40 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 1065, + "y": 570, + "width": -340, + "height": 55, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 20 + ], + [ + -340, + 20 + ], + [ + -340, + 55 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_100", + "type": "text", + "x": 150, + "y": 155.7, + "width": 500, + "height": 37.5, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1100, + "version": 1, + "versionNonce": 2100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Stable thread", + "fontSize": 30, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Stable thread", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 90, + "y": 220, + "width": 520, + "height": 90, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 90, + "y": 238.16, + "width": 520, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Turn 1\nsame model + MCP + agent", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Turn 1\nsame model + MCP + agent", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 90, + "y": 350, + "width": 520, + "height": 90, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 90, + "y": 368.16, + "width": 520, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Turn 2\ncached prefix reused", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Turn 2\ncached prefix reused", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 90, + "y": 480, + "width": 520, + "height": 90, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 90, + "y": 498.16, + "width": 520, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Turn 3\nonly newest request changes", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Turn 3\nonly newest request changes", + "lineHeight": 1.22 + }, + { + "id": "txt_104", + "type": "text", + "x": 870, + "y": 155.7, + "width": 500, + "height": 37.5, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1104, + "version": 1, + "versionNonce": 2104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Cache-busted thread", + "fontSize": 30, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Cache-busted thread", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 805, + "y": 220, + "width": 520, + "height": 90, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 805, + "y": 238.16, + "width": 520, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Turn 1\nmodel A + MCP set A", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Turn 1\nmodel A + MCP set A", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 805, + "y": 350, + "width": 520, + "height": 90, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 805, + "y": 368.16, + "width": 520, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Mid-thread switch\nmodel/MCP/agent changes", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Mid-thread switch\nmodel/MCP/agent changes", + "lineHeight": 1.22 + }, + { + "id": "shape_107", + "type": "rectangle", + "x": 805, + "y": 480, + "width": 520, + "height": 90, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3107, + "version": 1, + "versionNonce": 4107, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_607", + "type": "text", + "x": 805, + "y": 498.16, + "width": 520, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1607, + "version": 1, + "versionNonce": 2607, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Turn 3\nprefix reprocessed + stale history", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Turn 3\nprefix reprocessed + stale history", + "lineHeight": 1.22 + }, + { + "id": "shape_108", + "type": "rectangle", + "x": 500, + "y": 625, + "width": 450, + "height": 105, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3108, + "version": 1, + "versionNonce": 4108, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_608", + "type": "text", + "x": 500, + "y": 633.58, + "width": 450, + "height": 90.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1608, + "version": 1, + "versionNonce": 2608, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Better:\nhandoff summary,\nthen fresh session", + "fontSize": 24, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Better:\nhandoff summary,\nthen fresh session", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/context-loading-boundaries.excalidraw b/docs/diagrams/context-loading-boundaries.excalidraw new file mode 100644 index 0000000..efc67b3 --- /dev/null +++ b/docs/diagrams/context-loading-boundaries.excalidraw @@ -0,0 +1,467 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Context loading boundaries", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Context loading boundaries", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Always-on is a tax; scoped and on-demand context loads only when useful.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Always-on is a tax; scoped and on-demand context loads only when useful.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 440, + "y": 415, + "width": 60, + "height": 0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 60, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_710", + "type": "text", + "x": 385.0, + "y": 386.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1710, + "version": 1, + "versionNonce": 2710, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "prune", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "prune", + "lineHeight": 1.22 + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 910, + "y": 415, + "width": 60, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 60, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_711", + "type": "text", + "x": 855.0, + "y": 386.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1711, + "version": 1, + "versionNonce": 2711, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "defer", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "defer", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 80, + "y": 175, + "width": 360, + "height": 480, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 80, + "y": 327.15999999999997, + "width": 360, + "height": 180.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "ALWAYS-ON\nloaded every turn\n\n\u2022 repo instructions\n\u2022 AGENTS.md/CLAUDE.md\n\u2022 active MCP schemas", + "fontSize": 24, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "ALWAYS-ON\nloaded every turn\n\n\u2022 repo instructions\n\u2022 AGENTS.md/CLAUDE.md\n\u2022 active MCP schemas", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 500, + "y": 220, + "width": 410, + "height": 380, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 500, + "y": 333.14, + "width": 410, + "height": 157.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "SCOPED\nloads by path\n\n.github/instructions/*.md\n\napplyTo: src/api/**", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "SCOPED\nloads by path\n\n.github/instructions/*.md\n\napplyTo: src/api/**", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 970, + "y": 285, + "width": 320, + "height": 250, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 970, + "y": 339.85, + "width": 320, + "height": 143.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "ON-DEMAND\nloads when invoked\n\nskills, checklists,\nprompt snippets", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "ON-DEMAND\nloads when invoked\n\nskills, checklists,\nprompt snippets", + "lineHeight": 1.22 + }, + { + "id": "txt_103", + "type": "text", + "x": 150, + "y": 680.62, + "width": 1100, + "height": 72.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1103, + "version": 1, + "versionNonce": 2103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Target shape: tiny core + narrow scoped slices +\noccasional skills.", + "fontSize": 29, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Target shape: tiny core + narrow scoped slices +\noccasional skills.", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/enterprise-governance-control-plane.excalidraw b/docs/diagrams/enterprise-governance-control-plane.excalidraw new file mode 100644 index 0000000..41701ee --- /dev/null +++ b/docs/diagrams/enterprise-governance-control-plane.excalidraw @@ -0,0 +1,879 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1392, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Enterprise governance control plane", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Enterprise governance control plane", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1392, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Spend control is budgets + cohorts + model policy, not prompt compression alone.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Spend control is budgets + cohorts + model policy, not prompt compression alone.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 390, + "y": 242, + "width": 185, + "height": 88, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 185, + 88 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 390, + "y": 422, + "width": 185, + "height": -62, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 185, + -62 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 390, + "y": 602, + "width": 185, + "height": -207, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 185, + -207 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 925, + "y": 360, + "width": 145, + "height": -118, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 145, + -118 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 1225, + "y": 300, + "width": 0, + "height": 105, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 105 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_15", + "type": "arrow", + "x": 1225, + "y": 540, + "width": 0, + "height": 75, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5015, + "version": 1, + "versionNonce": 6015, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 75 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_16", + "type": "arrow", + "x": 1070, + "y": 660, + "width": -835, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5016, + "version": 1, + "versionNonce": 6016, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -70, + 110 + ], + [ + -835, + 110 + ], + [ + -835, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_716", + "type": "text", + "x": 567.5, + "y": 621.48, + "width": 170, + "height": 40.0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1716, + "version": 1, + "versionNonce": 2716, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "monthly review\nloop", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "monthly review\nloop", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 80, + "y": 185, + "width": 310, + "height": 115, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 80, + "y": 193.7, + "width": 310, + "height": 100.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Budgets\nenterprise/org/cost\ncenter\nstop usage when needed", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Budgets\nenterprise/org/cost\ncenter\nstop usage when needed", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 80, + "y": 365, + "width": 310, + "height": 115, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 80, + "y": 385.9, + "width": 310, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "User-level budgets\n$0 blocks usage-based\nfeatures", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "User-level budgets\n$0 blocks usage-based\nfeatures", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 80, + "y": 545, + "width": 310, + "height": 115, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 80, + "y": 565.9, + "width": 310, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Model access policy\nenable premium\nnarrowly", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Model access policy\nenable premium\nnarrowly", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 575, + "y": 275, + "width": 350, + "height": 170, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 575, + "y": 303.88, + "width": 350, + "height": 115.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Usage reports\nbilling CSVs\nAI-credit consumption\nagent workflow spend", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Usage reports\nbilling CSVs\nAI-credit consumption\nagent workflow spend", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 1070, + "y": 185, + "width": 310, + "height": 115, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 1070, + "y": 205.9, + "width": 310, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Spend cohorts\nbaseline / power users\nreview cadence", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Spend cohorts\nbaseline / power users\nreview cadence", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "diamond", + "x": 1085, + "y": 405, + "width": 280, + "height": 135, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 1085, + "y": 446.88, + "width": 280, + "height": 52.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Value justifies\nspend?", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Value justifies\nspend?", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 1070, + "y": 615, + "width": 310, + "height": 90, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 1070, + "y": 634.38, + "width": 310, + "height": 52.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Expand, rollback,\nor retune policy", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Expand, rollback,\nor retune policy", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/format-tax-pipeline.excalidraw b/docs/diagrams/format-tax-pipeline.excalidraw new file mode 100644 index 0000000..7c98a53 --- /dev/null +++ b/docs/diagrams/format-tax-pipeline.excalidraw @@ -0,0 +1,725 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Format tax pipeline", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Format tax pipeline", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Convert rich files to Markdown before they enter AI context.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Convert rich files to Markdown before they enter AI context.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 340, + "y": 280, + "width": 85, + "height": 0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 85, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 705, + "y": 280, + "width": 95, + "height": 0, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 95, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 1050, + "y": 280, + "width": 90, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 90, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 1255, + "y": 340, + "width": -245, + "height": 160, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 5, + 130 + ], + [ + -245, + 160 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 565, + "y": 545, + "width": 325, + "height": 0, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 325, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_714", + "type": "text", + "x": 642.5, + "y": 516.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1714, + "version": 1, + "versionNonce": 2714, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "working format", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "working format", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 80, + "y": 220, + "width": 260, + "height": 120, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 80, + "y": 253.16, + "width": 260, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "DOCX / PDF / HTML\nslides / media", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "DOCX / PDF / HTML\nslides / media", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 425, + "y": 190, + "width": 280, + "height": 180, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 425, + "y": 226.32, + "width": 280, + "height": 110.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Format noise\nfonts, XML,\nlayout,\npositioning, tags", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Format noise\nfonts, XML,\nlayout,\npositioning, tags", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 800, + "y": 205, + "width": 250, + "height": 150, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 800, + "y": 239.74, + "width": 250, + "height": 82.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "MarkItDown\nnormalize\nstructure", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "MarkItDown\nnormalize\nstructure", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 1140, + "y": 220, + "width": 230, + "height": 120, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 1140, + "y": 226.32, + "width": 230, + "height": 110.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Clean Markdown\nheadings,\nlists,\ntables, links", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Clean Markdown\nheadings,\nlists,\ntables, links", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 225, + "y": 500, + "width": 340, + "height": 90, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 225, + "y": 506.57, + "width": 340, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Pay for semantic\ncontent,\nnot page decoration.", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Pay for semantic\ncontent,\nnot page decoration.", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 890, + "y": 500, + "width": 320, + "height": 90, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 890, + "y": 506.57, + "width": 320, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Generate rich delivery\nformat\nonly at the end.", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Generate rich delivery\nformat\nonly at the end.", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/graphify-navigation.excalidraw b/docs/diagrams/graphify-navigation.excalidraw new file mode 100644 index 0000000..0e8e697 --- /dev/null +++ b/docs/diagrams/graphify-navigation.excalidraw @@ -0,0 +1,721 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Persistent graph navigation", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Persistent graph navigation", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Front-load codebase orientation once; query the map across sessions.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Front-load codebase orientation once; query the map across sessions.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 340, + "y": 300, + "width": 95, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 95, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 735, + "y": 300, + "width": 95, + "height": 0, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 95, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 1090, + "y": 300, + "width": 90, + "height": -100, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 90, + -100 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 1090, + "y": 300, + "width": 90, + "height": 25, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 90, + 25 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 1090, + "y": 300, + "width": 90, + "height": 150, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 90, + 150 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 70, + "y": 245, + "width": 270, + "height": 110, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 70, + "y": 273.16, + "width": 270, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Repo files\ncode + docs", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Repo files\ncode + docs", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 435, + "y": 205, + "width": 300, + "height": 190, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 435, + "y": 257.91, + "width": 300, + "height": 86.25, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Graphify build\nAST + optional\nsemantic extraction", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Graphify build\nAST + optional\nsemantic extraction", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 830, + "y": 240, + "width": 260, + "height": 120, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 830, + "y": 259.74, + "width": 260, + "height": 82.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "graphify-\nout/graph.json\nshared map", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "graphify-\nout/graph.json\nshared map", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 1180, + "y": 160, + "width": 210, + "height": 80, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 1180, + "y": 175.6, + "width": 210, + "height": 50.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "query\nwhere is auth?", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "query\nwhere is auth?", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 1180, + "y": 285, + "width": 210, + "height": 80, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 1180, + "y": 300.6, + "width": 210, + "height": 50.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "path\nRouter \u2192 DB", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "path\nRouter \u2192 DB", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 1180, + "y": 410, + "width": 210, + "height": 80, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 1180, + "y": 425.6, + "width": 210, + "height": 50.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "explain\nQueueWorker", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "explain\nQueueWorker", + "lineHeight": 1.22 + }, + { + "id": "txt_106", + "type": "text", + "x": 230, + "y": 582.06, + "width": 970, + "height": 67.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1106, + "version": 1, + "versionNonce": 2106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Agents stop rereading broad file sets for the same\norientation questions.", + "fontSize": 27, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Agents stop rereading broad file sets for the same\norientation questions.", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/mcp-tooling-stack.excalidraw b/docs/diagrams/mcp-tooling-stack.excalidraw new file mode 100644 index 0000000..279f6b7 --- /dev/null +++ b/docs/diagrams/mcp-tooling-stack.excalidraw @@ -0,0 +1,916 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1392, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "MCP and tooling stack", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "MCP and tooling stack", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1392, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Reduce schema cost, turn count, command output, and repeated orientation separately.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Reduce schema cost, turn count, command output, and repeated orientation separately.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 290, + "y": 280, + "width": 0, + "height": 370, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -140, + 0 + ], + [ + -140, + 370 + ], + [ + 0, + 370 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 750, + "y": 280, + "width": 0, + "height": 370, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 370 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 1210, + "y": 280, + "width": 0, + "height": 370, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 150, + 0 + ], + [ + 150, + 370 + ], + [ + 0, + 370 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 445, + "y": 510, + "width": 165, + "height": 140, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 65 + ], + [ + 165, + 65 + ], + [ + 165, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_713", + "type": "text", + "x": 442.5, + "y": 551.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1713, + "version": 1, + "versionNonce": 2713, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Graphify", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Graphify", + "lineHeight": 1.22 + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 1060, + "y": 510, + "width": -170, + "height": 140, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 65 + ], + [ + -170, + 65 + ], + [ + -170, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_714", + "type": "text", + "x": 890.0, + "y": 541.48, + "width": 170, + "height": 40.0, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1714, + "version": 1, + "versionNonce": 2714, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Coach /\nchronicle", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Coach /\nchronicle", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 95, + "y": 175, + "width": 390, + "height": 105, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 95, + "y": 199.44, + "width": 390, + "height": 57.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Tool schemas\nMCP servers, extensions", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Tool schemas\nMCP servers, extensions", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 555, + "y": 175, + "width": 390, + "height": 105, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 555, + "y": 199.44, + "width": 390, + "height": 57.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Turn loop\nmodel \u2194 tool \u2194 model", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Turn loop\nmodel \u2194 tool \u2194 model", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 1015, + "y": 175, + "width": 390, + "height": 105, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 1015, + "y": 199.44, + "width": 390, + "height": 57.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Command output\ntests, git, grep, build", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Command output\ntests, git, grep, build", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 250, + "y": 405, + "width": 390, + "height": 105, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 250, + "y": 429.44, + "width": 390, + "height": 57.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Orientation reads\nsame files every session", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Orientation reads\nsame files every session", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 865, + "y": 405, + "width": 390, + "height": 105, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 865, + "y": 429.44, + "width": 390, + "height": 57.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Visibility/audit\nmeasure what loads", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Visibility/audit\nmeasure what loads", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 95, + "y": 650, + "width": 390, + "height": 80, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 95, + "y": 663.16, + "width": 390, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Fix: scope MCPs\nprefer built-ins", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Fix: scope MCPs\nprefer built-ins", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 555, + "y": 650, + "width": 390, + "height": 80, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 555, + "y": 663.16, + "width": 390, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Fix: CodeAct\nfor long tool chains", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Fix: CodeAct\nfor long tool chains", + "lineHeight": 1.22 + }, + { + "id": "shape_107", + "type": "rectangle", + "x": 1015, + "y": 650, + "width": 390, + "height": 80, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3107, + "version": 1, + "versionNonce": 4107, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_607", + "type": "text", + "x": 1015, + "y": 663.16, + "width": 390, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1607, + "version": 1, + "versionNonce": 2607, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Fix: RTK or snip\none filter layer", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Fix: RTK or snip\none filter layer", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/mode-decision-tree.excalidraw b/docs/diagrams/mode-decision-tree.excalidraw new file mode 100644 index 0000000..140ceff --- /dev/null +++ b/docs/diagrams/mode-decision-tree.excalidraw @@ -0,0 +1,1022 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Copilot mode decision tree", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Copilot mode decision tree", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Pick the smallest mode that can finish the job.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Pick the smallest mode that can finish the job.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 585, + "y": 205, + "width": -155, + "height": 0, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -155, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_710", + "type": "text", + "x": 422.5, + "y": 176.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1710, + "version": 1, + "versionNonce": 2710, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "no", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "no", + "lineHeight": 1.22 + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 725, + "y": 275, + "width": -210, + "height": 60, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 30 + ], + [ + -210, + 30 + ], + [ + -210, + 60 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_711", + "type": "text", + "x": 535.0, + "y": 276.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1711, + "version": 1, + "versionNonce": 2711, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "yes", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "yes", + "lineHeight": 1.22 + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 655, + "y": 402, + "width": 165, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 165, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_712", + "type": "text", + "x": 652.5, + "y": 373.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1712, + "version": 1, + "versionNonce": 2712, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "no", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "no", + "lineHeight": 1.22 + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 515, + "y": 470, + "width": 0, + "height": 140, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_713", + "type": "text", + "x": 430.0, + "y": 511.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1713, + "version": 1, + "versionNonce": 2713, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "yes", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "yes", + "lineHeight": 1.22 + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 960, + "y": 470, + "width": -130, + "height": 140, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 65 + ], + [ + -130, + 65 + ], + [ + -130, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_714", + "type": "text", + "x": 810.0, + "y": 511.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1714, + "version": 1, + "versionNonce": 2714, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "no/vague", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "no/vague", + "lineHeight": 1.22 + }, + { + "id": "arrow_15", + "type": "arrow", + "x": 960, + "y": 470, + "width": 200, + "height": 140, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5015, + "version": 1, + "versionNonce": 6015, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 80 + ], + [ + 200, + 80 + ], + [ + 200, + 140 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_715", + "type": "text", + "x": 975.0, + "y": 511.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1715, + "version": 1, + "versionNonce": 2715, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "yes", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "yes", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "diamond", + "x": 585, + "y": 135, + "width": 280, + "height": 140, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 585, + "y": 192.19, + "width": 280, + "height": 26.25, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Need code changes?", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Need code changes?", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 150, + "y": 155, + "width": 270, + "height": 100, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 150, + "y": 166.57, + "width": 270, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "ASK\nquestions +\nexplanations", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "ASK\nquestions +\nexplanations", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "diamond", + "x": 375, + "y": 335, + "width": 280, + "height": 135, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 375, + "y": 378.1, + "width": 280, + "height": 50.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Single file\nclear target?", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Single file\nclear target?", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "diamond", + "x": 820, + "y": 335, + "width": 280, + "height": 135, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 820, + "y": 376.88, + "width": 280, + "height": 52.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Multi-file\nclear scope?", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Multi-file\nclear scope?", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 385, + "y": 610, + "width": 260, + "height": 100, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 385, + "y": 621.57, + "width": 260, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "EDIT\n1-2 calls\ntargeted change", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "EDIT\n1-2 calls\ntargeted change", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 690, + "y": 610, + "width": 280, + "height": 110, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 690, + "y": 626.57, + "width": 280, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "CLARIFY FIRST\nplan / ask mode\nthen execute", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "CLARIFY FIRST\nplan / ask mode\nthen execute", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 1030, + "y": 610, + "width": 260, + "height": 105, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 1030, + "y": 624.07, + "width": 260, + "height": 78.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "AGENT\n5-25 steps\nmulti-file work", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "AGENT\n5-25 steps\nmulti-file work", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/outcome-per-token-loop.excalidraw b/docs/diagrams/outcome-per-token-loop.excalidraw new file mode 100644 index 0000000..8e82b84 --- /dev/null +++ b/docs/diagrams/outcome-per-token-loop.excalidraw @@ -0,0 +1,824 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Outcome-per-token loop", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Outcome-per-token loop", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "The goal is fewer wrong turns, not merely fewer words.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "The goal is fewer wrong turns, not merely fewer words.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 865, + "y": 190, + "width": 50, + "height": 115, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 25, + 0 + ], + [ + 25, + 115 + ], + [ + 50, + 115 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 1055, + "y": 355, + "width": 0, + "height": 145, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 145 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 915, + "y": 548, + "width": -50, + "height": 117, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -25, + 0 + ], + [ + -25, + 117 + ], + [ + -50, + 117 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 585, + "y": 665, + "width": -55, + "height": -117, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -25, + 0 + ], + [ + -25, + -117 + ], + [ + -55, + -117 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 390, + "y": 500, + "width": 0, + "height": -145, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + -145 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_15", + "type": "arrow", + "x": 530, + "y": 305, + "width": 55, + "height": -115, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5015, + "version": 1, + "versionNonce": 6015, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 30, + 0 + ], + [ + 30, + -115 + ], + [ + 55, + -115 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "shape_100", + "type": "ellipse", + "x": 585, + "y": 145, + "width": 280, + "height": 90, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 585, + "y": 175.97, + "width": 280, + "height": 28.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Pick task shape", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Pick task shape", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 915, + "y": 260, + "width": 280, + "height": 95, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 915, + "y": 293.47, + "width": 280, + "height": 28.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Plan before code", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Plan before code", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 915, + "y": 500, + "width": 280, + "height": 95, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 915, + "y": 519.44, + "width": 280, + "height": 57.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Route model by\nphase", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Route model by\nphase", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 585, + "y": 620, + "width": 280, + "height": 95, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 585, + "y": 653.47, + "width": 280, + "height": 28.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Target context", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Target context", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 250, + "y": 500, + "width": 280, + "height": 95, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 250, + "y": 533.47, + "width": 280, + "height": 28.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Verify evidence", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Verify evidence", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 250, + "y": 260, + "width": 280, + "height": 95, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 250, + "y": 293.47, + "width": 280, + "height": 28.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Close cleanly", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Close cleanly", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 545, + "y": 355, + "width": 360, + "height": 120, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 545, + "y": 378.4, + "width": 360, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "High outcome\nper token", + "fontSize": 30, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "High outcome\nper token", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/plan-execute-cheaply.excalidraw b/docs/diagrams/plan-execute-cheaply.excalidraw new file mode 100644 index 0000000..c6802a0 --- /dev/null +++ b/docs/diagrams/plan-execute-cheaply.excalidraw @@ -0,0 +1,832 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1342, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Plan first, execute cheaply", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Plan first, execute cheaply", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1342, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Spend premium reasoning before code; run mechanical execution in a clean lane.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Spend premium reasoning before code; run mechanical execution in a clean lane.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 395, + "y": 305, + "width": 180, + "height": 0, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 180, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_710", + "type": "text", + "x": 400.0, + "y": 276.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1710, + "version": 1, + "versionNonce": 2710, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "capture", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "capture", + "lineHeight": 1.22 + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 875, + "y": 305, + "width": 180, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 180, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_711", + "type": "text", + "x": 880.0, + "y": 276.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1711, + "version": 1, + "versionNonce": 2711, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "fresh session", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "fresh session", + "lineHeight": 1.22 + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 1205, + "y": 380, + "width": -480, + "height": 120, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 75 + ], + [ + -480, + 75 + ], + [ + -480, + 120 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 865, + "y": 578, + "width": 160, + "height": 2, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 160, + 2 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_713", + "type": "text", + "x": 860.0, + "y": 550.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1713, + "version": 1, + "versionNonce": 2713, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "yes", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "yes", + "lineHeight": 1.22 + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 585, + "y": 578, + "width": -170, + "height": 2, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -170, + 2 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_714", + "type": "text", + "x": 415.0, + "y": 550.24, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1714, + "version": 1, + "versionNonce": 2714, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "no", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "no", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 95, + "y": 230, + "width": 300, + "height": 150, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 95, + "y": 234.85000000000002, + "width": 300, + "height": 143.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "PHASE 1: PLAN\nstrong reasoning\nmodel\nAsk / Plan /\nresearch", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "PHASE 1: PLAN\nstrong reasoning\nmodel\nAsk / Plan /\nresearch", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 575, + "y": 210, + "width": 300, + "height": 190, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 575, + "y": 234.85000000000002, + "width": 300, + "height": 143.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Saved plan\nsteps\nacceptance criteria\nverification\ncommand", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Saved plan\nsteps\nacceptance criteria\nverification\ncommand", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 1055, + "y": 230, + "width": 300, + "height": 150, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 1055, + "y": 262.91, + "width": 300, + "height": 86.25, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "PHASE 2: EXECUTE\nfresh session\ncheaper/mid model", + "fontSize": 23, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "PHASE 2: EXECUTE\nfresh session\ncheaper/mid model", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "diamond", + "x": 585, + "y": 510, + "width": 280, + "height": 135, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 585, + "y": 551.88, + "width": 280, + "height": 52.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Acceptance\ncriteria met?", + "fontSize": 21, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Acceptance\ncriteria met?", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 1035, + "y": 535, + "width": 250, + "height": 90, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 1035, + "y": 553.16, + "width": 250, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Verified\nimplementation", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Verified\nimplementation", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 155, + "y": 535, + "width": 250, + "height": 90, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 155, + "y": 553.16, + "width": 250, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Revise plan\nbefore more code", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Revise plan\nbefore more code", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/prompt-compression-ladder.excalidraw b/docs/diagrams/prompt-compression-ladder.excalidraw new file mode 100644 index 0000000..82c9336 --- /dev/null +++ b/docs/diagrams/prompt-compression-ladder.excalidraw @@ -0,0 +1,934 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1292, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Prompt compression ladder", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Prompt compression ladder", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1292, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Drop filler, keep technical substance exact.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Drop filler, keep technical substance exact.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 410, + "y": 255, + "width": 35, + "height": 0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 35, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 695, + "y": 255, + "width": 35, + "height": 0, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 35, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 980, + "y": 255, + "width": 35, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 35, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_13", + "type": "arrow", + "x": 300, + "y": 455, + "width": 0, + "height": -125, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5013, + "version": 1, + "versionNonce": 6013, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + -125 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_713", + "type": "text", + "x": 215.0, + "y": 363.74, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1713, + "version": 1, + "versionNonce": 2713, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "remove", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "remove", + "lineHeight": 1.22 + }, + { + "id": "arrow_14", + "type": "arrow", + "x": 700, + "y": 455, + "width": 0, + "height": -125, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5014, + "version": 1, + "versionNonce": 6014, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + -125 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_714", + "type": "text", + "x": 615.0, + "y": 363.74, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1714, + "version": 1, + "versionNonce": 2714, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "preserve", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "preserve", + "lineHeight": 1.22 + }, + { + "id": "arrow_15", + "type": "arrow", + "x": 1090, + "y": 455, + "width": 0, + "height": -125, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5015, + "version": 1, + "versionNonce": 6015, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0, + -125 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "txt_715", + "type": "text", + "x": 1005.0, + "y": 363.74, + "width": 170, + "height": 20.0, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1715, + "version": 1, + "versionNonce": 2715, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "clarify", + "fontSize": 16, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "clarify", + "lineHeight": 1.22 + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 80, + "y": 190, + "width": 330, + "height": 130, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 80, + "y": 218.4, + "width": 330, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Verbose\n\"Could you please help\nme refactor...\"", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Verbose\n\"Could you please help\nme refactor...\"", + "lineHeight": 1.22 + }, + { + "id": "shape_101", + "type": "rectangle", + "x": 445, + "y": 190, + "width": 250, + "height": 130, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3101, + "version": 1, + "versionNonce": 4101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_601", + "type": "text", + "x": 445, + "y": 228.16, + "width": 250, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1601, + "version": 1, + "versionNonce": 2601, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Lite\nremove filler", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Lite\nremove filler", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 730, + "y": 190, + "width": 250, + "height": 130, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 730, + "y": 228.16, + "width": 250, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Full\nfragments OK", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Full\nfragments OK", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 1015, + "y": 190, + "width": 250, + "height": 130, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 1015, + "y": 228.16, + "width": 250, + "height": 55.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Ultra\narrows + abbrev", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Ultra\narrows + abbrev", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 180, + "y": 455, + "width": 260, + "height": 95, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 180, + "y": 465.9, + "width": 260, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Articles\npleasantries\nhedging", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Articles\npleasantries\nhedging", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 570, + "y": 455, + "width": 260, + "height": 95, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 570, + "y": 465.9, + "width": 260, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Technical terms\nfile names\ncode unchanged", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Technical terms\nfile names\ncode unchanged", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 960, + "y": 455, + "width": 260, + "height": 95, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 960, + "y": 465.9, + "width": 260, + "height": 75.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Scope\nacceptance criteria\nexact constraints", + "fontSize": 20, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Scope\nacceptance criteria\nexact constraints", + "lineHeight": 1.22 + }, + { + "id": "txt_107", + "type": "text", + "x": 170, + "y": 622.06, + "width": 980, + "height": 67.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1107, + "version": 1, + "versionNonce": 2107, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Visual rule: compression is a funnel, not a shredder.\nMeaning must survive.", + "fontSize": 27, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Visual rule: compression is a funnel, not a shredder.\nMeaning must survive.", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/diagrams/token-cost-anatomy.excalidraw b/docs/diagrams/token-cost-anatomy.excalidraw new file mode 100644 index 0000000..8c108e0 --- /dev/null +++ b/docs/diagrams/token-cost-anatomy.excalidraw @@ -0,0 +1,810 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "txt_1", + "type": "text", + "x": 54, + "y": 36.260000000000005, + "width": 1292, + "height": 42.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1001, + "version": 1, + "versionNonce": 2001, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Token cost anatomy", + "fontSize": 34, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Token cost anatomy", + "lineHeight": 1.22 + }, + { + "id": "txt_2", + "type": "text", + "x": 54, + "y": 76.02, + "width": 1292, + "height": 22.5, + "angle": 0, + "strokeColor": "#526171", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1002, + "version": 1, + "versionNonce": 2002, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Most input is hidden context; output is small but premium-priced.", + "fontSize": 18, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Most input is hidden context; output is small but premium-priced.", + "lineHeight": 1.22 + }, + { + "id": "arrow_10", + "type": "arrow", + "x": 850, + "y": 330, + "width": 130, + "height": 0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5010, + "version": 1, + "versionNonce": 6010, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 130, + 0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_11", + "type": "arrow", + "x": 370, + "y": 619, + "width": 610, + "height": -199, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5011, + "version": 1, + "versionNonce": 6011, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 530, + 0 + ], + [ + 530, + -199 + ], + [ + 610, + -199 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "arrow_12", + "type": "arrow", + "x": 850, + "y": 565, + "width": 80, + "height": 67, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 3, + "strokeStyle": "dashed", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 5012, + "version": 1, + "versionNonce": 6012, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 40, + 0 + ], + [ + 40, + 67 + ], + [ + 80, + 67 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "shape_100", + "type": "rectangle", + "x": 70, + "y": 155, + "width": 780, + "height": 520, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3100, + "version": 1, + "versionNonce": 4100, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_600", + "type": "text", + "x": 70, + "y": 401.58, + "width": 780, + "height": 27.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1600, + "version": 1, + "versionNonce": 2600, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "", + "lineHeight": 1.22 + }, + { + "id": "txt_101", + "type": "text", + "x": 105, + "y": 187.92000000000002, + "width": 700, + "height": 35.0, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1101, + "version": 1, + "versionNonce": 2101, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "INPUT TOKENS", + "fontSize": 28, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "INPUT TOKENS", + "lineHeight": 1.22 + }, + { + "id": "shape_102", + "type": "rectangle", + "x": 110, + "y": 250, + "width": 680, + "height": 64, + "angle": 0, + "strokeColor": "#2563eb", + "backgroundColor": "#dbeafe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3102, + "version": 1, + "versionNonce": 4102, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_602", + "type": "text", + "x": 110, + "y": 268.58, + "width": 680, + "height": 27.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1602, + "version": 1, + "versionNonce": 2602, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "System prompt + repo instructions", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "System prompt + repo instructions", + "lineHeight": 1.22 + }, + { + "id": "shape_103", + "type": "rectangle", + "x": 110, + "y": 335, + "width": 680, + "height": 64, + "angle": 0, + "strokeColor": "#0f766e", + "backgroundColor": "#ccfbf1", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3103, + "version": 1, + "versionNonce": 4103, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_603", + "type": "text", + "x": 110, + "y": 353.58, + "width": 680, + "height": 27.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1603, + "version": 1, + "versionNonce": 2603, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "File context + open tabs + imports", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "File context + open tabs + imports", + "lineHeight": 1.22 + }, + { + "id": "shape_104", + "type": "rectangle", + "x": 110, + "y": 420, + "width": 680, + "height": 64, + "angle": 0, + "strokeColor": "#7c3aed", + "backgroundColor": "#ede9fe", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3104, + "version": 1, + "versionNonce": 4104, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_604", + "type": "text", + "x": 110, + "y": 438.58, + "width": 680, + "height": 27.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1604, + "version": 1, + "versionNonce": 2604, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Conversation history grows every turn", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Conversation history grows every turn", + "lineHeight": 1.22 + }, + { + "id": "shape_105", + "type": "rectangle", + "x": 110, + "y": 505, + "width": 680, + "height": 64, + "angle": 0, + "strokeColor": "#d97706", + "backgroundColor": "#fef3c7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3105, + "version": 1, + "versionNonce": 4105, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_605", + "type": "text", + "x": 110, + "y": 523.58, + "width": 680, + "height": 27.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1605, + "version": 1, + "versionNonce": 2605, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "MCP/tool schemas: loaded per step", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "left", + "verticalAlign": "middle", + "containerId": null, + "originalText": "MCP/tool schemas: loaded per step", + "lineHeight": 1.22 + }, + { + "id": "shape_106", + "type": "rectangle", + "x": 110, + "y": 590, + "width": 260, + "height": 58, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3106, + "version": 1, + "versionNonce": 4106, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_606", + "type": "text", + "x": 110, + "y": 605.58, + "width": 260, + "height": 27.5, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1606, + "version": 1, + "versionNonce": 2606, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Your typed prompt", + "fontSize": 22, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Your typed prompt", + "lineHeight": 1.22 + }, + { + "id": "shape_107", + "type": "rectangle", + "x": 980, + "y": 235, + "width": 360, + "height": 265, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "#fee2e2", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 3107, + "version": 1, + "versionNonce": 4107, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_607", + "type": "text", + "x": 980, + "y": 296.74, + "width": 360, + "height": 145.0, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1607, + "version": 1, + "versionNonce": 2607, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "OUTPUT TOKENS\nvisible answer\n5x pricing\nintuition", + "fontSize": 29, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "OUTPUT TOKENS\nvisible answer\n5x pricing\nintuition", + "lineHeight": 1.22 + }, + { + "id": "shape_108", + "type": "ellipse", + "x": 930, + "y": 570, + "width": 430, + "height": 125, + "angle": 0, + "strokeColor": "#16a34a", + "backgroundColor": "#dcfce7", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 3108, + "version": 1, + "versionNonce": 4108, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "txt_608", + "type": "text", + "x": 930, + "y": 586.75, + "width": 430, + "height": 93.75, + "angle": 0, + "strokeColor": "#14213d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1608, + "version": 1, + "versionNonce": 2608, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "CACHED TOKENS\nstable prefix gets\ncheaper", + "fontSize": 25, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "CACHED TOKENS\nstable prefix gets\ncheaper", + "lineHeight": 1.22 + }, + { + "id": "txt_109", + "type": "text", + "x": 965, + "y": 144.5, + "width": 350, + "height": 62.5, + "angle": 0, + "strokeColor": "#dc2626", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 0, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1109, + "version": 1, + "versionNonce": 2109, + "isDeleted": false, + "boundElements": null, + "updated": 1, + "link": null, + "locked": false, + "text": "Optimize first:\nconstrain responses", + "fontSize": 25, + "fontFamily": 3, + "textAlign": "center", + "verticalAlign": "middle", + "containerId": null, + "originalText": "Optimize first:\nconstrain responses", + "lineHeight": 1.22 + } + ], + "appState": { + "viewBackgroundColor": "#fbfcfe", + "gridSize": 20 + }, + "files": {} +} \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d367f9f..54b50e3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,8 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and [Start with Part 1](01-why-tokens-matter.md){ .md-button .md-button--primary } [Jump to Practical Setup](10-practical-setup.md){ .md-button } +Concise practitioner briefing +Full 8-hour workshop ## What This Covers @@ -19,26 +21,36 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and 1. Constrain output by default: `Code only, no explanation.` and `No explanations unless asked.` 2. Keep `.github/copilot-instructions.md` small and specific. -3. Use Ask Mode for questions that do not need tools. -4. Retune prompts and instructions against the official guide for your target model. -5. Disable MCP servers you are not using. -6. Audit long-running agent sessions and repeated back-and-forth. -7. Install [RTK](https://github.com/rtk-ai/rtk) — CLI proxy that filters `git`, test runners, `grep`, and 100+ other shell commands before output reaches the agent. One install, 60-90% savings on tool-call results in agent and coding-agent sessions. +3. Protect cache in long sessions: keep `{model, reasoning effort, loaded skills, active MCP/tool set, agent/profile}` stable; if you must change one, start a fresh chat with a short handoff summary. +4. Use Ask Mode for questions that do not need tools. +5. Retune prompts and instructions against the official guide for your target model. +6. Disable MCP servers you are not using. +7. Convert DOCX/PDF/Office/media inputs to Markdown before AI work; start with [MarkItDown](https://github.com/microsoft/markitdown). +8. Audit long-running agent sessions and repeated back-and-forth. +9. Install one shell-output filter: [RTK](https://github.com/rtk-ai/rtk) or [`snip`](https://github.com/edouard-claude/snip). These CLI proxies filter `git`, test runners, `grep`, build tools, and other command output before it reaches the agent. Use one filter layer per command path; do not stack them by default. +10. Build a persistent codebase graph with [Graphify](https://github.com/Graphify-Labs/graphify) — map code once via tree-sitter AST, write `graphify-out/graph.json`, then let agents query the graph instead of re-reading project files each session. Install: `uv tool install graphifyy`. ## Read by Topic ### Foundations - [Why Tokens Matter](01-why-tokens-matter.md) -- [Comparisons & Data](09-comparisons-data.md) ### Techniques +- [Prompt Compression](02-prompt-compression.md) +- [Language Comparison](03-language-comparison.md) - [Context Management](04-context-management.md) - [Output Control](05-output-control.md) - [Workflow Optimization](06-workflow-optimization.md) +- [Always-On Context Problem](07-agents-md-problem.md) - [MCP & Tool Costs](08-mcp-tool-costs.md) +### Comparisons + +- [Comparisons & Data](09-comparisons-data.md) +- [Outcome per Token](13-outcome-per-token.md) + ### Implementation - [Practical Setup](10-practical-setup.md) @@ -53,6 +65,7 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and - **Ask Mode**: single-shot interaction. Lowest-overhead choice for simple questions. - **Agent Mode**: multi-step interaction. Higher leverage, higher cost. - **Content Exclusion**: admin control for keeping selected repo content out of Copilot context. +- **Format tax**: extra tokens from rich file metadata and layout noise in DOCX, PDF, HTML, slides, spreadsheets, images, and audio/video extraction. Convert to Markdown first. ## Useful Links @@ -63,9 +76,15 @@ Practical guide to reducing GitHub Copilot token spend while keeping answers and - [LLMLingua](https://github.com/microsoft/LLMLingua) - [Caveman project](https://github.com/JuliusBrussee/caveman) - [RTK — Rust Token Killer](https://github.com/rtk-ai/rtk) +- [snip](https://github.com/edouard-claude/snip) — YAML-extensible shell-output filter for Copilot CLI and other agent shells +- [Tokentop](https://github.com/tokentopapp/tokentop) — local live dashboard for agent token, cost, and burn-rate visibility; supports Copilot CLI +- [minimal-context-tools](https://github.com/SebastienDegodez/copilot-instructions/tree/main/plugins/minimal-context-tools) — skill pack for lower-context CLI search/query patterns +- [Graphify](https://github.com/Graphify-Labs/graphify) — build a persistent knowledge graph of your codebase; agents query `graphify-out/graph.json` instead of re-reading files. Supports GitHub Copilot, VS Code workflows, and other assistants. PyPI package: `graphifyy` +- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) — convert PDF, Office files, images, audio, HTML, ZIP contents, YouTube URLs, EPUBs, and more to Markdown for LLM workflows +- [Marc Bara: "Your .docx Is Wasting 33% of Your AI Budget"](https://medium.com/@marc.bara.iniesta/your-docx-is-wasting-33-of-your-ai-budget-86a3d229d042) - [Dina Berry: "How I Cut Token Usage from 52% to 13%"](https://dfberry.github.io/2026-05-06-tuning-up-copilot-context) — real measured numbers from a Copilot CLI production setup (Microsoft/GitHub content contributor) ## Notes -- `/chronicle` (full, all subcommands) is **Copilot CLI**. `/chronicle:tips` is also available in **VS Code**. +- `/chronicle` is **Copilot CLI** only (also available inside JetBrains via interactive Copilot CLI sessions). It is **not** available in VS Code — use [AI Engineering Coach](06-workflow-optimization.md#258-vs-code-usage-analytics-ai-engineering-coach) there. Subcommands include `cost tips`, `improve`, `tips`, `standup`, `search`, and `reindex`. - Usage-Based Billing is labeled **UBB** in this repo. diff --git a/mkdocs.yml b/mkdocs.yml index 6141434..44d8d30 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ plugins: markdown_extensions: - admonition - attr_list + - footnotes - md_in_html - pymdownx.details - pymdownx.superfences @@ -45,3 +46,4 @@ nav: - Practical Setup: 10-practical-setup.md - Model Selection & Pricing: 11-models-and-pricing.md - Enterprise Governance: 12-enterprise-governance.md + - Outcome per Token: 13-outcome-per-token.md diff --git a/slides/briefing.html b/slides/briefing.html new file mode 100644 index 0000000..aaacbb7 --- /dev/null +++ b/slides/briefing.html @@ -0,0 +1,213 @@ + + + + + + GitHub Copilot Token Optimization - Practitioner Briefing + + + + + + +
+
+
+

Practitioner briefing

+

GitHub Copilot Token Optimization

+

18 actions for cheaper, faster, more reliable AI-assisted engineering.

+

Need the full training? Open the 8-hour workshop.

+
+ +
+

Outcome: useful work per token

+
+

Spend less

Reduce unnecessary input, output, and tool overhead.

+

Move faster

Keep context focused. Avoid expensive rework loops.

+

Ship better

Plan, verify, and use the right agent mode for the task.

+
+

Community guidance, not official GitHub or Microsoft policy.

+
+ +
+

Know what you pay for

+
+

Input

System prompt, instructions, files, history, tool schemas, and your prompt.

+

Output

Responses, reasoning, and tool calls. Usually the highest-cost token type.

+

Cached input

Stable request prefixes can be reused at a lower effective cost.

+

Agent loops

Every read, command, retry, and rework step compounds cost.

+
+
+ +
+

Priority stack

+
    +
  1. Constrain output. Stop paying for prose you do not need.
    2. +
  2. Shrink context. Keep always-on instructions and files focused.
    3. +
  3. Reduce tool overhead. Load only needed MCP tools and compress command output.
    4. +
  4. Avoid rework. Choose the right mode, model, plan, and verification.
    5. +
+
+ +
+

1. Default to constrained output

+
Code only. No explanation unless asked.
+

Use short, explicit formats for code tasks, reviews, and summaries. Output control compounds across every interaction.

+

Do not compress reasoning or evidence when the task needs it.

+
+ +
+

2. Compress always-on instructions

+
+

Keep

Project landmines, commands, naming, architecture rules, output constraints.

+

Remove

Boilerplate, discovery facts, duplicate rules, occasional workflow checklists.

+
+

Every token in .github/copilot-instructions.md is paid repeatedly. Put rare guidance in scoped or on-demand files.

+
+ +
+

3. Target context deliberately

+
    +
  • Close unrelated editor tabs and avoid attaching broad files.
    • +
  • Use applyTo instruction files for path-specific rules.
    • +
  • Convert rich input to Markdown before AI work.
    • +
  • Send the relevant plan and files, not an entire project history.
    • +
+
+ +
+

4. Protect cached prefixes

+

For one long task, keep this stable:

+
{ model, reasoning effort, loaded skills, MCP/tool set, agent/profile }
+

Changing the lane or harness can lose cached-prefix savings. Start a fresh chat with a compact handoff instead.

+
+ +
+

5. Use the smallest capable mode

+
+

Ask

Questions, explanations, decisions. No tools needed.

+

Edit

Bounded changes with known files and intent.

+

Agent

Multi-file work that needs exploration, commands, and verification.

+
+

Do not use Agent mode for a question that Ask mode can answer.

+
+ +
+

6. Route models by task

+
    +
  • Auto first for everyday work.
    • +
  • Lightweight for lookup, syntax, small mechanical edits.
    • +
  • Strong reasoning for planning, architecture, and hard debugging.
    • +
  • Execution lane after the hard decisions are written down.
    • +
+

Choose reasoning effort before the long session. Do not raise it mid-thread.

+
+ +
+

7. Plan, then execute fresh

+ Plan first, then execute cheaply +

Capture acceptance criteria, likely files, risks, and verification. Start execution with only that handoff.

+
+ +
+

8. Keep the MCP baseline small

+
    +
  • Every enabled MCP tool schema is repeated in agent context.
    • +
  • Disable servers and extensions not needed for this repo or task.
    • +
  • Use a clean profile or focused agent for repeat workflows.
    • +
  • Run /context in Copilot CLI to see what is loaded.
    • +
+
+ +
+

9. Compress shell output once

+
+

RTK

Compiled defaults for common developer command output.

+

snip

YAML pipelines and local savings tracking.

+
+

Choose one filter layer per command path. Do not stack both by default.

+
+ +
+

10. Reuse codebase orientation

+

Graphify maps a large repo once, then agents query structure instead of repeatedly reading broad file sets.

+ 
graphify query "where is auth middleware?"
+graphify path "Router" "Database"
+

Best for large repos and repeated agent sessions. Skip it for small, one-off changes.

+
+ +
+

11. Make token use visible

+
+

In-session

Use /context to inspect Copilot CLI context pressure and loaded tools.

+

Cross-session

Tokentop shows local live tokens, cost, burn rate, and budget alerts.

+
+

Visibility finds waste. It does not compress context by itself.

+
+ +
+

12. Set a stable session harness

+
Model + effort + mode + agent + skills + MCP tools + output filter + repo instructions
+

Choose it before long work. If the task needs a different harness, create a fresh session rather than mutating a long transcript.

+
+ +
+

13. Verify before completion

+
    +
  1. Name the acceptance criteria.
    2. +
  2. Run the targeted test, build, or check.
    3. +
  3. Report evidence, not a generic “done.”
    4. +
+

Small verification cost prevents a new debugging or review session later.

+
+ +
+

14. Adopt and sustain

+
+

Week 1

Constrain output. Trim repo instructions.

+

Week 2

Route Ask, Edit, and Agent deliberately.

+

Week 3

Audit MCP tools and command output.

+

Week 4

Plan-first workflows, cache stability, and usage review.

+
+

Every task: constrain output, target context, choose the harness, plan, and verify.

+

Read the guide · Open the full workshop

+
+
+
+ + + + diff --git a/slides/index.html b/slides/index.html index 7f3cee6..2eafcdc 100644 --- a/slides/index.html +++ b/slides/index.html @@ -172,6 +172,27 @@ .left { text-align: left; } + + .diagram { + display: block; + max-width: 96%; + max-height: 560px; + margin: 0.35em auto 0; + border-radius: 18px; + background: #f8fafc; + } + + .diagram-compact { + max-height: 470px; + } + + .star-history { + max-width: 96%; + max-height: 420px; + background: #ffffff; + border-radius: 14px; + padding: 0.35em; + } @@ -226,8 +247,9 @@

8 hour agenda

03:15-04:15Workflow + modesMode routing cheat sheet 04:15-05:15MCP/tool costs + dataMCP audit list 05:15-06:15Practical setupRepo setup checklist - 06:15-07:30Model/pricing + governanceCustomer admin rollout - 07:30-08:00Capstone30 day token plan + 06:15-07:10Model/pricing + governanceCustomer admin rollout + 07:10-07:40Outcome per tokenPlan/execute/verify loop + 07:40-08:00Capstone30 day token plan @@ -241,7 +263,7 @@

Navigation

Quick Start

-

11 things to do right now

+

14 things to do right now

Start with output, then shrink structural input, then route models and tools.

@@ -263,29 +285,42 @@

More fast wins

  • Write precise prompts: target file, function, done condition.
  • Retune prompts to target model.
  • Audit MCP servers.
    • -
  • Run /chronicle improve in Copilot CLI.
    • +
  • Convert rich files to Markdown first.
    • + +
    + +
    +

    More fast wins, continued

    +
      +
    1. Run /chronicle cost tips & /chronicle improve in Copilot CLI.
      2. +
    2. Use AI Engineering Coach for VS Code habit review.
    3. Try CodeAct for long CLI tool chains.
      4. +
    4. Build a Graphify map for repeated codebase navigation.

    The priority stack

    -
    +

    Output first

    -

    Verbose answers are expensive. One default instruction changes every response.

    +

    One default changes every response.

    Always-on second

    -

    Instruction files and tool schemas load repeatedly. Small baselines compound.

    +

    Small baselines compound.

    Mode third

    -

    Ask for questions. Edit for single-file changes. Agent for multi-step work.

    +

    Ask, Edit, Agent by task shape.

    Governance fourth

    -

    Budgets cap spend. Model policy limits expensive lanes.

    +

    Budgets and model policy cap spend.

    +
    +
    +

    Outcome fifth

    +

    Plan, route, verify, close.

    @@ -329,14 +364,7 @@

    Core insight

    Cost model

    - - - - - - - -
    BucketWhat it containsLever
    InputPrompt, context, files, history, toolsScope and compress
    CachedStable reused prefixesKeep stable context stable
    OutputModel responseCode-only, concise format
    + Token cost anatomy: input tokens include hidden context, output tokens are the visible answer, cached tokens reuse stable prefix.

    Output tokens usually cost materially more than input tokens in vendor pricing examples.

    @@ -384,6 +412,7 @@

    Goal

    Part 2.1

    Prompt compression

    Say same thing in fewer tokens. Preserve technical precision.

    + Prompt compression ladder from verbose to lite to full to ultra while preserving technical substance.
    @@ -593,24 +622,22 @@

    Use scoped instructions

    Always-on vs conditional vs on-demand

    - - - - - - - -
    ScopeUse forToken posture
    Always-onUniversal rulesKeep tiny
    ConditionalPath/layer rulesapplyTo
    On-demandReview checklists, release notesLoad only when invoked
    + Always-on context should be tiny; scoped instructions load by path; on-demand skills load when invoked. +
    + +
    +

    Normalize rich files first

    + Rich files carry format noise; MarkItDown converts them to clean Markdown before AI work.

    Cache-friendly behavior

    -
      -
    • Keep stable context at the top.
      • -
    • Do not churn instruction files constantly.
      • -
    • Reuse saved snippets instead of re-pasting large context.
      • -
    • Summarize and restart when history gets stale.
      • -
    + Stable thread reuses prefix; cache-busted thread switches model, tools, or agent and should start fresh with a handoff. +
    + +
    +

    Persistent graph navigation

    + Graphify builds graph.json once so agents can query the map instead of rereading broad file sets.
    @@ -718,16 +745,7 @@

    Review

    Ask vs Edit vs Agent

    - - - - - - - - - -
    TaskModeReason
    What does function do?AskOne call
    Syntax questionAskNo tools
    Single-file tweakEditTargeted
    Multi-file refactorAgentNeeds tools
    Issue-to-PRCoding AgentAutonomous workflow
    + Decision tree: use Ask for questions, Edit for targeted single-file changes, Agent for clear multi-file work, and clarify vague tasks first.
    @@ -761,7 +779,7 @@

    Close loop with usage coaching

    /chronicle

    -

    Copilot CLI session history. Use /chronicle improve for recurring confusion.

    +

    Copilot CLI session history (not VS Code). Use /chronicle cost tips for token spend and /chronicle improve for recurring confusion.

    AI Engineering Coach

    @@ -770,6 +788,11 @@

    AI Engineering Coach

    +
    +

    Plan first, execute cheaply

    + Plan with strong model, save plan, execute in fresh cheaper session, then verify acceptance criteria. +
    +

    Lab 8: mode routing drill

    @@ -860,6 +883,7 @@

    Goal

    Part 2.7

    MCP and tool costs

    Tool schemas are hidden token tax.

    + Tooling stack: scope MCP schemas, use CodeAct for turn loops, RTK or snip for output, Graphify for orientation.
    @@ -908,11 +932,33 @@

    Audit rule

    Tool output compression

    -
    -

    RTK

    -

    CLI proxy filters noisy shell output before agent reads it: tests, git diff, grep, logs, file listings.

    - 
    rtk init --copilot
    +
    +
    +

    RTK

    +

    Rust CLI proxy filters noisy shell output: tests, git diff, grep, logs, file listings.

    + 
    rtk init --copilot
    +
    +
    +

    snip

    +

    YAML-extensible command filters with local savings stats and team-maintained rules.

    + 
    snip init --agent copilot
    +
    +

    Pick one output filter layer per command path. Do not stack RTK and snip by default.

    +
    + +
    +

    One tool per layer

    + + + + + + + + + +
    LayerToolReduces
    Workflow turnsCodeActRepeated model-tool loops
    Command outputRTK or snipVerbose shell results
    Command choiceminimal-context-toolsBroad search/read behavior
    Codebase orientationGraphifyRepeated file rereads
    VisibilityChronicle / CoachWaste you would miss
    @@ -1063,6 +1109,22 @@

    Agent mode controls

    Cap runaway sessions carefully. Increase only when task requires it.

    +
    +

    Agent mode cost loop

    + Agent loop: load context, decide tool, ingest result, replay context, repeat. +
    + +
    +

    Session harness checklist

    + 
    model
+mode
+agent/profile
+active MCP/tools
+output filter
+repo instructions
    +

    Choose before the session starts. Stable harness = predictable cost and cache behavior.

    +
    +

    Lab 13: repo implementation

    @@ -1150,11 +1212,7 @@

    Enterprise governance

    Spend levers

    -
      -
    1. Budget ceilings.
      2. -
    2. User-level AI-credit budgets.
      3. -
    3. Model availability policy.
      4. -
    + Enterprise governance control plane connects budgets, user-level caps, model access, usage reports, cohorts, and policy review.

    Prompt compression does not cap spend. It reduces waste inside allowed usage.

    @@ -1248,6 +1306,98 @@

    Scenario

    +
    +
    +

    Part 4.4

    +

    Outcome per token

    +

    Optimize for accepted work, not the shortest prompt.

    +
    + +
    +

    The metric

    +
    + outcome per token = verified work completed / total tokens spent +
    +

    A short prompt that causes wrong-direction work is more expensive than a longer plan that lands correctly.

    +
    + +
    +

    Agentic cost research signal

    + + + + + + + + +
    FindingImplication
    Agentic coding can consume far more than chatDo not extrapolate simple-chat cost
    Same task can vary widely across runsUse budgets and stop rules
    More tokens do not guarantee accuracyOptimize loop quality
    Input dominates agentic costContext hygiene matters
    +
    + +
    +

    Outcome loop

    + Outcome-per-token loop: pick task shape, plan, route model, target context, verify evidence, close cleanly. +
    + +
    +

    Skills as practices

    + + + + + + + + + + +
    SkillToken effect
    BrainstormingPrevents early lock-in
    PlanningReduces guessing during execution
    GreennessAvoids debugging unknown baseline failures
    VerificationPrevents false completion
    Impeccable closePrevents review churn
    Branch-close disciplineStops stale context carryover
    +
    + +
    +

    Skill libraries: borrow patterns

    +
    +

    SDLC

    Superpowers, planning, TDD, branch finish.

    +

    Handoff

    agent-toolkit patterns for requirements, plans, entropy control.

    +

    Guardrails

    Secrets, cloud, DB, Docker, dependency, and retry-stop cautions.

    +

    QA / writing

    Browser evidence, writing review, QA depth on demand.

    +
    +

    Do not install every skill. Load only what changes the next action.

    +
    + +
    +

    Skill library adoption signal

    + Star history for selected community skill libraries. +

    Stars show attention, not quality. Judge by whether the skill changes the next agent action.

    +
    + +
    +

    Plan first, execute cheaply

    + Plan with strong reasoning model, save acceptance criteria, execute in a fresh cheaper session, verify implementation. +
    + +
    +

    Day-to-day model guidance

    +
      +
    1. Auto first for unknown everyday work.
      2. +
    2. Lightweight for tiny bounded work.
      3. +
    3. Mid-tier for normal implementation after clear plan.
      4. +
    4. Powerful for planning, architecture, hard debugging.
      5. +
    5. Fresh session when changing model/tool/agent lane.
      6. +
    +
    + +
    +

    Benchmark caveats

    +
      +
    • Benchmarks choose candidates; repo tasks choose defaults.
      • +
    • Harness, tools, retrieval, and reasoning effort affect scores.
      • +
    • Compare outcome and cost together, not score alone.
      • +
    • Label sources: verified, directional, anecdotal.
      • +
    +
    +
    +

    Capstone

    @@ -1261,9 +1411,9 @@

    Week-by-week rollout

    WeekTeam actionAdmin action 1Output defaults + Ask ModeUsage baseline - 2Instruction pruning + scoped rulesBudget pilot - 3MCP audit + model routingModel access review - 4Agent issue templates + setup stepsMonthly reporting cadence + 2Instruction pruning + scoped rules + Markdown conversionBudget pilot + 3MCP audit + output filter + Graphify pilotModel access review + 4Plan-first execution + verification/close disciplineMonthly outcome-per-token review
    @@ -1288,7 +1438,7 @@

    Developer

  • Code-only default
  • Ask/Edit/Agent routing
  • Concise prompts
    • -
  • Fresh sessions
    • +
  • Plan first, fresh sessions
    • @@ -1298,6 +1448,7 @@

    Repository

  • Scoped applyTo files
  • Coding Agent setup steps
  • Precise issue templates
    • +
  • Graphify map where useful
    • @@ -1306,7 +1457,8 @@

    Platform

  • MCP profiles
  • Content Exclusion
  • Model access policy
    • -
  • RTK/CLI tool output strategy
    • +
  • RTK or snip output strategy
    • +
  • One tool per layer
    • @@ -1315,7 +1467,7 @@

    Enterprise

  • Budgets
  • User-level caps
  • Usage reporting
    • -
  • Monthly review
    • +
  • Monthly outcome review
    • @@ -1337,6 +1489,68 @@

    Closing message