Optional subsystems19AI Agent Workflows

Supported commands

The environment provides wrapper support for agents such as claude, qwen, agy, gemini, codex, opencode, and copilot. The generic ai command can start or manage these wrappers.

To start whichever installed agent is preferred by the wrapper logic:

ai start

ai start tries each supported wrapper in a fixed order, launching the first one it finds installed, and stops there: it checks opencode, then agy, gemini, qwen, copilot, claude, and finally codex. This order is fixed in the wrapper script and is not user-configurable; to bypass it, start the wrapper you want directly by name. If no supported wrapper is installed, ai start prints a list of the agents that can be installed and exits with a non-zero status.

You can also start a specific wrapper through ai, such as ai codex or ai claude, or by running the wrapper command directly. Use the wrapper command name itself when you want its dedicated command reference, such as codex, claude, gemini, qwen, or opencode.

The ai management command

The generic ai command is the management layer above the individual wrappers. It can start whichever installed agent is available, forward directly to a named wrapper, manage the shared skills directory, and edit the user's persistent AGENTS.md file.

The most common commands are:

ai start

ai codex --continue

ai agentsmd edit

ai skills list -v

ai codex --continue and ai agentsmd edit hand off to an interactive program (the codex CLI, or an editor) and produce no output of their own to inspect; success looks like the named program starting normally. ai skills list -v prints a flat list and is useful for confirming what an agent will actually see; a representative excerpt looks like:

ai skills list -v

AI skills (* for user skills, ! for user skills which shadow):



  * adding-agent-tools

      - Use when adding a new AI agent tool to the RISC OS build environment.



    allocating-resources

      - Guidance for registering RISC OS allocations with the RISC OS Open

        allocation service. Use when the user wants to register a module

        name, SWI chunk, error block, *command, filetype, system variable,

        or any other RISC OS allocation...

(remaining skills omitted)

A leading * marks a user skill from ~/.config/ai/skills; a leading ! marks a user skill that shadows (overrides) a system skill of the same name from /etc/agentskills; no marker means the skill is taken from the system directory unmodified.

User skills live in ~/.config/ai/skills and override matching system skills from /etc/agentskills. The command ai skills setup creates the shared ~/.agents/skills view used by multiple agent wrappers by symlinking every user skill into it first, then symlinking each system skill only if no user skill of the same name has already claimed that name; this is why a user skill always wins over a system skill with the same name in the merged view, and it is also why ai skills setup must be re-run (it runs automatically as part of ai skills list and most other ai skills subcommands) after adding or removing a user skill, so that the merged view picks up the change.

Wrapper-specific startup behaviour

Each supported wrapper uses its own upstream CLI and preserves its own per-project state, but the environment tries to make them behave consistently:

• codex stores per-project state under ~/.config/ai/codex/project.<name>/, keeps authentication in the shared file ~/.config/ai/codex/auth.json via per-project symlinks, merges system, user, and project configuration, and maps --continue to resume --last;
• claude stores per-project state under ~/.config/ai/claude/project.<name>/ and links the shared skills plus a CLAUDE.md view of the user's instructions;
• gemini stores per-project state under ~/.config/ai/gemini/project.<name>/, links ~/.gemini there, and maps --continue to --resume latest;
• qwen stores per-project state under ~/.config/ai/qwen/project.<name>/, links ~/.qwen there, and generates a QWEN.md instructions file;
• opencode stores project config, data, state, and cache under ~/.config/ai/opencode/project.<name>/ and maps --continue to run -c;
• agy (Antigravity, Google's agentic coding CLI) stores per-project state under ~/.config/ai/agy/project.<name>/, merges system and user AGENTS.md content into that project directory, and copies saved credentials forward from the previous project the first time a new project is used;
• copilot stores per-project state under ~/.config/ai/copilot/project.<name>/, exposes the shared skills through a skills symlink inside that directory, builds a combined copilot-instructions.md from the system and user AGENTS.md files, and maps --continue to resume --last.

In all these cases the wrapper exists to keep project state separate and to inject the build environment's instructions and skills into the upstream CLI's normal configuration model.

Project isolation

Wrapper state is kept distinct by project base directory. In practice this means that running an agent inside one Git repository does not pollute the history or cached state of another repository. This behaviour is important in the build environment because the container path is stable while the host project may vary.

AGENTS.md and shared skills

Agents are expected to read project instructions from files such as AGENTS.md. The build environment also supplies system guidance in /etc/agents/AGENTS.md and a shared skills mechanism under /etc/agentskills.

The user's personal configuration file can be edited through ai agentsmd nano or ai agentsmd edit. User skills live in ~/.config/ai/skills and override system skills when the same skill name exists in both places.

For what each shipped system skill is for and how it can help, see Appendix Z: AI agent skills.

To edit the user's own persistent guidance file:

ai agentsmd edit

Practical usage boundaries

The environment is set up to help agents inspect files, run tools, and follow RISC OS-specific guidance, but it does not remove the need for normal human judgement. Users should still constrain goals clearly, expect occasional wrong turns, and provide explicit boundaries where testing, commits, or network operations should be limited.

Recommended workflow

For early use, a small empty project is the easiest place to learn the agent behaviour. Typical prompts ask the agent to read a specification file, build a small command, or create a new module skeleton before moving to more complex tasks such as remote testing or reverse engineering.

Skill visibility is easiest to inspect with:

ai skills list -v

If a specific wrapper supports a more suitable resume or one-shot mode, use the wrapper directly. For example, codex --continue, claude --continue, or opencode --continue preserve the wrapper-specific session behaviour while still using the project's isolated configuration.