docs: add DESIGN.md explaining why the skill is built this way

Browse Source

1082-line design note covering:
- Empirical facts about Codex CLI 0.121.0 (invocation, streams,
  resume semantics, known failure modes) with copy-pasteable
  verification commands.
- Claude Code harness facts (Bash truncation, cwd drift, Opus
  literal-interpretation tendencies).
- 12 design decisions in a uniform format: what, where in SKILL.md,
  alternatives considered, why chosen, trade-offs accepted.
- Rejected ideas (marker files, per-round naming, $(pwd), etc.) with
  reasons, so future contributors don't re-propose them.
- Prior diagnostic errors from a previous agent-auditor's dump that
  turned out to be wrong when verified, kept as a methodological
  lesson.
- Smoke-test protocol (§7) with concrete commands and expected
  outputs so any maintainer can verify the Codex contract still holds
  in minutes.
- Update protocol: when and how to revise this file, with a pointer
  that future Opus generations interpret instructions more literally
  and SKILL.md hardening must track that.
- Mermaid flow diagram of the round-trip.

Intended audiences: future Claude sessions resuming work on the skill,
human developers, and new contributors. The file is self-contained —
does not rely on conversation history that produced the current design.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

...

This commit is contained in:

ddadmin

2026-04-17 14:29:16 +03:00

co-authored by Claude Opus 4.7

parent 6cf42ad130

commit 3f0d1321ff

1 changed files with 1082 additions and 0 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download Patch File Download Diff File Expand all files Collapse all files

docs/DESIGN.md

+1082

File diff suppressed because it is too large Load Diff