AGENTS.md

1# .agents/ — Project-Scope Skills & Commands (Migration Target)
2 
3**Generated:** 2026-07-17 / 7d664b96b
4 
5## OVERVIEW
6 
7Project-scope skills + slash commands under the new `.agents/` directory name. During the `oh-my-opencode` → `oh-my-openagent` rename transition, this directory is the **target** of the migration from `.opencode/`. It is a strict SUPERSET of `.opencode/` (5 -> 13 skills; 5 commands).
8 
9Loaded alongside `.opencode/` by [`packages/omo-opencode/src/features/opencode-skill-loader/`](../packages/omo-opencode/src/features/opencode-skill-loader/). When both directories declare the same skill or command name, the higher-priority scope wins per the loader's deduplication rules.
10 
11## SKILLS (13, superset of `.opencode/`)
12 
13| Skill | Also in `.opencode/`? | Purpose |
14|-------|------------------------|---------|
15| `work-with-pr/` | yes | Full PR lifecycle |
16| `work-with-pr-workspace/` | yes | Iteration workspace + benchmark inputs |
17| `github-triage/` | yes | Read-only issue/PR triage with evidence reports |
18| `hyperplan/` | yes | Adversarial multi-agent planning |
19| `pre-publish-review/` | yes | 16-agent pre-publish release gate |
20| `get-unpublished-changes/` | NEW | Skill form of the `/get-unpublished-changes` command |
21| `omomomo/` | NEW | Skill form of the `/omomomo` easter egg |
22| `publish/` | NEW | Skill form of the `/publish` command |
23| `remove-deadcode/` | NEW | Skill form of the `/remove-deadcode` command |
24| `security-research/` | NEW | Team Mode security research audit: 3 vulnerability hunters + 2 PoC engineers |
25| `codex-qa/` | no | Isolated Codex Light QA: real `codex app-server` against an isolated `CODEX_HOME` + local mock model, hook-fired assertions; helper scripts each ship `--self-test` |
26| `opencode-qa/` | no | opencode CLI/TUI/event-stream QA: hook-fired assertions via SSE, session DB inspection, tmux TUI smoke; helper scripts each ship `--self-test` |
27| `tech-debt-audit/` | no | Technical-debt audit across 9 dimensions via AST-grep/grep + optional CodeGraph MCP; emits `TECH_DEBT_AUDIT.md` |
28 
29The 5 "NEW" skills here are skill-format equivalents of slash commands that exist in BOTH `.opencode/command/` and `.agents/command/`. They allow the same instructions to be triggered either by an explicit `/command` invocation OR by skill auto-loading on matching prompts. The `codex-qa`, `opencode-qa`, and `tech-debt-audit` skills are `.agents/`-only with no `.opencode/` counterpart and are not command-forms.
30 
31## COMMANDS (5 slash commands)
32 
33Identical set to `.opencode/command/`:
34- `/get-unpublished-changes`
35- `/omomomo`
36- `/publish`
37- `/remove-deadcode`
38- `/security-research`
39 
40## OTHER CONTENTS
41 
42- `background-tasks.json` — Runtime state (parallel to `.opencode/background-tasks.json` during the transition).
43- `bun.lock`, `package.json`, `node_modules/` — Skill dependencies.
44- `.gitignore` — Local scope ignore.
45 
46## MIGRATION STATUS
47 
48| Concern | Plan |
49|---------|------|
50| Why TWO directories? | `.opencode/` is the legacy layout. `.agents/` is the future-proof name after the harness rename. |
51| When does `.opencode/` go away? | After the multi-harness refactor lands and existing users have re-installed. Tracked in [ROADMAP](../ROADMAP.md). |
52| What if both exist with conflicting skills? | The skill-loader dedupes by name. Higher-priority scope wins. The 5 shared skills (`work-with-pr`, `hyperplan`, etc.) are byte-identical between the two dirs today; if they diverge, fix here first. |
53| Where do NEW skills go? | `.agents/` only. Do NOT add new entries to `.opencode/`. |
54 
55## CONVENTIONS
56 
57- **All NEW skills go in `.agents/`.** `.opencode/` is frozen aside from drift-sync of the 5 shared skills.
58- **Drift between shared skills is a bug.** When you update a shared skill, update both copies in the SAME commit until `.opencode/` is removed.
59- **Slash commands stay duplicated.** Both directories must contain the same `command/*.md` set for the transition window.
60 
61## ANTI-PATTERNS
62 
63- Never add a skill to `.opencode/` that does not also exist in `.agents/`.
64- Never let the 5 shared skills drift. CI should eventually enforce byte equality; for now, manual diligence.
65- Never delete `.opencode/` until the multi-harness refactor lands.
66