Communication Modes
Relevant source files
The following files were used as context for generating this wiki page:
Communication Modes define the structured interaction patterns between an agent and a user. These modes govern how skills are triggered, how technical information is presented, and how the agent conducts interactive design sessions to reach a shared understanding.
The project utilizes specific modes to optimize token usage, ensure architectural consistency, and manage the cognitive load of the user. Key variations include Stylistic Overrides like Caveman Mode for terseness, and Interactive Sessions like Grilling for deep technical resolution.
Sources: skills/caveman/SKILL.md, skills/writing-great-skills/SKILL.md, skills/writing-great-skills/GLOSSARY.md
Invocation Modes
Skills are categorized by how the agent reaches them during a conversation. The choice of invocation mode balances the agent's autonomy against the user's cognitive load and the system's context window.
Invocation Types
| Mode | Trigger Mechanism | Load Impact | Usage |
|---|---|---|---|
| Model-Invoked | Autonomous via description | High Context Load | Agent fires skill based on triggers or other skill needs. |
| User-Invoked | Explicit user typing | High Cognitive Load | User manually enters skill name; agent cannot see or fire it. |
Sources: skills/writing-great-skills/SKILL.md:12-25, skills/writing-great-skills/GLOSSARY.md:23-45
Invocation Flow Logic
The following diagram illustrates how the system determines whether a skill should be model-invoked or user-invoked.
This diagram shows the trade-off between autonomous agent discovery and manual human invocation.
Sources: skills/writing-great-skills/SKILL.md:12-25, skills/writing-great-skills/GLOSSARY.md:65-72
Stylistic Overrides: Caveman Mode
Caveman Mode is an ultra-compressed communication style that reduces token usage by approximately 75%. It prioritizes technical substance by removing filler words, articles, and pleasantries.
Core Rules
- Drop Articles: Remove "a", "an", and "the".
- Remove Filler: Strip words like "just", "really", "basically", and "simply".
- Skip Pleasantries: Do not use "sure", "certainly", or "happy to help".
- Technical Integrity: Keep code blocks, error quotes, and technical terms exact.
- Causality: Use arrows (X -> Y) for causal relationships.
Sources: skills/caveman/SKILL.md:16-29
Caveman Mode State Machine
This state machine describes how the agent toggles between normal communication and Caveman mode, including temporary reverts for safety.
Sources: skills/caveman/SKILL.md:8-14, skills/caveman/SKILL.md:38-42
Interactive Sessions: Grilling
Grilling is a relentless interview mode used to resolve design trees and dependencies. The agent challenges the user's plan against existing domain models and architectural decisions.
Interaction Process
- Iterative Questioning: The agent asks one question at a time, waiting for feedback before proceeding.
- Recommendation-First: The agent provides a recommended answer for every question asked.
- Codebase Exploration: The agent explores the code to answer questions itself whenever possible.
- Inline Updates: Terminology resolutions update
CONTEXT.mdor ADRs immediately during the session.
Sources: skills/grill-with-docs/SKILL.md:10-14, skills/grill-with-docs/SKILL.md:55-58
Grilling Sequence
The sequence shows the interactive loop where the agent uses existing documentation to grill the user and update the domain model in real-time.
Sources: skills/grill-with-docs/SKILL.md:10-20, skills/grill-with-docs/SKILL.md:55-58
Structured Reporting: Triage & Briefs
When communicating via issue trackers, the agent follows specific labeling and disclaimer protocols to maintain institutional memory.
Disclaimer Requirement
Every comment or issue posted to an external tracker during a triage session must start with the mandatory disclaimer: > *This was generated by AI during triage.*
Sources: skills/triage/SKILL.md:9-11
Agent Briefs
An Agent Brief is a structured contract posted to issues in a ready-for-agent state. It communicates:
- Behavioral Needs: What the system should do, not how to write it.
- Acceptance Criteria: Testable conditions for completion.
- Scope Boundaries: Explicitly stating what is out-of-scope to prevent gold-plating.
Sources: skills/triage/AGENT-BRIEF.md:10-33
Communication Constraints Summary
| Feature | Communication Rule |
|---|---|
| Bugs | Name reproduced symptom, traced root cause, and testable hypothesis. |
| Terminology | Call out immediate conflicts if user terms differ from CONTEXT.md. |
| ADRs | Surface conflicts explicitly when a proposal contradicts an ADR. |
| Caveman | Use [thing] [action] [reason] pattern. |
Sources: skills/production-preflight/SKILL.md:36-40, skills/grill-with-docs/SKILL.md:41-43, skills/caveman/SKILL.md:32-32
Communication modes in this project prioritize clarity through structured interaction. Whether using Caveman mode for efficiency or Grilling for design depth, the agent maintains a consistent technical vocabulary rooted in the project's domain model and architectural standards.