automata-terrarium

Imported from seijimorimoto/automata-terrarium (AGENTS.md). Install upstream with npx skills add seijimorimoto/automata-terrarium. Copyright stays with the author.

AGENTS.md

This repo stores reusable AI agent workflows for Claude Code and GitHub Copilot CLI: skills, agents, hooks, settings, and sync scripts.

AGENTS.md is the canonical instruction file. CLAUDE.md is kept as a compatibility symlink to this file for Claude Code.

Commit Message Style

Use Conventional Commits for individual commits on non-main branches. Merge commits (e.g., Merge branch 'main' into ...) are exempt — they are auto-generated by git and not subject to the format.

<type>(<scope>): <short summary in imperative mood>

<optional body -- explains the "why", wraps at 72 chars>

Types: feat, fix, docs, refactor, chore, test, style

Scope: the area of the codebase affected (e.g., hook, settings, skills, etc.)

Examples:

feat(skills): add code-review skill
fix(hooks): handle missing stdin in pre-commit hook
docs(settings): document permission presets
chore: update .gitignore

Pull Request Template

## Summary
<!-- 1-3 bullet points describing what this PR does and why -->

## Changes
<!-- List of notable changes, grouped by area if needed -->

## Test plan
<!-- How to verify this works — checklist format -->
- [ ] Step 1
- [ ] Step 2

Branching

• Never commit directly to main — a pre-commit hook enforces this.
• Create feature branches for all changes and merge via PRs.
• Name branches using the format u/{user_name}/{feature_title} (e.g., u/johndoe/organize-core-by-business-concern).

Shell commands

• When running commands like git commit -m or az repos pr create --description, always use single quotes around string arguments to avoid permission issues caused by shell expansion of $() or similar constructs.

Project Structure

skills/      - AI agent skills (shared or target-specific variants per skill)
agents/      - AI subagents/custom agents (Claude .md and Copilot .agent.md variants)
hooks/       - Event-driven hook scripts and runtime-specific hook registrations
settings/    - Reusable settings snippets and permission/config presets
bin/         - Sync executables (terrarium-*)
git-hooks/   - Git hooks for repo workflow (not Claude hooks)

Documentation Conventions

General style

• Docs should be tool-neutral by default. Use generic terms such as "runtime", "agent", "source variant", or "orchestrator" unless a section is explicitly about Claude Code or Copilot CLI.
• Put runtime-specific details under clearly labeled subsections.
• Refer to AGENTS.md, CLAUDE.md, .github\copilot-instructions.md, and similar orchestrator files broadly as "project instructions" unless the runtime-specific filename matters.
• Do not overstate support. Use ✅ only when the repo provides meaningful working support for that runtime.
• Every discoverable entry-point directory should have a README.md explaining its contents and usage. This means each skill, agent, hook, and settings-preset directory, plus any directory linked from a parent README.md.
• Implementation-detail subdirectories (e.g., scripts\, assets\) don't need their own README if the parent already documents them.

Paths

• Use Windows-style backslashes (\) as the primary path format in all inline references and examples (e.g., ~\.claude\hooks\, ~\.copilot\skills\, <project-root>\.github\skills\).
• Shared runtime-neutral workflows should use agent-neutral config/data paths such as ~\.agents\work-status-config.json, ~\.agents\work-status\, and ~\.agents\verify-findings\ instead of a runtime-specific home directory.
• Always show user-level and project-level install locations for both supported tools when applicable:
  • Claude Code user-level: ~\.claude\...
  • Claude Code project-level: <project-root>\.claude\...
  • Copilot CLI user-level: ~\.copilot\...
  • Copilot CLI project-level: <project-root>\.github\...

Code blocks

• Show Windows (PowerShell) commands first, followed by Linux / macOS alternatives in a separate code block.
• Use powershell as the language tag for Windows blocks, sh for Linux/macOS.
• Exception: platform-specific items (e.g., a Windows-only hook) should only show commands for their platform, without the # Windows (PowerShell) comment header.

Availability tables

• Parent-level READMEs (skills\README.md, agents\README.md, hooks\README.md) must include an Available [Skills/Agents/Hooks] table listing every item in that directory. settings\README.md and bin\README.md follow the same pattern for their own contents (presets and sync scripts respectively).
• The repo-level README.md must mirror those tables (and the bin\ script table) for discoverability.
• Every file with an availability table that lists Claude Code and Copilot CLI variants must include the marker legend once before the first availability table in that file.
• Use this exact marker legend format:

  | Marker | Meaning |
  |--------|---------|
  | ✅ | Supported |
  | ❌ | Not supported |
  | ⚠️ | Partial support or manual setup required |
  | 🛠️ | Planned |

• Every availability table that lists Claude Code and Copilot CLI variants must include a Notes column.
• Use ✅ only for broad, working parity. Use ⚠️ for partial, barebones, external-setup, or permission-model gaps. Use 🛠️ only for planned-but-not-implemented support, often tracked by a follow-up issue such as #19.
• Items that cannot be ported to one runtime should stay in the repo as single-target artifacts and be marked with ❌ or ⚠️ in availability tables, with a short note explaining why.

Installation instructions

• Each skill, agent, and hook README must include:
  1. Prerequisites with install commands (not just names).
  2. Install location information for supported runtimes. Include Claude Code (~\.claude\... and <project-root>\.claude\...) and/or Copilot CLI (~\.copilot\... and <project-root>\.github\...) as applicable.
  3. Sync script install steps as the default documented installation path when a sync script supports that artifact type.
  4. Registration or activation steps for each supported runtime, when required.
• Do not include manual copy/install fallback instructions in skill, agent, or hook READMEs by default. If a dedicated manual-install document or section is intentionally added, it must show runtime filename mapping explicitly. For example, agents\<name>\<name>.claude.md must be copied as <name>.md for Claude Code, and agents\<name>\<name>.copilot.md must be copied as <name>.agent.md for Copilot CLI.

Naming

• Use platform suffixes for platform-specific items (e.g., notify-windows instead of notify).

Runtime Hook Conventions

• Claude skill- and agent-scoped hooks are declared in frontmatter (hooks:) and live alongside their owning skill/agent under scripts\.
• Claude session-wide hooks under hooks\ are registered in ~\.claude\settings.json or the project-level equivalent.
• Copilot hooks are registered through ~\.copilot\hooks\*.json, <project-root>\.github\hooks\*.json, or the documented Copilot settings hooks block.
• Copilot hooks are lifecycle/tool hooks, not skill- or agent-frontmatter-scoped hooks. Do not describe Claude frontmatter hooks as Copilot-compatible or as something this repo simply has not added yet.
• Runtime hook preset files under hooks\<name>\ use the naming pattern <orchestrator>.hooks.json, such as claude.hooks.json and copilot.hooks.json.

Artifact Layout Rules

• Prefer shared artifacts when runtime-neutral wording, paths, and behavior are possible. Split variants only for real runtime differences such as frontmatter shape, tool names, hooks, install paths, MCP naming, config paths, or permission mechanics.

Skills

• Each skill must live in its own folder under skills\.
• Use one of these entrypoint layouts:
  • Shared: skills\<name>\SKILL.md when the same file is valid for Claude Code and Copilot CLI.
  • Split: skills\<name>\SKILL.claude.md and skills\<name>\SKILL.copilot.md when runtime-specific frontmatter, tool names, hooks, paths, or instructions are needed.
  • Single-target: skills\<name>\SKILL.claude.md or skills\<name>\SKILL.copilot.md when only one runtime is supported.
• Sync scripts must copy the target-specific variant as SKILL.md into the destination runtime directory.
• Copilot sync must skip Claude-only skills instead of installing Claude-only artifacts.

Agents

• Each agent must live in its own folder under agents\.
• Agent definition files and README.md sit at the top of that folder.
• Co-located implementation files (hook scripts the agent registers via frontmatter, helper scripts, fixtures) go under agents\<name>\scripts\, mirroring the skills convention (skills\<name>\scripts\).
• Use one of these entrypoint layouts:
  • Shared: agents\<name>\<name>.md when the same file is valid for Claude Code and Copilot CLI.
  • Split: agents\<name>\<name>.claude.md and agents\<name>\<name>.copilot.md when runtime-specific frontmatter, tool names, hooks, paths, or instructions are needed.
  • Single-target: agents\<name>\<name>.claude.md or agents\<name>\<name>.copilot.md when only one runtime is supported.
• Sync scripts must copy the target-specific variant to the filename expected by the destination runtime.

Variant alignment

• Keep target-specific variants semantically aligned.
• Shared behavior/instructions should use the same wording as much as practical.
• Diverge only for real runtime differences such as frontmatter shape, tool names, hooks, install paths, MCP naming, config paths, and permission mechanics.

Settings and Permissions

• Permission entries in settings preset files (settings\claude\*.json and settings\copilot\*.json) must be sorted alphabetically.
• Claude settings fragments belong under settings\claude\; do not add new Claude presets at the top level of settings\.
• Copilot settings, launch helpers, and permission notes belong under settings\copilot\.
• Do not imply Copilot settings JSON is equivalent to Claude Code permissions.allow.
• Copilot shell, MCP, URL, and path permissions often require CLI flags (--allow-tool, --deny-tool, --allow-url, --allow-all-paths), /mcp setup, skill allowed-tools, agent tools, or hooks.
• Mark Copilot settings support as ⚠️ unless the repo provides the full required setup.

Sync and Validation

• Sync scripts are target-specific.
• Claude sync installs Claude-compatible artifacts and filters/skips Copilot-only artifacts.
• Copilot sync installs Copilot-compatible artifacts and skips Claude-only artifacts.
• Sync scripts should support -DryRun.
• Use bin\terrarium-validate.ps1 to enforce dual-target invariants such as instruction-file compatibility, skill/agent entrypoint layout, Copilot frontmatter requirements, README availability coverage, and target-specific settings conventions.

Security

• Do not commit secrets, credentials, or .env files.