Fail before execution and convert prompts for the active Codex or Claude harness

Open
#372 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Domain
tooling

Research direction

Read ADR 0001 and docs/host-adapter/contract.md first, then run bin/validate to understand the current checks. Implement the runtime adaptation contract and deterministic Codex/Claude conversion fixtures described in the issue without rewriting shared Markdown or executing mismatched prompts. Done means the acceptance criteria pass, including setup documentation and independent fixture review.

Written by the indexing model from the issue text.

Description

agent-claimed complexity:complexify enhancement P2 triage:needs-scope

Problem

Agent Workflows uses one portable source pack across Codex and Claude, but pasteable prompts may still contain host-specific invocation and coordination mechanics. A Codex /goal prompt pasted into Claude, or a Claude-oriented subagent prompt pasted into Codex, can be misinterpreted or begin the wrong workflow.

The current model/effort enforcement and signed-launch machinery do not solve this problem. Model and effort choices are preferences and may be unavailable; host compatibility is the actionable pre-execution boundary.

Maintainer direction

Add a small runtime prompt-adaptation contract. Do not rewrite installed shared Markdown and do not execute an incompatible prompt.

Generated prompts should declare compact metadata such as:

Prompt host: codex|claude|portable
Prompt mode: goal|direct|batch
Preferred route: <model>/<effort>|default
Route requirement: advisory

Before any worker launch, repository mutation, or GitHub write, classify the prompt against the active harness:

  • compatible: proceed normally.
  • portable: apply the existing host adapter and proceed.
  • conversion-required: emit new prompt or prompts for the active harness and stop. The converted prompt is not executed in the same run.

Conversion preserves the objective, scope, targets, dependencies, safety gates, QA/review/merge requirements, and advisory route. It translates only host mechanics such as skill invocation syntax, Codex goal wrapping, Claude Agent/Workflow usage, worktree/subagent coordination, permissions, and availability checks.

Detection boundary

  • Prefer the explicit prompt header over heuristic detection.
  • Legacy detection may use unmistakable host-only syntax such as Codex /goal.
  • Mere mentions of Codex or Claude must not trigger conversion.
  • Ambiguous host state must not silently rewrite or execute a host-specific prompt.

Acceptance criteria

  • Generated batch prompts declare their target host/mode and mark model/effort as advisory.
  • A prompt for the active host proceeds without semantic rewriting.
  • A portable prompt resolves through docs/host-adapter/contract.md.
  • A mismatched prompt produces inert converted prompt text and performs no task work or external mutation.
  • Codex-to-Claude and Claude-to-Codex deterministic fixtures prove objective, scope, targets, dependencies, and gates survive conversion.
  • Legacy unambiguous syntax is detected; incidental host names do not cause false positives.
  • User setup documentation explains the conversion stop/relaunch flow.
  • bin/validate passes and independent review covers the conversion fixtures.

Non-goals

  • Cryptographically proving which model or effort executed.
  • Blocking because a preferred model or effort is unavailable.
  • Install-time rewriting of shared skills or workflows.
  • Automatically executing the converted prompt in the same run.

Related work

  • #151 owns advisory model/effort recommendations and best-effort observed provenance.
  • #299 owns removal of unsupported signed-launch and lifecycle enforcement plus the post-mortem.
  • #306 is superseded and should not merge.
  • ADR 0001 and docs/host-adapter/contract.md remain authoritative for identical shared text and runtime host adaptation.
Dominant language
Ruby
Stars
7
Forks
1
Avg merge
1d 16h
Merged PRs (30d)
150

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from shakacode/agent-workflows

All issues in shakacode/agent-workflows

Similar issues

More Ruby issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.