You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Single source of truth: this issue body owns the current specification, feature roster, decisions, gaps, and acceptance requirements. Evidence snapshots live in comments on this same issue. Update this body when decisions change; do not maintain a separate local PRD or audit as competing authority.
Status: compatibility discovery/design. Adding Codex alongside Claude Code remains the goal; implementation phases follow agreement on the remaining product choices. Last consolidated: 2026-09-08.
Recorded decisions
D01 — Coexistence: add Codex compatibility while preserving Claude Code and shared Devflow knowledge.
D02 — Authoring: retain Markdown Script and shared semantics with explicit harness targets.
D03 — MDS upgrade direction (2026-09-08): include upgrading from 0.2.0 to the latest stable release, currently 0.4.2, in this specification. Complete the breaking-change migration and preserve existing Claude behavior before relying on the new baseline. This replaces the earlier recommendation to stay on 0.2.0.
D04 — Scope: initially defer the dynamic graph Workflow runtime for Codex; separately decide standalone preference extraction.
Complete inventory: part 1/4, part 2/4, part 3/4, part 4/4. Includes all source hashes, policies, and both compiler probe baselines.
Implementation readiness — reviewed 2026-09-08
Feature roster: comprehensive. Full Codex implementation: not ready yet. The MDS upgrade is independently specified; the host contracts below still need design closure and runtime evidence. Readiness evidence and probe cases.
Enforced command/file boundaries across real tool paths; representative allowed/denied and failure fixtures; MCP assessed separately
R3 Rules
Actual instruction discovery/precedence, overrides, shared size budget, scope/shadowing and update timing
R4 Subagents
Proven role/context/model/permission selection, write effects, bounded concurrency, child lifecycle and result completeness
R5 Skill loading
Full required body/reference acquisition in workflows and roles; installed/enabled discovery is not preload; missing mandatory dependencies cannot become a pass
R6 Agent loading
Generated TOML, discovery, namespace, invocation and effective role identity verified together; task labels/file existence alone are insufficient
G03/G04/G09/G10 now explicitly cover: 64 KiB memory input versus ~2,500-token hook spill; the charter's 4,096-character skip; AGENTS.override.md precedence and 32 KiB budget; non-blocking SubagentStart continue: false; root-only charter isolation; and replacing the slash-only recursion guard. Each needs an observable load/failure result.
Validate R1–R7 in one fixture: workflow → roles → skill/reference → restored context → deny checks → coexistence/uninstall. Record the client/version and evidence, settle open product choices, then approve broad implementation. Runtime integration remains untested.
The checked-in feature roster is fully reconciled with the registry. The gaps are mostly inside feature contracts: prompt bodies, skill activation, role permissions, process control, configuration ownership, and artifact consumers. Copying or renaming the existing files would leave substantial Claude-specific behavior in the Codex installation.
Persistence follow-up (2026-09-09):P01–P13 evidence and fixtures add requirements for exclusive/replay-safe learning, identity-preserving synthesis, active-turn/citation coverage, bounded corpus reads, memory validation/divergence, conflict-safe KB/index updates, valid scoped KB commits, and run-owned artifacts. Decide native-memory control/authority and worktree state/opt-out continuity, including detached HEAD. These extend R1–R7; the roster is unchanged.
Evidence and limits
Audited Devflow 2.4.0 at 08fbdd4e37e0ec45a92279caf976822aea7a2e4c, branch feat/322-tracker-phase-0, initially clean. This is the same baseline as Codex compatibility — canonical specification and feature inventory #333. Remote main was still e726874729d9fdaf3aa6ceee4383b3ee72332fd6; the audit includes current tracker Phase 0 branch changes, not just released/main behavior.
Readiness recheck:23ea357 on 2026-09-08: all 258 asset paths retained; five assets revised. Carry forward degraded-fetch handling, normalized/dropped issue refs, feature-branch conventions commits, and ignore sentinel/user-entry preservation, plus newer test helpers. Counts remain unchanged; inventory hashes and original compiler measurements remain pinned to 08fbdd4. Details are in the readiness evidence.
Local Codex CLI: 0.153.4. This is an observation, not a minimum supported version.
Devflow's installed and pinned @mdscript/mds: 0.2.0. The sibling MDS repository describes the 0.4 language. The proposed upgrade target is 0.4.2, verified against npm and the release tag on 2026-09-08.
Enumerated all 258 files under src/assets, scanned their contents for host assumptions, inspected every command's workflow surface and every agent/skill's metadata, and read the affected instruction blocks and runtime seams. Keyword findings were interpreted manually: for example, architecture's “LSP” means Liskov substitution, not a missing language-server tool.
Inspected the registry, all public CLI registration surfaces, flags, manifests, installation paths, model configuration, hooks, workers, HUD assembly, and representative contract/packaging guards. The 96 TypeScript files under src are also enumerated in the inventory for follow-up ownership work; enumeration does not imply a line-by-line correctness review of every implementation.
Fetched official Codex documentation on the audit date. Documented capabilities can exceed installed/client behavior; no paid agent runs, browser installation, hook installation, permission changes, or end-to-end Codex port were performed.
Ran isolated MDS compilation probes and compiled all 13 existing MDS command entry points without writing their outputs into the repository. All 13 compiled with zero warnings. These are compiler checks, not workflow execution tests.
The machine-readable inventory snapshots linked above record names, source hashes, ownership, host-reference locations, dispositions and probe results. “Shared” means a proposed reuse disposition, not validated runtime parity.
Complete roster at this baseline
Surface
Count
Coverage
Registry feature groups
21
All registry entries; compliance is separately feature-owned
Public workflow entry points
14
13 MDS commands and the copied release.md
MDS partials
11
Shared contracts and dynamic-runtime instruction fragments
Authored agent roles
16
Includes report writers, code writers, validators, and maintenance
Domain/methodology skill roots
41
40 registry-owned plus compliance
Skill reference files
116
Including browser procedures and report/publication templates
Compliance framework assets
12
Fragment + reference for each of 6 frameworks
Rule files
13
12 registry-owned plus compliance
Script/hook assets
35
Includes the charter, workers, shared helpers, HUD launcher, and redactor
Public CLI management commands
16
Includes reset, shadowing, status, and interactive configuration surfaces
Claude setting/flag entries
29
Each needs a Codex disposition, including unsupported ones
HUD component IDs
15
Duration exists but is absent from the active default layout
Git role operations
18
Full list below; operation-specific failure/publication contracts matter
Security deny entries
154
129 command patterns and 25 sensitive-read patterns
Ignore-pattern entries
142
Ordered source entries, including duplicates and mixed purposes
Registry-to-filesystem reconciliation found zero missing and zero undeclared commands, agents, skills, or rules, counting compliance's explicit feature ownership. The inventory also includes 3 Claude configuration/ignore templates, build/package/CI entry points, and the 120 existing test files as validation coverage references. Counts do not add across these overlapping runtime and product views.
The 21 registry entries are core-skills, plan, implement, code-review, resolve, debug, explore, research, release, self-review, bug-analysis, ambient, dynamic, typescript, react, accessibility, ui-design, go, java, python, and rust (all prefixed devflow-). Core skills and ambient are always installed. Dynamic and the eight language/UI groups are optional. Current installation makes all registry skills available independently of plugin selection, while agents and rules follow selected ownership. Preserve that policy unless explicitly changed.
Product features and comparable Codex implementation
“Adapter” below means a concrete implementation direction backed by a host primitive. “Probe” means required behavior is not established end to end. “Deferred” is a scope disposition.
Harness-aware CLI dispatch and owned target installation. Emit skills, role TOMLs, instructions, hooks/config. Choose direct installation versus plugin packaging; plugins are not proof of standalone role/instruction installation.
Manifest ownership keyed by harness and scope; shared asset references prevent one uninstall deleting the other harness's runtime. Preserve user edits and explicit opt-outs.
MDS-generated workflow skills with the same inputs, artifacts, role contracts, retry budgets, decisions, and results. Use Codex subagents and supported interaction tools.
Ambient mode
Charter, role routing, context passing, workflow selection, plan continuation
Generate Codex-specific persistent/session instructions and prompt reminders. Explicitly request delegation. Native plan acceptance needs an approved-artifact continuation contract.
Target-specific catalogs, validation, persistence, TOML emission, and status labels. Native Codex models must not be treated as dormant because the Claude proxy is disabled.
Prompt/answer/assistant capture
Independently gated memory and learning queues, raw answer evidence, usage citations
Normalize host events with harness, root/agent/turn/tool identity. Adapt answer correlation; asynchronous question submission is not an answer.
Shared queue/reconciliation logic plus a codex exec runner. Decide process ownership, model, permissions, and cancellation. Preserve the re-entrancy guard.
Adapt the Learning role and launch directive; preserve the canonical log/ledger/rendered views. Its lifecycle differs from the detached memory worker.
Knowledge and conventions
Index discovery, full selected KB reads, relevance, write-back opt-out, scoped commits, learned naming/release process
Reuse .devflow/features, .devflow/conventions.md, and .release/RELEASE-FLOW.md. Translate file/Git operations and permissions. Knowledge loading and write-back have different gates.
Preserve shared schemas and Git operation contracts. Add run provenance and an explicit cross-harness marker policy. Consume the emerging tracker contract when it lands.
Initially deferred for Codex; retain Claude output. Preference extraction is a separate decision.
Codex's documented building blocks are skills, custom agents, instructions, hooks, and headless execution. The adapters in this table are Devflow design proposals derived from those primitives and the source contracts.
Every workflow entry point
All in-scope commands require target-specific invocation, arguments, skill references, delegation, and result collection. Codex workflow skill names such as $devflow-plan are proposed names, not existing command registrations. Preserve natural-language arguments and flags in the workflow input; do not leave $ARGUMENTS as a promised Codex runtime variable.
Preserve the individual retry counters and strategy-specific PR/CI ordering. model="haiku" and long-process instructions need adapters. Current CI exhaustion reports then continues; it is not a universal hard stop.
code-review
Worktree discovery/validation and sequential worktree processing; preflight; incremental/full diff; prior resolutions/convergence warning; 8 mandatory and up to 12 conditional focuses; file reports; synthesis; PR summary; head marker
Schedule within available concurrency instead of demanding 20 simultaneous spawns. Preserve each required focus and report. Resolve shared .last-review-head policy.
Preserve all 8 verdicts, failure/skip/degraded states, statistics schema, bounds, and sequential Git effects. Worktree skill path and role model literals require translation.
Use explicitly independent Codex investigations; route nested exploration through the orchestrator when depth/capacity is unavailable.
bug-analysis
Incremental/full and --no-static; static scanners/SARIF; decisions, knowledge and recent plan criteria; security/functional plus conditional integration/usability analysis; report/synthesis/head marker
Preserve scanner availability/timeout/exit status and scope; Diagnose needs report writes. Resolve .last-analysis-head provenance.
Scope decision. Its body requires no Workflow runtime, but imports a Workflow preamble. Codex needs a new session/question source and removal of that misleading preamble. Its current automatic consumer is deferred dynamic-plan.
The 11 partials are _compliance, _decisions, _engine, _factory, _knowledge, _plan_contract, _preamble, _publication, _roster, _ticket_template, and _wave. Include partials in the conversion and dependency inventory, including emitted fenced examples.
Every agent and its real execution contract
All 16 have Claude model metadata and skills: preload lists. Four also declare an explicit tools: field: Knowledge, Learning, Skim, and Test. Codex's documented role TOML requires name, description, and developer_instructions; role config can specify model/effort and other supported session settings. A role's settings can override spawn/default choices, so precedence must be tested rather than inferred. Custom agent configuration
Eight verdicts with issue-ID completeness and security gate; never writes/builds/tests
A genuinely read-only role; preserve decision evidence and duplicate validation
Validate
Discover/run build/typecheck/lint/tests; structured failure output; never fixes/commits
Builds may write outputs/caches despite the no-edit instruction. Define allowed side effects and real exit-status handling
Permission design cannot follow model tiers. Review, Diagnose, Research, and Synthesize write reports. Validate/Test execute tools with filesystem effects. Code/Simplify/Scrutinize/Knowledge commit. Default workspace-write protects .git, .agents, and .codex, including resolved worktree Git directories. Commit/install operations therefore need an explicit supported permission path. Protected paths
Candidate choices are scoped permission profiles for report paths, or read-only analysis agents returning results for a controlled artifact writer. Named profiles are currently beta and do not compose with legacy sandbox settings; require version-specific validation before choosing them. Permission profiles
Built-in Claude identities Explore and general-purpose are extra invocation dependencies, not two more authored agents. Translate their purposes explicitly. Also replace the charter's blanket assertions that subagents cannot delegate and see none of the conversation; context inheritance and depth are host/session contracts.
Every skill, rule, and reference dependency
All 41 skill roots contain both user-invocable: false and allowed-tools. Ten contain activation.file-patterns/exclude: accessibility, go, java, python, react, rust, test-driven-development, testing, typescript, and ui-design. Their source presence does not establish identical enforcement even across Claude versions; capture the intended selection behavior and test each target.
Do not translate user-invocable: false to allow_implicit_invocation: false. The latter disables automatic selection while leaving explicit invocation possible—the opposite control. Codex documents name/description discovery, optional invocation policy and dependency metadata, and explicit skill loading. Preserve domain skills' automatic applicability; exact hidden-from-picker behavior needs a supported mechanism or an accepted UX difference. Duplicate names can both appear; they do not merge. The initial catalog budget is 2% of the model context, with an 8,000-character fallback when the context window is unknown—not a universal 8,000-character ceiling. Skill behavior
Generic controls plus selected-framework composition
Feature ownership, metadata, five ${DEVFLOW_COMPLIANCE_*} composition tokens, installed references and activation lookup
The 13 rules are engineering, quality, security, reliability, accessibility, go, java, python, react, rust, typescript, ui-design, and compliance. Their core guidance can remain shared; selected rules become owned persistent instructions in Codex. The compliance rule additionally has composition/stamping tokens. Preserve overrides, existing instruction files, discovery order, and size budgets.
All 116 skill references and 12 framework files have individual inventory entries. Three particularly easy-to-miss reference adaptations are:
skills/qa/references/browser-testing.md: browser operations and dev-server ownership/cleanup.
The framework pairs cover GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, and SOX. Preserve active-framework-only reference installation, generic-controls mode with zero frameworks, remembered selections after disable, shadow precedence, and metadata/ownership-aware uninstall. This audit concerns feature behavior, not a legal reassessment of those frameworks.
Hooks, processes, and hidden prompt sources
Prompt generation must cover the charter and shell-injected directives as well as commands/agents/skills. session-start-context emits an Agent(... Learning ...) instruction and has its own opus/sonnet/haiku allowlist. preamble recognizes Claude's literal accepted-plan message and slash-prefix recursion guard. Neither is corrected by compiling workflow files alone.
capture-question rejects any tool_name other than AskUserQuestion and indexes answers by question text. A Codex event normalizer must correlate its actual request/result IDs and submitted answers; changing only the registered matcher produces zero captured answers. Cancellation, free text, multi-select, async delivery and errors need fixtures.
Capture/worker registration order is insufficient: Codex runs matching hooks concurrently. User/project/plugin hooks accumulate rather than replacing one another. Use one ordered dispatcher for capture-then-schedule and dedupe repeated event deliveries.
Hook tool names are not a simple textual translation table. Current docs explicitly alias unified exec_command to Bash, spawn_agent to Agent, and patch edits to Edit/Write; patch input is still a command/patch payload. Hosted tools are outside this path, and later stdin interaction does not repeat pre-tool checks.
Parent/child identity differs: subagent hooks can share the parent session_id. Include child and turn identifiers before queue dedupe or learning suppression.
Async hooks are session-bound and can be canceled at exit. Preserve detached memory recovery separately from Learning-agent lifetime. Inventory Interrupt and SessionEnd for cleanup/capture, as well as startup, prompt, tool, stop and compaction events.
The memory subprocess hardcodes claude -p, a Claude model, bypass flags, logging and watchdog assumptions. A Codex runner needs explicit auth/model/config and staged-output handling. Do not silently inherit unrelated plugins/hooks and recursively spawn maintenance.
“No subprocess”/“use the Read tool directly” instructions in knowledge loading and Skim need contextual adaptation where the client exposes file reads through shell tools. Preserve the prohibition on inventing model workers; do not forbid the only available file-read mechanism.
The factual hook constraints above come from the current hook contract. They still require fixtures on the minimum supported version. An App Server worker can pass an explicit skill input to request full skill injection; that does not prove preload behavior for interactive custom roles. App Server skills
CLI, settings, state and Git operations
All 16 management commands must address the selected harness where they affect installation/configuration:
Shadow/unshadow/list; full reference tree and generated source precedence
rules
Shadow/unshadow/list, enable/disable/status
agents
TUI/list/set model/set effort/reset/confirmation; installed/saved/unknown state
flags
TUI/list/status/enable/disable/set/unset; typed neutral/explicit/unknown states
hud
Enable/disable/status/detail setting; current detail setting has no rendered tool/agent rows
security
Status/enable/disable and user/managed scope
safe-delete
Enable/disable/status, shell install ownership
proxy
Enable/disable/status/port and remembered configuration; keep Claude-specific routing
compliance
Enable/disable/status/set frameworks, including empty set and remembered disabled state
debug
Enable/disable/status and correct log location
capture.ts and context.ts are wiring helpers, not additional public CLI commands. Interactive init also owns publication/attribution decisions; they must survive target selection even though they are not separate top-level commands.
Flag(s), covering all 29 entries
Codex disposition
default-model
Codex model config; validate against its catalog and selected account/provider
max-concurrent-subagents
Supported concurrency configuration, with bounded scheduling and capacity detection
Claude/provider-specific; no literal Codex configuration mapping
workflow-size-guideline, goal-checkin-minutes
Dynamic-runtime controls deferred; native goals would require a separately specified contract
Configuration candidates above refer to the Codex configuration reference. Do not write unsupported Claude keys into Codex TOML.
State design must cover more than manifest.json: agent-models.json, learning model/debug configuration, HUD configuration/cache/cost history, flags and provenance, proxy state, .devflow/config.json, knowledge/decisions/queues/locks, review/analysis markers, conventions, and preference profiles. The model layer currently defines external models as the complement of Claude names and makes them dormant without the proxy; that rule must live in the Claude adapter. Learning has a separate model allowlist in both TypeScript and injected shell text. Model dormancy source
The Git role's 18 operations are: ensure-pr-ready, validate-branch, setup-task, fetch-issue, fetch-issues-batch, post-review-summary, manage-debt, check-ci-status, create-release, gather-release-evidence, learn-conventions, fetch-review-threads, resolve-review-threads, post-resolution-summary, check-merge-readiness, backlink-shipped-issues, ensure-traceable-issue, and post-wave-report. Preserve bounded API work, marker dedupe, owned-path commits, body-file publication, redaction fallbacks, and the distinction between primary-action failure and optional traceability degradation. post-wave-report currently belongs to the deferred dynamic consumer.
Shared review artifacts create a specific coexistence decision: .last-review-head and .last-analysis-head contain a SHA, not harness/capability provenance. A Claude run can make Codex skip reviewing that same head. Reports can remain cross-readable while execution markers record harness, contract version, focus coverage, and commit; alternatively shared markers need an explicit equivalence policy. Do not accidentally change that behavior through path reuse.
Actual quota windows/reset data; consistent used/remaining interpretation
todoProgress
Codex plan events; completion is observed, not guessed
configCounts
Codex config/skills/hooks/MCP/instruction discovery; configured versus loaded versus used
learningCounts
Shared decisions ledger counts
versionBadge
Devflow installed/latest version check
sessionCost
Account-dependent estimate/unavailable; stable dedupe and consistent weekly/monthly basis
sessionDuration
Session start time; not currently included in Devflow's active layout
The current renderer does not display tool/agent activity rows; detail is persisted but not consumed by the rendering path. Adding activity rows is extra scope, not required parity. The retained HUD references below were source-inspected in the earlier session; they were not installed or tested end to end in this audit.
Use stock tui.status_line for a native subset, or a companion tmux/cmux process to reuse the full Devflow renderer. The inspected/publicly documented interface does not establish arbitrary custom footer output. The companion needs refresh/resize/exit/fallback behavior and exact thread binding; “newest rollout” is insufficient. App Server supplies structured thread/plan/usage events, but a new server does not automatically subscribe to another running CLI. A read-only collector should not resume a thread just to inspect it. App Server
Browser QA has a concrete candidate: Microsoft's Playwright MCP documents Codex configuration and provides navigation, snapshots, forms, JavaScript evaluation, console messages, and tab management. These correspond to the operations in Devflow's browser reference. It also documents browser-profile contention across concurrent clients; choose isolated or distinct profiles where needed. The built-in browser is documented as unavailable in CLI/IDE, so it cannot be the universal QA backend. Codex browser availability
Keep the dev-server lifecycle contract: reuse existing servers, own only servers started by the run, bound readiness waits, preserve logs and exit status, and clean up owned tabs/processes. Validate login/session requirements independently of tool availability. Browser/scanner outages must be represented in acceptance coverage, not reported as successful testing.
For sensitive files, Codex's permission profiles provide a candidate for path/glob read denial. This is a more concrete route than treating AGENTS.md or an invented .codexignore as enforcement. Profiles are beta, platform-sensitive and distinct from legacy sandbox settings. MCP servers and hosted tools require their own boundary assessment. Translate dangerous-command patterns through real exec policies/permissions; hook aliases and shell wrappers make literal pattern copying insufficient. Rules, Permission profiles
The security template's individual deny entries and every non-comment ignore pattern are preserved in the machine-readable inventory. The command-policy categories include destructive deletion/disk operations, shell/interpreter wrappers, downloaded-code execution, privilege/accounts/permissions, process/service termination, network listeners/scanning, kernel/firewall/container escape operations, scheduled persistence, log/history erasure, credential metadata access, remote transfer, mining, system package installation, mounts and protected-system writes. Sensitive reads cover environment/secrets, cloud/SSH credentials, private keys and system account files.
Do not turn every ignore entry into an enforced read denial. The current .claudeignore mixes secrets with context-noise exclusions, including SQL files, lockfiles, .git, and .gitignore. Devflow's database/dependency reviews, Git workflows, and ignore maintenance need some of those files. Classify confidentiality requirements separately from discovery preferences. Safe-delete also needs per-shell startup validation: existing support spans zsh, bash, fish and PowerShell with platform-specific trash behavior.
Prior HUD projects and pinned Codex footer sources are preserved in the linked discovery archive and readiness-review evidence; no dependency selection is implied.
MDS solution: shared semantics, harness targets
Use harness targets (claude-code, codex) as the term. MDS does not require a new “worlds” language feature. Keep tracker provider (github, later jira/linear), client capabilities, install scope, and harness as distinct inputs; an issue tracker is not a harness.
The historical 0.2.0 probes are preserved in the inventory and readiness-review evidence. The active target and verified 0.4.2 requirements follow below.
Proposed authoring and generation contract
Keep domain behavior shared. Author workflow/role semantics once. Retain unchanged domain references as ordinary Markdown. Convert target-sensitive bodies to .mds explicitly; do not reinterpret every brace in every existing Markdown example.
Use semantic MDS helpers. Define helpers for skill loading, delegation, result collection, human questions, long commands, project instructions, capability lookup, and report attribution. Pass the harness/target descriptor explicitly through imported functions so dependencies are visible. Keep complex behavior in target-selected blocks rather than a word-replacement dictionary.
Validate target inputs in TypeScript. Reject unknown harness IDs/capability combinations. Separate build-time target values from execution-time task placeholders. Do not compile a user's actual task into distributed assets.
Generate metadata separately. Parse shared role/skill metadata into a typed representation. Emit Claude Markdown frontmatter or Codex TOML / skill YAML / optional agents/openai.yaml with proper serializers. Render role bodies into developer_instructions. Preserve required skill lists as verified load contracts, not unsupported TOML keys.
Select fenced instruction examples as whole blocks. MDS conditionals belong outside fences. Where dynamic values are required, emit the instruction from a helper in ordinary text/inline code. Do not expect interpolation inside a fenced Agent(...) example. Preserve literal runtime placeholders deliberately.
Cover all prompt sources. Include release.md, agent bodies, affected skill bodies/references, charter, memory-runner prompt, and Learning/plan-handoff strings currently embedded in shell. Avoid parallel independently maintained copies.
Separate build output from install choices. Build both target artifacts; resolve scope, user shadows, selected compliance frameworks, available tools, and user model/effort choices through the target installer. Shared raw shadows must be validated for the requested target; incompatible overrides need a clear result, never a silent Claude copy.
Preserve compliance's composition stage. Its ${DEVFLOW_COMPLIANCE_*} tokens are not MDS target variables. Define and test the stage order: select/validate source or override, render target-sensitive body while preserving composition tokens, compose selected framework content, emit/stamp target metadata, install. Under 0.4.2, single-brace tokens remain literal; verify that framework composition consumes only its own tokens after MDS rendering.
Make every emitted asset owned and reachable. Target output manifests track source/dependency hashes, destination kind, logical ID, owner, and required capabilities. An install missing a required generated role/reference fails clearly. Legacy/default output paths can remain compatible while the new resolver is introduced.
Preserve Claude behavior during the extraction. Record existing outputs and use byte comparisons for mechanical changes; record intentional semantic changes separately. Validate names, references, metadata schemas, literal placeholders, and forbidden live host instructions in all generated bodies and examples.
Illustrative helper using the verified target 0.4.2 syntax:
@define load_skill(harness, name):
@if harness == "codex":
Read the discovered Codex skill {{name}} and its required references.
@else:
Invoke Skill(skill="devflow:{{name}}").
@end
@end
@export load_skill
The caller imports the helper and emits {{load_skill(harness, "testing")}}. The build invokes:
constresult=awaitcompileFile(sourcePath,{vars: {harness: target.harness}});if(result.kind!=="markdown")thrownewError("Expected a Markdown asset");constbody=result.output;
This illustrates one proven composition seam, not a complete production skill resolver. The actual helper should use the generated target namespace and discovered installed path/capability. A workflow should still receive runtime arguments, results, worktree, and selected skills explicitly.
Suggested output families are target-owned workflow skills/commands, role artifacts, skill trees, instruction fragments, and hook prompts. The existing build only permits dist/commands and the installer copies agents/skills from src/assets; extending onlycompileFile would therefore have no effect on those installations. Update asset resolution, packaging, model rewriting, shadowing, compliance convergence, and uninstall together with the generator.
Coordination with existing tracker work
#323 already proposes src/core/mds-variants.ts, generated Git agents, source resolution, and a byte-identical plumbing phase. It explicitly pins MDS 0.2.0 and excludes speculative variant lists in that phase.
#324 adds operation/provider generation and recursive reference installation with containment/atomic-overlay requirements.
#325 introduces tracker selection and Jira/Linear. All three were open on the audit date.
Agree one generator/asset ownership contract across this work. Do not introduce a competing compiler or inject Codex variants into Tracker Phase 1 — MDS plumbing, provably byte-identical #323's zero-behavior-change phase without an explicit scope revision.
The MDS 0.4.2 upgrade is now the chosen planning direction. Reconcile Tracker Phase 1 — MDS plumbing, provably byte-identical #323’s explicit 0.2.0 pin with this decision before implementation; retain its byte-equivalence objective. Keep the upgrade mechanically reviewable apart from later Codex behavior changes.
Target: exact @mdscript/mds0.4.2, npm latest verified 2026-09-08; published 2026-09-03. Keep it a development dependency, update the lockfile and native/WASM dependency resolution, and record any later target change here. The Devflow package currently remains on 0.2.0; this section specifies the migration. Published release, versioned changelog.
Fresh probe of the actual published package
Installed 0.4.2 in an isolated temporary directory and ran it against the current 13 command hosts. All 13 compiled with zero warnings, yet all 13 outputs changed. The six checked helper families alone left 33 literal call sites instead of injected instructions. For example, self-review shrank from 10,637 to 5,205 output bytes, and dynamic-build from 64,616 to 28,409. These are broken unconverted outputs, not optimizations.
The new double-brace imported-helper fixture compiled correctly for both claude-code and codex. Separate probes confirmed legacy escaped braces remain in output, source YAML remains unchanged by runtime vars, and messages results have no output field. Both compiler versions used their native backend; WASM and platform coverage remain upgrade checks. Full per-command results are saved in the evidence inventory.
Breaking changes and Devflow applicability
Change
What this requires here
Interpolation uses {{name}} / {{helper()}}; old single braces become literal
Migrate the 13 command hosts and 11 partials, including imported function calls and interpolated parameters. A dependency-only bump silently loses instructions.
Old \{ / \} escapes are no longer consumed; literal double-opening braces use \{{
Remove obsolete escapes from execution-time placeholders where the old compiler consumed them. Preserve literal examples, shell/JS expressions, JSON and framework tokens. Never double every brace indiscriminately.
Compile results are a Markdown/messages discriminated union
Narrow result.kind === "markdown" before reading result.output in build-mds.ts and future generators. Reject unexpected messages output for Markdown/TOML-body assets.
@message selects messages output; mixed loose content is invalid; old compileMessages/format APIs were removed
No current live @message/removed-API call sites were found. Explicitly keep workflow/role assets in Markdown mode; do not introduce chat-message output accidentally.
Fence recognition and whitespace semantics changed
Check tilde/indented/blockquote fences, multiline prompts, tables and blank-line boundaries. Preserve output bytes where feasible; document any necessary reviewed differences.
Comparisons are type-strict; inherited frontmatter deep-merges
Validate target variables and future capability conditions. If using inheritance, serialize only intended target metadata; do not leak base-template build keys.
File options/check API and diagnostics are stricter
Keep compileFile file-relative; no basePath/unknown options. Account for synchronous validation errors and changed diagnostic types if consumed. Current direct compileFile(host.file) needs no option migration.
CLI discovery/watch output and lint/fix contracts changed
Devflow currently uses its own walker, so it need not adopt MDS CLI layout. If using the migration CLI, enumerate intended sources explicitly, inspect fixes and residual diagnostics, and do not assume hidden/underscore files were all migrated.
Rust/Python-only API changes, removed messages APIs, and bundler/watch changes have no identified current Devflow consumer. They do not justify unrelated code changes. The 0.4.1/0.4.2 release notes mainly concern Python packaging; the relevant language/API breaks span 0.3 and 0.4. 0.4.2 package API, language specification.
Upgrade acceptance
Capture the old compiler’s 13 generated command outputs plus copied release.md, hashes and required semantic sections before editing. Include dynamic commands: their Codex deferral does not remove their Claude regression obligations.
Apply the compiler’s migration assistance to isolated/controlled sources, review transformations, update syntax-sensitive fixtures/guards, and compare generated artifacts. Compilation success is insufficient; ensure helper expansion, compliance/knowledge/decision instructions, placeholders and report/publication contracts remain intact.
Keep the existing golden/containment/escape checks meaningful. Add targeted guards for lost helper expansion and wrong output kind; never refresh goldens solely to hide missing instructions.
Run build, targeted MDS/contract checks, required full/integration checks and package-install validation; cover native and WASM backends. Record known suite contention separately from upgrade regressions.
Reconcile Tracker Phase 1 — MDS plumbing, provably byte-identical #323’s old exact 0.2.0 requirement with D03 while retaining its byte-equivalence intent. Record any sequencing change here and link the eventual upgrade work; do not start a separate competing specification.
Gaps requiring resolution before implementation
ID
Gap beyond the original broad inventory
Required disposition
G01
Body conversion is not wired for plain agents/skills/references, copied release command, or injected hook prompts
Extend generation and asset resolution across all affected content kinds
G02
Installed MDS versus sibling-spec syntax; raw frontmatter and fenced-block passthrough
Choose language baseline and typed metadata/stage contract
G03
All 41 skill visibility/tool declarations and 10 activation maps have different Codex semantics
Capture requires answer-schema adaptation, child identity, ordered dispatch, and duplicate control
Versioned normalized events and crash/interrupt/async fixtures
G10
Hooks, workers, config and instruction layers have distinct trust/permission/lifecycle behavior
Observable installation health and documented worker ownership
G11
Cross-harness review/analysis markers can suppress a requested run
Decide marker provenance/equivalence while preserving report interoperability
G12
Browser procedures, publication footers, file-read restrictions and external tool assumptions live in references
Include reference trees and injected templates in conversion/validation
G13
Existing workflows allow several degraded/skip/continue paths
Define acceptance coverage and failure policy explicitly; do not invent a universal hard gate
G14
Current tracker/MDS work changes the same generation/install seams
Reconcile the shared generator design and landing baseline
Known source defects must also remain visible while porting: #328 publication containment-rule placement; #329 debt-table backfill mismatch; #330 unescaped table content; #331 unconsumed planning inputs. These were already filed, not new Codex regressions. #332 tracks suite subprocess contention. The core-to-Claude import described by #274 is still present in learning-tuning-config.ts.
Decisions for the product owner
Initial clients/platforms. Recommended discovery baseline: CLI on macOS/Linux, with desktop/IDE evaluated separately and cloud explicitly deferred. Client scope remains open; this is a recommendation, not an approved support promise.
Packaging and names. Recommend retaining devflow init as the full lifecycle owner and generating explicit namespaced Codex workflow skills. Decide whether the first distribution also uses native plugin packages. All 41 domain skills becoming visible is an explicit UX question; do not invert implicit activation to hide them.
HUD experience. Choose native subset, full companion, or selectable modes. Recommend selectable native/full modes if accepting tmux/cmux setup; exact stock-footer patching remains a separate choice.
Quality coverage. Decide which missing skills, browser/scanners, review focuses, or exhausted retries block completion versus produce accepted partial/degraded results. Recommend mandatory acceptance coverage never reports PASS when unexecuted; keep optional maintenance non-blocking.
Role execution boundaries. Choose report-writing agents with scoped effects or read-only agents plus controlled artifact writes. Preserve user permission policy and deliberate Git authority; do not default every role or worker to unrestricted execution.
Shared versus target state. Recommend shared knowledge/decisions/conventions and interoperable reports, with harness/run provenance on queues, telemetry and incremental markers, and per-harness model/install settings. Decide whether an equivalent review from either harness satisfies incremental coverage.
Preference extraction. Keep the three graph workflows deferred. Decide whether standalone dynamic-profile earns initial scope given its cross-project data surface and deferred automatic consumer.
Minimum Codex version, exact browser package/version, and headless runner details should be selected from capability probes. They are engineering decisions to resolve against these product choices, rather than assumptions to bake into the inventory.
Verification contract for the eventual implementation
Machine-check registry coverage and all emitted asset/dependency ownership; fail on missing roles/references and unaccounted newly added assets.
Compile both targets; parse emitted YAML/TOML/JSON; validate names, paths, namespace references, composition tokens, literal placeholders and host-specific instructions even inside fences. Preserve unchanged shared references byte-for-byte.
Exercise representative workflow fixtures: approved-plan continuation; multi-issue context; all mandatory review focuses under limited capacity; report-writer permissions; long silent build success/failure/cancellation; real submitted/canceled questions; partial QA; redaction failure; truthful CI/verification outcomes.
Exercise install/coexist/upgrade/shadow/unshadow/uninstall/reset under local/global scopes, custom homes, conflicting skill names, protected configuration, hook trust changes and duplicate hook sources.
Exercise shared-state contention: same repo/worktree from both harnesses, same SHA reviews, resumed/compacted threads, root/child hooks, duplicate events, stale workers, concurrent human edits, disabled features mid-run, and interrupted/ended sessions.
Run existing Claude behavior/contract checks, targeted Codex fixtures, and tarball installation checks. The audit's successful compilation does not substitute for these runtime tests.
The roster is complete for the recorded source baseline. Planning readiness depends on resolving or explicitly accepting G01–G14 and the product decisions above, then recording the agreed requirements and delivery links in this issue.
Codex compatibility specification
Single source of truth: this issue body owns the current specification, feature roster, decisions, gaps, and acceptance requirements. Evidence snapshots live in comments on this same issue. Update this body when decisions change; do not maintain a separate local PRD or audit as competing authority.
Status: compatibility discovery/design. Adding Codex alongside Claude Code remains the goal; implementation phases follow agreement on the remaining product choices. Last consolidated: 2026-09-08.
Recorded decisions
Evidence on this issue
Implementation readiness — reviewed 2026-09-08
Feature roster: comprehensive. Full Codex implementation: not ready yet. The MDS upgrade is independently specified; the host contracts below still need design closure and runtime evidence. Readiness evidence and probe cases.
G03/G04/G09/G10 now explicitly cover: 64 KiB memory input versus ~2,500-token hook spill; the charter's 4,096-character skip;
AGENTS.override.mdprecedence and 32 KiB budget; non-blockingSubagentStart continue: false; root-only charter isolation; and replacing the slash-only recursion guard. Each needs an observable load/failure result.Validate R1–R7 in one fixture: workflow → roles → skill/reference → restored context → deny checks → coexistence/uninstall. Record the client/version and evidence, settle open product choices, then approve broad implementation. Runtime integration remains untested.
The checked-in feature roster is fully reconciled with the registry. The gaps are mostly inside feature contracts: prompt bodies, skill activation, role permissions, process control, configuration ownership, and artifact consumers. Copying or renaming the existing files would leave substantial Claude-specific behavior in the Codex installation.
Persistence follow-up (2026-09-09): P01–P13 evidence and fixtures add requirements for exclusive/replay-safe learning, identity-preserving synthesis, active-turn/citation coverage, bounded corpus reads, memory validation/divergence, conflict-safe KB/index updates, valid scoped KB commits, and run-owned artifacts. Decide native-memory control/authority and worktree state/opt-out continuity, including detached HEAD. These extend R1–R7; the roster is unchanged.
Evidence and limits
08fbdd4e37e0ec45a92279caf976822aea7a2e4c, branchfeat/322-tracker-phase-0, initially clean. This is the same baseline as Codex compatibility — canonical specification and feature inventory #333. Remotemainwas stille726874729d9fdaf3aa6ceee4383b3ee72332fd6; the audit includes current tracker Phase 0 branch changes, not just released/main behavior.23ea357on 2026-09-08: all 258 asset paths retained; five assets revised. Carry forward degraded-fetch handling, normalized/dropped issue refs, feature-branch conventions commits, and ignore sentinel/user-entry preservation, plus newer test helpers. Counts remain unchanged; inventory hashes and original compiler measurements remain pinned to08fbdd4. Details are in the readiness evidence.0.153.4. This is an observation, not a minimum supported version.@mdscript/mds:0.2.0. The sibling MDS repository describes the 0.4 language. The proposed upgrade target is 0.4.2, verified against npm and the release tag on 2026-09-08.src/assets, scanned their contents for host assumptions, inspected every command's workflow surface and every agent/skill's metadata, and read the affected instruction blocks and runtime seams. Keyword findings were interpreted manually: for example, architecture's “LSP” means Liskov substitution, not a missing language-server tool.srcare also enumerated in the inventory for follow-up ownership work; enumeration does not imply a line-by-line correctness review of every implementation.Complete roster at this baseline
release.mdRegistry-to-filesystem reconciliation found zero missing and zero undeclared commands, agents, skills, or rules, counting compliance's explicit feature ownership. The inventory also includes 3 Claude configuration/ignore templates, build/package/CI entry points, and the 120 existing test files as validation coverage references. Counts do not add across these overlapping runtime and product views.
The 21 registry entries are
core-skills,plan,implement,code-review,resolve,debug,explore,research,release,self-review,bug-analysis,ambient,dynamic,typescript,react,accessibility,ui-design,go,java,python, andrust(all prefixeddevflow-). Core skills and ambient are always installed. Dynamic and the eight language/UI groups are optional. Current installation makes all registry skills available independently of plugin selection, while agents and rules follow selected ownership. Preserve that policy unless explicitly changed.Product features and comparable Codex implementation
“Adapter” below means a concrete implementation direction backed by a host primitive. “Probe” means required behavior is not established end to end. “Deferred” is a scope disposition.
AGENTS.mdsections. Keep explicit reference-loading contracts. Probe activation and duplicate-name behavior.codex execrunner. Decide process ownership, model, permissions, and cancellation. Preserve the re-entrancy guard..devflow/features,.devflow/conventions.md, and.release/RELEASE-FLOW.md. Translate file/Git operations and permissions. Knowledge loading and write-back have different gates.Codex's documented building blocks are skills, custom agents, instructions, hooks, and headless execution. The adapters in this table are Devflow design proposals derived from those primitives and the source contracts.
Every workflow entry point
All in-scope commands require target-specific invocation, arguments, skill references, delegation, and result collection. Codex workflow skill names such as
$devflow-planare proposed names, not existing command registrations. Preserve natural-language arguments and flags in the workflow input; do not leave$ARGUMENTSas a promised Codex runtime variable.planimplementmodel="haiku"and long-process instructions need adapters. Current CI exhaustion reports then continues; it is not a universal hard stop.code-review.last-review-headpolicy.resolvedebugbug-analysis--no-static; static scanners/SARIF; decisions, knowledge and recent plan criteria; security/functional plus conditional integration/usability analysis; report/synthesis/head marker.last-analysis-headprovenance.self-reviewexploreExploreseparately from the authored Skim role; preserve opt-in KB creation.researchrelease.mdin generation. Preserve user release authority and operation-specific primary-effect failures.dynamic-ticketsdynamic-planDECISIONS-NEEDED.md, human gatedynamic-build_engine,_factory,_wave, and roster dependencies associated with this disposition.dynamic-profiledynamic-plan.The 11 partials are
_compliance,_decisions,_engine,_factory,_knowledge,_plan_contract,_preamble,_publication,_roster,_ticket_template, and_wave. Include partials in the conversion and dependency inventory, including emitted fenced examples.Every agent and its real execution contract
All 16 have Claude
modelmetadata andskills:preload lists. Four also declare an explicittools:field: Knowledge, Learning, Skim, and Test. Codex's documented role TOML requiresname,description, anddeveloper_instructions; role config can specify model/effort and other supported session settings. A role's settings can override spawn/default choices, so precedence must be tested rather than inferred. Custom agent configurationCLAUDE.mdauthority lookup; keep project-specific conventions rather than promoting example TS/React preferences universallyrskim/Skim orientation; exact content when needed; compact handoffPermission design cannot follow model tiers. Review, Diagnose, Research, and Synthesize write reports. Validate/Test execute tools with filesystem effects. Code/Simplify/Scrutinize/Knowledge commit. Default workspace-write protects
.git,.agents, and.codex, including resolved worktree Git directories. Commit/install operations therefore need an explicit supported permission path. Protected pathsCandidate choices are scoped permission profiles for report paths, or read-only analysis agents returning results for a controlled artifact writer. Named profiles are currently beta and do not compose with legacy sandbox settings; require version-specific validation before choosing them. Permission profiles
Built-in Claude identities
Exploreandgeneral-purposeare extra invocation dependencies, not two more authored agents. Translate their purposes explicitly. Also replace the charter's blanket assertions that subagents cannot delegate and see none of the conversation; context inheritance and depth are host/session contracts.Every skill, rule, and reference dependency
All 41 skill roots contain both
user-invocable: falseandallowed-tools. Ten containactivation.file-patterns/exclude: accessibility, go, java, python, react, rust, test-driven-development, testing, typescript, and ui-design. Their source presence does not establish identical enforcement even across Claude versions; capture the intended selection behavior and test each target.Do not translate
user-invocable: falsetoallow_implicit_invocation: false. The latter disables automatic selection while leaving explicit invocation possible—the opposite control. Codex documents name/description discovery, optional invocation policy and dependency metadata, and explicit skill loading. Preserve domain skills' automatic applicability; exact hidden-from-picker behavior needs a supported mechanism or an accepted UX difference. Duplicate names can both appear; they do not merge. The initial catalog budget is 2% of the model context, with an 8,000-character fallback when the context window is unknown—not a universal 8,000-character ceiling. Skill behaviorAgent(subagent_type="Explore")call; route the investigation appropriatelyreferences/browser-testing.mdhardcodes nine Claude-in-Chrome tools and shell/server lifecycle${DEVFLOW_COMPLIANCE_*}composition tokens, installed references and activation lookupThe 13 rules are engineering, quality, security, reliability, accessibility, go, java, python, react, rust, typescript, ui-design, and compliance. Their core guidance can remain shared; selected rules become owned persistent instructions in Codex. The compliance rule additionally has composition/stamping tokens. Preserve overrides, existing instruction files, discovery order, and size budgets.
All 116 skill references and 12 framework files have individual inventory entries. Three particularly easy-to-miss reference adaptations are:
skills/qa/references/browser-testing.md: browser operations and dev-server ownership/cleanup.skills/git/references/github-api.md: Claude-specific publication attribution.skills/review-methodology/references/report-template.md: Claude-specific report footer.The framework pairs cover GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, and SOX. Preserve active-framework-only reference installation, generic-controls mode with zero frameworks, remembered selections after disable, shadow precedence, and metadata/ownership-aware uninstall. This audit concerns feature behavior, not a legal reassessment of those frameworks.
Hooks, processes, and hidden prompt sources
Prompt generation must cover the charter and shell-injected directives as well as commands/agents/skills.
session-start-contextemits anAgent(... Learning ...)instruction and has its own opus/sonnet/haiku allowlist.preamblerecognizes Claude's literal accepted-plan message and slash-prefix recursion guard. Neither is corrected by compiling workflow files alone.capture-prompt,capture-question,capture-turnsession-start-context,session-start-memory,session-start-orchestrator,preamble,assets/orchestrator-charter.mdmemory-worker,background-memory-update,pre-compact-memoryensure-proxyrun-hook,hook-bootstrap,hook-log-init,debug-trace,log-paths,hud.shensure-devflow-init,ensure-root-gitignore,resolve-project-root,get-mtime,git-marker,is-hex-shaqueue-append,learning-lock,json-parse,json-helper.cjs,decisions-usage-scan.cjslib/decisions-format.cjs,lib/mkdir-lock.cjs,lib/project-paths.cjs,lib/render-decisions.cjs,lib/safe-path.cjs,redact-secrets.cjsConcrete gaps:
capture-questionrejects anytool_nameother thanAskUserQuestionand indexes answers by question text. A Codex event normalizer must correlate its actual request/result IDs and submitted answers; changing only the registered matcher produces zero captured answers. Cancellation, free text, multi-select, async delivery and errors need fixtures.exec_commandtoBash,spawn_agenttoAgent, and patch edits toEdit/Write; patch input is still a command/patch payload. Hosted tools are outside this path, and later stdin interaction does not repeat pre-tool checks.session_id. Include child and turn identifiers before queue dedupe or learning suppression.InterruptandSessionEndfor cleanup/capture, as well as startup, prompt, tool, stop and compaction events.claude -p, a Claude model, bypass flags, logging and watchdog assumptions. A Codex runner needs explicit auth/model/config and staged-output handling. Do not silently inherit unrelated plugins/hooks and recursively spawn maintenance.The factual hook constraints above come from the current hook contract. They still require fixtures on the minimum supported version. An App Server worker can pass an explicit skill input to request full skill injection; that does not prove preload behavior for interactive custom roles. App Server skills
CLI, settings, state and Git operations
All 16 management commands must address the selected harness where they affect installation/configuration:
inituninstallambientmemorylearningknowledgeskillsrulesagentsflagshudsecuritysafe-deleteproxycompliancedebugcapture.tsandcontext.tsare wiring helpers, not additional public CLI commands. Interactive init also owns publication/attribution decisions; they must survive target selection even though they are not separate top-level commands.default-modelmax-concurrent-subagentsforked-subagents,subagent-spawn-depth,agent-teamsalways-thinking,disable-adaptive-thinkingbrief,thinking-summariesshow-turn-durationsubprocess-env-scrubdisable-nonessential-trafficsuppress-attributionclear-context-on-planenable-todo-toolstool-search,lspdisable-bundled-skills,disable-git-instructionsdisable-compact,disable-autoupdatertui,view-mode,spellcheckprompt-caching-1h,pin-sonnet-4-6,disable-1m-contextworkflow-size-guideline,goal-checkin-minutesConfiguration candidates above refer to the Codex configuration reference. Do not write unsupported Claude keys into Codex TOML.
State design must cover more than
manifest.json:agent-models.json, learning model/debug configuration, HUD configuration/cache/cost history, flags and provenance, proxy state,.devflow/config.json, knowledge/decisions/queues/locks, review/analysis markers, conventions, and preference profiles. The model layer currently defines external models as the complement of Claude names and makes them dormant without the proxy; that rule must live in the Claude adapter. Learning has a separate model allowlist in both TypeScript and injected shell text. Model dormancy sourceThe Git role's 18 operations are:
ensure-pr-ready,validate-branch,setup-task,fetch-issue,fetch-issues-batch,post-review-summary,manage-debt,check-ci-status,create-release,gather-release-evidence,learn-conventions,fetch-review-threads,resolve-review-threads,post-resolution-summary,check-merge-readiness,backlink-shipped-issues,ensure-traceable-issue, andpost-wave-report. Preserve bounded API work, marker dedupe, owned-path commits, body-file publication, redaction fallbacks, and the distinction between primary-action failure and optional traceability degradation.post-wave-reportcurrently belongs to the deferred dynamic consumer.Shared review artifacts create a specific coexistence decision:
.last-review-headand.last-analysis-headcontain a SHA, not harness/capability provenance. A Claude run can make Codex skip reviewing that same head. Reports can remain cross-readable while execution markers record harness, contract version, focus coverage, and commit; alternatively shared markers need an explicit equivalence policy. Do not accidentally change that behavior through path reuse.HUD, browser and security gaps
The current renderer does not display tool/agent activity rows;
detailis persisted but not consumed by the rendering path. Adding activity rows is extra scope, not required parity. The retained HUD references below were source-inspected in the earlier session; they were not installed or tested end to end in this audit.Use stock
tui.status_linefor a native subset, or a companion tmux/cmux process to reuse the full Devflow renderer. The inspected/publicly documented interface does not establish arbitrary custom footer output. The companion needs refresh/resize/exit/fallback behavior and exact thread binding; “newest rollout” is insufficient. App Server supplies structured thread/plan/usage events, but a new server does not automatically subscribe to another running CLI. A read-only collector should not resume a thread just to inspect it. App ServerBrowser QA has a concrete candidate: Microsoft's Playwright MCP documents Codex configuration and provides navigation, snapshots, forms, JavaScript evaluation, console messages, and tab management. These correspond to the operations in Devflow's browser reference. It also documents browser-profile contention across concurrent clients; choose isolated or distinct profiles where needed. The built-in browser is documented as unavailable in CLI/IDE, so it cannot be the universal QA backend. Codex browser availability
Keep the dev-server lifecycle contract: reuse existing servers, own only servers started by the run, bound readiness waits, preserve logs and exit status, and clean up owned tabs/processes. Validate login/session requirements independently of tool availability. Browser/scanner outages must be represented in acceptance coverage, not reported as successful testing.
For sensitive files, Codex's permission profiles provide a candidate for path/glob read denial. This is a more concrete route than treating
AGENTS.mdor an invented.codexignoreas enforcement. Profiles are beta, platform-sensitive and distinct from legacy sandbox settings. MCP servers and hosted tools require their own boundary assessment. Translate dangerous-command patterns through real exec policies/permissions; hook aliases and shell wrappers make literal pattern copying insufficient. Rules, Permission profilesThe security template's individual deny entries and every non-comment ignore pattern are preserved in the machine-readable inventory. The command-policy categories include destructive deletion/disk operations, shell/interpreter wrappers, downloaded-code execution, privilege/accounts/permissions, process/service termination, network listeners/scanning, kernel/firewall/container escape operations, scheduled persistence, log/history erasure, credential metadata access, remote transfer, mining, system package installation, mounts and protected-system writes. Sensitive reads cover environment/secrets, cloud/SSH credentials, private keys and system account files.
Do not turn every ignore entry into an enforced read denial. The current
.claudeignoremixes secrets with context-noise exclusions, including SQL files, lockfiles,.git, and.gitignore. Devflow's database/dependency reviews, Git workflows, and ignore maintenance need some of those files. Classify confidentiality requirements separately from discovery preferences. Safe-delete also needs per-shell startup validation: existing support spans zsh, bash, fish and PowerShell with platform-specific trash behavior.Prior HUD projects and pinned Codex footer sources are preserved in the linked discovery archive and readiness-review evidence; no dependency selection is implied.
MDS solution: shared semantics, harness targets
Use harness targets (
claude-code,codex) as the term. MDS does not require a new “worlds” language feature. Keep tracker provider (github, laterjira/linear), client capabilities, install scope, and harness as distinct inputs; an issue tracker is not a harness.The historical 0.2.0 probes are preserved in the inventory and readiness-review evidence. The active target and verified 0.4.2 requirements follow below.
Proposed authoring and generation contract
.mdsexplicitly; do not reinterpret every brace in every existing Markdown example.agents/openai.yamlwith proper serializers. Render role bodies intodeveloper_instructions. Preserve required skill lists as verified load contracts, not unsupported TOML keys.Agent(...)example. Preserve literal runtime placeholders deliberately.release.md, agent bodies, affected skill bodies/references, charter, memory-runner prompt, and Learning/plan-handoff strings currently embedded in shell. Avoid parallel independently maintained copies.${DEVFLOW_COMPLIANCE_*}tokens are not MDS target variables. Define and test the stage order: select/validate source or override, render target-sensitive body while preserving composition tokens, compose selected framework content, emit/stamp target metadata, install. Under 0.4.2, single-brace tokens remain literal; verify that framework composition consumes only its own tokens after MDS rendering.Illustrative helper using the verified target 0.4.2 syntax:
The caller imports the helper and emits
{{load_skill(harness, "testing")}}. The build invokes:This illustrates one proven composition seam, not a complete production skill resolver. The actual helper should use the generated target namespace and discovered installed path/capability. A workflow should still receive runtime arguments, results, worktree, and selected skills explicitly.
Suggested output families are target-owned workflow skills/commands, role artifacts, skill trees, instruction fragments, and hook prompts. The existing build only permits
dist/commandsand the installer copies agents/skills fromsrc/assets; extending onlycompileFilewould therefore have no effect on those installations. Update asset resolution, packaging, model rewriting, shadowing, compliance convergence, and uninstall together with the generator.Coordination with existing tracker work
src/core/mds-variants.ts, generated Git agents, source resolution, and a byte-identical plumbing phase. It explicitly pins MDS 0.2.0 and excludes speculative variant lists in that phase.Markdown Script 0.2.0 → 0.4.2 upgrade requirements
Target: exact
@mdscript/mds0.4.2, npmlatestverified 2026-09-08; published 2026-09-03. Keep it a development dependency, update the lockfile and native/WASM dependency resolution, and record any later target change here. The Devflow package currently remains on 0.2.0; this section specifies the migration. Published release, versioned changelog.Fresh probe of the actual published package
Installed 0.4.2 in an isolated temporary directory and ran it against the current 13 command hosts. All 13 compiled with zero warnings, yet all 13 outputs changed. The six checked helper families alone left 33 literal call sites instead of injected instructions. For example,
self-reviewshrank from 10,637 to 5,205 output bytes, anddynamic-buildfrom 64,616 to 28,409. These are broken unconverted outputs, not optimizations.The new double-brace imported-helper fixture compiled correctly for both
claude-codeandcodex. Separate probes confirmed legacy escaped braces remain in output, source YAML remains unchanged by runtime vars, and messages results have nooutputfield. Both compiler versions used their native backend; WASM and platform coverage remain upgrade checks. Full per-command results are saved in the evidence inventory.Breaking changes and Devflow applicability
{{name}}/{{helper()}}; old single braces become literal\{/\}escapes are no longer consumed; literal double-opening braces use\{{result.kind === "markdown"before readingresult.outputinbuild-mds.tsand future generators. Reject unexpected messages output for Markdown/TOML-body assets.@messageselects messages output; mixed loose content is invalid; old compileMessages/format APIs were removed@message/removed-API call sites were found. Explicitly keep workflow/role assets in Markdown mode; do not introduce chat-message output accidentally.compileFilefile-relative; nobasePath/unknown options. Account for synchronous validation errors and changed diagnostic types if consumed. Current directcompileFile(host.file)needs no option migration.Rust/Python-only API changes, removed messages APIs, and bundler/watch changes have no identified current Devflow consumer. They do not justify unrelated code changes. The 0.4.1/0.4.2 release notes mainly concern Python packaging; the relevant language/API breaks span 0.3 and 0.4. 0.4.2 package API, language specification.
Upgrade acceptance
release.md, hashes and required semantic sections before editing. Include dynamic commands: their Codex deferral does not remove their Claude regression obligations.Gaps requiring resolution before implementation
Known source defects must also remain visible while porting: #328 publication containment-rule placement; #329 debt-table backfill mismatch; #330 unescaped table content; #331 unconsumed planning inputs. These were already filed, not new Codex regressions. #332 tracks suite subprocess contention. The core-to-Claude import described by #274 is still present in
learning-tuning-config.ts.Decisions for the product owner
devflow initas the full lifecycle owner and generating explicit namespaced Codex workflow skills. Decide whether the first distribution also uses native plugin packages. All 41 domain skills becoming visible is an explicit UX question; do not invert implicit activation to hide them.dynamic-profileearns initial scope given its cross-project data surface and deferred automatic consumer.Minimum Codex version, exact browser package/version, and headless runner details should be selected from capability probes. They are engineering decisions to resolve against these product choices, rather than assumptions to bake into the inventory.
Verification contract for the eventual implementation
The roster is complete for the recorded source baseline. Planning readiness depends on resolving or explicitly accepting G01–G14 and the product decisions above, then recording the agreed requirements and delivery links in this issue.