warp

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 30, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

README

warp

The warp package implements the Workspace Agent Resource Protocol (WARP) — a provider-agnostic, declarative format for defining AI agents and their supporting resources.

License

Warp is not tied to any particular LLM provider, orchestration framework, or runtime. Any tool that understands the format can load and execute the same resource files unchanged.

Getting Started

To add warp to your Go project:

go get github.com/your-username/warp

(Replace your-username with the appropriate repository path once hosted.)

File Format

---
apiVersion: warp/v1alpha1
kind: Agent            # Agent | Skill | Command
metadata:
  name: my-agent
  description: A helpful assistant.
spec:
  models: ["gpt-4o"]
  temperature: 0.7
  skills:
    - skills/finance.md
  commands:
    - cmd/report.md
---

# My Agent

You are a helpful assistant that specializes in financial analysis...

Resource Kinds

Kind Purpose
Agent An autonomous agent with LLM configuration and references to the skills and commands it may invoke.
Skill A bundle of expertise guidelines for a specific domain. Agents load skills to adopt a persona or follow conventions.
Command A discrete, reusable operation an agent can invoke (e.g. "generate a report").

Loading Resources

OS filesystem — default directory
// Loads from .agents/ in the current working directory.
registry, err := warp.LoadDefault()
if err != nil {
    log.Fatal(err)
}

if err := registry.Validate(); err != nil {
    log.Fatal(err)
}
OS filesystem — custom directory
registry, err := warp.Load("/custom/path")
Custom fs.FS (embedded assets, testing, etc.)
//go:embed testdata
var testFS embed.FS

registry, err := warp.NewLoader(testFS).Load()

Directory Layout

The default root directory is .agents. Inside it, resources are organised by kind into three sub-directories:

.agents/
├── cmd/              # Command definitions
│   └── report.md     # kind: Command
├── defs/             # Agent definitions
│   └── analyst.md    # kind: Agent
└── skills/           # Skill definitions
    └── finance.md    # kind: Skill

API Reference

Types
  • Registry – holds parsed resources indexed by their FS-relative path.
    • Agents, Skills, Commands — typed maps.
    • Validate() error — checks required fields and resolves Agent cross-references.
  • Loader – walks an fs.FS and parses every .md file it finds.
    • NewLoader(fsys fs.FS) *Loader
    • Load() (*Registry, error)
  • Load(root string) (*Registry, error) — loads resources from the given OS filesystem path.
  • LoadDefault() (*Registry, error) — loads resources from the default .agents directory in the current working directory.
  • Parse(content string) (*ParseResult, error) — parses a single warp Markdown string and returns the typed resource.

Validation & Tooling

CLI Tool

Warp includes a CLI tool for validating your resources and workspaces.

# Build the tool
go build -o warp ./cmd/warp

# Validate a workspace
./warp validate .
JSON Schema

A JSON Schema is available at schema/warp.json to provide real-time validation and autocompletion in IDEs like VS Code.

To use it in VS Code, add the following to your settings (requires the YAML extension):

"yaml.schemas": {
  "https://raw.githubusercontent.com/masterkeysrd/warp/main/schema/warp.json": [
    "**/.agents/**/*.md",
    "**/AGENT.md",
    "**/WORKSPACE.md"
  ]
}

Contributing

We welcome contributions! Please see the CONTRIBUTING.md file (if available) or open an issue to discuss your proposed changes.

License

This project is licensed under the Apache License 2.0.

Documentation

Overview

Package warp implements the Workspace Agent Resource Protocol (WARP) — a provider-agnostic, declarative format for defining AI agents and their supporting resources.

Warp is not tied to any particular LLM provider, orchestration framework, or runtime. Any tool that understands the format can load and execute the same resource files unchanged.

File Format

Each warp resource is either a Markdown file (delimited by "---") or a pure YAML/YML configuration file.

For Markdown files, the YAML front-matter carries metadata and configuration, while the Markdown body below the closing delimiter becomes the resource's Instructions field. 

---
apiVersion: warp/v1alpha1
kind: Agent
metadata:
  name: my-agent
  description: A helpful assistant.
spec:
  models: ["gpt-4o"]
  temperature: 0.7
  skills:
    - skills/finance.md
  commands:
    - cmd/report.md
---

# My Agent

You are a helpful assistant that specialises in...

Resource Kinds

Nine resource kinds are supported: 

Workspace      – root authority for the session; declares active projects
                 (WORKSPACE.md, optionally without front-matter).
Context        – identity and instructions for a project scope
                 (AGENT.md, optionally without front-matter).
Agent          – an autonomous agent with model configuration and references
                 to skills and commands it may use.
Skill          – a bundle of expertise guidelines for a specific domain.
Command        – a discrete, reusable operation an agent can invoke.
ModelProvider  – configuration for an LLM provider.
Tool           – a custom tool definition.
MCP            – a Model Context Protocol server configuration.
Toolkit        – a collection of referenced or inline tools.

Loading Resources

Use LoadDefault to start discovery from the current working directory: 

ws, err := warp.LoadDefault()

Use Load to specify a custom starting directory: 

ws, err := warp.Load("/custom/path")

Use LoadWorkspace for explicit control over the starting directory: 

ws, err := warp.LoadWorkspace("/absolute/path")

After loading, call [Workspace.Validate] to verify structural correctness and resolve cross-references declared inside Agent specs.

Index

Constants

View Source 
const (
	// DefaultAgentsDir is the subdirectory that contains Agent, Skill, and
	// Command resource files, both at the workspace root (global) and inside
	// each project directory (local).
	DefaultAgentsDir = ".agents"

	// WorkspaceFileName is the name of the file that defines the workspace
	// root authority.
	WorkspaceFileName = "WORKSPACE.md"

	// ContextFileName is the name of the file that defines a project's
	// identity and instructions.
	ContextFileName = "AGENT.md"

	// MarkdownExt is the file extension that the loader looks for when
	// walking the filesystem. Only files with this extension are parsed as
	// warp resources.
	MarkdownExt = ".md"
)
View Source 
const (
	// NamespaceLocal is the highest-priority namespace, corresponding to
	// project-local .agents/ resources.
	NamespaceLocal = "local"

	// NamespaceWorkspace corresponds to workspace-global .agents/ resources
	// (only populated when projects are sub-directories).
	NamespaceWorkspace = "workspace"

	// NamespaceUser corresponds to user-level configuration resources.
	NamespaceUser = "user"

	// NamespaceSystem corresponds to embedded builtin resources shipped with
	// the runtime.
	NamespaceSystem = "system"
)

Standard namespace identifiers. These are reserved; plugins must not use them.

View Source 
const (
	// APIVersion is the expected apiVersion value in all resource front-matter.
	APIVersion = "warp/v1alpha1"
)

Variables

This section is empty.

Functions

func MakeQualifiedName 

func MakeQualifiedName(namespace string, kind Kind, name string) string

MakeQualifiedName constructs the "namespace/Kind/name" qualified name.

func NamespacePriority 

func NamespacePriority(ns string) int

NamespacePriority returns the numeric priority for a namespace name. Unknown namespaces return 0.

func Render added in v0.0.2 

func Render(res Resource, opts *RenderOptions) (string, error)

Render processes the resource's instructions as a template. It supports both standard Go text/template syntax ({{.Name}}) and a convenient shorthand syntax ($Name, $1).

Types

type Agent 

type Agent struct {
	BaseResource `yaml:",inline"`
	// Spec holds the agent-specific configuration.
	Spec AgentSpec `yaml:"spec"`
}

Agent is a warp resource that describes an autonomous agent: its LLM configuration, persona instructions, and the set of skills and commands it may invoke at runtime.

func (*Agent) DeepCopy 

func (in *Agent) DeepCopy() *Agent

DeepCopy returns a deep copy of the Agent.

type AgentSpec 

type AgentSpec struct {
	// Extends is the Qualified Name or Short Name of another Agent resource to
	// inherit from. When set, the engine merges the parent's skills and tools
	// arrays (parent first) and prepends the parent's instructions to this
	// agent's instructions.
	Extends string `yaml:"extends,omitempty"`
	// Instructions is the persona prompt populated from the Markdown body of
	// the file (below the closing front-matter delimiter).
	Instructions string `yaml:"instructions"`
	// Triggers defines the architectural constraints on what can invoke this agent
	// (e.g., "human", "agent"). An empty list means the agent can be triggered
	// by anything.
	Triggers []string `yaml:"triggers,omitempty"`
	// Models is a prioritized list of LLM model identifiers to use (e.g.,
	// ["gpt-4o", "claude-3-5-sonnet"]). The runtime should attempt to use the
	// first available model.
	Models []string `yaml:"models,omitempty"`
	// Temperature controls the randomness of the model's output (0.0–2.0).
	Temperature float64 `yaml:"temperature"`
	// Tools is a list of resource refs (names or paths) restricting which
	// Tool resources this agent may use. An empty list means no restriction.
	Tools []string `yaml:"tools,omitempty"`
	// Skills is a list of file paths (relative to the FS root) that reference
	// Skill resources this agent is allowed to use.
	Skills []string `yaml:"skills,omitempty"`
	// Commands is a list of file paths (relative to the FS root) that
	// reference Command resources this agent can invoke.
	Commands []string `yaml:"commands,omitempty"`
}

AgentSpec contains the configuration details for an Agent resource.

func (*AgentSpec) DeepCopy 

func (in *AgentSpec) DeepCopy() *AgentSpec

DeepCopy returns a deep copy of the AgentSpec.

type BaseResource 

type BaseResource struct {
	// APIVersion declares the schema version, e.g. "tasksmith/v1".
	APIVersion string `yaml:"apiVersion"`
	// Kind identifies the resource type.
	Kind Kind `yaml:"kind"`
	// Metadata holds the resource's name, description, and display name.
	Metadata Metadata `yaml:"metadata"`
	// Directory is the FS path of the directory that contains the resource
	// file. It is populated by the Loader and is never serialised to YAML.
	Directory string `yaml:"-"`
	// Namespace is the registry namespace this resource belongs to.
	// Set by the assembler; empty for resources loaded via the legacy
	// filesystem path.
	Namespace string `yaml:"-"`
}

BaseResource contains the fields that every resource kind shares. Embed it with `yaml:",inline"` so the top-level YAML keys are promoted into the enclosing struct.

func (*BaseResource) DeepCopy 

func (b *BaseResource) DeepCopy() *BaseResource

DeepCopy returns a deep copy of the BaseResource.

func (*BaseResource) GetKind 

func (b *BaseResource) GetKind() Kind

GetKind implements Resource.

func (*BaseResource) GetMetadata added in v0.0.2 

func (b *BaseResource) GetMetadata() Metadata

GetMetadata implements Resource.

func (*BaseResource) GetName 

func (b *BaseResource) GetName() string

GetName implements Resource.

func (*BaseResource) GetNamespace 

func (b *BaseResource) GetNamespace() string

GetNamespace implements Resource.

func (*BaseResource) QualifiedName 

func (b *BaseResource) QualifiedName() string

QualifiedName implements Resource.

func (*BaseResource) SetNamespace 

func (b *BaseResource) SetNamespace(ns string)

SetNamespace sets the namespace of this resource.

func (*BaseResource) ValidateBase 

func (b *BaseResource) ValidateBase() error

ValidateBase verifies that the mandatory front-matter fields are present and that Kind is a known value. It returns a descriptive error for the first failing check it encounters.

type Command 

type Command struct {
	BaseResource `yaml:",inline"`
	// Spec holds the command-specific configuration.
	Spec CommandSpec `yaml:"spec"`
}

Command is a warp resource that encapsulates a discrete, reusable operation an agent can perform. Its instructions are authored as the Markdown body of the defining file.

func (*Command) DeepCopy 

func (in *Command) DeepCopy() *Command

DeepCopy returns a deep copy of the Command.

type CommandSpec 

type CommandSpec struct {
	// Instructions is the directive prompt populated from the Markdown body
	// of the file (below the closing front-matter delimiter).
	Instructions string `yaml:"instructions"`
	// Models is a prioritized list of LLM model identifiers to use for this
	// command (e.g., ["gpt-4o-mini", "claude-3-haiku"]). Overrides agent defaults.
	Models []string `yaml:"models,omitempty"`
	// Tools is a list of resource refs (names or paths) restricting which
	// Tool resources can be used while executing this command.
	Tools []string `yaml:"tools,omitempty"`
	// Hints is an ordered list of argument hints (e.g., ["ticker", "year"])
	// that UIs can use for autocompletion and runtimes can use for positional
	// template substitution.
	Hints []string `yaml:"hints,omitempty"`
}

CommandSpec contains the configuration details for a Command resource.

func (*CommandSpec) DeepCopy 

func (in *CommandSpec) DeepCopy() *CommandSpec

DeepCopy returns a deep copy of the CommandSpec.

type Context 

type Context struct {
	BaseResource `yaml:",inline"`
	// Spec holds the context-specific configuration.
	Spec ContextSpec `yaml:"spec"`
}

Context is a warp resource that defines the identity, rules, and instructions for any agent operating within a project directory. It is the authoritative entry point for the directory scope it lives in.

A file named AGENT.md (case-insensitive) is automatically treated as a Context. If the file lacks YAML front-matter the loader infers the apiVersion, kind, and metadata.name fields automatically.

func (*Context) DeepCopy 

func (in *Context) DeepCopy() *Context

DeepCopy returns a deep copy of the Context.

type ContextSpec 

type ContextSpec struct {
	// Instructions is the directive text populated from the Markdown body of
	// the file (below the closing front-matter delimiter).
	Instructions string `yaml:"instructions"`
	// Resources is a list of paths to other Warp files to be explicitly
	// loaded into the context.
	Resources []string `yaml:"resources"`
}

ContextSpec contains the configuration details for a Context resource.

func (*ContextSpec) DeepCopy 

func (in *ContextSpec) DeepCopy() *ContextSpec

DeepCopy returns a deep copy of the ContextSpec.

type FSResourceProvider 

type FSResourceProvider struct {
	// contains filtered or unexported fields
}

FSResourceProvider loads resources from a filesystem rooted at a resource library directory. Workspace and Context resources are ignored.

func NewFSResourceProvider 

func NewFSResourceProvider(fsys fs.FS) *FSResourceProvider

NewFSResourceProvider returns a resource provider that loads from fsys.

func (*FSResourceProvider) LoadResources 

func (p *FSResourceProvider) LoadResources() (*ResourceSet, error)

LoadResources loads Agent, Skill, Command, ModelProvider, Tool, MCP, and Toolkit resources from the provider filesystem.

type Kind 

type Kind string

Kind identifies the resource type declared in a file's front-matter. 

const (
	// KindWorkspace represents a Workspace resource (WORKSPACE.md).
	KindWorkspace Kind = "Workspace"
	// KindContext represents a Context resource (AGENT.md).
	KindContext Kind = "Context"
	// KindAgent represents an Agent resource.
	KindAgent Kind = "Agent"
	// KindSkill represents a Skill resource.
	KindSkill Kind = "Skill"
	// KindCommand represents a Command resource.
	KindCommand Kind = "Command"
	// KindModelProvider represents an LLM Provider resource.
	KindModelProvider Kind = "ModelProvider"
	// KindTool represents a Custom Tool resource.
	KindTool Kind = "Tool"
	// KindMCP represents an MCP Server resource.
	KindMCP Kind = "MCP"
	// KindToolkit represents a Toolkit resource.
	KindToolkit Kind = "Toolkit"
)

func ParseQualifiedName 

func ParseQualifiedName(qn string) (namespace string, kind Kind, name string, ok bool)

ParseQualifiedName splits a qualified name of the form "namespace/Kind/name" into its three components. Returns ok=false when the input does not contain exactly two "/" separators.

type MCP 

type MCP struct {
	BaseResource `yaml:",inline"`
	// Spec holds the MCP-specific configuration.
	Spec MCPSpec `yaml:"spec"`
}

MCP is a warp resource that describes an MCP server.

func (*MCP) DeepCopy 

func (in *MCP) DeepCopy() *MCP

DeepCopy returns a deep copy of the MCP.

type MCPFilter 

type MCPFilter struct {
	Include []string `yaml:"include"` // Glob patterns for tools to expose
	Exclude []string `yaml:"exclude"` // Glob patterns for tools to block (applied after include)
}

MCPFilter defines the inclusion/exclusion rules for MCP tools.

func (*MCPFilter) DeepCopy 

func (in *MCPFilter) DeepCopy() *MCPFilter

DeepCopy returns a deep copy of the MCPFilter.

type MCPSpec 

type MCPSpec struct {
	Command     []string                  `yaml:"command"`     // Command to start the MCP server via stdio
	Env         map[string]string         `yaml:"env"`         // Environment variables for the MCP server
	Annotations *ToolAnnotation           `yaml:"annotations"` // Default safety profile for all exposed tools
	Tools       *MCPFilter                `yaml:"tools"`       // Controls which tools are exposed by this server
	Overrides   map[string]ToolAnnotation `yaml:"overrides"`   // Tool-specific annotation overrides (key is tool name)
}

MCPSpec contains the configuration details for an MCP resource.

func (*MCPSpec) DeepCopy 

func (in *MCPSpec) DeepCopy() *MCPSpec

DeepCopy returns a deep copy of the MCPSpec.

type Metadata 

type Metadata struct {
	// Name is the unique identifier for the resource within its kind.
	Name string `yaml:"name"`
	// Description is a short human-readable summary of the resource.
	Description string `yaml:"description"`
	// DisplayName is an optional pretty-printed label for UIs.
	DisplayName string `yaml:"displayName"`
	// Labels are arbitrary key-value pairs for categorisation and filtering.
	Labels map[string]string `yaml:"labels,omitempty"`
}

Metadata holds the identifying and descriptive fields shared by every resource kind. These fields map directly to the front-matter "metadata" block in a Markdown file.

func (*Metadata) DeepCopy 

func (in *Metadata) DeepCopy() *Metadata

DeepCopy returns a deep copy of the Metadata.

type ModelProvider 

type ModelProvider struct {
	BaseResource `yaml:",inline"`
	// Spec holds the provider-specific configuration.
	Spec ModelProviderSpec `yaml:"spec"`
}

ModelProvider is a warp resource that describes an LLM provider configuration.

func (*ModelProvider) DeepCopy 

func (in *ModelProvider) DeepCopy() *ModelProvider

DeepCopy returns a deep copy of the ModelProvider.

type ModelProviderSpec 

type ModelProviderSpec struct {
	Type         string            `yaml:"type"`         // e.g., "ollama", "openai", "anthropic"
	Endpoint     string            `yaml:"endpoint"`     // API base URL
	DefaultModel string            `yaml:"defaultModel"` // Model to use if none specified
	Auth         map[string]string `yaml:"auth"`         // e.g., type="env", key="OPENAI_API_KEY"
	Models       []ProviderModel   `yaml:"models"`       // Available models from this provider
}

ModelProviderSpec contains the configuration details for a ModelProvider resource.

func (*ModelProviderSpec) DeepCopy 

func (in *ModelProviderSpec) DeepCopy() *ModelProviderSpec

DeepCopy returns a deep copy of the ModelProviderSpec.

type NamespacedFSProvider 

type NamespacedFSProvider struct {
	// contains filtered or unexported fields
}

NamespacedFSProvider wraps an fs.FS and presents its Agent, Skill, Command, ModelProvider, Tool, MCP, and Toolkit files as a NamespacedProvider.

func NewNamespacedFSProvider 

func NewNamespacedFSProvider(fsys fs.FS, namespace string, priority int) *NamespacedFSProvider

NewNamespacedFSProvider returns a provider that loads resources from fsys and tags them all with the given namespace and priority.

func (*NamespacedFSProvider) GetResources 

func (p *NamespacedFSProvider) GetResources(ctx context.Context) ([]Resource, error)

GetResources implements NamespacedProvider.

func (*NamespacedFSProvider) Namespace 

func (p *NamespacedFSProvider) Namespace() string

Namespace implements NamespacedProvider.

func (*NamespacedFSProvider) Priority 

func (p *NamespacedFSProvider) Priority() int

Priority implements NamespacedProvider.

type NamespacedProvider 

type NamespacedProvider interface {
	// Namespace returns the namespace all resources from this provider belong to.
	Namespace() string
	// Priority returns the numeric priority. Higher values beat lower ones.
	Priority() int
	// GetResources returns all resources this provider contributes.
	GetResources(ctx context.Context) ([]Resource, error)
}

NamespacedProvider loads resources for a specific namespace with a defined priority. When multiple providers supply a resource with the same qualified name, the one with the highest Priority wins.

type ParseResult 

type ParseResult struct {
	// Kind is the resource kind decoded from the front-matter.
	Kind Kind
	// Resource is the fully-typed resource pointer (*WorkspaceDef, *Context,
	// *Agent, *Skill, or *Command).
	Resource any
	// Inferred is true when the resource metadata was inferred rather than
	// read from an explicit YAML front-matter block. This happens when a
	// WORKSPACE.md or AGENT.md file is loaded without front-matter delimiters.
	Inferred bool
}

ParseResult is the output of a successful Parse call. It carries the detected resource Kind and the fully-decoded, typed resource value.

func Parse 

func Parse(filePath, content string) (*ParseResult, error)

Parse splits a warp Markdown file into its YAML front-matter and Markdown body, decodes the resource kind, unmarshals the appropriate typed struct, and injects the body text as the resource's Instructions field.

filePath is the path of the file relative to the loader root. It is used to detect special files that may omit the YAML front-matter block:

  • WORKSPACE.md (case-insensitive) is inferred as a Workspace resource.
  • AGENT.md (case-insensitive) is inferred as a Context resource.

A valid warp file has the form: 

---
apiVersion: warp/v1alpha1
kind: Agent
...
---
# Markdown instructions here

Parse returns an error if the delimiters are absent (and the file is not a special inferred kind), the front-matter is malformed, or the kind is unsupported.

type Project 

type Project struct {
	// Name is the slug identifier derived from the project's path.
	Name string

	// Path is the project's path relative to the workspace RootPath.
	Path string

	// RootPath is the absolute filesystem path of the workspace root.
	// Stored here so AbsPath() works without a back-pointer to Workspace.
	RootPath string

	// Context is the parsed AGENT.md resource for this project. Nil when no
	// AGENT.md was found.
	Context *Context
}

Project holds metadata for a single project directory discovered during workspace loading. Resources for the project are stored in the Registry under the project's slug namespace.

func (*Project) AbsPath 

func (p *Project) AbsPath() string

AbsPath returns the absolute filesystem path to the project directory.

func (*Project) DeepCopy 

func (p *Project) DeepCopy() *Project

DeepCopy returns a deep copy of the Project.

type ProviderModel 

type ProviderModel struct {
	ID     string              `yaml:"id"`     // Unique model ID (e.g., "gpt-4")
	Name   string              `yaml:"name"`   // Model name (e.g., "gpt-4")
	Label  string              `yaml:"label"`  // Human-friendly label (e.g., "GPT-4")
	Limits ProviderModelLimits `yaml:"limits"` // Context and output token limits
}

ProviderModel describes a specific model available from a provider.

type ProviderModelLimits 

type ProviderModelLimits struct {
	Context int `yaml:"context"` // Max context length in tokens
	Output  int `yaml:"output"`  // Max output length in tokens
}

ProviderModelLimits defines the token limits for a specific model.

type QueryOptions 

type QueryOptions struct {
	// Kinds filters by resource kind. An empty slice matches all kinds.
	Kinds []string
	// Namespaces filters by namespace. An empty slice matches all namespaces.
	Namespaces []string
	// Effective applies shadowing: when true, only the highest-priority
	// namespace version of each short name is returned.
	Effective bool
}

QueryOptions controls how ListResources filters and deduplicates results.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry is the base resource store, safe for concurrent use. Resources are keyed by their qualified name ("namespace/Kind/name"). Project-local resources are stored using the project slug as their namespace — the "local" constant is a virtual alias, never stored literally.

Consumers interact either through the base Registry (workspace-root scope: workspace/user/system only) or through a ScopedRegistry obtained via Project(), which elevates a specific project namespace to the top priority.

func Assemble 

func Assemble(ctx context.Context, providers []NamespacedProvider) (*Registry, error)

Assemble builds a Registry populated from an ordered list of NamespacedProviders. Providers are applied from lowest priority to highest; a higher-priority provider's resource overwrites any same-qualified-name entry from a lower-priority provider.

The returned Registry has no filesystem-derived Projects, Agents, etc. — those maps remain nil. Use LoadWorkspace for the full loading path.

func Load 

func Load(dir string, providers ...ResourceProvider) (*Registry, error)

Load loads a workspace starting from the given directory. 

reg, err := warp.Load("/my/project")

func LoadDefault 

func LoadDefault(providers ...ResourceProvider) (*Registry, error)

LoadDefault loads a workspace starting from the current working directory. It is equivalent to LoadWorkspace("."). 

reg, err := warp.LoadDefault()

func LoadWorkspace 

func LoadWorkspace(startDir string, providers ...ResourceProvider) (*Registry, error)

LoadWorkspace is the primary entry point for the 3-phase WARP loading algorithm.

Phase 1 — Workspace Discovery: climbs from startDir looking for a WORKSPACE.md file. If none is found, a synthetic workspace is created with its root set to startDir.

Phase 2 — Project Mapping: determines the active project directories from the workspace's spec.projects field (["*"], explicit list, or default ["."]).

Phase 3 — Contextual Loading: for each project directory, loads its AGENT.md (Context) and walks its .agents/ subdirectory for Agents, Skills, and Commands.

Authority Rule: when the only project is "." (WORKSPACE_PATH == PROJECT_PATH) the root .agents/ directory is owned by the Project. The workspace-global library is left empty to prevent double-loading.

func NewRegistry 

func NewRegistry(ws *Workspace) *Registry

NewRegistry returns an empty Registry bound to the given workspace spec. ws may be nil for registries assembled outside the loading path.

func (*Registry) AddProject 

func (r *Registry) AddProject(p *Project)

AddProject registers project metadata in the registry.

func (*Registry) GetProject 

func (r *Registry) GetProject(slug string) (*Project, bool)

GetProject returns the project with the given slug, or (nil, false) when not found.

func (*Registry) ListProjects 

func (r *Registry) ListProjects() []*Project

ListProjects returns all registered projects in undefined order.

func (*Registry) ListResources 

func (r *Registry) ListResources(opts QueryOptions) []Resource

ListResources implements Resolver for the base Registry. Only resources from standard namespaces (workspace/user/system) are included.

func (*Registry) Project 

func (r *Registry) Project(slug string) *ScopedRegistry

Project returns a ScopedRegistry scoped to slug. Resolution methods on the returned value treat slug as the highest-priority "local" namespace, and a ref beginning with "local/" is transparently rewritten to "<slug>/".

func (*Registry) ProjectFromPath 

func (r *Registry) ProjectFromPath(absPath string) (*Project, bool)

ProjectFromPath returns the project whose absolute directory matches absPath, or (nil, false) when no project matches. This is the preferred way for the application layer to determine which project is "current" — callers should pass os.Getwd() or an equivalent path rather than letting the Registry inspect the process environment.

func (*Registry) ResolveAgent 

func (r *Registry) ResolveAgent(ref string) (*Agent, error)

ResolveAgent resolves an agent by ref, applying recursive inheritance merging. Returns the fully merged *Agent or an error if the ref is not found, is not an Agent, or if a circular inheritance chain is detected.

func (*Registry) ResolveResource 

func (r *Registry) ResolveResource(ref string) (Resource, bool)

ResolveResource implements Resolver for the base Registry. Qualified refs ("namespace/Kind/name") are direct key lookups. Short names are resolved through [workspace, user, system]; project-specific namespaces are never returned, ensuring workspace-root isolation.

func (*Registry) Resources added in v0.0.2 

func (r *Registry) Resources() []Resource

Resources returns all resources stored in the registry across all namespaces.

func (*Registry) Set 

func (r *Registry) Set(qualifiedName string, res Resource)

Set stores a resource under the given qualified name. It overwrites any existing entry. Use this for programmatic registry construction in tests or custom providers. For loader paths, use the internal set() method instead.

func (*Registry) Validate 

func (r *Registry) Validate() error

Validate checks every resource for structural correctness and resolves Agent cross-references. Returns the first error encountered.

func (*Registry) Warnings 

func (r *Registry) Warnings() []string

Warnings returns non-fatal issues collected during loading.

func (*Registry) WorkspaceSpec 

func (r *Registry) WorkspaceSpec() *Workspace

WorkspaceSpec returns the immutable workspace specification.

type RenderOptions added in v0.0.2 

type RenderOptions struct {
	// Args are the positional arguments provided by the caller (typically for Commands).
	Args []string
	// Globals are WARP-managed contextual variables (e.g., project directories,
	// active environments) provided by the runtime.
	Globals map[string]any
}

RenderOptions holds the context for rendering a resource's instructions.

type Resolver 

type Resolver interface {
	ResolveResource(ref string) (Resource, bool)
	ListResources(opts QueryOptions) []Resource
}

Resolver is the common interface satisfied by both Registry (workspace-root scope) and ScopedRegistry (project scope).

type Resource 

type Resource interface {
	// GetKind returns the resource's Kind (e.g. KindSkill).
	GetKind() Kind
	// GetName returns the short metadata name declared in the YAML front-matter.
	GetName() string
	// GetNamespace returns the namespace this resource was loaded into. Empty
	// when the resource was loaded via the legacy filesystem path and has not
	// been assigned to a namespace.
	GetNamespace() string
	// QualifiedName returns the "namespace/Kind/name" key that uniquely
	// identifies this resource in the registry.
	QualifiedName() string
	// GetMetadata returns the resource's Metadata block.
	GetMetadata() Metadata
}

Resource is the common interface satisfied by every warp resource value stored in the registry. All concrete types (*Agent, *Skill, *Command, etc.) satisfy this interface through their embedded BaseResource.

type ResourceProvider 

type ResourceProvider interface {
	LoadResources() (*ResourceSet, error)
}

ResourceProvider loads workspace-global resources that should be merged into a workspace after filesystem discovery. Existing workspace resources keep precedence over provider resources.

type ResourceSet 

type ResourceSet struct {
	Agents         map[string]*Agent
	Skills         map[string]*Skill
	Commands       map[string]*Command
	ModelProviders map[string]*ModelProvider
	Tools          map[string]*Tool
	MCPs           map[string]*MCP
	Toolkits       map[string]*Toolkit
}

ResourceSet contains non-project, non-workspace resources that can be merged into a loaded workspace.

type ScopedRegistry 

type ScopedRegistry struct {
	// contains filtered or unexported fields
}

ScopedRegistry wraps a Registry with a project slug, implementing Resolver with that slug treated as the top-priority "local" namespace. Obtain one via Registry.Project(slug).

func (*ScopedRegistry) ListResources 

func (s *ScopedRegistry) ListResources(opts QueryOptions) []Resource

ListResources implements Resolver for ScopedRegistry. When opts.Effective is true, the active project namespace wins over all others for each short name.

func (*ScopedRegistry) ResolveAgent 

func (s *ScopedRegistry) ResolveAgent(ref string) (*Agent, error)

ResolveAgent resolves an agent by ref within this project scope, applying recursive inheritance merging. The project slug is the highest-priority namespace during resolution of every step in the chain.

func (*ScopedRegistry) ResolveResource 

func (s *ScopedRegistry) ResolveResource(ref string) (Resource, bool)

ResolveResource implements Resolver for ScopedRegistry.

  • "local/<Kind>/<name>" is rewritten to "<projectSlug>/<Kind>/<name>".
  • Other qualified refs ("namespace/Kind/name") are direct key lookups.
  • Short names are resolved through [projectSlug, workspace, user, system].

func (*ScopedRegistry) SkillsForAgent 

func (s *ScopedRegistry) SkillsForAgent(agentName string) ([]Skill, error)

SkillsForAgent returns the Skill resources available to the named agent within this project scope. Inheritance is resolved first via ResolveAgent, so the merged skill list from the full inheritance chain is used. If the merged agent declares a non-empty Skills list, only those referenced skills are returned. When the list is empty every skill visible in this project scope is returned.

func (*ScopedRegistry) ToolsForAgent 

func (s *ScopedRegistry) ToolsForAgent(agentName string) ([]*Tool, error)

ToolsForAgent returns the Tool resources available to the named agent within this project scope. Inheritance is resolved first via ResolveAgent, so the merged tool list from the full inheritance chain is used. If the merged agent declares a non-empty Tools list, only those referenced tools are returned. When the list is empty every tool visible in this project scope is returned.

type Skill 

type Skill struct {
	BaseResource `yaml:",inline"`
	// Spec holds the skill-specific configuration.
	Spec SkillSpec `yaml:"spec"`
}

Skill is a warp resource that bundles expertise guidelines for a specific domain. An agent loads a skill's instructions to adopt its persona or follow its conventions.

func (*Skill) DeepCopy 

func (s *Skill) DeepCopy() *Skill

DeepCopy returns a deep copy of the Skill.

type SkillSpec 

type SkillSpec struct {
	// Instructions is the expertise prompt populated from the Markdown body
	// of the file (below the closing front-matter delimiter).
	Instructions string `yaml:"instructions"`
}

SkillSpec contains the configuration details for a Skill resource.

func (*SkillSpec) DeepCopy 

func (s *SkillSpec) DeepCopy() *SkillSpec

DeepCopy returns a deep copy of the SkillSpec.

type Tool 

type Tool struct {
	BaseResource `yaml:",inline"`
	// Spec holds the tool-specific configuration.
	Spec ToolSpec `yaml:"spec"`
}

Tool is a warp resource that describes a custom tool.

func (*Tool) DeepCopy 

func (in *Tool) DeepCopy() *Tool

DeepCopy returns a deep copy of the Tool.

type ToolAnnotation 

type ToolAnnotation struct {
	IsOpenWorld  bool   `yaml:"isOpenWorld"`  // Interacts with external resources
	IsDangerous  bool   `yaml:"isDangerous"`  // Can perform destructive actions
	IsReadOnly   bool   `yaml:"isReadOnly"`   // Does not modify state
	IsIdempotent bool   `yaml:"isIdempotent"` // Safe to retry
	UserHint     string `yaml:"userHint"`     // Human-readable hint for approval prompts
}

ToolAnnotation defines the safety profile for a tool.

func (*ToolAnnotation) DeepCopy 

func (in *ToolAnnotation) DeepCopy() *ToolAnnotation

DeepCopy returns a deep copy of the ToolAnnotation.

type ToolSpec 

type ToolSpec struct {
	Name        string                 `yaml:"name,omitempty"` // Used only when defined inline in a Toolkit
	Command     []string               `yaml:"command"`        // Executable and static args (e.g., ["python", "script.py"])
	Description string                 `yaml:"description"`    // What the tool does (sent to the LLM)
	Env         map[string]string      `yaml:"env"`            // Environment variables injected into the process
	Parameters  map[string]interface{} `yaml:"parameters"`     // JSON Schema object defining arguments the LLM must pass
	Annotations *ToolAnnotation        `yaml:"annotations"`    // Safety profile for Tool Execution Security
}

ToolSpec contains the configuration details for a Tool resource.

func (*ToolSpec) DeepCopy 

func (in *ToolSpec) DeepCopy() *ToolSpec

DeepCopy returns a deep copy of the ToolSpec.

type Toolkit 

type Toolkit struct {
	BaseResource `yaml:",inline"`
	// Spec holds the toolkit-specific configuration.
	Spec ToolkitSpec `yaml:"spec"`
}

Toolkit is a warp resource that describes a collection of tools.

func (*Toolkit) DeepCopy 

func (in *Toolkit) DeepCopy() *Toolkit

DeepCopy returns a deep copy of the Toolkit.

type ToolkitSpec 

type ToolkitSpec struct {
	Tools []ToolkitTool `yaml:"tools"` // Array of tools (referenced or inline)
}

ToolkitSpec contains the configuration details for a Toolkit resource.

func (*ToolkitSpec) DeepCopy 

func (in *ToolkitSpec) DeepCopy() *ToolkitSpec

DeepCopy returns a deep copy of the ToolkitSpec.

type ToolkitTool 

type ToolkitTool struct {
	Ref      string           `yaml:"$ref,omitempty"` // Path to external tool (e.g., "tools/formatter.yaml")
	ToolSpec `yaml:",inline"` // Inline Tool definition
}

ToolkitTool can be either a reference to an external file or a fully inline ToolSpec.

func (*ToolkitTool) DeepCopy 

func (in *ToolkitTool) DeepCopy() *ToolkitTool

DeepCopy returns a deep copy of the ToolkitTool.

type Workspace 

type Workspace struct {
	// Def is the parsed WORKSPACE.md resource. Nil when Synthetic is true.
	Def *WorkspaceDef

	// RootPath is the absolute filesystem path to the workspace root directory.
	RootPath string

	// Synthetic is true when no WORKSPACE.md was found during discovery and
	// the workspace was inferred from the starting directory.
	Synthetic bool
}

Workspace holds the immutable specification of a WARP workspace. All loaded resources and projects live in a Registry. Use DeepCopy to obtain a safe, independent snapshot of the spec.

func (*Workspace) DeepCopy 

func (w *Workspace) DeepCopy() *Workspace

DeepCopy returns a deep copy of the Workspace spec, making the value safe to use as an immutable snapshot independent of the original.

type WorkspaceDef 

type WorkspaceDef struct {
	BaseResource `yaml:",inline"`
	Spec         WorkspaceDefSpec `yaml:"spec"`
}

WorkspaceDef is the parsed representation of a WORKSPACE.md resource.

func (*WorkspaceDef) DeepCopy 

func (w *WorkspaceDef) DeepCopy() *WorkspaceDef

DeepCopy returns a deep copy of the WorkspaceDef.

func (*WorkspaceDef) ValidateBase 

func (w *WorkspaceDef) ValidateBase() error

ValidateBase validates the WorkspaceDef base fields.

type WorkspaceDefSpec 

type WorkspaceDefSpec struct {
	Projects        []string `yaml:"projects"`
	DefaultProvider string   `yaml:"defaultProvider"`
	DefaultAgent    string   `yaml:"defaultAgent"`
	Plugins         []string `yaml:"plugins"`
	Instructions    string   `yaml:"instructions"`
}

WorkspaceDefSpec contains configuration for a Workspace resource.

func (*WorkspaceDefSpec) DeepCopy 

func (in *WorkspaceDefSpec) DeepCopy() *WorkspaceDefSpec

DeepCopy returns a deep copy of the WorkspaceDefSpec.

Source Files

View all Source files

Directories

Path Synopsis
cmd
warp command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.