tap

Steps

1. Read the repo's AGENTS.md and look at two or three existing entities of the same kind before writing.
2. Load the authoring skill for the entity and follow it: tap-agent-authoring skill for agents, tap-capability-authoring skill for capabilities, tap-deps-authoring skill for dep scripts, tap-skill-authoring skill for skills. Changing capability triggers or skill semantic() phrases also means the tap-model-training skill.
3. Reuse before creating: check capabilities/ for an existing capability or provider before adding one, and skills/ before writing a skill.
4. Write the smallest correct change, then run the checks below for everything you touched and fix every failure before reporting.

Checks

• Agents: bash scripts/lint-manifests.sh agents/<domain>/<spec>.toml and bin/load <domain>:<spec>
• Capabilities: bash scripts/setup-symlinks.sh, bash scripts/lint-capabilities.sh capabilities/<name>, bash scripts/validate-capabilities.sh; scripts/mcp-versions.sh test <name> for npx/uvx servers
• Deps: bash scripts/lint-deps.sh deps/<org>/<tool>.sh
• Skills: bash scripts/lint-skills.sh skills/<name>

agents/<domain>/<spec>.toml        one [[roles]], capabilities = [...] at top level
capabilities/<name>/config.toml    triggers (+ optional domains)
capabilities/<name>/<provider>.toml  [deps], [roles.mcp], [[mcp.servers]]
capabilities/<name>/default.toml   symlink to the active provider (real file for core, agent, orchestration)
deps/<org>/<tool>.sh + .md         installer + companion doc
skills/<name>/SKILL.md             frontmatter + body
workflows/<name>.toml              public workflows (owned by octomind:workflow)
bin/load                           resolves capabilities into the merged manifest
scripts/                           lint, validation, symlink setup, MCP pin management

Existing domains are the directories under agents/; a new domain is fine when none fits — name it by what it owns.

Domain routing

Tapping or clicking a native app → device; a web page → browser; writing or changing source → developer.

Capabilities

Agents declare capabilities, never MCP servers. At runtime octomind resolves each name to capabilities/<name>/default.toml (or the provider chosen in the user's [capabilities] config) and merges [deps] require, server_refs, allowed_tools, and [[mcp.servers]] (deduplicated by name); bin/load mirrors this for local checks. capability:provider pins a provider.

• Tiers: core for every agent; domain capabilities as needed; agent for sub-orchestrators; orchestration and runtime only for orchestrators and high-trust agents.
• allowed_tools: server:* exposes all of a server's tools; server:tool, bare names, and trailing-* prefixes narrow it.
• Every server_refs entry needs a matching [[mcp.servers]] block unless it is a built-in (core, octofs, agent, octocode).
• Secrets go in stdio env or http headers as {{ENV:EXACT_VAR_NAME}}; octomind passes env to the child and withholds the capability until the variable is set. Never put secrets in args.
• npx/uvx servers pin an exact version.
• To see what exists, list capabilities/ and read each provider's # Description: header.

Manifests

Required: # Agent:/# Title:/# Description: headers, top-level capabilities, one [[roles]] with system, welcome, temperature, top_p, top_k. Forbidden: name, [deps], [roles.mcp], [[mcp.servers]]. The system prompt uses XML blocks in canonical order with no {{CWD}}, {{DATE}}, or {{SYSTEM}}; those belong in welcome. Sampling values are dropped for models that reject them (current Claude models, thinking-enabled requests, OpenAI reasoning models), so behaviour comes from the prompt. Full spec in the tap-agent-authoring skill.

Multi-step pipelines are not manifest content: they are workflows/*.toml run by octomind workflow. [[layers]] and [[commands]] exist only in a user's local config.

Placeholders

{{INPUT:KEY}} and {{ENV:KEY}} resolve when a manifest loads (stored inputs; environment or a prompt saved to ./.env), and {{ENV:KEY}} in server env/headers resolves again at spawn. {{CWD}}, {{DATE}} and the other prompt placeholders expand only in system and welcome, never inside capability values.