Agents and Automation

Use this guide when an agent, script, or CI job works inside an Arashi meta-repository.

Quick start

Start in the meta-repository root and run aw doctor.
Read the root AGENTS.md, then the instructions in the child repository that owns the change.
Keep implementation, tests, and repository-specific docs in repos/<project>/.
Keep shared plans, specifications, and cross-repository coordination in the meta-repository.
Use aw status when the task needs detailed repository state.
Validate every affected repository before review or handoff.
Use aw handoff when pausing or transferring unfinished work.
Open focused, cross-linked PRs when a change spans repositories.

Install the Arashi skill

Install the optional skill to give supported coding agents reusable Arashi workflow and safety guidance:

npx skills add https://github.com/corwinm/arashi-skills --skill arashi

You can also view it on skills.sh or browse its source.

Keep work in its owning repository

Arashi separates shared coordination from project implementation:

Put code, tests, and project-specific docs in the affected child repository.
Put shared context, plans, specifications, and cross-repository guidance in the meta-repository.
Commit and open PRs separately in every affected repository; one Git commit cannot span them.

A root AGENTS.md only needs to state that boundary, point to child instructions, and name the validation expected in each repository. Avoid copying every child repository’s rules into the root file.

Coordinated workflow

Use the smallest repository set needed for the task:

aw create docs/update-reference --only arashi-docs --no-launch --no-switch
aw status --only arashi-docs
aw exec --only arashi-docs -- pnpm validate

aw create --interactive can build an intentionally partial coordinated worktree. From that worktree, use aw clone to add another configured child on the same branch. Use aw status --verbose or aw status --json when you need to see configured children that were intentionally omitted.

Use aw exec for repeated inspection or validation that is not covered by a built-in command. Apply --only or --group to mutating, network-heavy, or expensive work unless the task explicitly requires every repository.

Handoff

aw handoff produces a read-only report of current workspace state. Add only evidence and context Arashi cannot infer:

aw handoff \
  --link https://github.com/example/project/pull/42 \
  --validation "pnpm validate — passed" \
  --todo "watch CI" \
  --next-command "gh pr checks 42"

Report checks as validation only after they have actually run. Put pending or unverified work under --todo or --risk.

Automation and JSON

Use --json (or -j) when an agent, script, or CI job needs to parse command output.

stdout contains exactly one JSON document followed by a newline.
Human progress, tables, colors, spinners, and prompts stay off stdout.
Check both the process exit status and the envelope’s ok field.
Branch on error.code, not the human-readable message.
Read the fields you need and ignore unknown fields for forward compatibility.
Pass explicit selectors and non-interactive options when a command would otherwise prompt, switch shells, or launch another application.
Use the relevant command reference for command-specific data, warnings, errors, and JSON support.

A successful envelope has this common shape:

{
  "ok": true,
  "command": "status",
  "schemaVersion": 1,
  "data": {},
  "warnings": []
}

Failures use ok: false with a structured error object. stderr remains available for child-command diagnostics and unexpected runtime failures; do not parse human prose from stderr as an API.

Start automation with safe inspection commands:

aw doctor --json
aw status --json
aw list --json

Then use targeted commands such as aw exec --only arashi-docs --json -- pnpm validate. Interactive-only flows return a structured unsupported-mode error instead of prompting.

Specifications are optional

A spec framework such as OpenSpec can keep proposals and tasks in the meta-repository while implementation stays in child repositories. The important contract is repository ownership, not a particular planning tool.