Documentation
¶
Overview ¶
Package agents sets up the anfra skills in the coding agents on this machine (docs/designs/agent-setup.md): a plugin through the agent's own CLI where anfra knows one, a pointer to the skills repo's README for every other agent. It runs programs on this machine, so only the CLI uses it, never an op.
Index ¶
- Constants
- Variables
- func Attention(env Env, repoDir string) string
- func Badge(env Env, repoDir string) (mark, label string)
- func Failed(env Env, repoDir string, now time.Time) string
- func IDs() []string
- func MarkNoticed()
- func Newer(a, b string) bool
- func Notice(env Env, repoDir string) string
- func NoticeDue() bool
- func ParseStamp(skill []byte) (string, bool)
- func ReadmeFor(id string) string
- func RecordPlugins(ctx context.Context, env Env)
- func Succeeded()
- func WriteBlock(repoDir string) (wroteBlock, wroteImport bool, err error)
- type Agent
- type AgentSetup
- type AgentState
- type AgentStatus
- type AgentsMDSetup
- type AgentsMDState
- type Block
- type BlockState
- type CheckResult
- type ClaudeMDState
- type Copy
- type CopyState
- type Env
- type ImportError
- type Installed
- type LatestSkills
- type Options
- type Outcome
- type PluginState
- type Report
- type SetupActions
- type SetupResult
- type SkillsVersion
Constants ¶
const ( SkillsRepo = "holistics/anfra-skills" Marketplace = "anfra-skills" Plugin = "anfra" PluginID = Plugin + "@" + Marketplace )
The skills, published as a plugin marketplace that Claude Code and Codex each install from.
Variables ¶
var ErrIncomplete = errors.New("the anfra skills are not set up for every agent")
ErrIncomplete is setup leaving an agent without the skills, or the anfra block unwritten: Setup returns it with its result, as far as it got.
var Known = []Agent{ { ID: "claude-code", Name: "Claude Code", // contains filtered or unexported fields }, { ID: "codex", Name: "Codex", // contains filtered or unexported fields }, { ID: "cursor", Name: "Cursor", // contains filtered or unexported fields }, { ID: "github-copilot", Name: "GitHub Copilot", // contains filtered or unexported fields }, { ID: "opencode", Name: "OpenCode", // contains filtered or unexported fields }, { ID: "gemini-cli", Name: "Gemini CLI", // contains filtered or unexported fields }, { ID: "antigravity", Name: "Antigravity", // contains filtered or unexported fields }, { ID: "junie", Name: "Junie", // contains filtered or unexported fields }, { ID: "windsurf", Name: "Windsurf", // contains filtered or unexported fields }, { ID: "cline", Name: "Cline", // contains filtered or unexported fields }, { ID: "warp", Name: "Warp", // contains filtered or unexported fields }, }
Known are the agents anfra knows, in the order setup reports them. Each has a section in the skills repo's README, anchored by its id; adding one here means adding its section there.
Functions ¶
func Attention ¶
Attention is one line saying what of the agents' skills needs attention, and to run setup: the plugins behind, as anfra last recorded them; the copies behind and with deprecated skills, in the folders the agents read; and repoDir's AGENTS.md block ("" outside a repo). "" when nothing does. No network and no agent CLI: it is cheap enough to run after a command.
func Badge ¶ added in v0.18.0
Badge is Attention as a console's badge (docs/designs/console.md): a mark and a few words, the command to run being setup's. ↑ and the latest skills when a plugin or a copy is behind; ! and how many issues when something else needs attention; ! when the agents have no skills; "" when nothing needs attention.
func Failed ¶ added in v0.15.1
Failed records a failure the caller could fix (an invalid input, an unknown command or flag), off a terminal, and says what to hint in its error: "" but for the failure that makes hintAfter within hintWithin, once per streak, and only when an agent is detected and none has the skills. When the plugins have never been recorded, the hint is worded to hold either way.
func MarkNoticed ¶ added in v0.18.0
func MarkNoticed()
MarkNoticed records that the notice printed, now.
func Newer ¶
Newer reports whether version a is newer than b; false when either isn't a full version (1.2.3, without a prefix).
func Notice ¶
Notice is Attention, at most once a day: "" when it printed less than a day ago, or nothing needs attention. It records that it printed.
func NoticeDue ¶ added in v0.18.0
func NoticeDue() bool
NoticeDue reports whether a day has passed since the notice last printed, for one shown after a command, at most once a day.
func ParseStamp ¶
ParseStamp is the skills version a SKILL.md states, from its stamp; false when it has none, as a copy from before the stamp existed has none.
func ReadmeFor ¶
ReadmeFor is the README's install section for an agent id: its own for a known agent, the one for any other agent otherwise, so the link always lands on a section that exists.
func RecordPlugins ¶
RecordPlugins asks each agent's CLI for its plugins and keeps the answer, for the notice. Agents' CLIs start slowly, so this is for the background check and setup, never an ordinary command.
func Succeeded ¶ added in v0.15.1
func Succeeded()
Succeeded ends a streak of failures. A command that succeeds with none costs a missing file's stat.
func WriteBlock ¶
WriteBlock writes the anfra block into repoDir's AGENTS.md: it adds it to the file, creating it, or replaces the block that is there. It adds the import to the repo's CLAUDE.md, when it has one. It refuses a symlink, which would write outside the repo. It says whether it wrote the block, and the import. A failure to add the import is an *ImportError, so that a caller can tell it from a failure to write the block.
Types ¶
type Agent ¶
type Agent struct {
ID string // npx skills' id: the --agent value, and the README section's anchor
Name string
// contains filtered or unexported fields
}
Agent is a coding agent anfra knows: how to find it on this machine, and how it gets the skills.
func (Agent) Detected ¶
Detected reports whether the agent is on this machine: one of its CLIs is on the PATH, or one of its folders exists.
func (Agent) InstalledPlugin ¶
InstalledPlugin lists the agent's installed copies of the plugin, through its CLI. Nil when anfra doesn't install into it, its CLI isn't on the PATH, or the list fails. Agents' CLIs start slowly (Claude Code's starts Node), so this is for setup and update, never an ordinary command.
type AgentSetup ¶ added in v0.17.0
type AgentSetup struct {
// Agent is its id, what --agent takes; not in the pretty format, as the
// report's agents.
Agent string `json:"agent" doc:"the agent, as --agent takes it" pretty:"-"`
Name string `json:"name" doc:"the agent's name"`
Outcome Outcome `` /* 195-byte string literal not displayed */
Message string `json:"message" doc:"what to do next: restart the agent, install its CLI, or follow the README" pretty:",truncate"`
}
AgentSetup is what setup did for one agent.
type AgentState ¶ added in v0.17.0
type AgentState struct {
// ID is what --agent takes; not in the pretty format, where Name says
// the same to a person, and --help lists the ids.
ID string `json:"id" doc:"the agent, as --agent takes it" pretty:"-"`
Name string `json:"name" doc:"the agent's name"`
Status AgentStatus `` /* 174-byte string literal not displayed */
Plugins []PluginState `json:"plugins" doc:"its plugins, installed through its CLI"`
Copies []string `json:"copies" doc:"the folders it reads that hold anfra skills"`
// InstallFrom is where to install the skills from: its README section;
// absent when they're installed. Not in the pretty format, where a hint
// says it, so the agents' table fits a terminal.
InstallFrom string `json:"install_from,omitempty" doc:"a link to the instructions for installing the skills for this agent" pretty:"-"`
}
AgentState is where an agent's skills come from: the plugin, through its CLI, or copies in the folders it reads.
type AgentStatus ¶ added in v0.17.0
type AgentStatus string
AgentStatus is whether an agent has the anfra skills.
const ( AgentInstalled AgentStatus = "installed" AgentNotInstalled AgentStatus = "not-installed" )
type AgentsMDSetup ¶ added in v0.17.0
type AgentsMDSetup struct {
WroteBlock bool `json:"wrote_block" doc:"whether it wrote the anfra block"`
WroteImport bool `json:"wrote_import" doc:"whether it wrote @AGENTS.md in CLAUDE.md"`
Message string `json:"message,omitempty" doc:"why setup couldn't write the anfra block or @AGENTS.md in CLAUDE.md"`
// contains filtered or unexported fields
}
AgentsMDSetup is what setup wrote of the anfra block.
type AgentsMDState ¶ added in v0.17.0
type AgentsMDState struct {
Block BlockState `` /* 136-byte string literal not displayed */
ClaudeMD ClaudeMDState `` /* 231-byte string literal not displayed */
Message string `json:"message,omitempty" doc:"why AGENTS.md or CLAUDE.md can't be read"`
}
AgentsMDState is the repo's anfra block in AGENTS.md.
type Block ¶
type Block struct {
State BlockState
// HasClaudeMD: the repo has a CLAUDE.md.
HasClaudeMD bool
// NoImport: the repo has a CLAUDE.md, which doesn't import AGENTS.md.
NoImport bool
}
Block is the state of a repo's anfra block in AGENTS.md, and of the import in its CLAUDE.md.
func CheckBlock ¶
CheckBlock reports the anfra block in repoDir's AGENTS.md, and the import in its CLAUDE.md, when it has one.
type BlockState ¶
type BlockState string
BlockState is the state of the anfra block itself.
const ( BlockMissing BlockState = "missing" BlockOutdated BlockState = "outdated" // other than what this anfra writes BlockUpToDate BlockState = "up-to-date" )
const BlockUnreadable BlockState = "unreadable"
BlockUnreadable: AGENTS.md or CLAUDE.md can't be read as a file of the repo.
type CheckResult ¶ added in v0.17.0
type CheckResult struct {
Message string `json:"message" doc:"the outcome, in a sentence"`
Report `json:",inline"`
Hints []string `json:"hints,omitempty" doc:"what to do next, if any"`
}
CheckResult is `agent setup check`'s result: the Report, between its message, the outcome, and its hints, what to do next (docs/designs/commands-and-api.md#cli-output).
type ClaudeMDState ¶ added in v0.17.0
type ClaudeMDState string
ClaudeMDState is a repo's CLAUDE.md, against the import of AGENTS.md Claude Code needs to read it.
const ( ClaudeMDImported ClaudeMDState = "imported" ClaudeMDNotImported ClaudeMDState = "not-imported" ClaudeMDAbsent ClaudeMDState = "absent" )
type Copy ¶
type Copy struct {
Dir string // the skills folder, as shown: ~/… or relative to the repo
// Versions are its skills by the version they state: "" for those with no
// stamp. A copy installed whole has one.
Versions map[string][]string
// OldNames: it has skills of the names from before the prefix, which an
// agent loads next to the new ones until they are removed.
OldNames bool
// contains filtered or unexported fields
}
Copy is a copy of the skills in a folder anfra knows.
type CopyState ¶ added in v0.17.0
type CopyState struct {
Dir string `json:"dir" doc:"the folder"`
Status string `` /* 410-byte string literal not displayed */
Versions []SkillsVersion `json:"versions" doc:"its skills by version, oldest first"`
DeprecatedNames bool `` /* 126-byte string literal not displayed */
}
CopyState is a folder of copies of the skills against the latest.
type Env ¶
type Env struct {
Home string // the user's home folder
Getenv func(string) string // the environment
LookPath func(string) (string, error) // finds a CLI on the PATH
// Run runs a command where the user sees it, and can answer what it asks.
Run func(ctx context.Context, bin string, args ...string) error
// Output runs a command and returns what it prints.
Output func(ctx context.Context, bin string, args ...string) ([]byte, error)
}
Env is what the package touches outside this process, swapped in tests.
type ImportError ¶ added in v0.19.0
type ImportError struct{ Err error }
ImportError is WriteBlock failing on CLAUDE.md, after AGENTS.md is done, so that setup doesn't report the block as unwritten. Its text is its cause's.
func (*ImportError) Error ¶ added in v0.19.0
func (e *ImportError) Error() string
func (*ImportError) Unwrap ¶ added in v0.19.0
func (e *ImportError) Unwrap() error
type Installed ¶
Installed is an installed copy of the plugin: its version, and the scope the agent reports it at (user, project, …). anfra installs for the user only.
type LatestSkills ¶ added in v0.17.0
type LatestSkills struct {
Latest *string `json:"latest" doc:"the latest anfra skills version. Null when it isn't known."`
CheckedAt *time.Time `json:"checked_at" doc:"when anfra last checked for the latest version" pretty:",moment"`
}
LatestSkills is the latest anfra skills version, from the background check, as `anfra version` names it; null until the check has run.
type Options ¶
type Options struct {
// Agents are the ids named with --agent; none: the agents detected.
Agents []string
// RepoDir is the anfra repo setup runs in, whose AGENTS.md gets the anfra
// block, and whose copies of the skills the check looks for too; "" outside
// one.
RepoDir string
// Progress is where to say, for a person, what setup is doing and what to
// do next; nil says nothing. The result says what it did.
Progress io.Writer
}
Options are what setup acts on.
type Outcome ¶ added in v0.17.0
type Outcome string
Outcome is what setup did for an agent.
const ( OutcomeInstalled Outcome = "installed" // installed or updated OutcomeFailed Outcome = "failed" // an install step failed OutcomeCLIMissing Outcome = "cli_missing" // not tried: its CLI isn't on the PATH OutcomeInstructionsOnly Outcome = "instructions_only" // anfra doesn't install for it: the README says how )
type PluginState ¶ added in v0.17.0
type PluginState struct {
Scope string `json:"scope" doc:"the scope the agent installed the plugin at, such as \"user\" or \"project\""`
Version string `json:"version" doc:"the plugin's skills version"`
Status string `` /* 226-byte string literal not displayed */
}
PluginState is an installed plugin against the latest skills.
type Report ¶ added in v0.17.0
type Report struct {
Skills LatestSkills `json:"skills" doc:"the latest anfra skills version"`
Agents []AgentState `json:"agents" doc:"each agent, and where its skills come from"`
Copies []CopyState `json:"copies" doc:"each folder of copies of the skills"`
AgentsMD *AgentsMDState `json:"agents_md" doc:"the repo's anfra block in AGENTS.md. Null outside an anfra repo." pretty:"AGENTS.md"`
}
Report is the state of the agents' skills: what `agent setup check` answers, and setup with it, as setup leaves it.
type SetupActions ¶ added in v0.17.0
type SetupActions struct {
Agents []AgentSetup `json:"agents" doc:"what setup did for each agent"`
AgentsMD *AgentsMDSetup `json:"agents_md" doc:"what setup wrote to AGENTS.md and CLAUDE.md. Null outside an anfra repo." pretty:"AGENTS.md"`
}
SetupActions are what setup did.
type SetupResult ¶ added in v0.17.0
type SetupResult struct {
Message string `json:"message" doc:"the outcome, in a sentence"`
Setup SetupActions `json:"setup" doc:"what setup did"`
Report `json:",inline"`
Hints []string `json:"hints,omitempty" doc:"what to do next, if any"`
}
SetupResult is setup's result: what it did, then the Report as it leaves things (docs/designs/commands-and-api.md#new-state-as-output), between its message and its hints.
func Setup ¶
Setup installs the plugin into each agent anfra installs into, and writes the AGENTS.md block in an anfra repo, then reports the state it leaves, as Check does. It fails, with ErrIncomplete, when an install step failed or an agent named with --agent ends up without the plugin: an agent that was only detected doesn't fail it, as anyone with a second agent's folder would see setup fail on every run.
type SkillsVersion ¶ added in v0.17.0
type SkillsVersion struct {
Version *string `json:"version" doc:"the version. Null for skills with no version stamp."`
Skills []string `json:"skills" doc:"the names of the skills at this version"`
}
SkillsVersion is the skills of a copy at one version, oldest first.