@michaelmusyoka/eng-os-kit 1.0.0

package/skills/test-strategy/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: test-strategy
+description: What to test, at which layer, and how to prove a critical workflow actually works end to end including failure paths. Use this whenever writing or reviewing tests, when asked whether something is tested enough, before declaring a feature verified, and when a bug is found (it needs a regression test). Load this instead of guessing at coverage.
+---
+
+# Test Strategy
+
+## Layers
+Static checks → unit → integration → contract/API → E2E → security → performance → production smoke. Run what is applicable; state which you skipped and why.
+
+- **Unit**: business rules, validation, calculations, state transitions, authorization decisions, error branches.
+- **Integration**: real database, real adapters, real queue. A test that mocks the database does not prove persistence.
+- **Contract/API**: request and response schemas, status codes, error bodies, pagination.
+- **E2E**: critical journeys only, from the user's perspective — registration, login, recovery, the core transaction, checkout/payment, cancellation, refund, admin action.
+
+## Every critical workflow needs
+happy path · invalid input · missing input · unauthenticated · forbidden · missing resource · duplicate request · concurrent request · timeout · dependency failure · retry · recovery.
+
+If only the happy path is tested, the feature is not tested.
+
+## UI interaction audit
+For every button, link, form, search, filter, pagination control, modal and nav control, verify: correct action fired · permission enforced · request actually sent · validation triggered · loading state blocks double submit · success state · failure state · persistence survives reload · UI reflects server truth.
+
+A control that changes only local state is unimplemented.
+
+## Assertions
+Assert the outcome, not the call. `expect(db.orders.count()).toBe(1)` beats `expect(createOrder).toHaveBeenCalled()`. Assert the absence of the wrong thing too: no second record, no notification on failure, no state change on a 403.
+
+## Coverage
+Coverage is evidence, not correctness. Critical business rules need explicit tests regardless of the percentage. Never raise coverage by testing getters.
+
+## Regression
+Every material defect gets a test that fails before the fix and passes after. Reference the defect ID in the test name.
+
+## 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.

package/skills/traceability-audit/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: traceability-audit
+description: Audit a project for missing features, disconnected controls, orphan endpoints, placeholders and false completion claims, and keep the feature registry accurate. Use this before declaring any feature or project complete, when asked "is this done" or "what is left", when taking over an unfamiliar project, and whenever the feature registry may be stale. Run it before any release decision.
+---
+
+# Traceability and Completeness Audit
+
+## The chain
+REQ → FEATURE → WORKFLOW → UI → API → SERVICE → DATABASE → INTEGRATION → TEST → SECURITY TEST → EVIDENCE → RELEASE
+
+Any missing link is a finding, not a formality.
+
+## Run the mechanical audits first
+```bash
+.agent/scripts/placeholder-audit.sh        # TODO/mock/placeholder/dead links in production paths
+node .agent/scripts/validate-registry.mjs  # registry schema + status/evidence consistency
+```
+Paste real output into `.agent/audits/`. Do not summarise it as "clean" without the output.
+
+## Orphan detection
+Search for and list:
+- requirements with no implementation
+- features with no tests
+- UI controls with no handler, or a handler that only sets local state
+- frontend calls to endpoints that do not exist
+- endpoints with no consumer
+- database tables with no owning feature
+- integrations with no failure handling
+- tests asserting behaviour that no longer exists
+- documentation describing behaviour that does not exist
+- environment variables read but undocumented, or documented but unread
+
+## Completeness dimensions
+Functional · interaction · integration · security · data/state persistence · failure paths · operational (logs, metrics, alerts, recovery) · documentation.
+
+## Registry hygiene
+Every feature in `.agent/state/feature-registry.json` needs: id, title, criticality, status, requirements, acceptanceCriteria, tests, evidence. A `VERIFIED` or `PRODUCTION_READY` entry with an empty `evidence` array is a lie and the validator will fail it.
+
+## Report format
+```
+## Findings
+| Severity | Feature | Finding | Evidence |
+## Registry corrections applied
+## Blockers
+```
+Report honestly: implemented, tested, verified, blocked, incomplete. Never report complete while a critical journey is broken.

package/skills/verification-evidence/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: verification-evidence
+description: How to capture proof that a check actually ran, and how to write a verification record. Use this before claiming anything passed, when marking a feature VERIFIED, when the user asks for proof or test results, and after every test or build run. Load this instead of writing "tests pass" from memory.
+---
+
+# Verification and Evidence
+
+## Rule
+A claim without recorded output is not evidence. Never write "should work", "tests pass" or "verified" unless the command ran in this session and you have its output.
+
+## Capture
+```bash
+.agent/scripts/capture-evidence.sh <feature-id> "<command>"
+```
+Records command, exit code, timestamp, commit SHA and truncated output to `.agent/verification/<feature-id>/`. Run it for each check rather than pasting prose.
+
+## Verification record
+Use `.agent/templates/verification-record.md`. It must state date, commit, environment, then per-section pass/fail with the evidence path. Finish with one decision: `VERIFIED` / `NOT VERIFIED` / `BLOCKED`.
+
+## Manual verification
+Numbered steps a different person could repeat, each with the observed result — not the expected result. Include the account or role used, and the data you used.
+
+## What counts as evidence
+command output with exit code · test summary with counts · build output · security scan report · API response body with status · E2E run result · migration applied against a clean database · deployment smoke test result · a screenshot only when the claim is visual.
+
+## What does not count
+"I reviewed the code" · "the logic is correct" · a passing type check standing in for a behaviour test · a test that mocks the thing being verified · your own summary of output you did not capture.
+
+## When a check cannot run
+Say so explicitly: which check, why, what would unblock it, and what you verified instead. Mark the feature `BLOCKED` rather than `VERIFIED`. Fabricating a result is the single worst failure mode available to you.

package/state/decision-log.md

@@ -0,0 +1,6 @@
+# Decision Log
+
+One entry per material decision. Use `.agent/templates/adr.md` for anything architectural.
+
+| Date | Decision | Rationale | Reversal cost |
+|---|---|---|---|

package/state/feature-registry.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "./feature-registry.schema.json",
+  "features": [
+    {
+      "id": "F-000",
+      "title": "Example — delete this entry",
+      "criticality": "standard",
+      "status": "PLANNED",
+      "requirements": ["REQ-000"],
+      "acceptanceCriteria": ["Replace this entry with a real feature."],
+      "tests": [],
+      "evidence": [],
+      "security": [],
+      "dependencies": [],
+      "notes": ""
+    }
+  ]
+}

package/state/feature-registry.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature registry",
+  "type": "object",
+  "required": ["features"],
+  "properties": {
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "criticality", "status", "requirements", "acceptanceCriteria", "tests", "evidence"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^F-[0-9]{3,}$" },
+          "title": { "type": "string", "minLength": 3 },
+          "criticality": { "enum": ["critical", "standard"] },
+          "status": { "enum": ["PLANNED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "PRODUCTION_READY", "BLOCKED"] },
+          "requirements": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+          "acceptanceCriteria": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+          "tests": { "type": "array", "items": { "type": "string" } },
+          "evidence": { "type": "array", "items": { "type": "string" } },
+          "security": { "type": "array", "items": { "type": "string" } },
+          "dependencies": { "type": "array", "items": { "type": "string" } },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/state/known-issues.md

@@ -0,0 +1,6 @@
+# Known Issues
+
+Accepted defects and deferred work. An item here is a decision, not a forgotten thing.
+
+| ID | Feature | Issue | Severity | Accepted by | Date | Plan |
+|---|---|---|---|---|---|---|

package/templates/adr.md

@@ -0,0 +1,19 @@
+# ADR-{{NUMBER}} — {{TITLE}}
+
+Status:
+
+Date:
+
+## Context
+
+## Decision
+
+## Alternatives
+
+## Consequences
+
+## Security impact
+
+## Operational impact
+
+## Reversal strategy

package/templates/feature-record.md

@@ -0,0 +1,40 @@
+# {{FEATURE-ID}} — {{TITLE}}
+
+Status: DISCOVERED
+
+Requirement IDs:
+- REQ-...
+
+Actors/Roles:
+
+Preconditions:
+
+Workflow:
+
+UI:
+
+API:
+
+Services:
+
+Database:
+
+Integrations:
+
+Permissions:
+
+Security risks:
+
+Failure states:
+
+Acceptance criteria:
+
+Tests:
+
+Evidence:
+
+Dependencies:
+
+Known issues:
+
+Last verified:

package/templates/implementation-prompt.md

@@ -0,0 +1,49 @@
+# Implementation Prompt — {{WORK_ITEM_ID}} — {{TITLE}}
+
+## Goal
+
+## Skills consulted
+
+## Repository inspected
+
+## Existing behavior
+
+## Decisions
+
+## Assumptions
+
+## Files expected to change
+
+## Requirements
+
+### {{REQ-ID}}
+
+## Architecture impact
+
+## Security requirements
+
+## Data/API impact
+
+## Acceptance criteria
+
+- [ ] ...
+
+## Automated checks
+
+```text
+{{commands}}
+```
+
+## Manual verification
+
+1. ...
+2. ...
+3. ...
+
+## Failure-path tests
+
+## Out of scope
+
+## Approval
+
+- [ ] Approved

package/templates/incident-report.md

@@ -0,0 +1,29 @@
+# Incident {{ID}}
+
+Severity:
+
+Date:
+
+## Summary
+
+## Impact
+
+## Timeline
+
+## Detection
+
+## Containment
+
+## Root cause
+
+## Contributing factors
+
+## Recovery
+
+## Verification
+
+## Corrective actions
+
+## Preventive tests
+
+## Owner

package/templates/verification-record.md

@@ -0,0 +1,45 @@
+# Verification — {{FEATURE-ID}}
+
+Date:
+Commit:
+Environment:
+
+## Requirements
+- [ ] Requirement satisfied
+
+## Functional
+- [ ] Happy path
+- [ ] Failure paths
+- [ ] Edge cases
+
+## Security
+- [ ] Authentication
+- [ ] Authorization
+- [ ] Abuse cases
+
+## Integration
+- [ ] API
+- [ ] Database
+- [ ] External dependencies
+
+## Automated checks
+
+Command:
+Result:
+
+Command:
+Result:
+
+## Manual tests
+
+1.
+2.
+3.
+
+## Evidence
+
+## Remaining issues
+
+## Decision
+
+VERIFIED / NOT VERIFIED / BLOCKED