Repository navigation
Description
User Story
While reviewing OpenShell's Gator relocation in #5739, I encountered multiple definitions of the principal engineer reviewer and framework-specific skill directories. I need consistent contributor skills and reviewer behavior across Claude Code, Codex, and OpenCode without maintaining independent copies of the same policy.
Description
Reconcile .claude/, .codex/, and .opencode/ with the shared agent and skill layout in .agents/. Reassess discovery, configuration, and invocation against the frameworks' current capabilities; the existing arrangements predate their current support for portable skills and agents.
Inventory which files are canonical instructions, framework adapters, symlinks, generated artifacts, or local runtime state. Establish a maintainable source of truth for shared behavior while preserving necessary framework-specific metadata, permissions, and invocation details. Document intentional differences rather than silently allowing policy drift.
Study obra/superpowers for applicable compatibility patterns. Evaluate these patterns for OpenShell rather than requiring adoption of the framework or its workflows.
Context and Findings
.claude/skillsis a tracked symlink to../.agents/skills/, not a second set of skills..claude/agents/principal-engineer-reviewer.mdand.opencode/agents/principal-engineer-reviewer.mdare separate tracked files. Their bodies differ materially beyond framework-specific frontmatter, including review calibration, finding persistence, and Gator's evidence contract.- Gator currently copies the Claude definition into its payload and executes it through the selected harness, currently Codex. Its manifest, README, and ledger tests reference that Claude-specific source.
- A TOML definition of the same reviewer under
.codex/was also identified by the operator. That directory is ignored by.gitignoreand absent from the inspected checkout and fetchedmain; inspect the operator's copy and determine which configuration belongs in version control versus local state. .claude/README.mddescribes equivalent personas with different framework configuration, which does not reflect the observed policy drift.
Superpowers references inspected at commit 22f0b463e7a5e579904dd6211a520321035526f7:
- Shared skill instructions with platform adaptation references.
- Codex plugin manifest pointing to shared skills and Claude plugin manifest.
- OpenCode discovery, installation, migration, and tool mappings.
Related: #5739 (Gator bundle relocation), #5723 (agent organization).
Definition of Done
- Inventory all three framework directories, including the operator's Codex TOML reviewer, and document canonical content, adapters, links, and local state.
- Record the supported framework versions and compare current discovery and agent mechanisms with the relevant Superpowers patterns.
- Shared reviewer policy and skills have an explicit canonical source; necessary framework-specific differences remain explicit and do not require manually synchronizing policy copies.
- Gator consumes the canonical reviewer instructions, with manifest, test, and documentation references updated together.
- Decide and document the treatment of
.codex/in.gitignore, preserving local credentials and runtime state outside version control. - A contributor can discover the intended skills and invoke the reviewer through each supported framework using documented setup, without duplicate discovery or policy drift.
- Add focused validation for discovery, adapter/configuration validity, and shared-policy consistency; verify required permissions are preserved.
- Update contributor documentation and affected skills using
sync-agent-infra, with a migration path for existing checkouts.
Activity
purp commentedon Nov 19, 2026
Decisions
Current discovery (checked against each tool's docs):
.claude/skills/only.claude/agents/only.agents/skills/.codex/agents/*.toml.agents/skills/or.claude/skills/.opencode/agents/only.claude/agent-memory/. Keep the reviewer's current default behavior (memory: project, which also grants Read/Write/Edit for memory upkeep). Because.claude/becomes ignored, that memory is now local state instead of tracked content..agents/agents/principal-engineer-reviewer/prompts/principal-engineer-reviewer.mdwith no framework frontmatter. Per-framework frontmatter lives inadapters/claude.yamlandadapters/opencode.yaml, and a README explains what it is and where it is used. This mildly violates the.agents/agents/runtime layout from feat(review): add labeling agent in Claude Managed Agents #5407 (norun.*); chore(agents): make principal-engineer-reviewer a complete agent #5747 tracks turning it into a complete agent. The newer Claude body is canonical, so OpenCode picks up the review calibration and Gator evidence contract it was missing..agents/skills/discovery works against this issue's acceptance criteria..claude/and.opencode/from version control and ignore them.mise run agents:setupgenerates.claude/skills(a symlink to../.agents/skills),.claude/agents/principal-engineer-reviewer.md, and.opencode/agents/principal-engineer-reviewer.md. Migration for existing checkouts: pull, then runmise run agents:setup..codex/stays ignored. Codex already reads.agents/skills/, and Gator covers Codex reviewer runs through its payload, so no tracked TOML reviewer is needed.Validation:
mise run test:agent-adapters(run in Branch Checks) checks that every adapter embeds the canonical prompt unchanged, preserves each framework's permissions, and creates the skills link.chore(agents): Fix `principal-eng-reviewer.md` drift and obsolete `.c…