| name | amos |
| description | Load when working with amos nodes — markdown files carrying `whoami: amos` frontmatter — or when the user refers to "the plan", "the DAG", "the roadmap", "the tickets", "what's next", or similar work-tracking concepts. Installs the amos conventions (canonical naming, node format, when to reach for which sub-skill) into context so amos-graph, amos-show, amos-create, and amos-notify can be used correctly. Does not run the CLI on its own.
|
Amos
Amos is a CLI preprocessor that overlays a local markdown cache on the adapter's source of truth
(GitHub issues today, other trackers via adapter). The adapter is authoritative for what issues
exist, their state, milestone, and dependency edges. Local plan files are optional overlays that
hold AI-specific notes or pre-GA edges not yet pushed upstream.
Read: the DAG is fetched fresh from GitHub on every amos call. Issues appear whether or not
they have a local plan file.
The canonical name rule — NON-NEGOTIABLE
Every node — whether materialized from GitHub directly or from a local plan file — is identified
by an adapter-qualified name:
@github:<owner>/<repo>#<issue-number>
e.g. @github:tatolab/streamlib#326. This is the string amos uses for every edge lookup; every
blocked_by: / blocks: / related_to: reference uses it.
Dependency edges: GitHub native > plan file
GitHub's issue UI now exposes five typed relationships (blocked-by, blocks, parent,
sub-issue, duplicate). Amos reads these natively via GraphQL (blockedBy, blocking,
parent, subIssues). Any edge declared through the GitHub UI or REST/GraphQL API is
visible to amos graph / next / blocked with zero local state.
Plan files are no longer required to declare edges. The old blocked_by: / blocks:
frontmatter fields still work — they're merged with GitHub's native edges — but adding new
edges should go through GitHub's UI or gh api graphql so the dependency graph stays in one
place.
To migrate a project's existing plan-file edges to GitHub native:
"$HOME/.local/bin/amos" sync-edges --dry-run --dir <project-root>
"$HOME/.local/bin/amos" sync-edges --dir <project-root>
The operation is idempotent; re-running is safe.
Optional plan file format
Only create a plan file when you have AI-specific notes that shouldn't live in the public GitHub
issue body. The file format is:
---
whoami: amos
name: "@github:<owner>/<repo>#<N>"
description: "<short routing hint — free-form>"
# blocked_by / blocks are optional — prefer setting these in GitHub's UI instead.
adapters:
github: builtin
---
Local agent instructions here. Kept local so they don't clutter the public issue.
Filename convention: <N>-<short-kebab-slug>.md under plan/.
Sub-skill routing
- amos-file — file a new GitHub issue from short natural-language intent. Handles template
discovery, milestone inference, relationship setup, and atomic creation. Use whenever the
user says "file this", "open a ticket for X", "create an issue", or confirms a "want me to
file this?" prompt.
- amos-graph — print the full dependency tree. Use for "what's open", "what's next",
"what's blocked", "show me the roadmap", orientation queries.
- amos-next — pick up and execute the next ready-to-start issue in the focused milestone,
end-to-end (branch, work, test, PR).
- amos-focus — set or switch the current milestone focus.
- amos-show — resolve a single node to full content including
@-references. Use for
"tell me about #N".
- amos-notify — post a message to a node's source system, e.g. GitHub issue comment
(user-invoked via
/amos-notify).
The older amos-create skill scaffolded a plan file for an already-existing GitHub issue.
Since plan files are now optional and rarely needed, prefer amos-file for new issues and
skip the plan file entirely.
The CLI
Installed binary: $HOME/.local/bin/amos (placed there by tatolab/amos's install.sh).
Sub-skills invoke it as "$HOME/.local/bin/amos" <subcommand>. Don't prefix with bash — it's a
compiled binary, not a script.
