AGENTS.md git:20261012.5832dceB

Immutable. This exact content never changes and is served at /api/v1/blob/61b2f6e2a1946ef8.

# Development Guidelines

## Writing Skills and Guides

### Assume the Agent's Prior Knowledge

Claude Code and Codex already know accessibility standards thoroughly. Do not include:

- WCAG 2.x success criteria definitions
- WAI-ARIA roles, states, and properties
- Basic HTML semantics
- General accessibility principles

Instead, focus on:

- **How** to apply the knowledge (review process, tool usage)
- **What** to output (report format, severity criteria)
- **When** to flag issues for manual verification
- Project-specific conventions

### Keep It Actionable

- Write instructions, not tutorials
- Use tables and lists for quick reference
- Include concrete examples of expected output

## Localization

This project maintains documentation in both English and Japanese.

### File Naming Convention

| English (default) | Japanese |
|-------------------|----------|
| `SKILL.md` | `SKILL.ja.md` |
| `README.md` | `README.ja.md` |
| `references/*.md` | `references/*.ja.md` |

### Sync Rules

- **Always keep English and Japanese versions in sync**
- Japanese (`.ja.md`) files are the source of truth for content
- English files are translations of the Japanese source
- When updating content, update the Japanese version first, then sync to English
- When adding a new file, create both language versions

### Shared Skill Compatibility

- Keep one shared `SKILL.md` for Claude Code and Codex; do not duplicate platform-specific skill bodies.
- Preserve `argument-hint` and `allowed-tools` in skill frontmatter. Claude Code uses them, and the supported Codex runtime tolerates these extensions.
- Validate skills with `npm run validate:skills`. The upstream Codex `quick_validate.py` is not the compatibility gate because it rejects the Claude Code `argument-hint` extension.
- Express workflow steps in terms of capabilities instead of platform-specific tool names.
- Put Codex presentation metadata in `agents/openai.yaml`, not in a second skill file.
- Keep the version synchronized across `.claude-plugin/plugin.json`, both version fields in `.claude-plugin/marketplace.json`, and `.codex-plugin/plugin.json`.

### Language Links

Each file should include a link to its counterpart at the top:

```markdown
# English file
[日本語版 (Japanese)](./FILENAME.ja.md)

# Japanese file
[English](./FILENAME.md)
```

## ship-plan の設定

- **プラン**: `plans/<NNN>-*.md`
- **Issue**: 既存の issue があればその URL をプラン冒頭に `- **Issue**: <url>` で書く。新しく立てない。PR 本文に `Closes #<issue>`
- **着手前に読む**: `AGENTS.md`、`packages/a11y-audit/README.ja.md`
- **検証**: `npm run lint && npm run format:check && npm run typecheck && npm test && npm run validate:skills`
- **整形**: `npx prettier --write <path>`
- **worktree でのコマンド**: `npm --prefix <worktree> run <script>`
- **再レビューが要るパス**: `packages/` `skills/`
- **CI の注意**: CI は `.github/workflows/ci.yml`。`--checks all` の CLI スモークが新しいチェックも通すので、fixture でハングやエラーを起こさないこと