Agentguidance agent guidance

Read GLOSSARY.md for the authored and rendered resource terms. ADR 0001 explains fragment ownership and the one supported convergence path.

Skill directories under skills/ are templates. The installed copies under ~/.local/share/agentstart/resources/skills/ are rendered artifacts — never edit them. After changing any template, a fragment in fragments/, or an extension prompt in ~/.config/agentguidance/, run ~/code/agentstart/scripts/sync-skills to rebuild them. That is the only path that reaches a live session: it ships these templates, execs scripts/render over them, and fans the result out into the per-harness trees a session loads (resources/claude/agent/skills, resources/codex-marketplace/…). Running scripts/render by hand renders nothing — it refuses without an install root, because choosing its own would write a tree nobody reads.

Render points work in SKILL.md and sibling Markdown references. Keep the entry skill focused on scope, decisions, and links; detailed software and lifecycle procedures belong in references and use the same shared fragments. The renderer stamps and makes those reference files read-only too. A missing fragment fails the render regardless of which Markdown file references it.

Two kinds of render point, spliced by scripts/render:

• <!-- fragment: NAME.md --> — repo-owned shared doctrine from fragments/. A missing fragment fails the render. The default AgentStart role also incorporates domain-model.md into its installed prompt.
• <!-- extension-prompt: NAME.md --> — operator-owned machine voice from ~/.config/agentguidance/ (linked there by AgentStart from its prompts/agentguidance/). An absent file renders to nothing.

This checkout is an ordinary agent* scan participant: AgentStart's sync-skills ships skills/<name>/ whole into the fixed private fleet resources, then runs scripts/post-sync — the render — so the raw templates it just shipped are immediately replaced by rendered artifacts. That hook is why the templates may live in skills/ at all; without it, every six-hour sync would strip the extensions until the next render. Do not add an installer here and do not bypass the hook.

Model invocability is declared only by disable-model-invocation in SKILL.md; AgentStart derives Codex's inverse allow_implicit_invocation, so never maintain that field in source.

Retiring a skill is deleting its directory: the render prunes the installed copy it once produced (banner-matched, so other tools' skills are untouched). The default AgentStart role owns general collaboration and build behavior. Keep shared domain guidance in fragments/domain-model.md so the role and any specialist readers get the same vocabulary convention.

maintain is doctrine for a kind of repository — a fork workshop such as fxnk or zmax — rather than for a tool, which is why it lives here; the one script it ships, skills/maintain/scripts/reconcile-branches.sh, is the deterministic owner of the mirror and carry refs rebased workshops declare, proven by tests/branch-policy.sh, and a workshop calls the installed copy through a thin entrypoint rather than copying it. Explicit merge-only workshops select their own history-preserving branch procedure from MAINTAIN.md; bare /maintain resolves this without extra arguments. Other fork heads are reported and left unchanged; DELETEME/* is explicit human state.

A tool-specific runbook normally lives with its tool. notify is the older entrypoint that now routes to AgentNotify's tool-owned notifications skill and the AgentStart terminal-notifier router. email uses Gog's authenticated Google MCP and CLI and has no fleet tool checkout to own its workflow. A runbook for a fleet tool belongs in that tool's checkout. All resource skills are discovered through their names and descriptions.

domain-modeling, writing-for-agents, diagnosing-bugs, prototype, and code-review are selected MIT-licensed skills adapted from Matt Pocock's v1.3 release. Keep their source pins and notices with each skill. They support active model work, agent-facing writing, hard bug diagnosis, disposable design probes, and two-axis code review. Everyday glossary reading remains in the default role. Do not import the whole upstream catalog as a competing workflow.

AGENTS.md is the sole repository guidance entrypoint. Run tests/validate.sh before committing.

The fleet

This checkout is one of the agent* fleet under ~/code. Shared machinery lives in two siblings, and some changes here must cascade:

• Skills under skills/<name>/ ship into AgentStart's fixed private fleet resources (~/code/agentstart/scripts/sync-skills, run six-hourly by the scheduled updater). Bare permission shims do not load these resources; explicit roles can expose /agent:<name> in Claude Code and $agent:<name> in Codex. A SKILL.md edit is live within six hours, or on demand by running that script. Skill names and descriptions provide capability discovery; do not add a second tool catalog to prompts. See agentwiki get tool-advertisement-policy.
• Adding or removing a call to another fleet tool changes the fleet map: update ~/code/agentstart/skills/fleet/MAP.md (served by the fleet skill, every edge with evidence) in the same change.
• General agent doctrine — the default role, maintain, story, the resource skills — is ~/code/agentguidance; tool-specific runbooks stay here.