[bracyw]

Changes

Add Argos's default Codex workspace. CI merges main into each workspace tree, prepares inheritance using the merged harness/configuration, validates ownership, and publishes one changed commit. Canonical Claude skills stay on main; inherited native copies and their ledger live only on workspace branches.

Each harness descriptor supplies native paths, a translator and optional settings generation. Skill references use the receiving workspace's catalog. Claude skill bytes and existing workspace configuration stay intact.

Diagram

One refresh: merge main → prepare inheritance for the merged harness → commit changed files → push.
Blue steps run the shared native preparation pipeline. All preparation happens in temporary CI files.

1. The workspace branch receives one finished result

---
config:
  theme: base
  htmlLabels: false
  fontSize: 16
  themeVariables:
    primaryColor: '#f3f4f6'
    primaryTextColor: '#111827'
    primaryBorderColor: '#64748b'
    nodeTextColor: '#111827'
    clusterBkg: '#f8fafc'
    clusterBorder: '#94a3b8'
    titleColor: '#111827'
    lineColor: '#64748b'
    edgeLabelBackground: '#f3f4f6'
  flowchart:
    htmlLabels: false
    useMaxWidth: true
    subGraphTitleMargin:
      top: 10
      bottom: 18
---
flowchart TD
    CHANGE["Push to main or ws/name"] --> SYNC["ci/sync.sh: refresh()"]
    subgraph CI["Temporary CI workspace"]
        MERGE["1. Merge main into workspace tree"]
        RENDER["2. stage_inheritance()"]
        APPLY["3. apply_inheritance()"]
        COMMIT["4. Create publish commit if changed"]
        MERGE --> RENDER --> APPLY --> COMMIT
    end
    SYNC --> MERGE
    COMMIT --> PUSH["5. Push ws/name"]
    style RENDER fill:#eff6ff,stroke:#2563eb,color:#111827,stroke-width:2px

Loading

Step 2 reads the merged workspace.yml. Step 3 verifies ownership and installs the prepared bytes,
ledger and native settings; main's runtime is added before publication. Owned-file conflicts are
reported. An unchanged tree leaves the workspace ref untouched. Prior source output may be replayed
to verify ownership during application; there is no current-source render before the merge.

Claude inheritance	Before this PR	With this PR
Call path	refresh() → with_inherited() → inherited()	refresh() → shared preparation below → Claude descriptor
Result	Original .claude/skills/ files	Same paths and bytes, plus ownership tracking

2. Every harness uses these shared function calls

Solid arrows are calls. The workspace harness selects the descriptor used for path mapping and content.

---
config:
  theme: base
  htmlLabels: false
  fontSize: 16
  themeVariables:
    primaryColor: '#f3f4f6'
    primaryTextColor: '#111827'
    primaryBorderColor: '#64748b'
    nodeTextColor: '#111827'
    clusterBkg: '#f8fafc'
    clusterBorder: '#94a3b8'
    titleColor: '#111827'
    lineColor: '#64748b'
    edgeLabelBackground: '#f3f4f6'
  flowchart:
    htmlLabels: false
    useMaxWidth: true
    subGraphTitleMargin:
      top: 10
      bottom: 18
---
flowchart TD
    STAGE["ci/sync.sh: stage_inheritance()"] --> RENDER["ci/render.sh: render_workspace()"]
    RENDER --> SELECT["ci/inherit.sh: inherited_files()"]
    SELECT --> BUNDLE["ci/sources.sh: bundle_files()"]
    BUNDLE --> PATH["source_path(): map destination"]
    RENDER --> FILE["ci/harnesses.sh: harness_file()"]
    FILE --> CONVERT["Descriptor: translate_skill()"]
    style PATH fill:#eff6ff,stroke:#2563eb,color:#111827,stroke-width:2px
    style CONVERT fill:#eff6ff,stroke:#2563eb,color:#111827,stroke-width:2px

Loading

source.yml selects the input format (Claude by default); the workspace's harness: selects the
output. The renderer hashes the exact prepared bytes into workspace.generated. Non-skill helper
scripts keep their bytes. apply_inheritance() checks these records against trusted prior output,
protects owned/retired files and copies the prepared output into the merged workspace tree.

Codex example	Source	Prepared result
Skill destination	.claude/skills/commit/SKILL.md	.agents/skills/commit/SKILL.md
Skill content	/commit, CLAUDE.md, allowed-tools	$commit, AGENTS.md, omitted unsupported field
Helper command text	bash scripts/x.sh	Explicit .delphi/exec.sh invocation

Conversion happens during CI preparation. The harness reads finished native files on its branch;
the command wrapper runs later, when a helper is invoked. Qualified paths and filenames in inline or fenced code stay literal. Bare instruction names in prose map to the target instruction file.

3. A new harness plugs into the descriptor interface

---
config:
  theme: base
  htmlLabels: false
  fontSize: 16
  themeVariables:
    primaryColor: '#f3f4f6'
    primaryTextColor: '#111827'
    primaryBorderColor: '#64748b'
    nodeTextColor: '#111827'
    clusterBkg: '#f8fafc'
    clusterBorder: '#94a3b8'
    titleColor: '#111827'
    lineColor: '#64748b'
    edgeLabelBackground: '#f3f4f6'
  flowchart:
    htmlLabels: false
    useMaxWidth: true
    subGraphTitleMargin:
      top: 10
      bottom: 18
---
flowchart TD
    CONFIG["workspace.yml: harness"] -. selects .-> LOAD["Load ci/harnesses/HARNESS.sh"]
    FILE["harness_file(harness, file)"] --> LOAD
    LOAD -->|claude-code| CLAUDE["claude-code.sh"]
    LOAD -->|codex| CODEX["codex.sh"]
    LOAD -->|future| NEW["future.sh: add descriptor"]
    CLAUDE --> CAT["translate_skill(): cat"]
    CODEX --> CONVERT["translate_skill(): convert"]
    NEW --> CUSTOM["translate_skill(): your conversion"]
    style NEW fill:#e6f4ea,stroke:#1a7f37,color:#111827,stroke-width:2px
    style CUSTOM fill:#e6f4ea,stroke:#1a7f37,color:#111827,stroke-width:2px

Loading

Add a descriptor and its instruction template, implement its translator, then select the harness in
workspace.yml. Shared sync, rendering, validation and creation use the registered interface.

Shared caller	Descriptor supplies
source_path() → harness_field()	Native instruction and skill paths
harness_file() → translate_skill()	Native metadata, identifiers and helper guidance
harness_settings() → registered generator	Optional native settings generation
tools/new-workspace.sh → harness_field()	Instruction template and optional common base

Creation, proposals and runtime

• Creation: tools/new-workspace.sh seeds owned defaults once through the same path/content
  adapters, generates settings and opens a main PR. Inherited copies and ledgers stay off main.
• Proposals: propose() merges into a temporary main candidate, verifies and removes managed
  inheritance, then regenerates settings and runs ci/check.sh. Owned native files and opted-out
  copies return to main in their existing format.
• Validation: ci/check.sh uses ci/render.sh --check, plus .delphi/names.sh and
  .delphi/version.sh. Validation may independently render disposable output.
• Runtime: Codex uses .delphi/exec.sh → .delphi/paths.sh → helper; Claude retains its
  SessionStart hook. Workspace setup/switch/parking and code worktrees keep their existing layout.

Testing

• 193 sandbox end-to-end checks pass, including ShellCheck, repository validation and migration coverage.
• Regressions cover merge-first preparation, branch-only harness switches, ownership/retirement protection, failed-proposal isolation and unchanged refs.
• Translation regressions preserve literal filenames, paths and commands; retain native backticked skill calls; report known Claude leaks with translated-line diagnostics; and isolate each workspace's skill catalog.
• All staged Claude skill copies remain byte-identical to their sources. A generated Codex command runs the real journal helper from a fresh environment and unrelated directory, with spaces in the workspace path.
• Codex CLI 0.159.2 loads all 17 staged Argos skills without errors; forced reloads are stable and all 32 staged hashes/modes match their ledger.
• All three PR diagrams and the design diagram pass browser checks for unclipped SVG text in light and dark themes.

Notes

Runtime release 2.1.0 adds the shared command bootstrap on top of main's 2.0.0. CI creates ws/s.app.argos.default-codex after merge. Existing native workspace configuration and the Argos development workflow remain intact. Shared paths and opt-outs support + and @; spaces and control characters remain unsupported and are documented. Owned filenames are unaffected.

The ownership regression also covers #81, which remains open for review. Ownership is validated during application using trusted prior source output, with historical replay when required. Current inheritance generation happens after the merge. Codex uses per-command bootstrap; this setup has no Codex SessionStart hook. Host provisioning stays separate. Tests ran on Linux; no live model or Argos application smoke test ran. Real Claude mod tests were skipped because its executable is unavailable.

Checklist

• ci/check.sh and sandbox end-to-end checks pass for this revision
• Canonical Claude skill definitions and existing workspace configuration remain unchanged
• Release 2.1.0 hash and main merge are validated
• Request reviewers & ping on Slack

[bracyw]

Review: bugs and suggested fixes

tests/e2e.sh (173 checks), ci/check.sh . and shellcheck all pass on 646a452. The bugs below were reproduced in a sandbox built from merge base 4e89012 (old sync creates the ws branches, then this PR's tree goes on main) unless marked otherwise.

Merge conflict

Only .delphi/manifest.yml and .delphi/versions conflict. Main is now at 2.0.0, so the 1.3.0/1.3.1 entries no longer go up from it. Fix: replace them with one 2.1.0 line (MINOR, since exec.sh is new) with a fresh version.sh hash. Drop 1.3.1: it describes removing a launcher that main never had.

High

1. ci/sync.sh:337-346: every main commit pushes to every ws branch. The no-op guard now also requires main to be an ancestor of the branch. So an unrelated main commit, such as a README edit, pushes 3 commits that leave the tree unchanged ("prepare owned files", merge, "sync generated") to all 6 ws branches. Each push starts another CI sync, and the empty commits land in people's clones. The e2e test "unrelated main changes leave other ws branches' trees alone" compares trees, so it misses this.
   Fix: skip the push when the resulting tree equals the branch's tree, or squash strip/merge/re-add into one commit. Make the test compare refs.

2. ci/sync.sh:84-100, 128-143: renaming a folder while keeping its short-name breaks refresh for good. previous_records looks up $base:<new folder>/workspace.yml, which doesn't exist, so the trusted set comes back empty. Every inherited file then fails with CONFLICT: workspace-owned … collides with managed output on every sync. (Repro: rename nero → nero-app with short-name nero.) The current sync handles this case.
   Fix: find the previous folder by workspace name (names.sh at the base revision), not by path.

3. ci/sources.sh:37-41 + ci/render.sh: a Claude-only file in a shared workspace-inherit/ makes check.sh fail for all of main. For example, adding .claude/commands/x.md fails with "has no mapping to codex". Adding opt-out: - .claude/commands to the Codex workspace doesn't help, because mapping runs before opt-outs are applied. Every PR to main is blocked until someone edits the adapters.
   Fix: apply opt-outs before mapping, or skip paths a harness has no mapping for (with a notice).

Medium

4. ci/sync.sh:155-159: plugins enabled on a ws branch are dropped until its proposal merges. After the upgrade, a branch with argos.testing got settings with only delphi@delphi, and .delphi/plugins.sh then uninstalls the plugin locally. The e2e test expects this, but it contradicts what CLAUDE.md says plugins.sh does. Fix: keep the branch's plugins, or document the change in CLAUDE.md, docs/design.md and the PR body.
5. ci/harnesses.sh:13-44 (from reading the code): the Codex translation matches exact sentences from specific skills. These include the switch-workspace "No restart needed…" and /ws-delphi lines and the "GitHub MCP server's pull_request_read" phrase. Rewording a skill silently disables its translation. The awk also replaces every CLAUDE.md in SKILL.md bodies, including references to a code repo's own CLAUDE.md. Skill scripts are never translated. Fix: let a skill's source carry its own harness-specific variants, for example per-harness sections or a small override file, instead of matching sentences centrally.
6. (suspected) Nothing sets $DELPHI_ROOT automatically for Codex. It depends on the model following the AGENTS.md rule to wrap commands in .delphi/exec.sh. Meanwhile the translated SKILL.md bodies still say bash scripts/<x>.sh, so skill scripts under set -u fail whenever the model doesn't wrap the call. Fix: rewrite the skill invocations to go through exec.sh, or have the scripts fall back to a known root without searching for it.
7. ci/managed.sh:22-25 (from reading the code): safe_path allows only [A-Za-z0-9._/-]. Any inherited file name with a space, + or @ now fails render, and so check, for every workspace. The current code accepts these. Fix: quote paths and allow these characters, or document the restriction.

Low / quality

8. default-codex/docs/CONTEXT.md is byte-identical to argos-dev's. AGENTS.md mostly repeats argos-dev's CLAUDE.md, and the Codex template's first paragraph repeats templates/workspace/CLAUDE.md. This conflicts with the PR's "author once" goal; consider moving the shared text into workspace-inherit/ or project defaults.
9. harness() sets the globals instruction, skills, plugins and foreign. source_path calls it twice, so callers depend on call order. Fix: return values, or set them with a prefix that names the harness.
10. Size: sync.sh grows from 215 to 424 lines, with history-walking trust reconstruction (previous_main, staged_recipe, legacy_workspace) and a full git archive + cp -R per workspace. Refresh takes about 27 s for 6 workspaces. The check.sh header no longer describes its rules.

Extensibility (adding OpenCode or another harness)

ci/harnesses.sh isn't the only place to extend. A new harness currently touches:

• ci/harnesses.sh: a new case, its folder added to every other harness's foreign list, and its own text translation.
• ci/sources.sh: the (claude-code|codex) regex and the native-path case in source_path.
• ci/render.sh: the protected-path case and the plugins = claude branch.
• ci/check.sh: the protected list and the find paths for skills.
• tools/new-workspace.sh usage, and templates/harnesses/<h>/. Claude's template lives in templates/workspace/, which is inconsistent.
• Settings, plugins, MCP config and a way to set $DELPHI_ROOT: none exist for any harness but Claude. Supporting them means a new generator, changes to the plugins.sh-specific code in sync.sh and to .delphi/plugins.sh, and possibly a migration.

Suggestion: move these per-harness facts (native paths, protected files, folders to treat as foreign, a settings generator, a bootstrap command) into one registry entry per harness, for example ci/harnesses/<name>.sh. The other scripts would then only loop over the registry.

---

Generated by Claude Code

[bracyw]

Re-review at 3126309, and a correction to my earlier suggestion

tests/e2e.sh (185 checks), ci/check.sh . and shellcheck pass. The branch merges cleanly with main. 2.1.0 84b00128fc22 matches version.sh, and .delphi/versions only gains that one line.

Correction: drop the per-skill BODY.<harness>.md overrides

My earlier finding 5 suggested per-harness override files. That was the wrong direction: skills should be written once, in native Claude Code format, and each harness should translate them with its own function. The 5 BODY.codex.md files are copies that nothing keeps in step with their SKILL.md, and every new harness would need its own set. OpenCode, for example, would silently get the Claude wording until someone copied all 5.

Proposed instead: one translation function per harness descriptor (ci/harnesses/<h>.sh) that rewrites Claude identifiers, not whole sentences:

• claude-code.sh lists what is Claude-specific: CLAUDE.md, /<skill> references, mcp__* and MCP tool names, /ws-delphi, .claude/.
• Each descriptor maps those identifiers. The instruction file becomes its own (AGENTS.md). Skill references follow its own call syntax, such as skill_ref='$%s' for Codex. Codex calls skills with $commit (or the /skills picker) and reserves / for session commands, while OpenCode v2 lists skills as /<id>. So rewrite /commit instead of turning it into "the commit skill", which loses the direct call. A Claude-only feature, like the /ws-delphi pane line, is dropped or replaced at the level of one bullet or sentence.
• A leak check in check.sh: after translating, any Claude identifier left in a non-Claude skill fails CI and names the harness that is missing a mapping. Nothing goes stale silently, and fixes go in the translator, never in a skill.

Earlier findings

#	Status
Merge conflict; 1 empty pushes; 2 folder rename; 4 branch plugins dropped; 9 global variables	Fixed (1, 2 and 4 re-run in the sandbox)
5 sentence-matching awk	Replaced by the overrides; see the correction above
8 copied content	Fixed
3 Claude-only file in a shared bundle	Partly fixed: check.sh passes once the Codex workspace opts out, but sync now gets stuck (new #1)
6 $DELPHI_ROOT for Codex	Partly fixed: each skill gets a setup block and exec.sh routing, but it still relies on the model filling in paths; there's no hook
7 safe_path	Partly fixed: @ and + are allowed, spaces are still rejected
10 size	Worse: sync.sh is 215 lines on main and 498 here; the PR is +2196/-357

New findings

1. High (reproduced): a shared Claude-only file plus its opt-out deadlocks Codex refresh. refresh() calls with_generated "$from", which renders with the branch's workspace.yml before main is merged in. Scenario: one main PR adds .claude/commands/x.md to a shared workspace-inherit/ and adds opt-out: - .claude/commands to default-codex. This is the only order check.sh accepts, because an opt-out added earlier fails as "nothing it inherits". Every refresh of ws/s.app.argos.default-codex then fails with "has no mapping to codex", because the opt-out never reaches the branch. The e2e covers this only through render.sh, not through sync. Fix: use the opt-outs from both main's and the branch's workspace.yml in that render, or skip files a harness can't map, with a notice. The translation function above would also remove most of these failures.
2. Low (reproduced): reconstruct_records has dead code. It looks for then entry=\$main_native/\$path; fi in historical ci/sync.sh, but that line only ever existed in 646a452, never on main. Delete it.
3. Low (reproduced): aligned_refs adds 3 artificial "align" commits on a folder move. One of them carries a whole main-shaped tree, and they reach ws/* history and, through proposals, main's.
4. Low (from reading the code): a refresh still writes several commits per real change ("prepare owned files", the merge, "sync generated"). This now happens only when something actually changed.

Extensibility

I added OpenCode in the sandbox with one descriptor and one template, and needed no edits to sync, check or new-workspace. That works. What's still left:

• the skill overrides, which the correction above addresses;
• a new skill metadata format still means editing the awk in ci/harnesses.sh;
• plugins, settings, MCP config and a SessionStart hook still exist only for Claude (ci/plugins.sh and .delphi/plugins.sh are Claude-only).

---

Generated by Claude Code

[bracyw]

Third review at b2c53a5

tests/e2e.sh (192 checks), ci/check.sh . and shellcheck all pass. The branch merges cleanly with origin/main. .delphi/ hasn't changed since 3126309, so 2.1.0 still holds.

Status of the items from the last comment

Item	Status
BODY.<harness>.md replaced by a translation function per harness, skill_ref and a leak check	Fixed, with gaps (see 1–2 below). The overrides are deleted. codex.sh sets skill_ref='$%s', the Claude identifiers live in claude-code.sh, and check.sh fails when one it knows about survives translation
Refresh deadlock (shared Claude-only file plus opt-out in the same main PR)	Fixed, reproduced through sync: refresh now merges main before rendering
Dead reconstruct_records grep	Fixed
aligned_refs "align" commits	Fixed, reproduced: refresh publishes one merge with parents (from, main), and propose uses (main, owner)
Several commits per refresh	Fixed: one delphi: refresh commit per real change
Earlier fixes: no pushes on unrelated main commits, folder rename with the same short-name, plugins chosen on a branch	Still fixed (re-run)
Adding OpenCode	Fixed, reproduced: one ci/harnesses/opencode.sh plus a template needed no other edits. Plugins and settings are still Claude-only
$DELPHI_ROOT for Codex	Partly fixed, unchanged: setup text plus exec.sh, still no hook
Spaces in safe_path	Not fixed
sync.sh size	Partly fixed: 485 lines (215 on main); the PR is +2464/-358

New findings

1. Medium (reproduced): the leak check only catches identifiers on a hand-written list (claude_identifiers in ci/harnesses/claude-code.sh). These all reached Codex output with exit 0:

   • ~/.claude/settings.json and $HOME/.claude/CLAUDE.md, because a .claude preceded by / is excluded from the match;
   • subagent_type=Explore, WebFetch, claude plugin install, slack_send_message, ultrathink.

   It also reports only the first hit on each line, and its line numbers count lines in the translated output (including the setup text), not in the source SKILL.md.

2. Medium (reproduced): some rewrites are wrong.

   • Every bare CLAUDE.md becomes AGENTS.md, including inside code blocks and when it means a code repo's own file ("read the code repo's CLAUDE.md", grep -n rules CLAUDE.md). Only path-qualified references like worktrees/argos/CLAUDE.md are kept.
   • The slash rewrite loop matches again at the start of the text left after each match, so /tmp/commit becomes /tmp$commit.

   Suggest skipping code blocks and inline code, and only rewriting /<skill> at a word boundary that no / or word character comes before.

3. Low (from reading the code): harness_skill_names (ci/harnesses.sh) takes every SKILL.md folder name under software/. That includes workspace-owned and plugin skills, and generic names like review and workflow. A workspace adding a generically named skill changes /word rewriting in every shared skill. Suggest limiting it to the skills that workspace actually inherits.

4. Low (reproduced): "Use the pull_request_read tool" becomes "Use the PR-reading tool tool".

5. Low (from reading the code): the mapped Claude identifiers (pull_request_read, playwright-cdp, the delphi mod bullet, /ws-delphi) are hard-coded in the claude_identifiers awk, not kept as data. Each new one means editing the awk and adding a value to every other harness file. Suggest a data table, one identifier per row with a value for each harness, that both the translator and the leak check read.

Not checked: the new requirement in apply_inheritance that every path in a branch's workspace.generated is in the trusted records. The normal flow holds, but a harness switch made on the branch alone wasn't tested.

---

Generated by Claude Code

[bracyw]

On the latest review, two qualifications:

• 1: The home-directory .claude gaps and misleading diagnostic line numbers reproduce. A finite identifier contract cannot detect every harness-specific instruction, and tool names such as slack_send_message depend on the configured integration. I’ll fix the concrete gaps without globally rejecting integration-specific tool names.
• 5: Shared declarative mapping rules are a useful cleanup, but a table containing a column for every harness would couple new harnesses to existing ones. I’ll keep target values in their descriptors and share the recognition rules between conversion and validation.

For 2, skipping all inline code would also skip valid backticked skill calls such as /commit; those still need translation while literal paths and commands remain intact. Branch-only harness switching is already covered by the passing refresh/proposal tests in both directions.

[bracyw]

Review of d28f42f

The fixes from the last round check out. tests/harnesses.sh passes, and a sample skill translated to Codex gives the expected output:

• `/commit` and `/commit fix` become $commit;
• /tmp/commit and URLs are left alone;
• code blocks, inline code, CLAUDE.md.bak and docs/CLAUDE.md stay literal;
• "pull_request_read tool" becomes "PR reader tool".

The leak check now catches ~/.claude, subagent_type=Explore, WebFetch, ultrathink and claude plugin install, and reports every hit on a line. Slash rewriting only uses the skills the workspace actually has.

One simplification: please remove the repository-reference check (repository_file() in ci/harnesses/claude-code.sh). It's English-phrase matching ("repo's", "in the repo"), which is what we wanted to avoid, and it doesn't handle every case anyway. For now, always rewrite a bare CLAUDE.md to the target's instruction file (AGENTS.md). Keep the exceptions for code blocks, inline code and qualified paths. If a skill needs to mean a code repo's own file, it can name it by path later.

---

Generated by Claude Code

[bracyw]

Addressed the simplification request in 08ea327.

Removed repository_file() and its English-phrase matching. Bare CLAUDE.md references in prose now always map to the target instruction file; inline/fenced code and qualified paths retain their existing exceptions. Updated the fixtures, docs and PR wording.

Validation: all 193 sandbox checks, focused harness tests, ShellCheck and repository validation pass. Existing prepared workspace output is byte-identical.