{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.png\">\n    <img src=\"assets/logo.png\" width=\"360\" alt=\"seudesign\">\n  </picture>\n</p>\n\n<h1 align=\"center\">seudesign</h1>\n\n<p align=\"center\">\n  <em>Don't read system design. Run it.</em><br>\n  Portable system design workflows for design docs, architecture reviews,\n  mock interviews, and capacity estimation.\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/github/stars/SeuPut0705/seudesign?style=flat-square&color=111111&label=stars\" alt=\"Stars\">\n  <img src=\"https://img.shields.io/badge/package-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Gemini-111111?style=flat-square\" alt=\"Claude Code, Codex, and Gemini package\">\n  <img src=\"https://img.shields.io/badge/cases-22-111111?style=flat-square\" alt=\"22 case studies\">\n  <img src=\"https://img.shields.io/github/actions/workflow/status/SeuPut0705/seudesign/ci.yml?style=flat-square&color=111111&label=ci\" alt=\"CI\">\n  <img src=\"https://img.shields.io/badge/license-MIT-111111?style=flat-square\" alt=\"MIT license\">\n</p>\n\n<p align=\"center\">\n  <sub>English &middot; <a href=\"README.ko.md\">한국어</a> &middot; <a href=\"README.ja.md\">日本語</a> &middot; <a href=\"README.zh.md\">中文</a></sub>\n</p>\n\n---\n\nseudesign is a **working skill**, not a prompt collection. Its thin router\nloads only the workflow and references needed for the current request. The\nagent answers in your conversation language.\n\n## Workflows\n\n| Mode | Outcome |\n|---|---|\n| `design <system>` | A focused architecture decision or full design grounded in workload and failure boundaries |\n| `review [path]` | Read-only architecture audit with severity, `file:line` evidence, impact, and the smallest fix |\n| `interview [problem]` | Mock interview with progressive hints and rubric scoring |\n| `estimate <target>` | RPS, bandwidth, storage, memory, and sizing limits with explicit assumptions and unknowns |\n\nReuse supplied context, ask only for decisions that are blocked, and complete\nexplicit sequences such as review followed by an improvement design. Chat is\nthe default; requested files use the supplied path or a suitable workspace\npath. An update request authorizes a scoped edit of that document.\n\n## Invoke it on each host\n\n| Host | Invocation |\n|---|---|\n| Claude Code plugin | `/seudesign:sdp design a chat service` |\n| Codex | `$sdp design a chat service`, or open `/skills` and select `sdp` |\n| Gemini CLI extension | Ask naturally, for example “Use the sdp skill to review this repository.” |\n| GitHub Copilot CLI, OpenCode, Cursor, and other AGENTS.md hosts | Ask naturally. Use a host selector only when that host documents it. |\n\nDo not assume that one host's slash command works on another host.\n\n## Install\n\n### Claude Code\n\nSend these as separate prompts:\n\n```text\n/plugin marketplace add https://github.com/SeuPut0705/seudesign.git#v3.0.0\n```\n\n```text\n/plugin install seudesign@seudesign\n```\n\n### Codex\n\n```bash\ncodex plugin marketplace add SeuPut0705/seudesign --ref v3.0.0\ncodex plugin add seudesign@seudesign\n```\n\nThis installation selects the immutable `v3.0.0` release. The marketplace and\nplugin come from that same snapshot. Only stable release versions are managed.\n\nStart a **new Codex session** after installation so the bundled skill is\nloaded. Invoke it with `$sdp` or the `/skills` selector.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/SeuPut0705/seudesign --ref v3.0.0\n```\n\nThe extension loads [AGENTS.md](AGENTS.md), so invoke the four workflows in\nnatural language after starting a new Gemini session. Add `--ref v3.0.0` or a\nfull commit SHA for an immutable install.\n\n### Update an existing installation\n\n```bash\nclaude plugin update seudesign@seudesign\ncodex plugin marketplace upgrade seudesign\ncodex plugin add seudesign@seudesign\ngemini extensions update seudesign\n```\n\nRun only the command for your host, then start a new session. Codex separates\nmarketplace refresh from plugin reinstall, so both Codex commands are required.\nThese update commands preserve a configured Git ref. To move an intentionally\npinned Claude Code, Codex, or Gemini install to `NEW_TAG`, reconfigure that pin explicitly:\n\n```bash\nclaude plugin marketplace remove seudesign\nclaude plugin marketplace add \"https://github.com/SeuPut0705/seudesign.git#NEW_TAG\"\nclaude plugin install seudesign@seudesign\n\ncodex plugin marketplace remove seudesign\ncodex plugin marketplace add SeuPut0705/seudesign --ref NEW_TAG\ncodex plugin add seudesign@seudesign\n\ngemini extensions uninstall seudesign\ngemini extensions install https://github.com/SeuPut0705/seudesign --ref NEW_TAG\n```\n\n### Repository-aware hosts\n\nClone and open the repository. OpenCode, Cursor, and other agents that load\n[AGENTS.md](AGENTS.md) can route natural-language system design requests to\nthe skill. For GitHub Copilot CLI, use its documented extension or\nskill-directory flow rather than copying another host's command syntax.\n\n### Generic skill-directory installer\n\n```bash\nSDP_REF=\"${SDP_REF:-v3.0.0}\"\n(\n  SDP_INSTALLER=$(mktemp \"${TMPDIR:-/tmp}/seudesign-install.XXXXXX\") &&\n  trap 'rm -f \"$SDP_INSTALLER\"' 0 HUP INT TERM &&\n  curl -fsSL --connect-timeout 10 --max-time 120 \\\n    \"https://raw.githubusercontent.com/SeuPut0705/seudesign/$SDP_REF/install.sh\" -o \"$SDP_INSTALLER\" &&\n  REF=\"$SDP_REF\" sh \"$SDP_INSTALLER\"\n)\n```\n\nThe installer stages and validates the skill before activation, recognizes\nthe exact package-owned regular-file inventory and owned installs, and rolls\nback if activation or its root postcondition fails.\nConcurrent invocations for the same `DEST` are serialized by a bounded-wait\ntarget lock, and a symlink used as `SOURCE_DIR` is copied into an independent\nreal directory. Its controls are:\n\n- `DEST=/path/to/skills` changes the parent skills directory.\n- `SDP_REF=<commit>` before the public snippet pins both the installer code and\n  its archive to the same selector. Use a full commit SHA for an immutable,\n  reproducible install; `main`, branches, and movable tags can change.\n- `REF=<tag-or-commit>` selects the archive when running an already obtained\n  `install.sh` directly.\n- `SOURCE_DIR=/path/to/seudesign/skills/sdp` installs a local tree without a\n  network download; this is the deterministic CI path.\n- `FORCE=1` permits replacing an existing target that lacks seudesign's\n  ownership marker. Review that target first because the override is explicit.\n- `LOCK_WAIT_SECONDS=30` sets the maximum lock wait in the `0..86400` second\n  range. A timeout\n  leaves the unverified existing lock untouched and reports its metadata paths\n  for operator inspection.\n- `SIGKILL` and power loss cannot run shell traps. The installer therefore\n  leaves transaction/lock evidence and fails closed; confirm that no process\n  owns it and inspect `previous-sdp` before any manual restore or lock removal.\n- `DOWNLOAD_CONNECT_TIMEOUT_SECONDS=10` and `DOWNLOAD_MAX_TIME_SECONDS=120`\n  bound the single remote archive attempt to `1..86400` seconds. It is not\n  retried automatically; inspect a failure and rerun explicitly.\n\nThe current immutable release is `v3.0.0`. Use that tag for a reproducible\nrelease install, or a full commit SHA when the exact source identity must be\nindependent of a movable Git reference.\n\nPackage validation rejects development/version suffixes and binds installer\ndefaults and release notes to the stable manifest version.\n\nExample local install:\n\n```bash\nSOURCE_DIR=\"$PWD/skills/sdp\" DEST=\"$HOME/.agents/skills\" sh install.sh\n```\n\n## What each installation contains\n\n| Path | Installed components |\n|---|---|\n| Claude Code plugin | `sdp` skill plus the bundled `sdp-reviewer` Claude agent, constrained to read-only `Read`/`Grep`/`Glob` tools |\n| Native Codex plugin | `sdp` skill and install-surface metadata using the existing logos; no app, MCP server, hook, or Claude-agent companion is declared |\n| Gemini CLI extension | Repository context through `AGENTS.md`, which routes natural-language requests to `skills/sdp` |\n| Generic installer | `skills/sdp` only; it does not install reviewer agents, manifests, evals, or repository tooling |\n| Repository checkout | Full package, including AGENTS routing, examples, evals, validators, and installer tests |\n\n## Package contents and counts\n\n- Four on-demand workflow files: `design`, `review`, `interview`, and\n  `estimate`.\n- [22 indexed case studies](skills/sdp/references/cases/index.md).\n- 17 non-case guides: 12 topic references, four workflow files, and one\n  design-document template.\n- Twelve independent eval suites covering scoped decisions, artifacts, partial\n  estimates, workflow sequences, review evidence, and interview behavior;\n  see [evals/README.md](evals/README.md) for execution and verification limits.\n- A deterministic package validator and a staged, target-locked,\n  rollback-safe installer.\n\nRun the local package gates with:\n\n```bash\npython3 scripts/validate_package.py .\npython3 -m unittest discover -s tests -v\nsh -n install.sh\nsh -n tests/test_install.sh\ndash -n install.sh\ndash -n tests/test_install.sh\nsh -n evals/review-evidence/scaffold.sh\nsh -n evals/review-seeded-defect/scaffold.sh\nINSTALLER_SHELL=sh sh tests/test_install.sh\nINSTALLER_SHELL=dash dash tests/test_install.sh\nclaude plugin validate --strict .\ngemini extensions validate .\ngit diff --check\n```\n\nFull sample outputs live in [examples/](examples/).\n\n## Design philosophy\n\n- **No premature scaling** — add infrastructure only after a bottleneck is\n  supported by workload estimates.\n- **Every choice is a trade-off pair** — state what you gain and what you give\n  up.\n- **No design without numbers** — begin with explicit assumptions and units.\n\nExample invocations:\n\n```text\nClaude Code: /seudesign:sdp review\nCodex:       $sdp review\n```\n",
  "bytes": 9758,
  "sha": "1924bd0ffba3a2b3a8f7f0cb1aa5d7b025acbb676c2a32d14c544cd3d70ee671",
  "repo_slug": "seuput0705/seudesign",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_seuput0705_seudesign_6e424ae0/readme"
}