How to manage a master prompt
Maintain baseline behavior for a named Buffaly agent profile without blindly editing implementation files.
Use this when inspecting, reviewing, or changing default operating rules, tool-selection preferences, validation expectations, response style, or escalation behavior. If the instruction is reusable task guidance, use a workflow memory or prompt action. If it is situational, use a context prompt. Durable facts belong in ontology memory or protected secret storage as appropriate.
Quick answer
Agent profiles are loaded from the active project Agents directory as *.agent.json. Each profile can point to a project-relative PromptFile, usually under Prompts.
For the checked-in default Buffaly profile, the profile file is content/projects/OpsAgent/Agents/buffaly-agent.agent.json and it points to Prompts/master.md.
Runtime profile hydration resolves that file to master prompt text. Session initialization stores the resolved master prompt on the session. The final system prompt is composed from the master prompt text, optional context prompt overlay, runtime path information, structured progress-update rules, and ontology or entity context selected by the session root entity and action configuration.
What a master prompt is
A master prompt is the baseline instruction contract for a Buffaly agent profile. It defines role, durable operating rules, safety posture, tool-selection preferences, planning expectations, response style, and escalation or question behavior.
It is not every instruction the Buffaly agent sees. Runtime can add context prompts, path sections, ontology summaries, tool schemas, session state, and user messages after the master prompt loads.
A good master prompt answers
- What role should this agent profile play?
- What safety boundaries should it always respect?
- How should it choose tools and validate work?
- When should it ask a question or escalate?
- What response style should future sessions follow?
- What belongs somewhere else instead?
Master prompt versus nearby concepts
| Layer | Use it for | Change when |
|---|---|---|
| Master prompt | Durable baseline behavior for a named agent profile. | Every new session for that profile should follow the rule. |
| Context prompt | Situational overlay for a session, task, environment, or operating mode. | The behavior should apply only in a specific context. |
| Prompt skill or action | Reusable task instruction or workflow. | Users should be able to invoke the workflow by intent. |
| Plan, Scratch, Tasks | Current route, working notes, durable task scope, acceptance, and validation. | The instruction is about current work, not baseline behavior. |
| Ontology memory | Durable facts, preferences, contacts, accounts, repos, environments, and workflows. | The information is stable knowledge, not prompt wording. |
| Secrets | Credentials and sensitive values in protected storage. | The value is private, credential-like, or environment-sensitive. |
Where master prompts live
In the active source tree, agent profiles are project-scoped files under Agents/*.agent.json, and prompt text is commonly stored under Prompts/*.md.
- The profile loader opens the active project Agents directory and reads *.agent.json.
- PromptFile resolves relative to the project root.
- The prompt file is read and trimmed into profile.MasterPrompt.
- Sessions use the resolved master prompt during initialization.
- The final system prompt composes the base master prompt with context and runtime sections.
Different installs and project roots can vary. Verify the active project name, root, and profile before editing.
Inspect the current master prompt
Inspect the active agent profile and master prompt. Show the profile path, prompt path, and a summary of behavior rules. Do not edit anything.
Manual pattern
- Identify the active project and agent name.
- Open the matching Agents/<agent>.agent.json.
- Read PromptFile and resolve it relative to the project root.
- Read the prompt file.
- Check whether the current session has an explicit master-prompt override.
For the default profile, inspect content/projects/OpsAgent/Agents/buffaly-agent.agent.json and content/projects/OpsAgent/Prompts/master.md.
Change a master prompt safely
Update the default Buffaly agent master prompt to clarify that docs work must use the active wiki path, not stale staging paths. Inspect the profile first. Edit only the prompt file if appropriate. Preserve existing behavior. Validate that the profile resolves, show the diff, and commit only the intentional prompt/profile change if I approve.
- Confirm the correct repo and active project root.
- Confirm the target profile and PromptFile.
- Use backup, git diff, or an equivalent review path before editing.
- Make the smallest change that solves the baseline behavior issue.
- Do not add secrets, private machine values, or one-off task state.
- Do not change unrelated behavior, profile metadata, action roots, or provider settings.
- Re-read the prompt and validate the profile resolves with non-empty master prompt text.
- Start or refresh a test session and run a focused behavior check.
- Commit only prompt or profile files when a commit is requested.
New versus existing sessions
Session initialization stores the resolved MasterPrompt. Exact effect depends on creation, restore, and override behavior.
- A master prompt edit definitely affects newly initialized sessions that load the edited profile.
- An already-running session may not use the new file.
- If an explicit override exists, verify whether that override is still in effect.
Show whether this session is using the current profile master prompt, a stored older master prompt, or an explicit override. If needed, start a fresh test session for the edited profile.
Test behavior after a change
Tool-selection rule
Ask for a small task where Buffaly should prefer a typed tool before shell.
Docs path rule
Ask for a dry-run target path validation before any edit.
Output format rule
Ask for a tiny final answer and verify it follows the profile’s style.
Safety rule
Ask for a destructive action and verify Buffaly asks, refuses, or escalates as expected.
Report profile path, prompt path, a short excerpt of the changed rule, the test request, observed behavior, scoped git status, and no commit unless I ask.
Rollback
- Stop making prompt edits.
- Inspect the diff or commit that introduced the behavior.
- Revert the prompt file to the last known-good version.
- Start a fresh test session and verify the bad behavior is gone.
- Commit the rollback separately when a commit is needed.
If the issue appears only in an existing session, verify whether that session has a stored older master prompt, a prompt override, or a different profile.
Common mistakes
Troubleshooting
| Symptom | First checks | Good next action |
|---|---|---|
| New behavior absent | Active profile, resolved PromptFile, fresh session, override state. | Start a fresh test session and show the resolved master prompt source. |
| Prompt file not found | Project root, profile path, PromptFile relative path. | Resolve the prompt path from the active project root and verify it exists. |
| Context-specific behavior unchanged | Context prompt, session overlay, user request, and task artifacts. | Check whether the behavior belongs in a context prompt instead. |
| Tool access changed unexpectedly | Profile metadata, action roots, provider settings, loaded tools. | Compare profile metadata separately from prompt text changes. |
| Prompt includes private data | Prompt file, git diff, logs, memory, task artifacts. | Remove the data, rotate credentials if needed, and move secrets to protected storage. |