Documentation
¶
Overview ¶
Package prompt deterministically renders the coding agent's stable system prompt, discovers the instruction files and environment that make up its dynamic context, and renders those as model-visible attachments. It does not own session state.
Index ¶
- Constants
- func BuildSystem(opts SystemOptions) string
- func ContextRevision(env Environment, contextFiles []ContextFile) string
- func RenderBaseContext(env Environment, contextFiles []ContextFile) string
- func RenderContextUpdate(revision string, env Environment, contextFiles []ContextFile) string
- func RenderSkillListing(revision string, skills []SkillInfo) string
- func RenderSkillsUpdate(revision string, current []SkillInfo, delta SkillsDelta) string
- type ContextFile
- type ContextScope
- type Environment
- type SkillInfo
- type SkillsDelta
- type SystemOptions
- type ToolInfo
Constants ¶
const DefaultInstructions = "You are Or, a coding agent. " +
"Use the available tools to inspect and modify files and run commands. " +
"Make focused changes, verify your work, and report what you did concisely."
DefaultInstructions is the baseline preamble used when SystemOptions.Instructions is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildSystem ¶
func BuildSystem(opts SystemOptions) string
BuildSystem assembles the stable system prompt from opts. Dynamic instruction files, environment, and skill listings deliberately do not belong here; keeping those out lets a session preserve its provider prompt-cache prefix.
func ContextRevision ¶
func ContextRevision(env Environment, contextFiles []ContextFile) string
ContextRevision fingerprints the model-visible environment and instruction state. Callers compare revisions to decide whether a refresh is needed, so it must depend on exactly what RenderBaseContext shows and nothing else.
func RenderBaseContext ¶
func RenderBaseContext(env Environment, contextFiles []ContextFile) string
RenderBaseContext renders the session's environment together with its instruction files. It is stable for one context epoch; RenderContextUpdate supersedes it when either input changes.
func RenderContextUpdate ¶
func RenderContextUpdate( revision string, env Environment, contextFiles []ContextFile, ) string
RenderContextUpdate renders a bounded, self-contained refresh of the environment and instruction files. Like a skills update it carries complete current state, so this single block supersedes the base context and every earlier update without the model replaying a delta history.
func RenderSkillListing ¶
RenderSkillListing renders the initial discovery snapshot. An empty Skill set has neither a listing attachment nor a Skill tool.
func RenderSkillsUpdate ¶
func RenderSkillsUpdate( revision string, current []SkillInfo, delta SkillsDelta, ) string
RenderSkillsUpdate renders a bounded, self-contained refresh. It identifies what changed but also includes the complete current listing; this single block supersedes all earlier skill listings and updates.
Types ¶
type ContextFile ¶
type ContextFile struct {
Path string
Content string
Scope ContextScope
}
ContextFile is one instruction document rendered into model-visible context. Files must arrive in precedence order, broadest first and most specific last.
func LoadContextFiles ¶
func LoadContextFiles(root string) []ContextFile
LoadContextFiles discovers every instruction file that applies to a workspace, broadest first so the most specific instructions read last:
- the user-level file under ~/.or, applied to every workspace;
- one project file per directory from the filesystem root down to the workspace root;
- the workspace root's local, uncommitted file.
Files that cannot be read are skipped.
type ContextScope ¶
type ContextScope string
ContextScope identifies where an instruction file was discovered. Scope is model-visible so precedence remains explicit when different layers use the same filename.
const ( ScopeUser ContextScope = "user" ScopeProject ContextScope = "project" ScopeLocal ContextScope = "local" )
type Environment ¶
type Environment struct {
// Cwd is the session's tool root. It may be an isolated scratch directory,
// not a user-selected project.
Cwd string
// OS and Arch are the Go runtime's platform identifiers, e.g. "darwin" and
// "arm64". Shell commands differ between platforms, so the model needs them.
OS string
Arch string
// Shell is the user's login shell, e.g. "/bin/zsh". Empty when unknown.
Shell string
// Date is the local calendar date in YYYY-MM-DD form. A model's training
// cutoff makes it a poor source for "today".
Date string
// GitRepo reports whether the workspace is inside a Git working tree.
GitRepo bool
// GitBranch is the checked-out branch, or a short commit for a detached
// HEAD. Empty when the workspace is not a repository or HEAD is unreadable.
GitBranch string
}
Environment is the ambient machine state a coding agent has to know before it can write a correct shell command or reason about dates. It is captured from the host rather than guessed by the model, and it is refreshed with the rest of the session context, so a session that crosses midnight or switches branch does not keep reporting stale values.
func DetectEnvironment ¶
func DetectEnvironment(root string) Environment
DetectEnvironment captures the environment for a session's tool root. Git state is read directly from the repository's HEAD file rather than by running git: it avoids a subprocess on a hot path, and it cannot report a working tree as clean when it is not, because it never claims to know.
type SkillInfo ¶
SkillInfo is the discovery metadata advertised before a skill is loaded. Complete instructions remain behind the skill tool.
type SkillsDelta ¶
SkillsDelta describes the discovery changes included in a skills-update attachment. Current state is rendered separately in the same attachment so a model never has to replay an unbounded delta history.
type SystemOptions ¶
type SystemOptions struct {
// Instructions is the base preamble that opens the prompt.
Instructions string
// Tools are the active tools' prompt contributions, in advertise order.
Tools []ToolInfo
}
SystemOptions are the stable inputs to BuildSystem. A coding session captures them at construction; instruction files, environment, and skill listings are rendered separately as dynamic context.
type ToolInfo ¶
type ToolInfo struct {
// Name is the tool's advertised name.
Name string
// Guidelines are bullets appended to the Tool guidelines section.
Guidelines []string
}
ToolInfo is a tool's contribution to the system prompt. A tool's own description travels in its schema; only cross-tool rules that no single schema can state belong here.
Source Files