engineering-excellence
ALWAYS-ON: audits plans and code for KISS, YAGNI, DRY, SOLID, and testability; maintains .heyeddi/docs/engineering/. Use on every chat that plans or changes code, before merge, refactor, ADRs, or reuse-catalog work. Not for visual UX (ux-flow-auditor) or full CI (pre-merge-gate includes this audit).
How do I install this agent skill?
npx skills add https://github.com/heyeddi-com/heyeddi-skills --skill engineering-excellenceIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a software engineering audit utility that manages project documentation and performs static analysis on codebase files. It includes a hardened command execution utility and processes local source code, which introduces a minor surface for indirect prompt injection from audited content.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Engineering Excellence
Simple solutions that scale: documented so the next agent does not over-build or repeat work.
Always on for every chat that plans or changes code. See reference/engineering-always-on.md and hub docs/always-on-skills.md.
All artifacts go under .heyeddi/docs/: never repo root.
When to use
- Every chat that proposes an implementation plan or edits code
- After a feature ships: capture how it works
- Before adding abstractions: check reuse catalog
- Refactor / architecture review: KISS, YAGNI, SOLID
- User asks: "don't over-engineer", "document the system", "engineering notes"
Subagents (default)
See reference/subagents.md. Delegate audit_engineering.py, check_engineering_plan.py, and doc init to Task shell. Main chat interprets findings and updates living docs.
Pipeline
check_engineering_plan → plan gate (docs + optional plan smells)
init_engineering_docs → .heyeddi/docs/engineering/{architecture,reuse-catalog,decisions}.md
implement / refactor
audit_engineering → .heyeddi/docs/engineering-audit-<date>.md (--check = errors fail)
append_decision → ADR when trade-off is non-obvious
Instructions
- Plan gate (every chat before coding):
python scripts/check_engineering_plan.py --project-root <root> --check(add--plan-filewhen a written plan exists). - First time in project:
python scripts/init_engineering_docs.py --project-root <root> - While coding: read
reuse-catalog.mdbefore new components/composables/services - After meaningful change: update
architecture.mdmodule map and add reuse rows - Non-obvious trade-off:
append_decision.py --title … --context … --decision … - Change gate (every chat after edits):
audit_engineering.py --check(errors fail; warns advisory). Use--strictonly when the user asks for warn-blocking.
Principles (how we enforce)
| Principle | Skill behavior |
|---|---|
| KISS | Warn on oversized files; error when extreme; prefer flat modules |
| YAGNI | Flag abstraction names without clear reuse; plan gate errors on new Factory/Manager without reuse cite |
| DRY | Maintain reuse-catalog.md; chain @no-duplicate-ui for UI |
| SOLID | Warn on fat routers; views thin, services fat |
| Testable | Note views missing smoke specs |
.heyeddi/ outputs
| Path | Purpose |
|---|---|
.heyeddi/docs/engineering/architecture.md | System map, data flow, boundaries |
.heyeddi/docs/engineering/reuse-catalog.md | What exists: do not rebuild |
.heyeddi/docs/engineering/decisions.md | Engineering ADRs (not design log) |
.heyeddi/docs/engineering-audit-<date>.md | Point-in-time audit report |
Design decisions stay in .heyeddi/design.md Decision log: do not mix.
Chain
@heyeddi: always-on router before this skill when the task is ambiguous@project-engineering: scaffold first@composable-patterns/@backend-type-bridger: after architecture notes exist@pre-merge-gate: final CI; includesaudit_engineering --check
When the task is complete: suggest next skills
When you have finished the user's request for this skill (not after every tool call or subagent phase), suggest what to run next:
-
Run:
python .agents/skills/heyeddi/scripts/suggest_next_skill.py --current-skill engineering-excellence --project-root .Add
--route /pathif you worked a specific route. -
Include the script's
### Next stepblock in your final reply. The user copies the Prompt line into chat (e.g.@visual-auditor review and fix /settings).
Pass --mode audit when the change-gate audit just finished.
See @heyeddi → reference/next-skill-handoff.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/heyeddi-com/heyeddi-skills/engineering-excellence">View engineering-excellence on skillZs</a>