Skip to content
Back to search

gauntlet

An SDLC toolkit for AI coding agents: spec → plan → build → verify → review → ship.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/e-landeros--gauntlet/badge.svg)](/listings/e-landeros--gauntlet)

HTML

<a href="/listings/e-landeros--gauntlet"><img src="/api/listings/e-landeros--gauntlet/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/e-landeros/gauntlet.git
cd gauntlet
./install.sh --dry-run     # print every action, change nothing
./install.sh               # skills + references + personas + router
./install.sh --claude      # also expose skills to Claude Code

Flags: `--no-router`, `--force`, `--dry-run`, `--check`, `--uninstall`, `--help`. Bash plus `cp`/`rsync`/`sed`. No network, no package manager.

**Canonical target is `~/.agents/skills/`** — the cross-harness Agent Skills location. Claude Code is the one harness that does not read it, so `--claude` links the same tree into `~/.claude/skills`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 169 lines
  1. # Gauntlet
  2. **An SDLC toolkit for AI coding agents.** Spec → plan → build → verify → review →
  3. ship, with a quality bar that does not quietly lower itself.
  4. Most agent "skill" collections are prompt libraries: a pile of advice the model
  5. may or may not follow. Gauntlet is structured as a lifecycle with exit criteria —
  6. each stage produces an artifact, and a stage without its artifact did not happen.
  7. ```text
  8. DEFINE spec-driven-development
  9. PLAN planning-and-task-breakdown
  10. BUILD incremental-implementation + test-driven-development
  11. VERIFY debugging-and-error-recovery
  12. REVIEW code-review-and-quality (fan-out: reviewer, security, tests)
  13. SHIP shipping-and-launch + observability-and-instrumentation
  14. ```
  15. 26 skills · 5 personas · 10 command definitions · 1 router · 1 installer.
  16. ---
  17. ## The problem it solves
  18. An agent asked to "add tests" writes tests that pass. That is the rational
  19. behavior when the success criterion is a green checkmark, and it produces a suite
  20. that grows fast and asserts nothing.
  21. The same failure appears at every stage: a "spec" that restates the prompt, a
  22. "plan" that is a list of file names, a "review" that says looks good to me. The
  23. agent is not lazy — it is optimizing the only signal it was given.
  24. Gauntlet replaces those signals with artifacts. Red-before-green. An evidence
  25. bundle before "done." A go/no-go decision with a rollback plan before "shipped."
  26. The point is not more process, it is *unfakeable* process.
  27. ## Architecture
  28. Three composable layers, deliberately separated:
  29. | Layer | What it is | Job |
  30. |---|---|---|
  31. | **Skills** (`skills/<name>/SKILL.md`) | workflow + steps + exit criteria | the *how* |
  32. | **Personas** (`agents/<role>.md`) | role, perspective, output format | the *who* |
  33. | **Commands** (`commands/*.toml`) | user-facing entry points | the *when* |
  34. **Composition rule: the human is the orchestrator.** A persona may load a skill.
  35. A persona must never invoke another persona — that is the anti-pattern that turns
  36. a clean separation into a router nobody can debug.
  37. The one endorsed multi-agent pattern is parallel fan-out with a merge step, used
  38. by `/ship`: three independent personas investigate, one session synthesizes their
  39. reports into a go/no-go.
  40. `AGENTS.md` is the router: an intent→skill table, the lifecycle, six hard rules,
  41. and an explicit anti-rationalization section naming the thoughts that are wrong
  42. ("this is too small for a skill", "the tests pass, so it's done").
  43. ## Install
  44. ```bash
  45. git clone https://github.com/e-landeros/gauntlet.git
  46. cd gauntlet
  47. ./install.sh --dry-run # print every action, change nothing
  48. ./install.sh # skills + references + personas + router
  49. ./install.sh --claude # also expose skills to Claude Code
  50. ```
  51. Flags: `--no-router`, `--force`, `--dry-run`, `--check`, `--uninstall`, `--help`.
  52. Bash plus `cp`/`rsync`/`sed`. No network, no package manager.
  53. **Canonical target is `~/.agents/skills/`** — the cross-harness Agent Skills
  54. location. Claude Code is the one harness that does not read it, so `--claude`
  55. links the same tree into `~/.claude/skills`.
  56. ## What is enforced, and what is not
  57. Being precise about this matters more than the feature list.
  58. | Mechanism | Enforced by | Strength |
  59. |---|---|---|
  60. | Skill discovery | filesystem scan by the harness | real |
  61. | Skill frontmatter validity | harness rejects missing `name`/`description` | real |
  62. | Reference links resolve | `install.sh --check` | real |
  63. | Install/uninstall correctness | manifest + idempotent rsync | real |
  64. | Router rules | prompt text in the system prompt | **advisory** |
  65. | Lifecycle ordering | model compliance | **advisory** |
  66. | Artifacts before "done" | model compliance | **advisory** |
  67. The router is a 7 KB instruction file injected into every session. It is not a
  68. gate — nothing stops a model from ignoring it. Two things make non-compliance
  69. visible instead of silent: rule 5 requires the agent to state which skill it
  70. loaded (`Using: test-driven-development`), and rule 6 gives the human explicit
  71. authority to override, so a skipped stage is a stated decision rather than a
  72. quiet one.
  73. If you want enforcement rather than advice, the pattern is gates in CI and
  74. CODEOWNERS on the tests — skills shape the first attempt, gates catch what the
  75. attempt missed.
  76. ## Compatibility, verified rather than assumed
  77. | Harness | Reads `~/.agents/skills/` | Note |
  78. |---|---|---|
  79. | Pi | yes, native | documented Agent Skills location |
  80. | Codex | yes, recommended | `~/.codex/skills` is the legacy path |
  81. | GitHub Copilot | yes | personal skills |
  82. | Cursor | yes | user-level |
  83. | VS Code | yes | documented |
  84. | Claude Code | **no** | only `~/.claude/skills/` — hence `--claude` |
  85. Every skill and persona carries only `name` and `description` frontmatter — no
  86. `allowed-tools`, no `compatibility`, no vendor metadata. That minimalism is what
  87. makes the tree portable across six harnesses.
  88. Four skills assume capabilities that are not universal, and degrade predictably:
  89. | Skill | Assumes | Without it |
  90. |---|---|---|
  91. | `idea-refine` | `AskUserQuestion` tool | agent improvises the interview |
  92. | `test-driven-development` | subagent spawning | reproduces the bug inline |
  93. | `doubt-driven-development` | fresh subagent context | adversarial pass runs in-context |
  94. | `browser-testing-with-devtools` | Chrome DevTools MCP | loads, no tools to call |
  95. ## Engineering notes
  96. Things that were non-obvious and cost real debugging time:
  97. **The reference-path trap.** Twelve skills link to `../../references/<file>.md`.
  98. Installed at `~/.agents/skills/<name>/`, that resolves to `~/.agents/references/`.
  99. Copy `skills/` without `references/` and twelve skills silently lose their
  100. checklists — no error, the agent just improvises. The installer copies both, and
  101. `--check` verifies every link resolves.
  102. **Why the router is not in `~/.agents/`.** No harness reads
  103. `~/.agents/AGENTS.md`; the only thing `~/.agents` is scanned for is `skills/`.
  104. The router has to be written to each harness's own global instruction path
  105. (`~/.pi/agent/AGENTS.md`, `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`) or it is a
  106. correct file in a directory nobody reads.
  107. **Idempotent install with a clean exit.** Re-running does not duplicate or spam
  108. backups (it skips the backup when the target already matches). Uninstall reads a
  109. manifest and removes only what it wrote, restoring any instruction file it
  110. replaced.
  111. **No harness-specific edits.** An earlier version rewrote Hermes'
  112. `config.yaml` to enable an external skills dir. It worked, but the running
  113. gateway rewrote that file underneath it and the backup vanished — so the
  114. dependency was dropped rather than patched. The installer now touches only
  115. directories it owns.
  116. ## Limitations
  117. - The router is advisory. It improves behavior; it does not guarantee it.
  118. - Skill descriptions are English-language routing hints. A model that misreads
  119. the intent will load the wrong skill, and no mechanism catches that.
  120. - macOS and Linux only. No Windows path handling.
  121. - `commands/*.toml` is the Gemini/Antigravity format; other harnesses ignore it.
  122. - The skills encode one engineer's opinions about process. Reasonable people
  123. disagree about several of them, which is why they are readable markdown rather
  124. than a framework.
  125. ## Credit
  126. The skills, personas, references and commands began as
  127. [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills), Copyright
  128. (c) 2025 Addy Osmani, MIT. This repo is maintained independently — no upstream
  129. tracking, no sync script. The router, installer, documentation and the
  130. verification work above are mine, MIT. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.