eng-os-kit

An engineering operating system for AI coding agents, installable with npm. Rules that stay in context, standards that load on demand as Agent Skills, and scripts that actually fail a build.

Built for Kilo Code, and installs just as well into Claude Code, Roo Code, Cursor, or any agent implementing the Agent Skills standard.

Install

Per project (recommended):

npx @michaelmusyoka/eng-os-kit init

Every project on this machine:

npx @michaelmusyoka/eng-os-kit init --global

Other agents:

npx @michaelmusyoka/eng-os-kit init --agent claude
npx @michaelmusyoka/eng-os-kit init --agent all

Then reload your editor — Kilo Code only reliably picks up new SKILL.md files on reload.

What lands in your project

.kilocode/
├── rules/00-engineering-contract.md   # ~50 lines, always in context
├── skills/                            # generic skills, loaded on demand
├── skills-architect/                  # planning skills, Architect mode only
└── skills-code/                       # code + UI skills, Code mode only
.agent/
├── state/feature-registry.json        # machine-validated project state
├── state/project-context.md           # living: stack, commands, conventions (kept current, not dated)
├── state/roadmap.md                   # living: what's next, in order
├── state/known-issues.md
├── state/decision-log.md
├── templates/                         # prompt, verification, ADR, incident, feature
├── scripts/                           # the enforcement layer
├── prompts/  plans/  audits/  verification/  reports/

Commands

| Command | Does | |---|---| | npx @michaelmusyoka/eng-os-kit init | install rules, skills and .agent/ scaffolding | | npx @michaelmusyoka/eng-os-kit add security-review test-strategy | install a subset | | npx @michaelmusyoka/eng-os-kit list | every skill and its trigger description | | npx @michaelmusyoka/eng-os-kit check | run the enforcement scripts (CI-safe, exits non-zero) | | npx @michaelmusyoka/eng-os-kit doctor | what is installed where |

Flags: --agent kilocode|claude|roo|cursor|codex|all, --global, --skills a,b, --link (symlink so npm update propagates), --force, --cwd <path>.

Skills

The work loop, start to finish: project-scope → repo-inspection → implementation-prompt → (build) → test-strategy → code-review → change-handoff → release-gate. Run systematic-debugging and incident-response whenever something breaks, wherever you are in that loop.

| Skill | Mode | Triggers on | |---|---|---| | engineering-contract | all | starting non-trivial work, "what's the process" | | project-scope | architect | new product, planning the next slice, "what's the plan" | | repo-inspection | architect | unfamiliar codebase, before any edit | | implementation-prompt | architect | auth/money/migrations/integrations, >3 files, an undecided design | | api-database-contract | all | any endpoint, schema, migration, idempotency | | security-review | all | auth, permissions, uploads, payments, webhooks | | test-strategy | all | writing tests, "is this tested", bug found | | systematic-debugging | all | something throws, fails, or behaves wrong | | traceability-audit | all | "is this done", before release | | verification-evidence | all | before claiming anything passed | | code-review | code | reviewing a diff, after generating code | | change-handoff | all | change is done, before PR/merge/release | | release-gate | all | before any production deploy | | incident-response | all | production broken, writing a postmortem | | signature-dark-ui | code | any UI work |

The enforcement layer

Documentation that nothing checks is decoration. Three scripts do the checking:

• placeholder-audit.sh — fails on committed secrets, TODO/FIXME/placeholder/not implemented, mocks in production paths; warns on dead href="#" links and debug output. Tests, docs and .agent/ are excluded.
• validate-registry.mjs — validates feature-registry.json and enforces the rule that matters: a feature cannot be VERIFIED or PRODUCTION_READY with an empty evidence array, or with evidence paths that do not exist.
• capture-evidence.sh — runs a command and writes command + exit code + commit SHA + output to .agent/verification/<feature-id>/, so evidence is a file rather than a claim.

Copy .github/workflows/eng-os.yml into your project and make the deploy job needs: eng-os. A pipeline that deploys on push without a passing gate makes every gate unreachable.

Design

• Always in context: one ~50-line rules file. Precedence, six hard rules, statuses, report format.
• On demand: everything else as a skill. The agent sees only name + description (~100 tokens each) until a task matches.
• Machine-checked: the claims that agents get wrong — "tests pass", "it's complete" — are validated by scripts, not trust.

Customising

Fork it. Edit rules/engineering-contract.md and the skills/ folders, bump the version, then npm publish under your own scope, or install straight from git:

npx github:<you>/eng-os-kit init

Use --link during authoring so edits in the package show up in your project immediately.

License

MIT.