Coming from other agents
Buffaly feels structurally different if you are used to ChatGPT custom GPTs, Claude projects, coding agents (like Cursor or Claude Code), or MCP-first CLI wrappers.
Buffaly is an enterprise-grade, self-evolving engine. To get the most out of it, you have to unlearn the "chat-box" habits. This page explains what mental models to keep, what practices to drop, and how to operate Buffaly without treating it like a fragile text-loop.
The shift in mental model
Standard agents are static amnesiacs. You have to constantly remind them of rules in massive prompts. Buffaly isn't just a prompt bolted to a fixed list of functions. It is a session-based runtime built around semantic discovery, dynamic tool loading, ontology-backed memory, and typed native execution.
What you should stop doing
- Writing "System Prompts of Doom" with 50 rules and tools.
- Guessing exact internal tool names to force execution.
- Stuffing permanent context into chat history.
What you should start doing
- Telling Buffaly to write code to remember new workflows.
- Relying on typed native services over brittle CLI commands.
- Managing state using Sessions, Plan, Scratch, and Task Artifacts.
Quick answer: Old habits vs. Buffaly habits
| Old Agent Habit | Better Buffaly Habit |
|---|---|
| Paste a giant tool inventory. | State outcome, target, source of truth, constraints, and validation. Let Buffaly discover tools. |
| Keep long-term context in a project prompt. | Ask Buffaly to save durable facts, entities, and workflows to structured Ontology Memory. |
| Shell out to the CLI for absolutely everything. | Prefer typed tools, C# services, or ProtoScript actions when they fit. Shell is a fallback. |
| Treat MCP as the whole tool system. | Use MCP for external boundaries. Use native services or ProtoScript actions for internal logic. |
| Treat every chat as isolated. | Use Sessions, Plan, Scratch, task artifacts, timelines, and continuation prompts. |
| Accept plausible-sounding text answers. | Demand evidence: exact paths, scoped git status, validation checks, and commit hashes. |
Buffaly is self-evolving (Code over Prompts)
With a normal agent, if it makes a mistake, you go back and tweak the system prompt. With Buffaly, you just tell it what to do differently next time, and let it rewrite its own code.
Buffaly promotes repeated workflows from text-based guessing into typed, deterministic ProtoScript actions. It literally learns by writing software to handle your tasks.
Old Agent Way
"Always remember that when I ask you to process an invoice, you need to check these 3 fields first. Adding this to the 10,000-token project instructions."
Buffaly Way
"Next time I ask you to process an invoice, check those 3 fields first. Write a new ProtoScript action for this workflow and save it to your capabilities."
You don't need every tool in the prompt
Buffaly can search your workspace by meaning, enumerate available skills dynamically, and load a concrete action just in time to call it. Exact internal names can help, but they are not required for normal use.
Old prompt
Here is every tool, command, MCP server, and workflow. Always pick from this list.
Better Buffaly prompt
Update the docs page at this exact path using this source of truth. Preserve route and nav conventions. Edit only that file. Validate scoped status and report evidence.
Semantic discovery
Actions and entities in Buffaly have semantic tags. Instead of writing API requests, you just name the outcome, target entity, or environment, and let Buffaly natively discover and map the right tools for the job.
"Investigate why the Gemini provider route is failing. Do not print secrets. Inspect provider configuration, runtime status, logs, loaded services, and recent session evidence. Report the exact route checked, whether the provider and model settings are loaded, what error was observed, and the safest next fix."
Expected behavior: Buffaly dynamically binds the phrase "Gemini provider route" to the relevant runtime objects, avoids exposing secret values, inspects source evidence, and distinguishes between complete, blocked, and progress-only states.
Structured memory, not prompt stuffing
Use memory for durable facts and reusable workflows. It is not a place to hide credentials or paste every future instruction.
Good memory candidates
- Repo roots, wiki roots, and default install paths.
- Project roles, preferences, contacts, accounts, and environments.
- Reusable workflows with inputs, steps, validation, risks, and completion rules.
Wrong memory boundary
Do not store credentials here. Secret values belong in configured secret storage and should never be injected into prompts, wiki pages, task artifacts, logs, or commits.
Typed and native before CLI
Prefer a typed or native route when the task involves filesystem, session, provider, wiki, SQL, HTTP, browser, secret, or semantic tools and a typed route exists.
Prefer typed/native when:
- Strict parameters or structured validation are needed.
- The audit trail needs to be highly traceable.
- Secrets/PHI must be processed without hitting the LLM context.
Use CLI / Shell when:
- The command is the authoritative interface (e.g., git).
- Local diagnostics require command output.
- No typed route exists yet.
MCP and services
Model Context Protocol (MCP) is supported, but it is not Buffaly’s whole integration model. Do not force every integration through MCP. Buffaly natively prefers typed code over generic CLI tools and can call native tools, prompt actions, ProtoScript actions, and non-MCP services.
MCP server binding
An MCP binding can be a service instance with endpoint, process command, transport, auth source, capability set, filesystem root, and intended use. Good for external tool boundaries.
Native Service boundary
A service represents lifecycle, identity, state, config, and method boundaries. Use a native service when lifecycle, state, or multiple internal methods matter.
The Integration Philosophy
You might notice Buffaly doesn't have 100 out-of-the-box integrations for consumer apps or every single chat provider on the market. This is deliberate.
1. Different Domain Focus
Buffaly isn't a personal assistant built to summarize your emails. It is built for complex, deterministic, audit-heavy enterprise workflows (like medical revenue cycles and back-office automation). We prioritize deep, native capability over shallow API wrappers.
2. Proving an Architecture
Buffaly exists to prove that AI can scale safely by strictly separating reasoning from execution. We are establishing a high-trust paradigm, not competing with standard chatbot feature lists.
3. Open and Extensible
Because Buffaly is a platform to build upon, you don't need us to write an integration for you. If you need a specific internal tool, API, or provider, you can build a Service or ProtoScript action for it in minutes.
4. Lean Maintenance
Buffaly is created and maintained by a single developer (Matt) alongside Buffaly itself. Integrations will grow as time permits and as the community contributes.
Sessions carry the work
Sessions preserve timeline evidence, artifacts, status, parent and child relationships, queued work, provider and model settings, Plan, Scratch, and task artifacts. Use them instead of treating every chat as isolated.
"Continue the previous provider troubleshooting session. Inspect timeline evidence, Plan, Scratch, task artifacts, queued work, provider settings, and scoped status before acting. Summarize the last completed step first."
"Create or update a durable task artifact with target paths, source evidence, decisions, validation, blockers, and the next safe step."
Verification (Stop assuming it worked)
- Which implementation or source files were inspected?
- What is the exact absolute target path?
- What does scoped git status show?
- Was checked-in design compared with deployed behavior?
- Is the result complete, blocked, or only progress?
- Is there a validation result, artifact path, or commit hash?
Practical old habit versus Buffaly habit
| Area | Old habit | Buffaly habit |
|---|---|---|
| Documentation work | Paste all docs rules and hope the agent follows them. | Name source, target file, constraints, route conventions, and validation evidence. |
| Provider troubleshooting | Ask for guesses based on logs pasted into chat. | Ask Buffaly to inspect provider settings, runtime status, diagnostics, and source evidence without revealing secrets. |
| Remembering context | Add another paragraph to a project prompt. | Store durable facts and workflows in memory with clear boundaries and validation rules. Tell it to rewrite its own code. |
| MCP integration | Wrap every operation as an MCP tool. | Use MCP for external boundaries; use services or actions when lifecycle, identity, or simpler stateless execution fits better. |
Common migration mistakes
- Prompt stuffing instead of structured memory.
- Static tool thinking instead of semantic discovery.
- Shell by default when a typed route is safer.
- MCP absolutism.
- Ignoring sessions, Plan, Scratch, timelines, and task artifacts.
- Skipping validation because an answer sounds plausible.
- Storing secrets or volatile details in normal memory.
- Overbuilding extensions when a service, action, or existing tool already fits.
Troubleshooting
| Symptom | First check | Good next prompt |
|---|---|---|
| Wrong tool | Did Buffaly bind the target and search likely actions or entities? | "Inspect the target and load the safest typed action before using shell." |
| Asks a question too early | Was safe discovery already done? | "Inspect obvious files, logs, sessions, and entities first; ask only if ambiguity remains consequential." |
| Not evidence-based | Paths, scoped status, validation, artifacts, or commit hash. | "Show the exact evidence for the answer and whether it is complete or blocked." |
| Interrupted work | Session timeline, Plan, Scratch, task artifacts, queued work. | "Continue from the prior session and summarize the last completed step before acting." |
| Provider or model route fails | Provider settings, model selection, runtime diagnostics, logs, secret source. | "Diagnose provider route without printing secrets and report loaded settings plus observed error." |
| Integration feels like it needs MCP | Lifecycle, identity, state, config, method grouping, external boundary. | "Recommend MCP, service, native tool, or ProtoScript action based on boundary and validation needs." |