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 Check(ctx context.Context, env Env, o Options) error
- func Failed(env Env, repoDir string, now time.Time) string
- func IDs() []string
- func Newer(a, b string) bool
- func Notice(env Env, repoDir string) string
- func ParseStamp(skill []byte) (string, bool)
- func ReadmeFor(id string) string
- func RecordPlugins(ctx context.Context, env Env)
- func Setup(ctx context.Context, env Env, o Options) error
- func Succeeded()
- func WriteBlock(repoDir string) (wroteBlock, wroteImport bool, err error)
- type Agent
- type Block
- type BlockState
- type Copy
- type Env
- type Installed
- type Options
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 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 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 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 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 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, and what to do next. It fails 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.
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.
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 Block ¶
type Block struct {
State BlockState
// 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" )
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 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 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 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
// NotRepo: setup runs in a folder that isn't an anfra repo, so it leaves its
// AGENTS.md alone, and the report says so.
NotRepo bool
Out io.Writer
}
Options are what setup acts on.