feat: add cross-tool support for OpenCode and Codex CLI

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ralph-specum",
       "description": "Spec-driven development with research, requirements, design, tasks, and autonomous execution. Fresh context per task.",
-      "version": "3.3.3",
+      "version": "3.4.0",
       "author": {
         "name": "tzachbon"
       },

.gitignore

@@ -1,3 +1,6 @@
+# Generated files (created by generate-agents-md.sh / config bridge)
+AGENTS.md
+
 # State files (created at runtime in user's spec directory)
 .ralph-state.json
 **/.progress.md

CLAUDE.md

@@ -100,6 +100,25 @@ Quality checkpoints inserted every 2-3 tasks throughout all phases.
 
 Spec-executor must output `TASK_COMPLETE` for coordinator to advance. Coordinator outputs `ALL_TASKS_COMPLETE` to end the Ralph Loop. If task fails, retries up to 5 times then blocks with error.
 
+### Cross-Tool Adapters
+
+```
+adapters/
+├── opencode/              # OpenCode execution loop adapter (TS hooks)
+│   ├── hooks/execution-loop.ts
+│   └── README.md
+├── codex/                 # Codex CLI SKILL.md adapter (hook-free)
+│   ├── skills/ralph-implement/SKILL.md
+│   ├── AGENTS.md.template
+│   └── README.md
+└── config/                # Configuration bridge (multi-tool setup)
+    ├── ralph-config.schema.json
+    ├── generate-config.sh
+    └── README.md
+```
+
+Universal SKILL.md files live in `plugins/ralph-specum/skills/workflow/` and work across all three tools (Claude Code, OpenCode, Codex CLI).
+
 ### Dependencies
 
 Ralph Specum v3.0.0+ is self-contained with no external plugin dependencies. The execution loop is handled by the stop-hook.

CONTRIBUTING.md

@@ -159,6 +159,36 @@ How you tested it
 - Use kebab-case for files: `spec-executor.md`, `task-planner.md`
 - Use descriptive names that indicate purpose
 
+## Cross-Tool Testing
+
+Smart Ralph supports Claude Code, OpenCode, and Codex CLI. When making changes, verify cross-tool compatibility:
+
+### Run the test suite
+
+```bash
+# SKILL.md discoverability (frontmatter, progressive disclosure, tool-agnosticism)
+bash tests/test-skill-discovery.sh
+
+# Spec artifact portability (templates, state files, schemas)
+bash tests/test-artifact-portability.sh
+
+# Claude Code zero-regression (plugin.json, hooks, commands, agents unchanged)
+bash tests/test-claude-code-regression.sh
+```
+
+### What to check
+
+- **SKILL.md changes**: Ensure no Claude Code-specific references leak in (no "Task tool", "AskUserQuestion", "TeamCreate", "allowed-tools", "subagent_type")
+- **Template/schema changes**: Run `test-artifact-portability.sh` to verify tool-agnosticism
+- **Plugin core changes**: Run `test-claude-code-regression.sh` to verify zero regression
+- **Adapter changes**: Test with the target tool if available, otherwise verify file structure and content
+
+### Adapter directories
+
+- `adapters/opencode/` - OpenCode execution loop hooks (TypeScript)
+- `adapters/codex/` - Codex CLI SKILL.md adapter (no code, pure guidance)
+- `adapters/config/` - Configuration bridge script
+
 ## Getting Help
 
 Stuck? Have questions?

README.md

@@ -396,6 +396,81 @@ Specs live in `./specs/` in your project:
 
 ---
 
+## Cross-Tool Support
+
+Smart Ralph works across multiple AI coding tools. The spec-driven workflow (research, requirements, design, tasks, execute) is portable via universal SKILL.md files.
+
+### Tool Support Matrix
+
+| Feature | Claude Code | OpenCode | Codex CLI |
+|---------|------------|----------|-----------|
+| Spec workflow (research through tasks) | Full (plugin commands) | Full (SKILL.md) | Full (SKILL.md) |
+| Execution loop | Automatic (stop-hook) | Automatic (TS hooks) | Manual (re-invoke skill) |
+| Parallel research | TeamCreate | Subagents | Sequential |
+| AGENTS.md generation | Optional | Recommended | Recommended |
+
+### Quick Start: Claude Code
+
+Already works via the plugin system. No additional setup needed.
+
+```bash
+/plugin marketplace add tzachbon/smart-ralph
+/plugin install ralph-specum@smart-ralph
+# Restart Claude Code, then:
+/ralph-specum:start my-feature Add a cool feature
+```
+
+### Quick Start: OpenCode
+
+Copy the adapter files and configure `opencode.json` to use the execution loop hooks.
+
+```bash
+# 1. Copy adapter hooks
+cp -r adapters/opencode/hooks/ .opencode/hooks/
+
+# 2. Copy workflow SKILL.md files
+cp -r plugins/ralph-specum/skills/workflow/ .opencode/commands/
+
+# 3. Configure opencode.json (add plugin entry)
+# See adapters/opencode/README.md for full config
+
+# 4. Use workflow skills: $ralph:start, $ralph:research, etc.
+```
+
+See [adapters/opencode/README.md](adapters/opencode/README.md) for full setup instructions.
+
+### Quick Start: Codex CLI
+
+Copy SKILL.md files to `.agents/skills/` and use skill discovery to drive the workflow.
+
+```bash
+# 1. Copy workflow skills
+mkdir -p .agents/skills/
+cp -r plugins/ralph-specum/skills/workflow/ .agents/skills/ralph/
+
+# 2. Copy Codex-specific implement skill (overrides default)
+cp adapters/codex/skills/ralph-implement/SKILL.md .agents/skills/ralph/implement/SKILL.md
+
+# 3. (Optional) Generate AGENTS.md from a spec's design.md
+bash plugins/ralph-specum/scripts/generate-agents-md.sh --spec-path ./specs/my-feature
+
+# 4. Invoke skills manually: "use the ralph start skill", etc.
+```
+
+See [adapters/codex/README.md](adapters/codex/README.md) for full setup instructions.
+
+### Configuration Bridge
+
+Use the configuration bridge to generate tool-specific configs from a single `ralph-config.json`:
+
+```bash
+bash adapters/config/generate-config.sh
+```
+
+See [adapters/config/README.md](adapters/config/README.md) for config format and options.
+
+---
+
 ## Troubleshooting
 
 **Task keeps failing?**

adapters/codex/AGENTS.md.template

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+> Project instructions generated from spec: {{spec_name}}
+
+## Architecture
+
+{{architecture_section}}
+
+## Coding Conventions
+
+{{conventions_section}}
+
+## File Structure
+
+{{file_structure_section}}
+
+## Key Decisions
+
+{{decisions_section}}
+
+---
+
+## Ralph Spec Workflow
+
+This project uses [Smart Ralph](https://github.com/tzachbon/smart-ralph) for spec-driven development.
+
+### Active Spec
+
+- **Spec**: {{spec_name}}
+- **Spec directory**: `{{spec_path}}`
+- **Current phase**: Check `.ralph-state.json` in the spec directory
+
+### Available Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `ralph-implement` | Execute the next task from tasks.md |
+
+To execute tasks, invoke the `ralph-implement` skill. It reads the state file, runs one task, and prompts you to re-invoke for the next.
+
+### Spec Artifacts
+
+| File | Description |
+|------|-------------|
+| `{{spec_path}}/research.md` | Codebase analysis and external research |
+| `{{spec_path}}/requirements.md` | User stories, acceptance criteria, FR/NFR |
+| `{{spec_path}}/design.md` | Architecture, components, technical decisions |
+| `{{spec_path}}/tasks.md` | Ordered task list with Do/Verify/Commit format |
+| `{{spec_path}}/.progress.md` | Progress tracking and learnings |
+| `{{spec_path}}/.ralph-state.json` | Execution state (current task index) |
+
+---
+*Generated by Ralph Specum*