steroid-engine

Files (1)

• SKILL.md

SKILL.md (first lines)

# Steroid Engine (Autonomous Execution Orchestrator)

This skill autonomously executes the checklist in `.memory/changes/<feature>/plan.md`. It uses the Subagent-Driven Development model forked from `Steroid` (see `Steroid internal reference` and `Steroid internal reference`) combined with the autonomous loop pattern from Steroid (see `Steroid internal reference`).

## Governed Baseline

The live governed authority for this phase is:

- `Steroid runtime contract`
- `Steroid runtime contract`
- `Steroid runtime contract`
- `Steroid runtime contract`

In the live repo, this skill is the execution entry point for the governed `steroid-execution-engine`. The current runtime emits standalone live equivalents for `tasks_md` and `execution_receipts` at `.memory/changes/<feature>/tasks.md` and `.memory/changes/<feature>/execution.json`.
In the live repo, this skill is also one of the runtime surfaces for the governed `steroid-progress-memory`. `.memory/progress.md` is the durable append-only progress artifact.

If `.memory/changes/<feature>/prompt.json` exists, read it before the first task. Treat its assumptions, non-goals, continuation state, and recommended route as execution guardrails. They do not replace `plan.md` or `diagnosis.md`, but they explain why the current plan is shaped the way it is.

## The Circuit Breaker Mandate

All terminal commands executed by this skill or any sub-agent it dispatches MUST be wrapped in the physical Node.js circuit breaker:

```
node steroid-run.cjs '<command>'
```

Direct terminal commands (`npm install`, `npx jest`, `node script.js`, etc.) are strictly forbidden. The `steroid-run` wrapper physically tracks errors in `.memory/execution_state.json`. If the error count reaches 5, the wrapper hard-faults and prevents further execution. The AI has no ability to override this.

## Anti-Summarization Directive

NEVER summarize code. NEVER write comments like `// rest of the code here` or `// ...existing code...`. NEVER truncate file contents. If modifying a file, write the complete replacement content or use precise line-targeted edits.

Before marking any task as `[x]`, run the verification guard:

## .gitignore Protection (v5.0.1)

NEVER overwrite the project's `.gitignore`. The installer appends steroid entries (`.memory/`, `.steroid/`, `steroid-run.cjs`, `.agents/`). If you need to create or modify `.gitignore`, ALWAYS APPEND to the existing file — never replace it. The commit command will auto-restore missing entries, but prevention is better than cure.

## Protected Files (v5.0.2)

These files MUST NOT be replaced entirely. Always read first, then modify:

| File                              | Rule                                           |
| --------------------------------- | ---------------------------------------------- |
| `.gitignore`                      | APPEND only. Never replace.                    |
| `package.json`                    | Add/update fields. Never rewrite from scratch. |
| `tsconfig.json`                   | Modify options. Never replace.                 |
| `.env` / `.env.local`             | NEVER touch. Contains secrets.                 |
| `next.config.*` / `vite.config.*` | Read before modifying.                         |
| Any file in `.memory/`            | Read-only during engine phase.                 |

If you must create one of these files for a fresh project, ensure existing content (if any) is preserved.

### Anti-Deletion Guard (v5.5.0)

When modifying an existing file, you MUST preserve all existing:

- Exported functions and components
- UI elements and layouts
- Route definitions
- Configuration values

You may only delete existing code if the spec or plan **explicitly** says to remove it. "Refactoring" is not a valid reason to delete working features. If in doubt, ADD alongside existing code rather than REPLACING it.

```
node steroid-run.cjs verify <path/to/file> --min-lines=<expected>
```

If the file is shorter than expected, the verify command will exit with an error, blocking the task from completion.

## Scaffold Safety (v5.6.0)

NEVER run scaffold commands (`npm create`, `npx create-*`, `npm init`, `yarn create`, `pnpm create`) targeting the project ROOT directory (`.`).

The circuit breaker will physically block these commands. If you attempt `node steroid-run.cjs 'npm create vite . ...'`, the circuit breaker will refuse execution and suggest the safe alternative.

**Safe pattern (v6.0.0 — uses shell-free fs-\* subcommands):**

1. Scaffold into a temp subdirectory:
   `node steroid-run.cjs 'npx create-next-app@latest .steroid-scaffold-tmp --typescript ...'`
2. Copy scaffolded files into root:
   `node steroid-run.cjs fs-cp .steroid-scaffold-tmp .`
3. Remove temp directory:
   `node steroid-run.cjs fs-rm .steroid-scaffold-tmp`
4. Install dependencies:
   `node steroid-run.cjs 'npm install'`
5. Rescan to update memory:
   `node steroid-run.cjs scan <feature> --force`

**Why:** Scaffold tools like `create-vite` prompt "Remove existing files and continue" when the target directory is non-empty. If the AI selects this option (intentionally or accidentally), it deletes `.git/`, `.memory/`, `steroid-run.cjs`, and all infrastructure — destroying the circuit breaker itself and making recovery impossible.

## Phase Gate (Physical Enforcement)

Before doing anything, run the gate check:

```
node steroid-run.cjs gate engine <feature>
```

If this command fails, STOP. The architecture phase is not complete.

## Pre-Execution Setup

Before starting the checklist, create a rollback safety point:

```
node steroid-run.cjs git-init
```

If the build goes wrong, the user can recover with `git reset --hard`.

Also inspect whether this feature is coming from:

- `plan.md` for the normal build/refactor/migrate/document path
- `diagnosis.md` for the targeted fix path

If the feature came from a `split-work` route, complete one clearly scoped sub-problem or story at a time instead of mixing separate intents in the same execution burst.

## Live Execution Artifacts

From nzkbuild/steroid-workflow, MIT.

More from nzkbuild/steroid-workflow