Skip to content
Back to search

idst

MarketplaceWorks with Claude CodeGitHub

Skills from IDST UK

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/idstuk--ultra-epic/badge.svg)](/listings/idstuk--ultra-epic)

HTML

<a href="/listings/idstuk--ultra-epic"><img src="/api/listings/idstuk--ultra-epic/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

In the target repo:

mkdir -p .claude/skills tools
cp -R <this repo>/skills/ultra-epic .claude/skills/ultra-epic
cp -R <this repo>/skills/sdlc .claude/skills/sdlc
cp -R <this repo>/tools/sdlc tools/sdlc
cp <this repo>/profile/delivery-profile.example.json .claude/delivery-profile.json

Edit `.claude/delivery-profile.json` (see below), then check it:

python3 .claude/skills/ultra-epic/scripts/delivery_profile.py check
python3 tools/sdlc/sdlc.py selftest

Register the guard hook in `.claude/settings.json`:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/tools/sdlc/guard.sh", "timeout": 30 }]
      }
    ]
  }
}

The repo also has a `.claude-plugin/` manifest. A plugin install gives you the two skills; you still copy `tools/sdlc` into the project and register the hook, because the gates run the project's own copy.

Then, in a Claude Code session: `/ultra-epic #<epic number>`.

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.

.claude-plugin/marketplace.json · Manifest · 13 lines
  1. {
  2. "name": "idst",
  3. "description": "Skills from IDST UK",
  4. "owner": { "name": "IDST UK", "url": "https://idst.uk" },
  5. "plugins": [
  6. {
  7. "name": "ultra-epic",
  8. "source": "./",
  9. "description": "Take a Ready epic through every SDLC gate in one session, with two human stops.",
  10. "version": "3.0.0"
  11. }
  12. ]
  13. }
README.md · README · 218 lines
  1. # ultra-epic
  2. An attempt to automate the software development life cycle.
  3. One Claude Code session, the orchestrator, takes a Ready epic and drives it through every gate in
  4. order. It plans, builds in parallel, checks its own work, reviews it with several models, runs
  5. security and the full test harness, and opens a pull request with the evidence. A human answers the
  6. plan's decisions at the first stop and types `DEPLOY` at the second. Nothing reaches main before that.
  7. It is not magic. It needs well-written tickets, a local test stack, and someone who reads the plan.
  8. It ran on two real epics (15 and 48 tickets) before this release. This is the third version, made
  9. generic.
  10. ## How a run goes
  11. ```
  12. preflight ─► STOP 1: plan ─► build lanes ─► QA once ─► unit gate ─► main merged in
  13. ▲ │
  14. the human ▼
  15. approves review ─► security ─► harness (last)
  16. │
  17. the human STOP 2: PR with evidence ◄───────────────┘
  18. types DEPLOY ──────► deploy steps, push to main
  19. ```
  20. | Step | What happens |
  21. |---|---|
  22. | Preflight | Machine load, free disk, main equals the remote main, one epic branch, the epic's test stack free, GitHub API quota. Fails closed. |
  23. | STOP 1: plan | One agent per ticket refines it to Definition of Ready, in parallel. Tickets become lanes from their files and their GitHub blocked-by links. Three critics attack the plan. The human gets a lane graph and numbered decisions, each with a recommendation, and approves. |
  24. | Build | One lane per git worktree, test first, started as soon as the lanes it depends on have merged. A lane merges when its unit tests pass and the merge is clean. |
  25. | QA | Once, on the merged epic. An acceptance checker and a spec reviewer per lane, each scoped to the lane's own tickets and test tier. Gaps go to the lane that owns them. |
  26. | Unit gate | The gate tool runs every touched component's unit command itself. |
  27. | Review | Main merged into the epic first. Six review lenses and, optionally, a cross-model panel, in parallel. Three read-only sceptics try to refute each finding. Only regressions, high-severity and security findings block; the rest become tickets. |
  28. | Security, then harness | On the merged baseline, local stack only, never live. Security first. The harness runs last, and only when security passed. |
  29. | STOP 2 | A PR with the evidence table. The human types `DEPLOY`. |
  30. | Deploy | The profile's deploy steps: approved migrations to live, then the push to main. |
  31. ## The gates
  32. Five gates: `plan`, `unit`, `review`, `security`, `harness`. `tools/sdlc/sdlc.py` records each one as
  33. a hidden-JSON comment on the epic issue and as an `sdlc/<gate>` commit status, against the commit it
  34. judged. Any code change after a pass makes that gate stale, so the epic drops back to that phase.
  35. Changes to docs and the epic's own evidence do not.
  36. `tools/sdlc/guard.sh` is a PreToolUse hook. It blocks any merge or push of an epic into main until all
  37. five gates are fresh passes. It reads `git merge`, `git push`, `gh pr merge` and `gh api` merge calls,
  38. with the bypass forms the earlier runs found (`git -C`, `HEAD:refs/heads/main`, a temp branch carrying
  39. an epic merge). It fails closed: a lookup it cannot make blocks the command.
  40. ## Agent roles and models
  41. | Role | Model |
  42. |---|---|
  43. | Plan drafting, review and security finders | Opus |
  44. | Ticket refinement, lane implementers, mergers, QA checkers, sceptics | Sonnet |
  45. | Setup, test sweeps, lint | Haiku |
  46. The profile's `models` block changes this.
  47. ## Requirements
  48. - Claude Code with the **Workflow tool** (the workflows use its script API: `agent()`, `parallel()`,
  49. `phase()`, `log()` and `export const meta`).
  50. - The `gh` CLI, signed in, with access to the repo's issues, sub-issues and dependencies.
  51. - git with worktrees.
  52. - Python 3 (standard library only for the gate tool; `merge_scenarios.py` needs PyYAML if you use a
  53. scenario catalogue).
  54. - A local test stack you can start per epic, and a harness runner that writes the summary contract.
  55. - Optional: a multi-model review skill such as [panel-review](https://github.com/IDSTUK/panel-review),
  56. named in the profile's `review.panel_skill`.
  57. - Node, only to run this repo's workflow tests.
  58. ## Install
  59. In the target repo:
  60. ```sh
  61. mkdir -p .claude/skills tools
  62. cp -R <this repo>/skills/ultra-epic .claude/skills/ultra-epic
  63. cp -R <this repo>/skills/sdlc .claude/skills/sdlc
  64. cp -R <this repo>/tools/sdlc tools/sdlc
  65. cp <this repo>/profile/delivery-profile.example.json .claude/delivery-profile.json
  66. ```
  67. Edit `.claude/delivery-profile.json` (see below), then check it:
  68. ```sh
  69. python3 .claude/skills/ultra-epic/scripts/delivery_profile.py check
  70. python3 tools/sdlc/sdlc.py selftest
  71. ```
  72. Register the guard hook in `.claude/settings.json`:
  73. ```json
  74. {
  75. "hooks": {
  76. "PreToolUse": [
  77. {
  78. "matcher": "Bash",
  79. "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/tools/sdlc/guard.sh", "timeout": 30 }]
  80. }
  81. ]
  82. }
  83. }
  84. ```
  85. The repo also has a `.claude-plugin/` manifest. A plugin install gives you the two skills; you still
  86. copy `tools/sdlc` into the project and register the hook, because the gates run the project's own copy.
  87. Then, in a Claude Code session: `/ultra-epic #<epic number>`.
  88. ## The delivery profile
  89. Everything project-specific lives in `.claude/delivery-profile.json`. The core never names a database,
  90. a device, a port or a path. The profile answers six questions:
  91. | Question | Keys |
  92. |---|---|
  93. | How do I start the local test stack? | `stack.up`, `stack.check`, `stack.env_file`, `stack.ports` |
  94. | How do I run unit tests? | `components.<name>.unit` |
  95. | How do I run the harness? | `harness.command`, `harness.suite_command` |
  96. | How do I check capacity? | `capacity.*`, `capacity.device_rules` |
  97. | What is live, that tests must never touch? | `live.description`, `live.markers` |
  98. | What are the deploy steps? | `deploy.steps` |
  99. Every key, and the harness summary contract, is in [profile/delivery-profile.md](profile/delivery-profile.md).
  100. A full worked example for a mobile, web and Postgres product is in
  101. [examples/flying-start/](examples/flying-start/).
  102. ## What a Ready epic looks like
  103. - An issue labelled `epic` with its tickets as GitHub sub-issues.
  104. - Each ticket INVEST-sized, with acceptance criteria as Given/When/Then, each naming the test that
  105. will prove it.
  106. - Dependencies as GitHub blocked-by links, not prose.
  107. - A ticket that changes timing or state carries a state table that answers every combination of its
  108. conditions.
  109. The plan step refines tickets, but it cannot invent product decisions. Thin tickets come back as
  110. questions at STOP 1.
  111. ## Cost guidance from real runs
  112. | | Epic 10 (v1) | Epic 14 (v2) |
  113. |---|---|---|
  114. | Tickets | 15 | 48 |
  115. | Models | all Opus | mostly Sonnet |
  116. | Tokens | 3.52 bn | 2.47 bn |
  117. | Tokens per ticket | about 235 m | about 51 m |
  118. | API-equivalent cost | roughly 90 to 110 US dollars per ticket | roughly 22 to 30 US dollars per ticket |
  119. Tokens per ticket fell by about four fifths between the runs; v2 moved builders and checkers to
  120. Sonnet and kept Opus for planning and finding. At the Epic 14 rate, a 40-ticket epic costs around a
  121. thousand dollars at API prices. A subscription plan changes the sums but not the
  122. volume: plan for long runs and the rate limits that come with them.
  123. ## What changed since v2
  124. | Lesson from the second run | v3 | Where |
  125. |---|---|---|
  126. | QA before each merge held lanes back for gaps that were not theirs. | Build and merge every lane first (a lane merges when its unit tests pass and the merge is clean), then QA once on the merged epic, then security, then the harness last. QA gaps never unmerge a lane. | code: `build.js`, `final.js` |
  127. | Checkers failed lanes for work another lane owned, or for tests above the lane's tier. | Each QA checker gets its lane's tickets, files, components and the plan's test tier. A gap in another lane's work goes to that lane. | code: `build.js` |
  128. | One long lane blocked most others and turned the build into a queue. | Lanes of at most 5 tickets; a plan where one lane blocks more than half the others is refused. | code: `waves.py`, `plan.js`, `sdlc.py lint-lanes` and the plan gate |
  129. | Harness lanes started before the features they test were in, and kept chasing failures. | Harness lanes start only after every feature lane merged, and stop after 2 full suite runs to report. | code: `build.js` (start rule, report); prompt: the run limit |
  130. | Medium and low review findings blocked the gate and forced extra rounds. | Only regressions, high-severity and security findings block; the rest become tickets. A circuit breaker asks the human after `review.max_rounds`. | code: `review.js` |
  131. | Timing and state tickets were built against half-specified behaviour. | Definition of Ready: a ticket that changes timing or state needs a state table that answers every combination. No table, not Ready. | code: `plan.js` |
  132. | Two lanes could run the same simulator or E2E suite at once. One shared stack let one tree's migrations show up in another's runs. | One suite lock for exclusive suites. One isolated test stack (database and functions ports) per epic. | code: `suite_lock.sh`, `delivery_profile.py ports`; prompt: lanes must use the lock |
  133. | Runs started on a busy machine, a stale main, a taken stack or a nearly spent API quota. | Preflight checks machine load, main equals the remote main, the test stack is free, and the API quota. | code: `preflight.py` |
  134. "Prompt" means the rule is in the agent's instructions and the code cannot force it. The suite lock,
  135. for example, works only if each lane calls it.
  136. ## Known limits
  137. - **v3 has not run on a real epic yet.** v1 and v2 ran on real epics; this generic version is covered by
  138. its tests (stubbed agents, a stubbed `gh`), not yet by a production run. Expect rough edges in your profile.
  139. - **One epic per machine today.** Each epic has its own stack, but the capacity guard and the suite
  140. lock are per machine, and two orchestrators would each think they own it.
  141. - **It needs Ready tickets.** Vague tickets come back as questions. That is the plan step doing its
  142. job, but it means the run waits on you.
  143. - **Attention is still needed.** The two stops are real decisions. Between them, a circuit breaker or a
  144. migration that went red stops the run and waits.
  145. - **The workflows' prompts are long.** They carry rules learned the hard way. Trim them for your
  146. project, but read the test that guards a rule before you remove it.
  147. - **The guard sees only Bash commands in Claude Code.** A merge in the GitHub web UI bypasses it. Add
  148. branch protection where your plan allows.
  149. - **The harness summary contract is yours to meet.** `sdlc.py` judges the summary; your runner must
  150. write it honestly (local target, not narrowed, not dirty, every failure named).
  151. ## Tests
  152. ```sh
  153. python3 -m unittest discover -s tests -v
  154. ```
  155. The workflow tests run each workflow under Node with stubbed agents. The gate tool has its own
  156. `python3 tools/sdlc/sdlc.py selftest` (118 checks), which the tests also run.
  157. ## Layout
  158. ```
  159. skills/ultra-epic/ the orchestrator skill
  160. SKILL.md the run, step by step
  161. lane-brief.md what every lane implementer reads
  162. summary-template.md the PR body
  163. workflows/ plan.js, build.js, review.js, final.js (Workflow tool scripts)
  164. scripts/ preflight, waves, snapshot, merge_scenarios, delivery_profile,
  165. capacity, suite_lock, lane_env
  166. skills/sdlc/SKILL.md the gate model
  167. tools/sdlc/ sdlc.py (the gate tool), guard.sh (the hook), page.html (board page)
  168. profile/ the profile reference and an example
  169. examples/flying-start/ the worked example the tool was built on
  170. tests/ unittest suites
  171. ```
  172. ## Licence
  173. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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