Skip to content

Commit cec6048

Browse files
WenyuChiouWenyuChiou
authored
Merge pull request #7 from WenyuChiou/feat/port-codex-prompt-blocks
docs(skill): port codex prompt-block engineering layer from codex-plugin-cc
2 parents e542906 + fda8575 commit cec6048

7 files changed

Lines changed: 317 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,32 @@ marketplace; see that repo's CHANGELOG for the catalog-side history.
1111

1212
## [Unreleased]
1313

14+
### Added
15+
16+
- `references/codex-prompt-blocks.md` — composable XML prompt blocks
17+
(`<verification_loop>`, `<grounding_rules>`, `<action_safety>`, …), four
18+
task recipes, and a prompt anti-pattern table for judgment-sensitive briefs.
19+
Adapted from the `gpt-5-4-prompting` skill in
20+
[`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc)
21+
(Apache-2.0); reframed for this skill's single-shot brief-file workflow.
22+
23+
### Changed
24+
25+
- `SKILL.md` and `references/task-template.md` now point judgment-sensitive
26+
tasks (debugging, write-capable changes, review, research) at the new
27+
prompt-blocks reference; mechanical sweeps keep the flat template.
28+
- `references/patterns.md` (Pattern 5) and `references/review-checklist.md`:
29+
added an explicit "do not auto-apply fixes from a review run — present
30+
findings and ask the user first" rule.
31+
- `references/model-selection.md`: documented the `spark` shorthand
32+
(`--model gpt-5.3-codex-spark`).
33+
34+
### Fixed
35+
36+
- `references/patterns.md` (Pattern 5): the review-mode code block used the
37+
deprecated `--full-auto` flag; replaced with `--sandbox workspace-write` to
38+
match `SKILL.md`, `wrapper.md`, and `examples.md`.
39+
1440
## [0.1.0] - 2026-05-15
1541

1642
The initial published version. Captures the skill state at commit

‎skills/codex-delegate/SKILL.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ Full routing table and good/bad examples: `references/delegation-targets.md`.
7676

7777
## Workflow
7878

79-
1. **Brief**: write `.ai/codex_task_<name>.md` with Context / Goal / Constraints / Acceptance. Template: `references/task-template.md`. If the brief was already written by `agent-task-splitter` at `.ai/codex_task_<NNN>_<slug>.md`, read `.coord/plan.yml` for round context first.
79+
1. **Brief**: write `.ai/codex_task_<name>.md` with Context / Goal / Constraints / Acceptance. Template: `references/task-template.md`. For a judgment-sensitive task (debugging, write-capable change, review, research) — where an unsupported guess or a half-finished fix would hurt — also add the XML prompt blocks from `references/codex-prompt-blocks.md` to the Goal/Constraints. A pure mechanical sweep does not need them. If the brief was already written by `agent-task-splitter` at `.ai/codex_task_<NNN>_<slug>.md`, read `.coord/plan.yml` for round context first.
8080

8181
2. **Run**: from Claude Code Bash, invoke the wrapper from its install location:
8282
```bash
@@ -112,6 +112,7 @@ Full routing table and good/bad examples: `references/delegation-targets.md`.
112112
- `references/delegation-targets.md` — when to use vs avoid
113113
- `references/wrapper.md` — full wrapper invocation, env vars, Windows runner notes
114114
- `references/task-template.md` — task brief template
115+
- `references/codex-prompt-blocks.md` — XML prompt blocks + recipes + anti-patterns for judgment-sensitive briefs
115116
- `references/output-contract.md` — full `.result.json` schema, status semantics, `.fallback_claude` quota sentinel
116117
- `references/review-checklist.md` — extended acceptance gate
117118
- `references/patterns.md` — five single-task delegation shapes (context file, parallel, resume, structured output, review mode)

‎skills/codex-delegate/references/codex-prompt-blocks.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Codex prompt blocks — phrasing the task so Codex performs well
2+
3+
`task-template.md` defines the *shape of the brief file* (Context / Goal /
4+
Constraints / Acceptance). This file defines the *phrasing layer*: a set of
5+
composable XML-tagged blocks you drop **inside** the brief's Goal and
6+
Constraints when the task is judgment-sensitive.
7+
8+
For a pure mechanical sweep (batch rename, docstring add) the flat template is
9+
enough — do not bolt these blocks on. Reach for them when an unsupported guess,
10+
a half-finished fix, or an unrelated refactor would actually hurt the result:
11+
debugging, write-capable changes, review, research.
12+
13+
> Adapted from the `gpt-5-4-prompting` skill in
14+
> [`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc)
15+
> (Apache-2.0). Reframed for this skill's single-shot brief-file workflow.
16+
17+
## Where the blocks go
18+
19+
The wrapper runs `--prompt "Read .ai/codex_task_<name>.md and execute..."`, so
20+
Codex reads the brief file. XML tags inside that markdown file are read fine.
21+
Put the blocks under the brief's Goal (what done looks like) or Constraints
22+
(how to stay safe). Keep them compact — a better contract beats raising the
23+
reasoning effort or padding the prompt with prose.
24+
25+
Core rules:
26+
27+
- One clear task per Codex run. Split unrelated asks into separate runs.
28+
- Tell Codex what *done* looks like; do not assume it infers the end state.
29+
- Add a block only where the task needs it. Remove redundant ones before sending.
30+
- Use the exact tag names below so briefs stay consistent across runs.
31+
32+
## Block library
33+
34+
Wrap each block in the XML tag shown. Pick the smallest set that fits.
35+
36+
### `task` — use in nearly every brief
37+
38+
```xml
39+
<task>
40+
The concrete job, the relevant repo or failure context, and the expected end state.
41+
</task>
42+
```
43+
44+
### `structured_output_contract` — when the response shape matters
45+
46+
```xml
47+
<structured_output_contract>
48+
Return exactly the requested output shape and nothing else.
49+
Keep it compact. Put the highest-value findings or decisions first.
50+
</structured_output_contract>
51+
```
52+
53+
### `compact_output_contract` — concise prose instead of a schema
54+
55+
```xml
56+
<compact_output_contract>
57+
Keep the final answer compact and structured.
58+
No long scene-setting, no repeated recap.
59+
</compact_output_contract>
60+
```
61+
62+
### `default_follow_through_policy` — when Codex should act, not ask
63+
64+
```xml
65+
<default_follow_through_policy>
66+
Default to the most reasonable low-risk interpretation and keep going.
67+
Only stop to ask when a missing detail changes correctness, safety, or an
68+
irreversible action.
69+
</default_follow_through_policy>
70+
```
71+
72+
### `completeness_contract` — multi-step work that must not stop early
73+
74+
```xml
75+
<completeness_contract>
76+
Resolve the task fully before stopping. Do not stop at the first plausible
77+
answer. Check for follow-on fixes, edge cases, or cleanup needed for a
78+
correct result.
79+
</completeness_contract>
80+
```
81+
82+
### `verification_loop` — when correctness matters
83+
84+
```xml
85+
<verification_loop>
86+
Before finalizing, verify the result against the task requirements and the
87+
changed files or tool outputs. If a check fails, revise — do not report the
88+
first draft.
89+
</verification_loop>
90+
```
91+
92+
### `missing_context_gating` — when Codex might otherwise guess
93+
94+
```xml
95+
<missing_context_gating>
96+
Do not guess missing repository facts. If required context is absent, retrieve
97+
it with tools or state exactly what remains unknown.
98+
</missing_context_gating>
99+
```
100+
101+
### `grounding_rules` — review, research, root-cause analysis
102+
103+
```xml
104+
<grounding_rules>
105+
Ground every claim in the provided context or your tool outputs.
106+
Do not present inferences as facts. Label any hypothesis clearly.
107+
</grounding_rules>
108+
```
109+
110+
### `action_safety` — write-capable or potentially broad tasks
111+
112+
```xml
113+
<action_safety>
114+
Keep changes tightly scoped to the stated task. Avoid unrelated refactors,
115+
renames, or cleanup unless required for correctness. Call out any risky or
116+
irreversible action before taking it.
117+
</action_safety>
118+
```
119+
120+
### `research_mode` — exploration, comparisons, recommendations
121+
122+
```xml
123+
<research_mode>
124+
Separate observed facts, reasoned inferences, and open questions.
125+
Prefer breadth first, then go deeper only where evidence changes the answer.
126+
</research_mode>
127+
```
128+
129+
### `dig_deeper_nudge` — review and adversarial inspection
130+
131+
```xml
132+
<dig_deeper_nudge>
133+
After the first plausible issue, check for second-order failures, empty-state
134+
behavior, retries, stale state, and rollback paths before finalizing.
135+
</dig_deeper_nudge>
136+
```
137+
138+
### `progress_updates` — long-running, tool-heavy runs
139+
140+
```xml
141+
<progress_updates>
142+
Keep progress updates brief and outcome-based. Mention only major phase
143+
changes or blockers.
144+
</progress_updates>
145+
```
146+
147+
## Recipes
148+
149+
Copy the smallest recipe that fits, then trim. These slot into the brief's
150+
Goal/Constraints; the brief still carries Context (file lists) and Acceptance
151+
(verification commands) per `task-template.md`.
152+
153+
### Narrow fix
154+
155+
```xml
156+
<task>
157+
Implement the smallest safe fix for the identified issue. Preserve existing
158+
behavior outside the failing path.
159+
</task>
160+
<structured_output_contract>
161+
Return: 1. summary of the fix 2. touched files 3. verification performed
162+
4. residual risks or follow-ups
163+
</structured_output_contract>
164+
<completeness_contract>
165+
Resolve the task fully. Do not stop after identifying the issue without
166+
applying the fix.
167+
</completeness_contract>
168+
<verification_loop>
169+
Before finalizing, verify the fix matches the requirements and the changed
170+
code is coherent.
171+
</verification_loop>
172+
<action_safety>
173+
Keep changes tightly scoped. Avoid unrelated refactors or cleanup.
174+
</action_safety>
175+
```
176+
177+
### Diagnosis (read-only — pair with a read-only run)
178+
179+
```xml
180+
<task>
181+
Diagnose why the failing test or command breaks in this repository. Identify
182+
the most likely root cause.
183+
</task>
184+
<compact_output_contract>
185+
Return: 1. most likely root cause 2. evidence 3. smallest safe next step
186+
</compact_output_contract>
187+
<missing_context_gating>
188+
Do not guess missing repository facts. State exactly what remains unknown.
189+
</missing_context_gating>
190+
<verification_loop>
191+
Before finalizing, verify the proposed root cause matches the observed evidence.
192+
</verification_loop>
193+
```
194+
195+
### Root-cause review
196+
197+
```xml
198+
<task>
199+
Analyze this change for the most likely correctness or regression issues.
200+
Focus on the provided repository context only.
201+
</task>
202+
<structured_output_contract>
203+
Return: 1. findings ordered by severity 2. supporting evidence per finding
204+
3. brief next steps
205+
</structured_output_contract>
206+
<grounding_rules>
207+
Ground every claim in the repo context or tool outputs. Label inferences.
208+
</grounding_rules>
209+
<dig_deeper_nudge>
210+
Check second-order failures, empty-state handling, retries, stale state, and
211+
rollback paths before finalizing.
212+
</dig_deeper_nudge>
213+
```
214+
215+
### Research / recommendation
216+
217+
```xml
218+
<task>
219+
Research the available options and recommend the best path for this task.
220+
</task>
221+
<structured_output_contract>
222+
Return: 1. observed facts 2. reasoned recommendation 3. tradeoffs
223+
4. open questions
224+
</structured_output_contract>
225+
<research_mode>
226+
Separate observed facts, reasoned inferences, and open questions.
227+
</research_mode>
228+
```
229+
230+
## Prompt anti-patterns
231+
232+
These are about *prompt phrasing*, distinct from the brief-file anti-patterns
233+
in `task-template.md` (vague goals, missing scope fence).
234+
235+
| Anti-pattern | Bad | Fix |
236+
|---|---|---|
237+
| Vague task framing | "Take a look at this and let me know what you think." | Wrap a concrete job in `<task>`. |
238+
| Missing output contract | "Investigate and report back." | Add `structured_output_contract` or `compact_output_contract`. |
239+
| No follow-through default | "Debug this failure." (Codex stalls asking) | Add `default_follow_through_policy`. |
240+
| Asking for more reasoning | "Think harder and be very smart." | Add `verification_loop` — a contract beats a pep talk. |
241+
| Mixing unrelated jobs | "Review this diff, fix the bug, update docs, suggest a roadmap." | One job per run; split into separate runs. |
242+
| Unsupported certainty | "Tell me exactly why production failed." | Add `grounding_rules` so inferences stay labeled. |
243+
244+
## Cross-references
245+
246+
- `task-template.md` — the brief-file shape these blocks slot into
247+
- `patterns.md` — the five delegation shapes (which recipe pairs with which)
248+
- `review-checklist.md` — Claude's acceptance gate after the run

‎skills/codex-delegate/references/model-selection.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,20 @@ Both produced correct, runnable code. The semantic difference is style: `gpt-5.5
3333
- Wall-time pressure (interactive iteration, TDD-style loops).
3434
- Time-to-first-byte matters more than the final-byte quality.
3535

36+
## The `spark` shorthand
37+
38+
`gpt-5.3-codex-spark` is a low-latency, low-cost Codex model. There is no alias
39+
resolution in the wrapper — it passes `--model` straight through — so the
40+
shorthand is a documentation convention: when the user (or a brief) says
41+
**`spark`**, invoke the wrapper with `--model gpt-5.3-codex-spark`
42+
(`-Model gpt-5.3-codex-spark` in PowerShell).
43+
44+
Reach for `spark` when the task is trivially mechanical and latency dominates —
45+
a fast first pass, a TDD-style loop, or a sweep where even `gpt-5.4` is more
46+
model than the edit needs. For anything where idiomatic style or subtle
47+
correctness matters, stay on the default. Confirm the exact name your CLI
48+
exposes with `codex models`.
49+
3650
## How to A/B another task in your project
3751

3852
```bash

‎skills/codex-delegate/references/patterns.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,11 +132,17 @@ Steps:
132132
2. Run review mode:
133133

134134
```bash
135-
codex exec review --full-auto </dev/null
135+
codex exec review --sandbox workspace-write </dev/null
136136
```
137137

138138
3. Read the review output as a hint, not a verdict. Claude still owns the acceptance decision and runs verification.
139139

140+
**Do not auto-apply fixes from a review run.** After presenting the findings,
141+
stop. Surface them to the user and ask which, if any, they want fixed before
142+
touching a single file — even when a fix looks obvious. A review produces a
143+
list of *candidate* issues, not an approved work order; turning it straight
144+
into edits skips the user's prioritisation call.
145+
140146
Review mode is cheaper than re-running the full implementation pattern when you only want a sanity check.
141147

142148
---

‎skills/codex-delegate/references/review-checklist.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,11 @@ Before accepting a Codex run, Claude must verify each of these:
3434
## Decision
3535

3636
If any answer is *no*, fix the task file or take the rest locally in Claude. Do not paper over a bad run.
37+
38+
## Review-mode runs (Pattern 5)
39+
40+
This checklist gates *acceptance of a delegated implementation*. A **review
41+
mode** run (`patterns.md` Pattern 5) is different: it produces candidate
42+
findings, not a diff to accept. After presenting those findings, stop — do not
43+
auto-apply fixes. Ask the user which issues they want addressed before
44+
touching any file, even when a fix looks obvious.

‎skills/codex-delegate/references/task-template.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,15 @@ Save the brief at `.ai/codex_task_<name>.md`. If the task is part of a multi-age
4343
- Missing scope fence (Codex will then "improve" unrelated files)
4444
- Acceptance written as prose instead of executable verification
4545
- Asking Codex to "decide" between alternatives instead of just executing
46+
47+
These are the failure modes of the *brief file*. The failure modes of the
48+
*task phrasing* (missing output contract, "think harder", mixing unrelated
49+
jobs) are separate — see `codex-prompt-blocks.md`.
50+
51+
## Judgment-sensitive tasks
52+
53+
For debugging, write-capable changes, review, or research, the flat template
54+
above is not enough on its own. Add the composable XML prompt blocks
55+
(`<verification_loop>`, `<grounding_rules>`, `<action_safety>`, …) from
56+
`codex-prompt-blocks.md` to the Goal/Constraints. A pure mechanical sweep
57+
does not need them.

0 commit comments

Comments
 (0)