This page is the beginner vocabulary and mental-model reference for technical users who use, operate, or extend Buffaly. It explains how Buffaly thinks, how memory works, and how to structure your requests for predictable outcomes.
The practical mental model
Buffaly is a session-based agent environment. You ask for an outcome in natural language, and the Buffaly agent turns that request into evidence-based, tool-assisted work. Here is how Buffaly processes a request:
- Target Binding: It maps your approximate words to concrete files, routes, docs, entities, or runtime objects.
- Discovery: If the route is not obvious, it searches for candidate actions, skills, or entities.
- Action Loading: It loads the typed domain tool, ProtoScript action, or service that fits the task.
- Execution & State: It takes the smallest safe step and preserves short-term route state in its Plan and Scratch.
- Validation: It validates important results with concrete evidence before presenting a final answer.
Anatomy of a strong request
You do not need to list every internal tool name in your prompt. Instead, provide Buffaly with the outcome, the source of truth, the target, safety boundaries, and validation expectations.
What should be true when done.
Docs, code, logs, or ticket to trust.
Exact file, route, or environment.
What Buffaly may NOT touch.
Evidence that proves it is ready.
| Weak request | Better request |
|---|---|
| Fix the docs page. | Improve Buffaly.Web/Pages/Site/Docs/WorkingWithBuffaly.cshtml using the staging wiki source. Edit only that file, validate scoped git status, and do not commit unless I ask. |
| Clean this up. | Read-only first: inspect the exact files and summarize what should be removed. Do not delete, stage, or commit anything until I approve the plan. |
Sessions and timelines
A session is the working container for a conversation or delegated task. It can have runtime status, provider/model settings, queued work, artifacts, child-session relationships, and a timeline.
The timeline is the chronological evidence stream: user messages, assistant progress, tool calls, tool results, validation evidence, and final answers.
- Ask Buffaly to continue prior work instead of restating everything.
- Ask what evidence was inspected before trusting a result.
- Ask for artifacts, changed files, or commit hashes when work should be reviewable.
Plan, Scratch, and task artifacts
Buffaly uses several layers of working memory. They are not interchangeable. A Plan is not a document draft. Scratch is not durable memory. A task artifact is not a substitute for a final answer.
| Layer | User-facing purpose | When you should care |
|---|---|---|
| Plan | Short current route: current step, next step, done, blocked. | When work has multiple steps or could drift. |
| Scratch | Free-form session notes, evidence, hypotheses, and pivots. | When investigation is ongoing. |
| Task artifact | Durable markdown record with scope, acceptance criteria, decisions, and evidence. | When work spans turns, child sessions, or interruptions. |
| Timeline | Full chronological evidence stream. | When reviewing what actually happened. |
| Artifacts | Saved files or outputs. | When an output must be inspected, reused, or committed. |
Tools, actions, and skills
Tool
A callable runtime surface. A tool call is the actual execution step, such as reading a file, searching, running validation, or writing a result.
Action
A named operation with typed input/output. Actions can be discovered by semantic phrases, loaded when needed, and then called as tools.
Skill
A grouped capability area. Skills make the action space navigable across file system, process, coding, sessions, secrets, wiki, SQL, browser automation, and more.
Extension boundaries
Don't over-engineer. Use the smallest extension that fits your need:
Prompts & ProtoScript
- Memory: Remember a workflow if the procedure is still evolving.
- Prompt Action: Create a prompt action when stable instructions are the main asset.
- ProtoScript Action: Create a ProtoScript action when typed parameters, validation, or executable logic matter.
Services
- Create a Service when identity, lifecycle, configuration, state, or related methods matter.
- MCP server bindings, SQL connections, Workspace/Account integrations belong here.
Note: MCP is one service exposure path, not Buffaly's whole integration model. Buffaly natively prefers typed native code over generic CLI tools.
Memory and ontology
Buffaly memory is explicit, structured knowledge the Buffaly agent can use later. It is different from dumping more text into a prompt.
| Need | Best fit |
|---|---|
| Current notes or hypotheses | Scratch or a task artifact |
| Durable fact, preference, contact, account, or environment detail | Ontology memory |
| Repeatable procedure | Workflow memory |
| Password, API key, OAuth token, or connection secret | User secrets (Do not use normal memory) |
| Stable callable behavior | Prompt action, ProtoScript action, service, or skill |
Verification & Progress vs Final
Buffaly may produce structured UI results before it is finished. Do not treat a progress update as a final answer. A task is only done when you receive concrete verification.
| Result type | What it means | How to respond |
|---|---|---|
| Status update | Work is underway or waiting on a check. | Do not treat it as completion if safe work remains. |
| Final answer | The task is complete or blocked. | Demand evidence: path checks, diffs, git status, or commit hashes. |
Questions to ask to verify work:
Troubleshooting & Common Mistakes
| Symptom / Mistake | First check | Good next prompt / Fix |
|---|---|---|
| Stuck work / Task dropped | Runtime status, queued work, timeline. | "Show whether the session is running, queued, blocked, or complete before I add input." |
| Too many questions | Did Buffaly inspect the obvious files/logs first? | "Do safe discovery first, then ask only if the ambiguity changes the action." |
| Edited wrong place | Absolute target path, route, scoped git status. | "Stop and show the exact files changed before making any more edits." |
| Unrelated commit risk | Scoped git status, staged files. | "Stage only the named files and show the exact commit hash afterward." |
| Asking Buffaly to use shell | Is there a typed/native tool? | Do not force CLI commands unless absolutely necessary. Buffaly prefers typed native paths. |
| Secrets exposed | Are credentials in normal memory or docs? | "Do not reveal secrets; identify storage risk and move them to the credential store." |