PE hyperstack: merge design-patterns and engineering-discipline into best-practices

[KailasMahavarkar]

Merges design-patterns-skill and engineering-discipline into one skill, best-practices, and adds the rules from a 100-rule general coding rulebook that neither of them covered. Net 483 insertions against 2957 deletions across 46 files.

Why merge

The two skills shipped the same six reference files, byte for byte:

File	Lines	cmp
patterns/design-architecture.md	477	identical
patterns/error-handling.md	364	identical
patterns/maintainability.md	548	identical
patterns/readability.md	195	identical
patterns/simplicity.md	279	identical
patterns/testing.md	309	identical

2172 lines carried twice, with no mechanism keeping them in sync. design-patterns-skill was also a strict subset of what engineering-discipline already advertised as its Quick Reference mode, so the split cost a duplicate and bought nothing.

What survived from each

From	Kept
engineering-discipline	Iron Laws, Coding Laws, 8-step Process Mode, architecture references, red-flag table
design-patterns-skill	Pattern-selection table (situation to pattern), AI-bias guidance, the book sources
Neither	Four new reference files, below

New reference files

Grepped the merged references and then every skill in the repo before writing anything: these had zero hits repo-wide.

File	Rules it now carries
references/practices/coupling-and-abstraction.md	Law of Demeter, Command-Query Separation, no flag arguments, rule of three, DRY-is-knowledge, leaky abstractions, cargo cult, god objects and lasagna layering
references/practices/change-hygiene.md	Atomic commits, commit-why, short-lived branches, never commit a secret, PR size 200-400, automate before human review, review the story, review the code not the coder, TODO(#id) tracked debt, bounded Boy Scout rule
references/practices/architecture-scale.md	Modular monolith default with the signals for splitting, dependencies point inward, no cycles, API-first, the 12 factors that still matter, ADRs
references/practices/operations-baseline.md	Structured logs, metrics vs logs, liveness vs readiness, degrade-do-not-collapse, config over branches, magic numbers, the N+1 shape

Routed rather than restated: OWASP to security-review, complexity analysis to optimizer, reviewer dispatch to code-review, framework specifics to react-pro-coder and python-pro-coder. A new "Owned Elsewhere" table in the skill makes that explicit so the next contributor does not add a fourth copy.

Source material corrections

The rulebook this drew from needed three fixes before ingesting:

Issue	Handling
Rule 5 restated rules 1-4	Dropped
Premature abstraction appeared as rules 3, 34, and 94	Folded into one rule with the rule-of-three test
"IBM modular study: 30% reduction in debugging time"	Traced to a marketing blog, not IBM. Number dropped, the underlying advice kept without a fabricated statistic

Its OWASP Top 10:2025 reference does check out (released November 2025, finalized January 2026), but that surface belongs to security-review, which is built on the OWASP Cheat Sheet Series, so this skill routes there instead of restating a list that will move again.

Also removed

references/misc/overview.md (450 lines): an orphaned Kiro-era install document. Nothing referenced it, it restated SKILL.md, it documented a .kiro/skills install path that does not apply, and it described a references/principles/ directory that has not existed under that name.

Callers updated

20 files: root SKILL.md, skills/hyperstack/SKILL.md, README.md, install.md, summary.md, CREDITS.md, src/internal/context-compiler.ts (bootstrap assertion list), and the 13 skills that reference the execution skill by name in their lifecycle chains.

CHANGELOG.md and docs/superpowers/specs/2026-06-21-pm-persona-design.md keep the old names. They record what happened at the time and are not documentation of the current state.

Verification

$ bun scripts/generate-skills-index.ts
Wrote .../skills/INDEX.md

$ bun run compile:context
Bootstrap char savings: 42.2% (19107 -> 11035)

$ bun test
 87 pass
 0 fail
 850 expect() calls
Ran 87 tests across 13 files. [392.00ms]

$ npx tsc --noEmit
(exit 0)

$ rg "engineering-discipline|design-patterns-skill" . (excluding CHANGELOG, dated specs, and the
  intentional supersedes/absorbs lines in the new skill)
(no matches)

29 skill directories, 29 rows in skills/INDEX.md, README section counts Core 13 / Domain 7 / Meta 2 match their tables.

Note for reviewers using this repo as their agent harness

Anything outside this repository that routes to hyperstack:engineering-discipline or hyperstack:design-patterns-skill by name (a personal CLAUDE.md, an AGENTS.md, a saved prompt) needs the new name. The skill declares supersedes: ["engineering-discipline", "design-patterns-skill"] in its frontmatter to make that discoverable.