Previous prose-dense rewrite went too far in stripping bullet structure.
Codex 5.1/5.2 prompts (the closest reference for an OpenAI deep-worker
prompt) actually use bullets liberally - just well-grouped (4-6 per list)
with prose introductions on each section. Restructure 5.5 to mirror that
style and tone while preserving Hephaestus's identity and all behavioral
rules from the prior round.
Sections lifted directly from Codex 5.1/5.2 organization:
- # How you work / ## Personality at the top for tonal priming
- # AGENTS.md spec as a standalone section with its own bullets
- ## Autonomy and Persistence with prose intro + Three-attempt sub-protocol
- ## Responsiveness with Frequency, Tone, Content, Examples sub-blocks
(examples rewritten to Hephaestus voice: 'Walking the agents/ tree',
'Found the dispatch in createSisyphusAgent', etc.)
- ## Plan tool with 'use a plan when' bullet list
- ## Validating your work with approval-mode granularity
(non-interactive / interactive / test-related)
- ## Presenting your work with categorical Final answer rules
(Section Headers / Bullets / Monospace / File references / Tone /
Verbosity / Don't)
- # Tool Guidelines as separate top-level section
Hephaestus-specific content preserved verbatim:
- Forge god identity, deep-worker / executor framing
- task() restricted to research subagents only
- Three-attempt failure protocol
- End-to-end usage gate (interactive_bash / playwright / curl / driver)
- Anti-duplication rule on parallel exploration
Amp-derived rules kept compact in their own ## Pragmatism and Scope:
- Smallest correct change, duplication > premature abstraction
- Default-no-tests with explicit exceptions
- WIP-not-legacy rule
- Multi-agent dirty worktree safety
Metrics: 110 -> 267 lines (still -14% from original 312), 4 -> 100 bullets
(grouped Codex-style, not scattered), 24 headers. 38/38 verification
checks pass; LSP clean.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Prior 5.5 prompt enumerated rules across 60+ bullets and 312 lines, which
fights GPT-5.5's strength: it follows prose instructions reliably and does
not need rule-by-rule cataloging. Rewrite as flowing paragraphs while
preserving the deep-worker identity and every load-bearing behavior.
Identity preserved:
- Forge god mythology ("Your boulder is code", "forge it until done")
- Direct executor, not orchestrator (research subagents only)
- Senior-colleague tone, end-to-end persistence
Behaviors preserved (compressed to prose):
- Three-attempt failure protocol → 1 paragraph
- Anti-duplication on parallel exploration
- End-to-end usage gate (interactive_bash / playwright / curl / driver)
- Implementation gate: when delegated, execute directly, no draft loop
Net additions distilled from Amp + Codex 5.2 evolution:
- Pragmatism block: smallest correct change, duplication > premature
abstraction, do not over-engineer, do not validate impossible scenarios
- Default-no-tests: add tests only when user asks, fixes a subtle bug,
or protects an important boundary; never to codebases without tests
- WIP-not-legacy: earlier unreleased shapes in the same turn are drafts,
not legacy contracts requiring backward compatibility
- Multi-agent worktree: continue task without reverting unknown changes
- Code-review mode trigger: "review" → findings-first, severity-sorted
- Personality-first opener (Codex 5.2 pattern) for tonal priming
Metrics: 312 → 110 lines (-65%), 60+ bullets → 4 bullets, 21,803 → 15,654
chars (-28%). 26/26 verification checks pass.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Hephaestus is the autonomous deep-worker - everything it receives is a
delegation. Existing 'Manual behavior' bullet vaguely said 'actually run
it' but left the validation surface unspecified, which lets a checked-in
diff plus passing tests masquerade as completion on user-visible work.
Add a dedicated 'End-to-end usage is the gate' subsection in Codex prose
style (no threats/CAPS, contract frames). Surface determines tool:
- TUI / CLI → interactive_bash (tmux), drive it like a real user
- Web / browser / UI → playwright skill, drive a real browser session
- HTTP API / service → curl or integration script against running service
- Library / SDK → minimal driver script
Reinforce in Forbidden stops trailer: when receiving a delegation,
execute directly and validate through the gate; do not loop back with
a draft when the work is yours to do.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
The existing FULL DELEGATION manual-QA rule said 'use it yourself' but
left the choice of tool implicit. Make it explicit and non-optional, so
the agent cannot satisfy the gate by reading the source instead of
running the artifact.
Surface → tool mapping:
- TUI / CLI work → interactive_bash (tmux). Launch in real terminal,
send keystrokes, run happy path, try bad input, hit --help.
- Web / browser / UI work → playwright skill. Drive a real browser,
click elements, fill forms, watch console, screenshot if helpful.
- HTTP API / service work → curl or integration script against the
running service.
- Library / SDK work → minimal driver script that imports + executes.
- Other surfaces → ask how a real user would discover it works, then
do that.
Frame the gate as a contract violation when bypassed: reporting
'implementation complete' without using the matching tool is the same
failure pattern as deleting a failing test for a green build.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Existing <verification> required tests pass + lsp clean + build green, but
that is insufficient for end-to-end delegation. Tests cover known cases;
they do not cover whether the user-visible feature actually works.
Add a NON-NEGOTIABLE rule: when the user hands off end-to-end ("ulw",
"implement and finish", "do the whole thing", "make it work", "ship it"),
verification escalates to:
1. BUILD the actual artifact
2. USE IT YOURSELF as a real user would
3. VERIFY end-to-end behavior matches the spec
4. TASK NOT DONE until usage confirms it works
Reporting "implementation complete" without having USED the artifact is
explicitly framed as a contract violation. Defects discovered during this
QA pass are the agent's to fix in the same turn.
This complements the existing 'lsp_diagnostics catches type errors, not
logic bugs' line by giving full-delegation cases a sharper, named gate.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Document the canonical ordering mechanism (Array.prototype.toSorted/sort shim in src/shared/agent-sort-shim.ts) and forbid ZWSP, U+2060, U+00AD, ANSI escape, and ASCII space prefixes. Reference sst/opencode#19127 as the upstream fix that will obsolete the shim.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
The sort shim from the previous commit enforces canonical core ordering at runtime, so ZWSP prefixes are no longer needed. Removing them eliminates the Bun.stringWidth vs terminal-width drift that broke the TUI status bar (#3259).
Drop AGENT_LIST_SORT_PREFIXES and getAgentRuntimeName from agent-display-names; switch all call sites to getAgentDisplayName. getAgentListDisplayName stays as a thin alias for external importers.
Keep stripInvisibleAgentCharacters and the ZWSP regex paths so legacy session state and configs from v3.14.0-v3.16.0 still resolve.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
OpenCode 1.4.x ignores the agent `order` field (sst/opencode#19127), so its
`Agent.list()` sorts purely by `agent.name` via Remeda `sortBy` which uses
native string `<`/`>` comparison. Without intervention, the four core agents
fall into alphabetical order (Atlas -> Hephaestus -> Prometheus -> Sisyphus),
which is not the canonical sisyphus -> hephaestus -> prometheus -> atlas order
the project ships.
Prior attempts to bias the sort key with invisible characters (ZWSP,
U+2060 WORD JOINER, U+00AD SOFT HYPHEN, ANSI escape) all caused
`Bun.stringWidth()` vs terminal-width drift, producing visible gaps and
column truncation in the TUI status bar (#3259, #3238).
Solution: a narrowly-scoped shim of `Array.prototype.toSorted` and
`Array.prototype.sort` that activates only when the array contains two or
more agent objects whose `.name` matches a canonical core display name.
The activation predicate guards against mixed-type arrays so unrelated
`.sort()` / `.toSorted()` calls (string arrays, number arrays, mixed
objects) execute native behavior unchanged. Install is idempotent.
Cubic P1 mitigations from PR #3267:
- `isAgentArray` rejects any array with non-object or null elements,
eliminating the throw-on-mixed-array failure mode.
- Strict activation predicate (>= 2 ranked elements) keeps the global
prototype patch from affecting unrelated sort calls.
Remove this shim once OpenCode honors the agent `order` field
(sst/opencode#19127).
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Discovered via post-implementation review (Oracle goal verification): the
prior commit's prefix swap (ZWSP -> ASCII spaces) inherited a pre-existing
architectural bug from the ZWSP era. `getAgentListDisplayName()` was an
alias for `getAgentRuntimeName()`, which meant every callsite that used
the "list display" name as an OBJECT KEY (config.agent keys, lookup keys,
HTTP-header-bound paths) ended up carrying the sort prefix.
This worked silently with ZWSP because zero-width characters are visually
invisible. With ASCII space prefixes, the same bug becomes user-visible
and violates the explicit RFC 7230 constraint documented in AGENTS.md:
"ZWSP MUST NOT appear in object keys (used as HTTP header values)."
Fix: separate the two concepts that were conflated.
- `getAgentListDisplayName(key)` now returns the CLEAN display name
(alias of `getAgentDisplayName`). Used for object keys, config keys,
and any path where the name will be sent over HTTP.
- `getAgentRuntimeName(key)` keeps its prefixed return value. Used ONLY
for the `.name` field that OpenCode reads for `localeCompare` sort.
`agent-key-remapper.ts` was already correct: it uses `getAgentRuntimeName`
for the `.name` field. The bug was that `getAgentListDisplayName` (used
as the object key) also returned the prefix.
Test updates:
- agent-display-names.test.ts splits the assertions: getAgentListDisplayName
asserts clean names, new getAgentRuntimeName describe asserts prefixes
- All other tests using getAgentListDisplayName as an expected object key
continue to pass because they always wanted clean names
Verification:
- bun test: 5769 pass / 10 pre-existing failures (unchanged)
- bun run typecheck: clean
- Manual: agent-key-remapper output keys verified RFC 7230 safe (no
leading whitespace, no ZWSP); name fields preserve descending-space
prefix for canonical core agent ordering
YeonGyu-Kim