chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: codex-cli-runtime
|
||||
description: Internal helper contract for calling the codex-companion runtime from Claude Code
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Codex Runtime
|
||||
|
||||
Use this skill only inside the `codex:codex-rescue` subagent.
|
||||
|
||||
Primary helper:
|
||||
- `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "<raw arguments>"`
|
||||
|
||||
Execution rules:
|
||||
- The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke `task` once and return that stdout unchanged.
|
||||
- Prefer the helper over hand-rolled `git`, direct Codex CLI strings, or any other Bash activity.
|
||||
- Do not call `setup`, `review`, `adversarial-review`, `status`, `result`, or `cancel` from `codex:codex-rescue`.
|
||||
- Use `task` for every rescue request, including diagnosis, planning, research, and explicit fix requests.
|
||||
- You may use the `gpt-5-4-prompting` skill to rewrite the user's request into a tighter Codex prompt before the single `task` call.
|
||||
- That prompt drafting is the only Claude-side work allowed. Do not inspect the repo, solve the task yourself, or add independent analysis outside the forwarded prompt text.
|
||||
- Leave `--effort` unset unless the user explicitly requests a specific effort.
|
||||
- Leave model unset by default. Add `--model` only when the user explicitly asks for one.
|
||||
- Map `spark` to `--model gpt-5.3-codex-spark`.
|
||||
- Default to a write-capable Codex run by adding `--write` unless the user explicitly asks for read-only behavior or only wants review, diagnosis, or research without edits.
|
||||
|
||||
Command selection:
|
||||
- Use exactly one `task` invocation per rescue handoff.
|
||||
- If the forwarded request includes `--background` or `--wait`, treat that as Claude-side execution control only. Strip it before calling `task`, and do not treat it as part of the natural-language task text.
|
||||
- If the forwarded request includes `--model`, normalize `spark` to `gpt-5.3-codex-spark` and pass it through to `task`.
|
||||
- If the forwarded request includes `--effort`, pass it through to `task`.
|
||||
- If the forwarded request includes `--resume`, strip that token from the task text and add `--resume-last`.
|
||||
- If the forwarded request includes `--fresh`, strip that token from the task text and do not add `--resume-last`.
|
||||
- `--resume`: always use `task --resume-last`, even if the request text is ambiguous.
|
||||
- `--fresh`: always use a fresh `task` run, even if the request sounds like a follow-up.
|
||||
- `--effort`: accepted values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`.
|
||||
- `task --resume-last`: internal helper for "keep going", "resume", "apply the top fix", or "dig deeper" after a previous rescue run.
|
||||
|
||||
Safety rules:
|
||||
- Default to write-capable Codex work in `codex:codex-rescue` unless the user explicitly asks for read-only behavior.
|
||||
- Preserve the user's task text as-is apart from stripping routing flags.
|
||||
- Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.
|
||||
- Return the stdout of the `task` command exactly as-is.
|
||||
- If the Bash call fails or Codex cannot be invoked, return nothing.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
name: codex-result-handling
|
||||
description: Internal guidance for presenting Codex helper output back to the user
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Codex Result Handling
|
||||
|
||||
When the helper returns Codex output:
|
||||
- Preserve the helper's verdict, summary, findings, and next steps structure.
|
||||
- For review output, present findings first and keep them ordered by severity.
|
||||
- Use the file paths and line numbers exactly as the helper reports them.
|
||||
- Preserve evidence boundaries. If Codex marked something as an inference, uncertainty, or follow-up question, keep that distinction.
|
||||
- Preserve output sections when the prompt asked for them, such as observed facts, inferences, open questions, touched files, or next steps.
|
||||
- If there are no findings, say that explicitly and keep the residual-risk note brief.
|
||||
- If Codex made edits, say so explicitly and list the touched files when the helper provides them.
|
||||
- For `codex:codex-rescue`, do not turn a failed or incomplete Codex run into a Claude-side implementation attempt. Report the failure and stop.
|
||||
- For `codex:codex-rescue`, if Codex was never successfully invoked, do not generate a substitute answer at all.
|
||||
- CRITICAL: After presenting review findings, STOP. Do not make any code changes. Do not fix any issues. You MUST explicitly ask the user which issues, if any, they want fixed before touching a single file. Auto-applying fixes from a review is strictly forbidden, even if the fix is obvious.
|
||||
- If the helper reports malformed output or a failed Codex run, include the most actionable stderr lines and stop there instead of guessing.
|
||||
- If the helper reports that setup or authentication is required, direct the user to `/codex:setup` and do not improvise alternate auth flows.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: gpt-5-4-prompting
|
||||
description: Internal guidance for composing Codex and GPT-5.4 prompts for coding, review, diagnosis, and research tasks inside the Codex Claude Code plugin
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# GPT-5.4 Prompting
|
||||
|
||||
Use this skill when `codex:codex-rescue` needs to ask Codex or another GPT-5.4-based workflow for help.
|
||||
|
||||
Prompt Codex like an operator, not a collaborator. Keep prompts compact and block-structured with XML tags. State the task, the output contract, the follow-through defaults, and the small set of extra constraints that matter.
|
||||
|
||||
Core rules:
|
||||
- Prefer one clear task per Codex run. Split unrelated asks into separate runs.
|
||||
- Tell Codex what done looks like. Do not assume it will infer the desired end state.
|
||||
- Add explicit grounding and verification rules for any task where unsupported guesses would hurt quality.
|
||||
- Prefer better prompt contracts over raising reasoning or adding long natural-language explanations.
|
||||
- Use XML tags consistently so the prompt has stable internal structure.
|
||||
|
||||
Default prompt recipe:
|
||||
- `<task>`: the concrete job and the relevant repository or failure context.
|
||||
- `<structured_output_contract>` or `<compact_output_contract>`: exact shape, ordering, and brevity requirements.
|
||||
- `<default_follow_through_policy>`: what Codex should do by default instead of asking routine questions.
|
||||
- `<verification_loop>` or `<completeness_contract>`: required for debugging, implementation, or risky fixes.
|
||||
- `<grounding_rules>` or `<citation_rules>`: required for review, research, or anything that could drift into unsupported claims.
|
||||
|
||||
When to add blocks:
|
||||
- Coding or debugging: add `completeness_contract`, `verification_loop`, and `missing_context_gating`.
|
||||
- Review or adversarial review: add `grounding_rules`, `structured_output_contract`, and `dig_deeper_nudge`.
|
||||
- Research or recommendation tasks: add `research_mode` and `citation_rules`.
|
||||
- Write-capable tasks: add `action_safety` so Codex stays narrow and avoids unrelated refactors.
|
||||
|
||||
How to choose prompt shape:
|
||||
- Use built-in `review` or `adversarial-review` commands when the job is reviewing local git changes. Those prompts already carry the review contract.
|
||||
- Use `task` when the task is diagnosis, planning, research, or implementation and you need to control the prompt more directly.
|
||||
- Use `task --resume-last` for follow-up instructions on the same Codex thread. Send only the delta instruction instead of restating the whole prompt unless the direction changed materially.
|
||||
|
||||
Working rules:
|
||||
- Prefer explicit prompt contracts over vague nudges.
|
||||
- Use stable XML tag names that match the block names from the reference file.
|
||||
- Do not raise reasoning or complexity first. Tighten the prompt and verification rules before escalating.
|
||||
- Ask Codex for brief, outcome-based progress updates only when the task is long-running or tool-heavy.
|
||||
- Keep claims anchored to observed evidence. If something is a hypothesis, say so.
|
||||
|
||||
Prompt assembly checklist:
|
||||
1. Define the exact task and scope in `<task>`.
|
||||
2. Choose the smallest output contract that still makes the answer easy to use.
|
||||
3. Decide whether Codex should keep going by default or stop for missing high-risk details.
|
||||
4. Add verification, grounding, and safety tags only where the task needs them.
|
||||
5. Remove redundant instructions before sending the prompt.
|
||||
|
||||
Reusable blocks live in [references/prompt-blocks.md](references/prompt-blocks.md).
|
||||
Concrete end-to-end templates live in [references/codex-prompt-recipes.md](references/codex-prompt-recipes.md).
|
||||
Common failure modes to avoid live in [references/codex-prompt-antipatterns.md](references/codex-prompt-antipatterns.md).
|
||||
@@ -0,0 +1,100 @@
|
||||
# Codex Prompt Anti-Patterns
|
||||
|
||||
Avoid these when prompting Codex or GPT-5.4.
|
||||
|
||||
## Vague task framing
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Take a look at this and let me know what you think.
|
||||
```
|
||||
|
||||
Better:
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Review this change for material correctness and regression risks.
|
||||
</task>
|
||||
```
|
||||
|
||||
## Missing output contract
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Investigate and report back.
|
||||
```
|
||||
|
||||
Better:
|
||||
|
||||
```xml
|
||||
<structured_output_contract>
|
||||
Return:
|
||||
1. root cause
|
||||
2. evidence
|
||||
3. smallest safe next step
|
||||
</structured_output_contract>
|
||||
```
|
||||
|
||||
## No follow-through default
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Debug this failure.
|
||||
```
|
||||
|
||||
Better:
|
||||
|
||||
```xml
|
||||
<default_follow_through_policy>
|
||||
Keep going until you have enough evidence to identify the root cause confidently.
|
||||
</default_follow_through_policy>
|
||||
```
|
||||
|
||||
## Asking for more reasoning instead of a better contract
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Think harder and be very smart.
|
||||
```
|
||||
|
||||
Better:
|
||||
|
||||
```xml
|
||||
<verification_loop>
|
||||
Before finalizing, verify that the answer matches the observed evidence and task requirements.
|
||||
</verification_loop>
|
||||
```
|
||||
|
||||
## Mixing unrelated jobs into one run
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Review this diff, fix the bug you find, update the docs, and suggest a roadmap.
|
||||
```
|
||||
|
||||
Better:
|
||||
- Run review first.
|
||||
- Run a separate fix prompt if needed.
|
||||
- Use a third run for docs or roadmap work.
|
||||
|
||||
## Unsupported certainty
|
||||
|
||||
Bad:
|
||||
|
||||
```text
|
||||
Tell me exactly why production failed.
|
||||
```
|
||||
|
||||
Better:
|
||||
|
||||
```xml
|
||||
<grounding_rules>
|
||||
Ground every claim in the provided context or tool outputs.
|
||||
If a point is an inference, label it clearly.
|
||||
</grounding_rules>
|
||||
```
|
||||
@@ -0,0 +1,150 @@
|
||||
# Codex Prompt Recipes
|
||||
|
||||
Use these as starting templates for Codex task prompts or other Codex/GPT-5.4 prompt construction.
|
||||
Copy the smallest recipe that fits the task, then trim anything you do not need.
|
||||
In `codex:codex-rescue`, run diagnosis and fix-oriented recipes in write mode by default unless the user explicitly asked for read-only behavior.
|
||||
|
||||
## Diagnosis
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Diagnose why the failing test or command is breaking in this repository.
|
||||
Use the available repository context and tools to identify the most likely root cause.
|
||||
</task>
|
||||
|
||||
<compact_output_contract>
|
||||
Return a compact diagnosis with:
|
||||
1. most likely root cause
|
||||
2. evidence
|
||||
3. smallest safe next step
|
||||
</compact_output_contract>
|
||||
|
||||
<default_follow_through_policy>
|
||||
Keep going until you have enough evidence to identify the root cause confidently.
|
||||
Only stop to ask questions when a missing detail changes correctness materially.
|
||||
</default_follow_through_policy>
|
||||
|
||||
<verification_loop>
|
||||
Before finalizing, verify that the proposed root cause matches the observed evidence.
|
||||
</verification_loop>
|
||||
|
||||
<missing_context_gating>
|
||||
Do not guess missing repository facts.
|
||||
If required context is absent, state exactly what remains unknown.
|
||||
</missing_context_gating>
|
||||
```
|
||||
|
||||
## Narrow Fix
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Implement the smallest safe fix for the identified issue in this repository.
|
||||
Preserve existing behavior outside the failing path.
|
||||
</task>
|
||||
|
||||
<structured_output_contract>
|
||||
Return:
|
||||
1. summary of the fix
|
||||
2. touched files
|
||||
3. verification performed
|
||||
4. residual risks or follow-ups
|
||||
</structured_output_contract>
|
||||
|
||||
<default_follow_through_policy>
|
||||
Default to the most reasonable low-risk interpretation and keep going.
|
||||
</default_follow_through_policy>
|
||||
|
||||
<completeness_contract>
|
||||
Resolve the task fully before stopping.
|
||||
Do not stop after identifying the issue without applying the fix.
|
||||
</completeness_contract>
|
||||
|
||||
<verification_loop>
|
||||
Before finalizing, verify that the fix matches the task requirements and that the changed code is coherent.
|
||||
</verification_loop>
|
||||
|
||||
<action_safety>
|
||||
Keep changes tightly scoped to the stated task.
|
||||
Avoid unrelated refactors or cleanup.
|
||||
</action_safety>
|
||||
```
|
||||
|
||||
## Root-Cause Review
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Analyze this change for the most likely correctness or regression issues.
|
||||
Focus on the provided repository context only.
|
||||
</task>
|
||||
|
||||
<structured_output_contract>
|
||||
Return:
|
||||
1. findings ordered by severity
|
||||
2. supporting evidence for each finding
|
||||
3. brief next steps
|
||||
</structured_output_contract>
|
||||
|
||||
<grounding_rules>
|
||||
Ground every claim in the repository context or tool outputs.
|
||||
If a point is an inference, label it clearly.
|
||||
</grounding_rules>
|
||||
|
||||
<dig_deeper_nudge>
|
||||
Check for second-order failures, empty-state handling, retries, stale state, and rollback paths before finalizing.
|
||||
</dig_deeper_nudge>
|
||||
|
||||
<verification_loop>
|
||||
Before finalizing, verify that each finding is material and actionable.
|
||||
</verification_loop>
|
||||
```
|
||||
|
||||
## Research Or Recommendation
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Research the available options and recommend the best path for this task.
|
||||
</task>
|
||||
|
||||
<structured_output_contract>
|
||||
Return:
|
||||
1. observed facts
|
||||
2. reasoned recommendation
|
||||
3. tradeoffs
|
||||
4. open questions
|
||||
</structured_output_contract>
|
||||
|
||||
<research_mode>
|
||||
Separate observed facts, reasoned inferences, and open questions.
|
||||
Prefer breadth first, then go deeper only where the evidence changes the recommendation.
|
||||
</research_mode>
|
||||
|
||||
<citation_rules>
|
||||
Back important claims with explicit references to the sources you inspected.
|
||||
Prefer primary sources.
|
||||
</citation_rules>
|
||||
```
|
||||
|
||||
## Prompt-Patching
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Diagnose why this existing prompt is underperforming and propose the smallest high-leverage changes to improve it for Codex or GPT-5.4.
|
||||
</task>
|
||||
|
||||
<structured_output_contract>
|
||||
Return:
|
||||
1. failure modes
|
||||
2. root causes in the current prompt
|
||||
3. a revised prompt
|
||||
4. why the revision should work better
|
||||
</structured_output_contract>
|
||||
|
||||
<grounding_rules>
|
||||
Base your diagnosis on the prompt text and the failure examples provided.
|
||||
Do not invent failure modes that are not supported by the examples.
|
||||
</grounding_rules>
|
||||
|
||||
<verification_loop>
|
||||
Before finalizing, make sure the revised prompt resolves the cited failure modes without adding contradictory instructions.
|
||||
</verification_loop>
|
||||
```
|
||||
@@ -0,0 +1,172 @@
|
||||
# Prompt Blocks
|
||||
|
||||
Use these blocks selectively when composing Codex or GPT-5.4 prompts.
|
||||
Wrap each block in the XML tag shown in its heading.
|
||||
|
||||
## Core Wrapper
|
||||
|
||||
### `task`
|
||||
|
||||
Use in nearly every prompt.
|
||||
|
||||
```xml
|
||||
<task>
|
||||
Describe the concrete job, the relevant repository or failure context, and the expected end state.
|
||||
</task>
|
||||
```
|
||||
|
||||
## Output and Format
|
||||
|
||||
### `structured_output_contract`
|
||||
|
||||
Use when the response shape matters.
|
||||
|
||||
```xml
|
||||
<structured_output_contract>
|
||||
Return exactly the requested output shape and nothing else.
|
||||
Keep the answer compact.
|
||||
Put the highest-value findings or decisions first.
|
||||
</structured_output_contract>
|
||||
```
|
||||
|
||||
### `compact_output_contract`
|
||||
|
||||
Use when you want concise prose instead of a schema.
|
||||
|
||||
```xml
|
||||
<compact_output_contract>
|
||||
Keep the final answer compact and structured.
|
||||
Do not include long scene-setting or repeated recap.
|
||||
</compact_output_contract>
|
||||
```
|
||||
|
||||
## Follow-through and Completion
|
||||
|
||||
### `default_follow_through_policy`
|
||||
|
||||
Use when Codex should act without asking routine questions.
|
||||
|
||||
```xml
|
||||
<default_follow_through_policy>
|
||||
Default to the most reasonable low-risk interpretation and keep going.
|
||||
Only stop to ask questions when a missing detail changes correctness, safety, or an irreversible action.
|
||||
</default_follow_through_policy>
|
||||
```
|
||||
|
||||
### `completeness_contract`
|
||||
|
||||
Use for debugging, implementation, or any multi-step task that should not stop early.
|
||||
|
||||
```xml
|
||||
<completeness_contract>
|
||||
Resolve the task fully before stopping.
|
||||
Do not stop at the first plausible answer.
|
||||
Check whether there are follow-on fixes, edge cases, or cleanup needed for a correct result.
|
||||
</completeness_contract>
|
||||
```
|
||||
|
||||
### `verification_loop`
|
||||
|
||||
Use when correctness matters.
|
||||
|
||||
```xml
|
||||
<verification_loop>
|
||||
Before finalizing, verify the result against the task requirements and the changed files or tool outputs.
|
||||
If a check fails, revise the answer instead of reporting the first draft.
|
||||
</verification_loop>
|
||||
```
|
||||
|
||||
## Grounding and Missing Context
|
||||
|
||||
### `missing_context_gating`
|
||||
|
||||
Use when Codex might otherwise guess.
|
||||
|
||||
```xml
|
||||
<missing_context_gating>
|
||||
Do not guess missing repository facts.
|
||||
If required context is absent, retrieve it with tools or state exactly what remains unknown.
|
||||
</missing_context_gating>
|
||||
```
|
||||
|
||||
### `grounding_rules`
|
||||
|
||||
Use for review, research, or root-cause analysis.
|
||||
|
||||
```xml
|
||||
<grounding_rules>
|
||||
Ground every claim in the provided context or your tool outputs.
|
||||
Do not present inferences as facts.
|
||||
If a point is a hypothesis, label it clearly.
|
||||
</grounding_rules>
|
||||
```
|
||||
|
||||
### `citation_rules`
|
||||
|
||||
Use when external research or quotes matter.
|
||||
|
||||
```xml
|
||||
<citation_rules>
|
||||
Back important claims with citations or explicit references to the source material you inspected.
|
||||
Prefer primary sources.
|
||||
</citation_rules>
|
||||
```
|
||||
|
||||
## Safety and Scope
|
||||
|
||||
### `action_safety`
|
||||
|
||||
Use for write-capable or potentially broad tasks.
|
||||
|
||||
```xml
|
||||
<action_safety>
|
||||
Keep changes tightly scoped to the stated task.
|
||||
Avoid unrelated refactors, renames, or cleanup unless they are required for correctness.
|
||||
Call out any risky or irreversible action before taking it.
|
||||
</action_safety>
|
||||
```
|
||||
|
||||
### `tool_persistence_rules`
|
||||
|
||||
Use for long-running tool-heavy tasks.
|
||||
|
||||
```xml
|
||||
<tool_persistence_rules>
|
||||
Keep using tools until you have enough evidence to finish the task confidently.
|
||||
Do not abandon the workflow after a partial read when another targeted check would change the answer.
|
||||
</tool_persistence_rules>
|
||||
```
|
||||
|
||||
## Task-Specific Blocks
|
||||
|
||||
### `research_mode`
|
||||
|
||||
Use for exploration, comparisons, or recommendations.
|
||||
|
||||
```xml
|
||||
<research_mode>
|
||||
Separate observed facts, reasoned inferences, and open questions.
|
||||
Prefer breadth first, then go deeper only where the evidence changes the recommendation.
|
||||
</research_mode>
|
||||
```
|
||||
|
||||
### `dig_deeper_nudge`
|
||||
|
||||
Use for review and adversarial inspection.
|
||||
|
||||
```xml
|
||||
<dig_deeper_nudge>
|
||||
After you find the first plausible issue, check for second-order failures, empty-state behavior, retries, stale state, and rollback paths before you finalize.
|
||||
</dig_deeper_nudge>
|
||||
```
|
||||
|
||||
### `progress_updates`
|
||||
|
||||
Use when the run may take a while.
|
||||
|
||||
```xml
|
||||
<progress_updates>
|
||||
If you provide progress updates, keep them brief and outcome-based.
|
||||
Mention only major phase changes or blockers.
|
||||
</progress_updates>
|
||||
```
|
||||
Reference in New Issue
Block a user