Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →avizmarlon/engineering-standards
Engineering standards and project governance — Charter, RFC, Specification, Architecture Decision Records, Threat Models, SBOM, Runbooks, Playbooks, CHANGELOG, PROGRESS. CI/CD gates, branch protection, security review, dependency audit, secret scanning, TDD, feature flags.
Passed 21 of 22 test cases with the skill, and 14 of 22 without it.
and 7 more in the full report
7 fixed14 passed either way1 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 7 test cases the skill fixed. Same model, same prompt, with and without the skill.
We decided to migrate our primary queue from Redis to Apache Kafka due to partition scalability requirements. Where in the repository should this choice be recorded, and what is the required file path pattern?
| Checked | Without skill | With skill |
|---|---|---|
| requires storing architecture decision records in the docs/adr/ folder with a timestamped filename | Missed | Passed |
The instructions your model reads when the skill loads.
Every non-trivial project should have the artifacts and process gates listed below. This skill defines what to create, when, and why. Gates marked ★ block merge or release if they fail.
| Artifact | Purpose | When to Create |
|---|---|---|
| Charter | 1–2 page document answering: why does this project exist? Vision, scope, stakeholders (who is affected), constraints (what are the hard limits), non-goals (what this is NOT), success criteria. Think of it as the north star for all decisions that follow. | Before any implementation work — even before detailed specs. Required for any project with multiple stakeholders. |
| One-pager / Executive Summary | Single page, no jargon. Problem → Solution → Expected impact → Cost → Timeline. Audience: CEO, investors, leadership without technical context. | Every business/product project. Update when direction changes. |
| RFC (Request for Comments) | Structured proposal inviting review before implementing something that affects multiple components, public APIs, or process. Format: Context + Proposal + Alternatives Considered + Impact Assessment + Decision Status. | Breaking changes, major redesigns, integrations with wide impact, significant process changes. |
| Specification / Design Document (SDD) | What to build, why, and the high-level approach. Distinct from architecture: this answers "what does the system do?" before detailing "how is it built?" | Every non-trivial feature. Can be a section in the RFC or a standalone document. |
| Technical Design Document | Low-level implementation plan: components, interfaces, data flows, performance decisions, edge cases, pseudocode where needed. More granular than the specification. | Complex features, critical modules, performance-sensitive systems. |
| Architecture.md | The system as actually built: components, communication patterns, security invariants, extension points. Must reflect real code, not the original plan. Keep it updated as the system evolves. | Every project with code. Part of the repository root. |
| Architecture Decision Records (ADRs) | Immutable log of design decisions that were non-obvious or consequential. Format: Context + Decision + Rationale + Consequences + Status. Stored in docs/adr/ with timestamp in filename. | Every significant technology choice, architectural shift, or design tradeoff. |
| Threat Model | Structured map of what can break or be attacked: valuable assets (data, tokens, credentials) + potential attackers + attack vectors + mitigations. Minimal format: STRIDE, or simple "What can go wrong + how we prevent it". | Any feature touching auth, user data, payments, external APIs, or permissions. Update when threat landscape changes. |
| Post-mortem | Blameless analysis after an incident. Answers: what happened, timeline, root cause, impact, corrective actions (with owner and deadline). Stored in docs/post-mortems/YYYY-MM-DD-incident-title.md. Focus on systems, not people. | After any production incident or significant failure. Published internally. |
| Software Bill of Materials (SBOM) | Complete, machine-readable inventory of all dependencies: name, version, license. Generated automatically via cyclonedx, syft, package-manager export, or equivalent. | Projects with compliance requirements, sensitive data, or third-party redistribution. Attach to releases. |
| CONTRIBUTING.md | How to contribute: environment setup, PR workflow, code standards, review process, who to contact. Written for humans and AI agents alike. | Any open-source project or repo with multiple contributors (human or AI). |
| Runbooks | Step-by-step operational procedures for routine tasks: deploy, rollback, scale infrastructure, restart service, restore backup. Stored in docs/runbooks/. Written to be executable under pressure, without requiring additional context. | Every operation that might need to happen in production. Include rollback steps. |
| Playbooks | Response scripts for emergencies: "service is down at 3am — what do you do?" / "data breach detected — sequence of actions." Different from runbooks (which are routine); playbooks handle crisis scenarios. Stored in docs/playbooks/. | Projects in production serving real users. Publish in Slack, incident-response tool, or wiki. |
| Build-in-Public Log / Devlog | Visible documentation of progress, milestones, and learnings for team, stakeholders, and community. Posts may live in blog, changelog, status page, or project wiki. | Projects with external visibility, community, or stakeholder reporting. Can be optional for internal-only projects. |
| CHANGELOG.md | Chronological record of all releases: features, fixes, breaking changes. Follows semantic versioning. Machine-readable format (Conventional Commits) enables automated generation. | Every project with a public version or release cycle. |
| PROGRESS.md or Dashboard | Executive summary of current phase, lane status, blockers, and key metrics. Updated continuously. | Business/product projects; multi-phase work. Keep it current so the next team/session knows where you are. |
| SESSION-HANDOFF.md or Equivalent | Snapshot of project state for the next person/AI: what's done, what's in progress, what's blocked, next steps, any gotchas or context that won't be obvious from reading code. | Multi-session, multi-phase, or multi-person projects. Update at end of session before you leave. |
| Gate | Purpose | Mandatory When |
|---|---|---|
| Conventional Commits | Standardized commit message format: type(scope): description. Types: feat (new feature), fix (bug fix), docs, refactor, test, chore, ci, perf, build. Breaking changes: feat! or BREAKING CHANGE: footer. Enables automated CHANGELOG generation and git history parsing. | Every project with version control. Non-negotiable for generating reliable release notes. |
| CI/CD Pipeline ★ | Automated build → lint → type-check → test → security scan → deploy, with failures blocking merge. Every step runs on every PR. | Every project with code. No exceptions. Failures are expected; they save time later. |
| Branch Protection + PR Review Gate ★ | Main/trunk branch protected: push directly is forbidden, PR required, at least one approver, passing CI required before merge. Prevents hotfixes and bypasses that lose audit trail. | Production projects and any repo with multiple contributors. |
| Security Review Gate ★ | Before merging features that expand attack surface (auth, permissions, new APIs, data handling): verify OWASP Top 10 checklist, threat model updated, no secrets exposed, inputs validated, dependencies audited. Can be manual or automated. | Features touching authentication, user data, payments, external APIs, or new permissions. |
| Dependency Audit / Lockfiles ★ | Run npm audit, pip audit, or equivalent before releases. Always commit lockfiles (pnpm-lock.yaml, Pipfile.lock, Cargo.lock). Critical vulnerabilities block release. Patch or upgrade; suppressing is the last resort. | Every project with external dependencies. No exceptions. |
| Secret Scanning ★ | Automated detection of secrets (API keys, tokens, passwords) in code, pre-commit and in CI. Tools: gitleaks, trufflehog, detect-secrets, or cloud provider native. Detected secrets = commit blocked. If already committed: revoke immediately, rotate credentials, assume all prior history is exposed. | Every repository, no exceptions. Set up on day 1. |
| License Compliance | Verify compatibility of all dependencies' licenses with your project's license. GPL in proprietary code requires legal approval. MIT/Apache/BSD generally safe. Use license-checker or equivalent. | Proprietary projects or anything with third-party redistribution. |
| Test-driven Development (TDD) | Red → Green → Refactor: write the test first (it fails), implement minimal code to pass, refactor. Guarantees code is testable and tests cover real behavior, not just happy paths. | Business logic, auth, scoring, validation, public APIs, critical modules. UI scaffolding and exploratory code can skip. |
| Feature Flags / Gradual Rollout | Every new production feature launched behind a flag. Rollout: 1-5% of users → 25% → 100%. Allows reversal without redeployment. Remove flag once stable (target: 4 weeks max). Every flag has a planned removal date. | New features in production with real users. Essential for safety. |
| Semantic Versioning (Semver) | Version numbering: MAJOR.MINOR.PATCH. MAJOR = breaking change, MINOR = backward-compatible feature, PATCH = bug fix. Communicate breaking changes loudly. | Every project with public releases or APIs. |
test cases passed, vs 14 / 22 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.