feat: fw-4.19.0 + cli-3.16.0 — Codex CLI (OpenAI) skill support (#203)

Adds a fourth parallel skill distribution under `dist/.codex/skills/` so the
OpenAI Codex CLI can discover StrayMark skills. Codex rejects Claude-only
frontmatter keys (`allowed-tools`) and only loads skills from
`~/.codex/skills/` (user-level), not from the project tree like Claude and
Gemini do — so the release also ships a new CLI subcommand that installs the
project's `.codex/skills/` into the user's Codex home.

Framework (fw-4.19.0):
- New `dist/.codex/skills/` tree (11 skills) generated from `.claude/skills/`
  with minimal frontmatter (only `name` + `description`); body byte-identical.
- `.codex/skills/` added to `dist/dist-manifest.yml`.
- `codex-cli-v1.0` added to the AGENT-RULES `agent:` examples (EN/es/zh-CN).

CLI (cli-3.16.0):
- `straymark install-skills --agent <codex|claude|gemini> [--path .]
  [--dry-run] [--symlink]`: copies (or symlinks) every `straymark-*` skill
  from `<path>/.codex/skills/` into `$CODEX_HOME/skills/` (or `~/.codex/skills/`).
  `--agent claude|gemini` exits with guidance since those agents read from the
  project tree directly.
- `straymark validate --agent codex`: verifies presence of `SKILL.md`,
  parseable YAML frontmatter, required `name`/`description`, and absence of
  Claude-only keys (`allowed-tools`, `argument-hint`, `model`) — a smell of
  someone copying skills from `.claude/`.
- `cli/src/bin/gen_codex_skills`: generator binary; `--check` mode for CI to
  detect drift between `.claude/skills/` and `.codex/skills/`.

Docs:
- CHANGELOG entry for fw-4.19.0 / cli-3.16.0.
- README + CLI-REFERENCE (EN + es + zh-CN): Codex column in skills table,
  `.codex/skills/` in multi-agent diagram, new sections for `install-skills`
  and `validate --agent`, Codex CLI in supported-platforms table.
- Version footers bumped fw-4.18.0 → fw-4.19.0 across governance docs.

Motivated by an adopter using Codex CLI for external Charter audits in
Sentinel. Out of scope for this PR (tracked as follow-ups): umbrella skill,
`agents/openai.yaml` per skill, tool-agnostic body rewrite, integration with
Codex's `~/.codex/skills/.system/skill-installer`.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: montfort

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## Framework 4.19.0 / CLI 3.16.0 — Codex CLI (OpenAI) skill support
+
+Adds first-class distribution of StrayMark skills for the **Codex CLI** (OpenAI), motivated by an adopter using Codex for external Charter audits in the Sentinel project. Codex's skill loader rejects the Claude-only `allowed-tools` frontmatter key and discovers skills only at the **user level** (`~/.codex/skills/`), not from the project tree like Claude and Gemini do. The release ships a fourth parallel skill variant generated from the Claude source, plus a new CLI command to install them.
+
+### Added (Framework)
+
+- **`dist/.codex/skills/` tree (11 skills)** — fourth parallel skill distribution alongside `.claude/skills/`, `.gemini/skills/`, and `.agent/workflows/`. Each `SKILL.md` keeps only the Codex-compatible frontmatter (`name`, `description`); the body is byte-identical to the Claude variant. Generated by `cargo run --bin gen_codex_skills` from the Claude source — one source of truth.
+- **`.codex/skills/` entry in `dist/dist-manifest.yml`** — `straymark init` and `straymark update` now materialize the tree in the adopter's project alongside the existing skill directories.
+
+### Added (CLI)
+
+- **`straymark install-skills --agent <codex|claude|gemini> [--path .] [--dry-run] [--symlink]`** *(new subcommand)* — installs StrayMark skills into an AI agent's user-level skills directory. Currently only `--agent codex` performs work: copies (or symlinks with `--symlink`) every `straymark-*` skill from `<path>/.codex/skills/` into `$CODEX_HOME/skills/` (or `$HOME/.codex/skills/`). `--dry-run` previews without writing. `--agent claude|gemini` exits with an explanatory error because those agents read skills from the project tree directly. Re-installs replace any existing `straymark-*` directories at the target; non-`straymark-*` skills (e.g. Codex's `.system/` bundle) are left untouched.
+- **`straymark validate --agent codex`** — agent-targeted validation path. Inspects `~/.codex/skills/straymark-*` for: presence of `SKILL.md`, parseable YAML frontmatter, required `name`/`description`, and absence of Claude-only keys (`allowed-tools`, `argument-hint`, `model`) whose presence signals a misinstallation (someone copied from `.claude/skills/`).
+- **`cli/src/bin/gen_codex_skills`** — generator binary that transforms `dist/.claude/skills/*/SKILL.md` → `dist/.codex/skills/*/SKILL.md` with minimal frontmatter. Idempotent; supports `--check` for CI to detect drift between the two trees.
+
+### Adopter guidance
+
+Adopters who use Codex CLI should run `straymark update` (or update CLI to `cli-3.16.0` + framework to `fw-4.19.0`), then once per machine:
+
+```bash
+straymark install-skills --agent codex
+straymark validate --agent codex      # confirms the install
+```
+
+Re-run `install-skills` after every `straymark update` to refresh skill content (or use `--symlink` once to track project changes automatically; Unix-only). Adopters who do **not** use Codex are unaffected — the `.codex/skills/` tree adds files but no CLI command runs against it without `--agent codex`.
+
+---
+
 ## Framework 4.18.0 — Polish Charter as debt-detection pattern + "surface declaration without wiring" anti-pattern
 
 Names a recurring anti-pattern surfaced empirically across a polish Charter session in the Sentinel adopter (`StrangeDaysTech/sentinel` CHARTER-19 → CHARTER-27, May 2026): **"Surface declaration without wiring"** — an artifact (env var documented in a runbook, metric instrument declared in a metrics package, URL referenced from an embedded HTML template, route marked public-by-contract) gets declared in one place while the implementation wiring lives in another place, with neither tooling nor review process correlating the two. Integration tests with mock adapters (`humatest`, in-memory event buses) systematically bypass the composed-app boot path where the gap would surface. The polish Charter — the closing Charter of an Etapa / SpecKit `Polish` Phase — is the load-bearing discovery vehicle because it exercises the documented operator runbook end-to-end against the real binary. New pattern doc + small charter-template addition formalize the convention so adopters treat the polish Charter as a debt-detection gate, not as cosmetic cleanup. Originated in [issue #199](https://github.com/StrangeDaysTech/straymark/issues/199). No CLI bump.

README.md

@@ -276,8 +276,8 @@ StrayMark uses independent version tags for each component:
 
 | Component | Tag prefix | Example | Includes |
 | --- | --- | --- | --- |
-| Framework | `fw-` | `fw-4.18.0` | Templates (12 types), governance, directives, Charter template + schema |
-| CLI | `cli-` | `cli-3.15.0` | The `straymark` binary |
+| Framework | `fw-` | `fw-4.19.0` | Templates (12 types), governance, directives, Charter template + schema |
+| CLI | `cli-` | `cli-3.16.0` | The `straymark` binary |
 
 Check installed versions with `straymark status` or `straymark about`.
 
@@ -309,7 +309,7 @@ See [CLI Reference](https://github.com/StrangeDaysTech/straymark/blob/main/docs/
 ```bash
 # Download the latest framework release ZIP from GitHub
 # Go to https://github.com/StrangeDaysTech/straymark/releases
-# and download the latest fw-* release (e.g., fw-4.18.0)
+# and download the latest fw-* release (e.g., fw-4.19.0)
 
 # Extract and copy to your project
 unzip straymark-fw-*.zip -d your-project/
@@ -486,15 +486,17 @@ StrayMark includes skills for AI agents that enable **active documentation creat
 
 ### Available Skills
 
-| Skill | Purpose | Claude | Gemini |
-| --- | --- | --- | --- |
-| `/straymark-status` | Check documentation compliance | ✅ | ✅ |
-| `/straymark-new` | Create any document type (unified) | ✅ | ✅ |
-| `/straymark-ailog` | Quick AILOG creation | ✅ | ✅ |
-| `/straymark-aidec` | Quick AIDEC creation | ✅ | ✅ |
-| `/straymark-adr` | Quick ADR creation | ✅ | ✅ |
-| `/straymark-sec` | Security Assessment creation | ✅ | ✅ |
-| `/straymark-mcard` | Model/System Card creation | ✅ | ✅ |
+| Skill | Purpose | Claude | Gemini | Codex |
+| --- | --- | --- | --- | --- |
+| `/straymark-status` | Check documentation compliance | ✅ | ✅ | ✅ |
+| `/straymark-new` | Create any document type (unified) | ✅ | ✅ | ✅ |
+| `/straymark-ailog` | Quick AILOG creation | ✅ | ✅ | ✅ |
+| `/straymark-aidec` | Quick AIDEC creation | ✅ | ✅ | ✅ |
+| `/straymark-adr` | Quick ADR creation | ✅ | ✅ | ✅ |
+| `/straymark-sec` | Security Assessment creation | ✅ | ✅ | ✅ |
+| `/straymark-mcard` | Model/System Card creation | ✅ | ✅ | ✅ |
+
+> **Codex CLI users** *(fw-4.19.0+)*: Codex reads skills from `~/.codex/skills/` (user-level), not from the project tree. After `straymark init` (or any subsequent `straymark update`), run `straymark install-skills --agent codex` once to populate it from the project's `.codex/skills/`.
 
 ### Usage Examples
 
@@ -552,7 +554,10 @@ your-project/
 ├── .gemini/skills/         # 🔵 Gemini CLI (Google)
 │   ├── straymark-new/SKILL.md
 │   └── ...
-└── .claude/skills/         # 🟣 Claude Code (Anthropic)
+├── .claude/skills/         # 🟣 Claude Code (Anthropic)
+│   ├── straymark-new/SKILL.md
+│   └── ...
+└── .codex/skills/          # 🟢 Codex CLI (OpenAI) — installed to ~/.codex/skills/
     ├── straymark-new/SKILL.md
     └── ...
 ```
@@ -562,6 +567,7 @@ your-project/
 | `.agent/workflows/` | Antigravity, generic | VS Code/Cursor extensions | `skill-name.md` with YAML frontmatter |
 | `.gemini/skills/` | Gemini CLI | Google's terminal CLI | `skill-name/SKILL.md` |
 | `.claude/skills/` | Claude Code | Anthropic's coding agent | `skill-name/SKILL.md` |
+| `.codex/skills/` *(fw-4.19.0+)* | Codex CLI | OpenAI's coding agent | `skill-name/SKILL.md` (minimal frontmatter) — installed to `~/.codex/skills/` via `straymark install-skills --agent codex` |
 
 > **Note**: `.agent/` is the **vendor-agnostic** standard. Agent-specific directories (`.gemini/`, `.claude/`) provide compatibility for those platforms while following their native conventions.
 
@@ -580,6 +586,7 @@ All skill implementations are **functionally identical**—only the format diffe
 | Cursor | `.cursorrules` | ✅ Full support |
 | GitHub Copilot CLI | `.github/copilot-instructions.md` | ✅ Full support |
 | Gemini CLI | `GEMINI.md` | ✅ Full support |
+| Codex CLI (OpenAI) *(fw-4.19.0+)* | `AGENTS.md` + `~/.codex/skills/` | ✅ Full support (run `straymark install-skills --agent codex`) |
 
 ### Operating Systems
 

cli/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "straymark-cli"
-version = "3.15.0"
+version = "3.16.0"
 edition = "2021"
 description = "CLI for StrayMark — the cognitive discipline your AI-assisted projects need"
 license = "MIT"

cli/Cargo.toml

@@ -0,0 +1,195 @@
+// Generator: transforms dist/.claude/skills/*/SKILL.md → dist/.codex/skills/*/SKILL.md
+// with a minimal frontmatter (only `name` + `description`).
+//
+// Usage:
+//   cargo run --bin gen_codex_skills [--check] [<dist-root>]
+//
+// Default <dist-root> is `../dist` relative to CWD (i.e. run from `cli/`).
+// With --check, exits 1 if the destination tree differs from what would be
+// generated. Used in CI to keep `.codex/skills/` in sync with `.claude/skills/`.
+
+use std::env;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process;
+
+fn main() {
+    let mut check_only = false;
+    let mut dist_arg: Option<String> = None;
+    for arg in env::args().skip(1) {
+        if arg == "--check" {
+            check_only = true;
+        } else if !arg.starts_with("--") && dist_arg.is_none() {
+            dist_arg = Some(arg);
+        } else {
+            eprintln!("unknown argument: {arg}");
+            process::exit(2);
+        }
+    }
+    let dist = PathBuf::from(dist_arg.unwrap_or_else(|| "../dist".to_string()));
+    if let Err(e) = run(&dist, check_only) {
+        eprintln!("error: {e}");
+        process::exit(1);
+    }
+}
+
+fn run(dist: &Path, check_only: bool) -> Result<(), String> {
+    let src = dist.join(".claude").join("skills");
+    let dst = dist.join(".codex").join("skills");
+
+    if !src.is_dir() {
+        return Err(format!("source not found: {}", src.display()));
+    }
+
+    let mut produced: Vec<(PathBuf, String)> = Vec::new();
+    let mut names: Vec<String> = Vec::new();
+
+    let mut entries: Vec<_> = fs::read_dir(&src)
+        .map_err(|e| format!("read_dir {}: {e}", src.display()))?
+        .filter_map(Result::ok)
+        .collect();
+    entries.sort_by_key(|e| e.file_name());
+
+    for entry in entries {
+        let path = entry.path();
+        if !path.is_dir() {
+            continue;
+        }
+        let skill_md = path.join("SKILL.md");
+        if !skill_md.exists() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().into_owned();
+        let content = fs::read_to_string(&skill_md)
+            .map_err(|e| format!("read {}: {e}", skill_md.display()))?;
+        let transformed = transform(&content);
+        let out = dst.join(&name).join("SKILL.md");
+        produced.push((out, transformed));
+        names.push(name);
+    }
+
+    if check_only {
+        let mut drift = Vec::new();
+        for (out, expected) in &produced {
+            let actual = fs::read_to_string(out).unwrap_or_default();
+            if &actual != expected {
+                drift.push(out.clone());
+            }
+        }
+        // Also flag extra files in dst that aren't in produced.
+        if dst.is_dir() {
+            for entry in fs::read_dir(&dst).map_err(|e| e.to_string())?.flatten() {
+                let p = entry.path();
+                if !p.is_dir() {
+                    continue;
+                }
+                let n = entry.file_name().to_string_lossy().into_owned();
+                if !names.contains(&n) {
+                    drift.push(p.join("SKILL.md"));
+                }
+            }
+        }
+        if drift.is_empty() {
+            println!("Codex skills are in sync ({} skills).", produced.len());
+            return Ok(());
+        }
+        eprintln!("Codex skills out of sync. Run: cargo run --bin gen_codex_skills");
+        for p in drift {
+            eprintln!("  - {}", p.display());
+        }
+        process::exit(1);
+    }
+
+    // Clean dst and write fresh.
+    if dst.exists() {
+        fs::remove_dir_all(&dst)
+            .map_err(|e| format!("remove_dir_all {}: {e}", dst.display()))?;
+    }
+    fs::create_dir_all(&dst).map_err(|e| format!("create_dir_all {}: {e}", dst.display()))?;
+    for (out, content) in &produced {
+        if let Some(parent) = out.parent() {
+            fs::create_dir_all(parent).map_err(|e| format!("mkdir {}: {e}", parent.display()))?;
+        }
+        fs::write(out, content).map_err(|e| format!("write {}: {e}", out.display()))?;
+    }
+    println!("Generated {} Codex skills in {}", produced.len(), dst.display());
+    for n in &names {
+        println!("  - {n}");
+    }
+    Ok(())
+}
+
+/// Strip Claude-specific frontmatter keys, keeping only `name` and `description`.
+fn transform(content: &str) -> String {
+    let lines: Vec<&str> = content.lines().collect();
+    if lines.first().map(|l| l.trim()) != Some("---") {
+        return content.to_string();
+    }
+    let close_idx = match lines.iter().enumerate().skip(1).find(|(_, l)| l.trim() == "---") {
+        Some((i, _)) => i,
+        None => return content.to_string(),
+    };
+    let fm = &lines[1..close_idx];
+    let body = &lines[close_idx + 1..];
+
+    let mut out = String::new();
+    out.push_str("---\n");
+    let mut in_kept_value = false;
+    for line in fm {
+        let trimmed = line.trim_start();
+        // Top-level key line (no leading whitespace, contains colon before any space).
+        let is_top_level_key = line.len() == trimmed.len() && line.contains(':');
+        if is_top_level_key {
+            let key = trimmed.split(':').next().unwrap_or("");
+            if key == "name" || key == "description" {
+                out.push_str(line);
+                out.push('\n');
+                in_kept_value = true;
+            } else {
+                in_kept_value = false;
+            }
+        } else if in_kept_value {
+            // Continuation of a kept multiline value (indented line).
+            out.push_str(line);
+            out.push('\n');
+        }
+        // Otherwise: continuation of a dropped key — skip.
+    }
+    out.push_str("---\n");
+    for line in body {
+        out.push_str(line);
+        out.push('\n');
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::transform;
+
+    #[test]
+    fn keeps_name_and_description_only() {
+        let input = "---\nname: foo\ndescription: bar\nallowed-tools: Read, Write\nargument-hint: \"X\"\n---\n\n# Body\n";
+        let out = transform(input);
+        assert!(out.contains("name: foo"));
+        assert!(out.contains("description: bar"));
+        assert!(!out.contains("allowed-tools"));
+        assert!(!out.contains("argument-hint"));
+        assert!(out.contains("# Body"));
+    }
+
+    #[test]
+    fn no_frontmatter_passthrough() {
+        let input = "# No frontmatter\nbody\n";
+        assert_eq!(transform(input), input);
+    }
+
+    #[test]
+    fn drops_unknown_keys() {
+        let input = "---\nname: a\nmodel: claude-opus\ndescription: b\n---\nbody\n";
+        let out = transform(input);
+        assert!(!out.contains("model:"));
+        assert!(out.contains("name: a"));
+        assert!(out.contains("description: b"));
+    }
+}