@michaelmusyoka/eng-os-kit 1.0.0 → 1.1.0

package/README.md

@@ -9,20 +9,20 @@ Built for **Kilo Code**, and installs just as well into Claude Code, Roo Code, C
 Per project (recommended):
 
 ```bash
-npx eng-os-kit init
+npx @michaelmusyoka/eng-os-kit init
 ```
 
 Every project on this machine:
 
 ```bash
-npx eng-os-kit init --global
+npx @michaelmusyoka/eng-os-kit init --global
 ```
 
 Other agents:
 
 ```bash
-npx eng-os-kit init --agent claude
-npx eng-os-kit init --agent all
+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.
@@ -37,6 +37,8 @@ Then **reload your editor** — Kilo Code only reliably picks up new `SKILL.md`
 └── 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
@@ -48,28 +50,33 @@ Then **reload your editor** — Kilo Code only reliably picks up new `SKILL.md`
 
 | Command | Does |
 |---|---|
-| `npx eng-os-kit init` | install rules, skills and `.agent/` scaffolding |
-| `npx eng-os-kit add security-review test-strategy` | install a subset |
-| `npx eng-os-kit list` | every skill and its trigger description |
-| `npx eng-os-kit check` | run the enforcement scripts (CI-safe, exits non-zero) |
-| `npx eng-os-kit doctor` | what is installed where |
+| `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 |
+| `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 |
-| `release-gate` | all | before any production deploy |
 | `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 |
 

package/bin/eng-os.mjs

@@ -100,7 +100,7 @@ function cmdInit() {
   const root = base();
   const opts = { force: flag("force"), link: flag("link") };
 
-  say(`${c.b}eng-os-kit ${pkg.version}${c.x} → ${root}\n`);
+  say(`${c.b}${pkg.name} ${pkg.version}${c.x} → ${root}\n`);
 
   for (const name of agents) {
     const target = resolveTarget(name);
@@ -135,18 +135,18 @@ function cmdInit() {
   }
   ok(".agent/ state, templates and scripts ready");
   say(`\n${c.d}Next:${c.x} reload your editor, then ask the agent: "read the engineering contract and run discovery".`);
-  say(`${c.d}Enforce:${c.x} npx eng-os check`);
+  say(`${c.d}Enforce:${c.x} npx ${pkg.name} check`);
 }
 
 function cmdList() {
-  say(`${c.b}Skills in eng-os-kit ${pkg.version}${c.x}\n`);
+  say(`${c.b}Skills in ${pkg.name} ${pkg.version}${c.x}\n`);
   for (const s of allSkills()) {
     const fm = frontmatter(s);
     say(`${c.b}${s}${c.x}${fm.mode ? c.d + " [mode: " + fm.mode + "]" + c.x : ""}`);
     say(`  ${c.d}${fm.description || ""}${c.x}\n`);
   }
-  say(`${c.d}Install all:  npx eng-os-kit init${c.x}`);
-  say(`${c.d}Install some: npx eng-os-kit add security-review test-strategy${c.x}`);
+  say(`${c.d}Install all:  npx ${pkg.name} init${c.x}`);
+  say(`${c.d}Install some: npx ${pkg.name} add security-review test-strategy${c.x}`);
 }
 
 function cmdAdd() {
@@ -194,14 +194,14 @@ function cmdDoctor() {
 }
 
 function cmdHelp() {
-  say(`${c.b}eng-os-kit${c.x} ${pkg.version} — engineering operating system for AI coding agents
+  say(`${c.b}${pkg.name}${c.x} ${pkg.version} — engineering operating system for AI coding agents
 
 ${c.b}Usage${c.x}
-  npx eng-os-kit init [options]          install rules + all skills + .agent scaffolding
-  npx eng-os-kit add <skill...>          install specific skills only
-  npx eng-os-kit list                    list bundled skills and their triggers
-  npx eng-os-kit check                   run the enforcement scripts (CI-safe)
-  npx eng-os-kit doctor                  show what is installed where
+  npx ${pkg.name} init [options]          install rules + all skills + .agent scaffolding
+  npx ${pkg.name} add <skill...>          install specific skills only
+  npx ${pkg.name} list                    list bundled skills and their triggers
+  npx ${pkg.name} check                   run the enforcement scripts (CI-safe)
+  npx ${pkg.name} doctor                  show what is installed where
 
 ${c.b}Options${c.x}
   --agent <name>   kilocode (default) | claude | roo | cursor | codex | all
@@ -212,10 +212,10 @@ ${c.b}Options${c.x}
   --cwd <path>     target project directory
 
 ${c.b}Examples${c.x}
-  npx eng-os-kit init                              # Kilo Code, this project
-  npx eng-os-kit init --agent kilocode --global     # every project on this machine
-  npx eng-os-kit init --link                        # stay in sync with npm updates
-  npx eng-os-kit add security-review --agent roo
+  npx ${pkg.name} init                              # Kilo Code, this project
+  npx ${pkg.name} init --agent kilocode --global     # every project on this machine
+  npx ${pkg.name} init --link                        # stay in sync with npm updates
+  npx ${pkg.name} add security-review --agent roo
 `);
 }
 

package/package.json

@@ -1,14 +1,36 @@
 {
   "name": "@michaelmusyoka/eng-os-kit",
-  "version": "1.0.0",
-  "description": "Production engineering operating system for AI coding agents: rules, Agent Skills, templates and enforcement scripts. Installs into Kilo Code, Claude Code, Roo, Cursor or any Agent Skills compatible agent.",
-  "keywords": ["kilocode", "kilo-code", "agent-skills", "skill", "claude-code", "roo-code", "ai-agent", "engineering-standards"],
+  "version": "1.1.0",
+  "description": "Production engineering operating system for AI coding agents: rules, Agent Skills, templates and enforcement scripts. 14 skills covering the full loop from scope to shipped. Installs into Kilo Code, Claude Code, Roo, Cursor or any Agent Skills compatible agent.",
+  "keywords": [
+    "kilocode",
+    "kilo-code",
+    "agent-skills",
+    "skill",
+    "claude-code",
+    "roo-code",
+    "ai-agent",
+    "engineering-standards"
+  ],
   "license": "MIT",
   "type": "module",
-  "engines": { "node": ">=18" },
-  "bin": { "eng-os": "bin/eng-os.mjs" },
-  "files": ["bin", "lib", "rules", "skills", "templates", "scripts", "state", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "eng-os": "bin/eng-os.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "rules",
+    "skills",
+    "templates",
+    "scripts",
+    "state",
+    "README.md"
+  ],
   "scripts": {
     "selftest": "node bin/eng-os.mjs list && node bin/eng-os.mjs --help"
   }
-}
+}

package/rules/engineering-contract.md

@@ -25,7 +25,10 @@ Surface material conflicts. Do not resolve them silently.
 
 `IMPLEMENTED` means code exists. It never means done. Only `VERIFIED` (evidence recorded) and `PRODUCTION_READY` (release gate passed) do.
 
-Track every feature in `.agent/state/feature-registry.json`. Conversation memory is not project state.
+Track every feature in `.agent/state/feature-registry.json`. Read and keep current `.agent/state/project-context.md` (stack, commands, conventions — see `repo-inspection`) and `.agent/state/roadmap.md` (what's next — see `project-scope`). Conversation memory is not project state; these files are.
+
+## Fresh sessions at handoffs
+Because state lives in files, not conversation, prefer starting a new session at major boundaries — after a merge, before the next feature — rather than continuing one long thread. The files carry the context forward; a shorter session costs less and drifts less. This also makes `code-review`'s second-opinion pass more honest.
 
 ## Blocked
 When a dependency, credential or decision is missing, stop and report: blocker, impact, what resolution is needed, what you could still verify. Never invent a dependency response.
@@ -48,4 +51,4 @@ UI → route/API → authentication → authorization → validation → service
 Keep it short. Detail belongs in `.agent/prompts/`, `.agent/verification/` and `.agent/audits/`.
 
 ## Skills available
-`repo-inspection`, `implementation-prompt`, `api-database-contract`, `security-review`, `test-strategy`, `traceability-audit`, `verification-evidence`, `release-gate`, `code-review`, `incident-response`, `signature-dark-ui`. Load the one that fits; do not work from memory of these standards.
+`project-scope`, `repo-inspection`, `implementation-prompt`, `api-database-contract`, `security-review`, `test-strategy`, `systematic-debugging`, `traceability-audit`, `verification-evidence`, `code-review`, `change-handoff`, `release-gate`, `incident-response`, `signature-dark-ui`. Load the one that fits; do not work from memory of these standards.

package/scripts/placeholder-audit.sh

@@ -13,9 +13,11 @@ SECRET_PATTERN='(AKIA[0-9A-Z]{16})|(sk_live_[0-9a-zA-Z]{10,})|(-----BEGIN (RSA |
 EXCLUDES=(--exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build
           --exclude-dir=.next --exclude-dir=coverage --exclude-dir=vendor --exclude-dir=.venv
           --exclude-dir=__tests__ --exclude-dir=tests --exclude-dir=test --exclude-dir=e2e
-          --exclude-dir=.agent --exclude-dir=.kilocode --exclude-dir=.claude
+          --exclude-dir=.agent --exclude-dir=.kilocode --exclude-dir=.claude --exclude-dir=.roo
+          --exclude-dir=.cursor --exclude-dir=.agents --exclude-dir=.github
           --exclude=*.test.* --exclude=*.spec.* --exclude=*.md --exclude=*.lock --exclude=*.map
-          --exclude=placeholder-audit.sh --exclude=validate-registry.mjs --exclude=capture-evidence.sh)
+          --exclude=placeholder-audit.sh --exclude=validate-registry.mjs --exclude=capture-evidence.sh
+          --exclude=eng-os.mjs)
 
 fail=0
 scan() {

package/skills/change-handoff/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: change-handoff
+description: Write the PR description, changelog entry, and release note from the actual diff, then reconcile the feature registry and known issues to what really shipped. Use this when a change is finished and ready for review or merge, before opening a pull request, and before tagging a release. Load this instead of writing the PR body from memory of the original plan.
+---
+
+# Change Handoff
+
+Implementation drifts from the plan. Write the human-facing summary from `git diff`, not from the implementation prompt you started with — they are often no longer the same thing.
+
+## PR description
+- **What changed and why** — in the diff's own terms, not the ticket's
+- **How it was verified** — point at the evidence in `.agent/verification/`, don't restate it
+- **Breaking changes / migration notes** — explicit, even if "none"
+- **Linked feature ID** from the registry
+
+## Changelog entry
+Group under `Added` / `Changed` / `Fixed` / `Security` / `Removed` (Keep a Changelog style). One line per entry, user-facing language — "what changed for someone using this," not internal refactor detail unless it affects them.
+
+## Release note
+Only for user-facing changes in a tagged release. Skip internal-only changes.
+
+## Reconcile state — do this before calling the change done
+Implementation and planning drift during real work. Close the loop:
+- Update the feature's `status` and `evidence` in `.agent/state/feature-registry.json` to match what actually merged — not what was originally scoped
+- If a decision got made mid-implementation that wasn't in the original prompt, add it to `.agent/state/decision-log.md`
+- If this change resolves an entry in `.agent/state/known-issues.md`, remove it; if it introduces a new deferred item, add it
+- If the stack, commands, or conventions changed, update `.agent/state/project-context.md` (see `repo-inspection`) so the next session isn't working from stale facts
+- If this closes or reorders an item in `.agent/state/roadmap.md`, update it (see `project-scope`)
+
+A change is not handed off until the files, not just the code, reflect reality. The next session — yours or someone else's — reads these files, not this conversation.
+
+## Postmortems
+For a production incident writeup, use `incident-response` instead — this skill is for routine merges, not outages.

package/skills/code-review/SKILL.md

@@ -29,6 +29,9 @@ Logging without sensitive data, metrics for the new failure mode, migration safe
 ## Reviewing your own output
 Look specifically for: leftover mocks, hardcoded values that should be config, copy-pasted blocks with one unchanged variable, an `await` that was dropped, error handlers that log and continue when they should abort, and confident code paths you never executed.
 
+## Second opinion
+A reviewer that already believes its own code is correct misses fewer of its own mistakes at random, not zero. For anything critical, prefer running this review in a fresh session — a new conversation with no memory of writing the code, or a different model — rather than immediately after implementing. Ask the same questions above as if handed someone else's diff with no context.
+
 ## Output
 ```
 ## Blocking

package/skills/implementation-prompt/SKILL.md

@@ -36,3 +36,8 @@ Good: "A valid payment request creates exactly one payment record and returns it
 
 ## After approval
 Implement strictly to the prompt. If reality forces a deviation, amend the prompt and say so in the report — do not silently expand scope.
+
+## The gate
+If building this feature would mean inventing an undecided architectural choice — which provider, what data model, how a page should look, which library — stop and write the decision here before continuing. Do not quietly pick one and move on; that decision becomes invisible the moment the session ends.
+
+You may proceed without full approval only when the user explicitly says to. If they do, the decision is not free: write it to `.agent/state/decision-log.md` tagged `ASSUMED — needs ratification`, and add a matching note on the feature's registry entry. Leave the flag in place until someone deliberately revisits and confirms or overturns it — it is a reminder that a decision is owed, not a blocker on shipping. `traceability-audit` should treat an unresolved `ASSUMED` flag on a `critical` feature as a finding.

package/skills/project-scope/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: project-scope
+description: Turn a product idea into a living, ordered plan of what to build next, and keep it current as work ships. Use this when starting a new product, when planning the next slice of work on an existing one, when asked "what should we build" or "what's the plan" at the whole-project level, or when the feature registry has entries but no sense of order. Distinct from traceability-audit (is a specific thing done) and implementation-prompt (how to build one feature) — this is what's next, across the whole project.
+mode: architect
+---
+
+# Project Scope
+
+The feature registry tracks status once a feature exists. This skill decides what gets a registry entry next, and in what order.
+
+## Output
+`.agent/state/roadmap.md` — a short, ordered list of slices (not a full backlog dump):
+```
+## Now
+- [ ] F-00X — <slice> — <why this one is next>
+
+## Next
+- [ ] <slice> — depends on F-00X
+
+## Later
+- <coarse, unordered — don't over-plan work you'll re-scope anyway>
+```
+Coarse and current beats detailed and stale. Re-derive order after every merge that changes what's next (see `change-handoff`).
+
+## Starting a new product (greenfield)
+1. Scope the idea into ordered slices, thinnest first.
+2. Decide the stack and architecture (`implementation-prompt`) before scaffolding — the roadmap depends on what's feasible.
+3. Scaffold the project.
+4. Run `repo-inspection` on the *real* scaffolded project to seed `.agent/state/project-context.md` — not on an empty repository.
+5. Enter the feature loop per slice: `implementation-prompt` → build → `test-strategy` → `code-review` → `change-handoff`.
+
+## Adding to an existing product (brownfield)
+1. Run `repo-inspection` first — the plan must account for what already exists, not assume a blank slate.
+2. Enroll existing functionality into the registry at whatever status it actually has (don't backfill fake `VERIFIED` status for old code no one has evidence for — mark it honestly, e.g. `IMPLEMENTED` with a note).
+3. Plan the next slice on top of that reality.
+
+## Monorepo
+One roadmap per workspace: `.agent/state/roadmap-<workspace>.md`, each with its own ordering, since workspaces ship independently.
+
+## Depth is a judgement call, not a fixed track
+Not every slice needs every gate in the work loop. A throwaway prototype might skip straight to `develop` and a self-check; a critical, user-facing slice should run the full loop through `code-review` and `change-handoff`. Decide the depth per slice and say so in the roadmap entry — don't apply the heaviest process to a one-off script, and don't skip verification on anything touching auth, money, or data because the rest of the project moves fast.
+
+## Rule
+This file records decisions about order and scope, not a copy of the registry's detail. If it starts duplicating `feature-registry.json`, it has grown past what it's for — prune it back to the next few slices.

package/skills/repo-inspection/SKILL.md

@@ -19,15 +19,22 @@ Never assume structure. Read it.
 8. CI workflows and deployment config
 9. Project skills and installed framework docs (for fast-moving frameworks, read the installed docs rather than trusting memory)
 
-## Produce a discovery note in `.agent/audits/discovery-<date>.md`
-- technology inventory with versions
-- repository map
-- existing feature inventory
-- auth and permission model as actually implemented
-- test inventory and how to run each layer
-- deployment path: what triggers a deploy, what gates exist
-- security observations
-- **unknowns** — list them; do not fill them with guesses
+## Two outputs, not one
+
+**A dated snapshot**, `.agent/audits/discovery-<date>.md` — the full inspection as of today: technology inventory with versions, repository map, existing feature inventory, auth and permission model as actually implemented, test inventory and how to run each layer, deployment path, security observations, and **unknowns** — list them; do not fill them with guesses. This is a point-in-time record; never edit an old one.
+
+**A living context file**, `.agent/state/project-context.md` — the current facts every other skill relies on, kept up to date rather than re-derived each session:
+```
+## Stack
+## Commands        (build, dev, lint, typecheck, test — the ones that actually work)
+## Test framework   (and how test-strategy should invoke it)
+## Conventions      (naming, file layout, patterns already in use)
+## Auth model
+## Deployment path
+```
+Create it if it doesn't exist; update it — don't append a new dated copy — whenever the facts change (a dependency upgrade, a new test runner, a changed deploy path). `change-handoff` updates this file too when a merge changes any of the above. Stale facts here are worse than no file: they get trusted.
+
+For a monorepo, write one context file per workspace: `.agent/state/context-<workspace>.md`.
 
 ## Red flags to record immediately
 - a deploy that fires without a passing test gate

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: systematic-debugging
+description: A disciplined root-cause loop for anything that throws, fails, or behaves wrong — as opposed to incident-response, which is for live production outages. Use this the moment something breaks during development, when a test fails unexpectedly, when behaviour doesn't match the spec, or before proposing any fix. Load this instead of guessing and editing until it goes away.
+---
+
+# Systematic Debugging
+
+Guessing and re-running is not debugging. It burns time and often "fixes" the symptom while the cause ships anyway.
+
+## Loop
+1. **Reproduce.** If you cannot reliably reproduce it, that is the first finding, not an excuse to guess. Note the exact input, state, and steps.
+2. **Read before theorizing.** The full error, stack trace, and the actual line it points to — not the line you assume is wrong.
+3. **Bisect.** If this used to work, find the exact commit or change that broke it (`git bisect`, or narrow by feature flag/branch) before reading a single line of application logic. This is faster than reasoning about a large diff.
+4. **Instrument, don't speculate.** Prefer a log line, a breakpoint, or a failing assertion that proves where reality diverges from your model, over editing code on a hunch.
+5. **One hypothesis at a time.** State it, predict what a specific check will show if it's true, run the check. Do not change two things at once — you will not know which one mattered.
+6. **Find the root cause, not the nearest symptom.** A null check that silences a crash is not a fix if the value should never have been null. Trace back to where the invalid state was produced.
+7. **Time-box.** After three failed hypotheses, stop and re-read the actual requirement and the actual data. Most stuck debugging comes from an unexamined assumption made in step 1.
+
+## Before you call it fixed
+- Can you explain, in one sentence, why the bug happened? If not, you have a workaround, not a fix.
+- Hand a regression test to `test-strategy` that fails on the old code and passes on the new. Reference the defect in the test name.
+- If the root cause is systemic (a missing validation layer, a whole class of unguarded null values, a pattern repeated elsewhere), record it in `.agent/state/known-issues.md` rather than fixing only the one instance you tripped over.
+
+## Traps to name out loud when you notice them
+- "It works now" without knowing why — the bug likely still exists, just relocated.
+- Patching around a flaky test instead of finding the race condition — flag it, don't hide it.
+- Fixing in the UI what is actually a server-side authorization or validation gap (check `security-review`).
+- A fix that only works for the exact input you tested — check the boundary and the empty/null case too.
+
+## Escalate rather than fabricate
+If you cannot reproduce it, cannot access the environment where it happens, or the fix requires a decision you're not authorized to make, say so plainly and mark the item `BLOCKED` per `engineering-contract`. Do not report a fix you have not actually verified.

package/skills/test-strategy/SKILL.md

@@ -34,3 +34,6 @@ Every material defect gets a test that fails before the fix and passes after. Re
 
 ## Release blockers
 Do not release with failing critical tests, failing security tests, a failing type check, a failing production build, failing critical E2E, unverified migrations, or unresolved critical vulnerabilities.
+
+## Don't re-derive the framework every session
+The first time you work out how tests actually run here — framework, config, the real command, per-package differences in a monorepo — write it to `.agent/state/project-context.md` (see `repo-inspection`). Future sessions read that instead of searching the repo again.

package/state/project-context.md

@@ -0,0 +1,25 @@
+# Project Context
+
+Kept current, not a dated snapshot — see `repo-inspection`. Overwrite sections in place when facts change; do not append duplicate copies.
+
+## Stack
+
+
+## Commands
+- build:
+- dev:
+- lint:
+- typecheck:
+- test:
+
+## Test framework
+
+
+## Conventions
+
+
+## Auth model
+
+
+## Deployment path
+

package/state/roadmap.md

@@ -0,0 +1,12 @@
+# Roadmap
+
+Coarse and current beats detailed and stale — see `project-scope`. For a monorepo, use `roadmap-<workspace>.md` per workspace.
+
+## Now
+
+
+## Next
+
+
+## Later
+