Merge branch 'main' into garrytan/team-supabase-store

Resolved 4 conflicts:
- scripts/gen-skill-docs.ts: kept ARTIFACT_SETUP + added main's new
  resolvers (SPEC_REVIEW_LOOP, DESIGN_SKETCH, BENEFITS_FROM,
  CODEX_REVIEW_STEP). Updated codex review-log to use new paths.
- ship/SKILL.md.tmpl: adopted {{CODEX_REVIEW_STEP}} macro from main
- test/skill-e2e.test.ts: added main's new E2E tests (office-hours
  spec review, plan-ceo benefits-from) + kept our E2E isolation cleanup

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CONTRIBUTING.md

@@ -216,10 +216,11 @@ SKILL.md files are **generated** from `.tmpl` templates. Don't edit the `.md` di
 # 1. Edit the template
 vim SKILL.md.tmpl              # or browse/SKILL.md.tmpl
 
-# 2. Regenerate
+# 2. Regenerate for both hosts
 bun run gen:skill-docs
+bun run gen:skill-docs --host codex
 
-# 3. Check health
+# 3. Check health (reports both Claude and Codex)
 bun run skill:check
 
 # Or use watch mode — auto-regenerates on save
@@ -230,6 +231,60 @@ For template authoring best practices (natural language over bash-isms, dynamic
 
 To add a browse command, add it to `browse/src/commands.ts`. To add a snapshot flag, add it to `SNAPSHOT_FLAGS` in `browse/src/snapshot.ts`. Then rebuild.
 
+## Dual-host development (Claude + Codex)
+
+gstack generates SKILL.md files for two hosts: **Claude** (`.claude/skills/`) and **Codex** (`.agents/skills/`). Every template change needs to be generated for both.
+
+### Generating for both hosts
+
+```bash
+# Generate Claude output (default)
+bun run gen:skill-docs
+
+# Generate Codex output
+bun run gen:skill-docs --host codex
+# --host agents is an alias for --host codex
+
+# Or use build, which does both + compiles binaries
+bun run build
+```
+
+### What changes between hosts
+
+| Aspect | Claude | Codex |
+|--------|--------|-------|
+| Output directory | `{skill}/SKILL.md` | `.agents/skills/gstack-{skill}/SKILL.md` |
+| Frontmatter | Full (name, description, allowed-tools, hooks, version) | Minimal (name + description only) |
+| Paths | `~/.claude/skills/gstack` | `~/.codex/skills/gstack` |
+| Hook skills | `hooks:` frontmatter (enforced by Claude) | Inline safety advisory prose (advisory only) |
+| `/codex` skill | Included (Claude wraps codex exec) | Excluded (self-referential) |
+
+### Testing Codex output
+
+```bash
+# Run all static tests (includes Codex validation)
+bun test
+
+# Check freshness for both hosts
+bun run gen:skill-docs --dry-run
+bun run gen:skill-docs --host codex --dry-run
+
+# Health dashboard covers both hosts
+bun run skill:check
+```
+
+### Dev setup for .agents/
+
+When you run `bin/dev-setup`, it creates symlinks in both `.claude/skills/` and `.agents/skills/` (if applicable), so Codex-compatible agents can discover your dev skills too.
+
+### Adding a new skill
+
+When you add a new skill template, both hosts get it automatically:
+1. Create `{skill}/SKILL.md.tmpl`
+2. Run `bun run gen:skill-docs` (Claude output) and `bun run gen:skill-docs --host codex` (Codex output)
+3. The dynamic template discovery picks it up — no static list to update
+4. Commit both `{skill}/SKILL.md` and `.agents/skills/gstack-{skill}/SKILL.md`
+
 ## Conductor workspaces
 
 If you're using [Conductor](https://conductor.build) to run multiple Claude Code sessions in parallel, `conductor.json` wires up workspace lifecycle automatically: