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

CREDITS.md

@@ -23,7 +23,7 @@ The designer plugin's knowledge base is distilled from publicly available design
 - **Typography and layout** - Bringhurst's *Elements of Typographic Style*, Müller-Brockmann's grid systems
 - **Design systems** - Patterns observed across Linear, Stripe, Vercel, Apple HIG, Carbon, shadcn, Notion, Supabase, and Figma - used as reference, not reproduced
 
-The design-patterns-skill draws on principles from:
+The best-practices skill draws on principles from:
 
 - *Clean Code* - Robert C. Martin
 - *The Pragmatic Programmer* - Hunt and Thomas

README.md

@@ -265,7 +265,7 @@ Domain-expert lenses `hyper` auto-engages when their triggers match the request
 | `blueprint` | Hard gate: no code without an approved design |
 | `forge-plan` | MCP-verified task-by-task implementation plan |
 | `run-plan` | Execute an existing plan |
-| `engineering-discipline` | 8-step Senior SDE framework with 5 Iron Laws |
+| `best-practices` | 8-step Senior SDE framework, 5 Iron Laws, patterns, coupling, review and ops rules |
 | `ship-gate` | No completion claims without fresh verification evidence |
 | `deliver` | Final verification and delivery |
 | `test-first` | No production code without a failing test first |
@@ -279,7 +279,7 @@ Domain-expert lenses `hyper` auto-engages when their triggers match the request
 </details>
 
 <details>
-<summary><strong>🎯 Domain (8)</strong> - specialized skills for specific contexts</summary>
+<summary><strong>🎯 Domain (7)</strong> - specialized skills for specific contexts</summary>
 
 | Skill | Role |
 |---|---|
@@ -288,7 +288,6 @@ Domain-expert lenses `hyper` auto-engages when their triggers match the request
 | `react-pro-coder` | 56 React/Next.js rules with stable IDs - rendering, state placement, audits |
 | `behaviour-analysis` | UI/UX state audits, Nielsen heuristics, interaction matrices |
 | `security-review` | OWASP audits, vulnerability checklists |
-| `design-patterns-skill` | Clean Code + Pragmatic Programmer patterns |
 | `readme-writer` | Evidence-based README generation (this skill) |
 | `python-pro-coder` | 60 FastAPI/Pydantic v2/SQLAlchemy 2.0 rules - layering, schemas, async, dead deps |
 

SKILL.md

@@ -58,7 +58,7 @@ Before writing any code, proposing any fix, or starting any architecture, you MU
 
 1.  **Stop Rationalizing:** Do not skip steps to "be helpful." Thoroughness is the highest form of help. Skipping is laziness, not speed.
 2.  **Verify the Stack:** Consult the relevant MCP plugins below for 100% accurate API syntax. Memory is not acceptable. Pattern-matching is not acceptable. Only MCP output is acceptable.
-3.  **Load the Discipline:** Read `skills/engineering-discipline/SKILL.md` for architectural gates.
+3.  **Load the Discipline:** Read `skills/best-practices/SKILL.md` for architectural gates.
 4.  **Adopt Negative Doubt:** List 5 failure modes for your plan before you type a single line of code.
 
 **The 1% Rule:** If there is even a 1% chance a system rule applies to your task, you MUST read the corresponding file in the `skills/` directory BEFORE acting. You do not have a choice. You cannot rationalize your way out of this.
@@ -77,13 +77,13 @@ Follow this state machine for every non-trivial task. Do not skip phases.
 
 ### Phase 2: Reasoning (The Architecture)
 -   **Actions:** Define invariants, module boundaries, and public APIs.
--   **Skill:** Use `skills/engineering-discipline/SKILL.md`. Reason in order: Responsibilities -> Invariants -> Dependency Direction -> Syntax.
+-   **Skill:** Use `skills/best-practices/SKILL.md`. Reason in order: Responsibilities -> Invariants -> Dependency Direction -> Syntax.
 -   **Visual work:** If the task changes how something looks, feels, moves, or is interacted with, use `skills/designer/SKILL.md` FIRST to produce a DESIGN.md contract before any visual code. The DESIGN.md becomes the input spec for `forge-plan`.
 -   **Constraint:** Never start at syntax. If you do, you are building slop.
 
 ### Phase 3: Execution (The Implementation)
 -   **Actions:** Apply surgical changes. Use real commands from MCP patterns.
--   **Skill:** Use `skills/design-patterns-skill/SKILL.md` to select the correct abstraction (Factory, Strategy, etc.).
+-   **Skill:** Use `skills/best-practices/SKILL.md` to select the correct abstraction (Factory, Strategy, etc.) and to hold the coupling limits.
 -   **Debugging:** If you encounter a failure during implementation, invoke `skills/debug-discipline/SKILL.md` before attempting any fix.
 -   **Rules:** No `rAF`. No redundant comments. No speculative code.
 
@@ -138,10 +138,9 @@ These are static guidelines in the `skills/` directory. Read them using file too
 - **Parallel Dispatch** (`skills/parallel-dispatch/SKILL.md`): Concurrent agent dispatch for independent tasks.
 
 ### Domain Skills (execution guidance)
-- **Engineering Discipline** (`skills/engineering-discipline/SKILL.md`): The Senior SDE phase-gate framework.
+- **Best Practices** (`skills/best-practices/SKILL.md`): The Senior SDE phase-gate framework, Clean Code and GoF patterns, coupling limits, change and review hygiene, architecture-at-scale calls, operations baseline.
 - **Designer** (`skills/designer/SKILL.md`): Intention gate for visual/UX work. Produces DESIGN.md contract before any visual code. Auto-resolves industry/personality/style, routes to cognitive laws, enforces anti-slop rules. Use for: landing pages, dashboards, component libraries, redesigns, any new visual direction.
 - **Behaviour Analysis** (`skills/behaviour-analysis/SKILL.md`): State audits & Nielsen heuristics.
-- **Design Patterns** (`skills/design-patterns-skill/SKILL.md`): Clean Code & Pragmatic patterns.
 - **Security Review** (`skills/security-review/SKILL.md`): OWASP audits & vulnerability checklists.
 - **Readme Writer** (`skills/readme-writer/SKILL.md`): Evidence-based documentation standards.
 

generated/runtime-context/hyperstack.bootstrap.md

@@ -56,7 +56,7 @@ Hyperstack is **ONE framework with four layers** - not four separate systems:
 - `hyperstack:designer`: Before any visual/UX work - produces DESIGN.md contract
 - `hyperstack:forge-plan`: After design approval - MCP-verified implementation plan
 - `hyperstack:run-plan`: Have an existing plan - validate then execute
-- `hyperstack:engineering-discipline`: During execution - Senior SDE phase gates
+- `hyperstack:best-practices`: During execution - Senior SDE phase gates
 - `hyperstack:ship-gate`: Before any completion claim - evidence required
 - `hyperstack:deliver`: After all tasks complete - final verification and delivery
 - `hyperstack:autonomous-mode`: Full autonomous execution - runs end-to-end, only stops on failure
@@ -68,7 +68,7 @@ Hyperstack is **ONE framework with four layers** - not four separate systems:
 - `hyperstack:designer`: Before any visual/UX work - produces DESIGN.md
 - `hyperstack:debug-discipline`: Any bug or unexpected behaviour - root cause first
 - `hyperstack:behaviour-analysis`: UI/UX audits, state machine correctness
-- `hyperstack:design-patterns-skill`: Selecting the right abstraction or design pattern
+- `hyperstack:best-practices`: Selecting the right abstraction or design pattern, coupling limits, review and ops rules
 - `hyperstack:security-review`: OWASP audits, API and infrastructure security
 - `hyperstack:readme-writer`: Evidence-based documentation
 - `hyperstack:codemode`: Understanding an unfamiliar codebase before reviewing or changing it - 7-phase context load

install.md

@@ -19,7 +19,7 @@ Three tightly-coupled pieces, installed together:
 
 1. **An internal harness** - bootstrap, internal role routing, and workflow control. Current internal roles include `main` and `website-builder`.
 2. **An MCP server** with 12 plugins and 80 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline.
-3. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `engineering-discipline`) and a SessionStart hook that face-injects the `hyperstack` skill at every session start.
+3. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `best-practices`) and a SessionStart hook that face-injects the `hyperstack` skill at every session start.
 
 The install steps below wire the public pieces the user actually needs: the MCP
 server and the skills. The internal harness is shipped inside the repository and

skills/INDEX.md

@@ -15,12 +15,12 @@ Categories:
 | Skill | Description |
 |---|---|
 | `autonomous-mode` | Use when the user chooses fully autonomous execution. Aggressively uses the entire Hyperstack to implement the solution  |
+| `best-practices` | The language-agnostic engineering rulebook - Clean Code and Gang of Four patterns, SOLID, architectural reasoning, coupl |
 | `blueprint` | Use before any feature build, component creation, or behaviour modification. MCP-surveyed design with a hard gate before |
 | `code-review` | Use when completing tasks, implementing features, or before merging - to dispatch a review subagent and handle feedback  |
 | `codemode` | Deep context-loading protocol. Use when you must understand an unfamiliar codebase before answering, reviewing, or chang |
 | `debug-discipline` | Use when encountering any bug, test failure, or unexpected behaviour. Root cause investigation is mandatory before any f |
 | `deliver` | Use after all implementation tasks are complete. Runs final verification, confirms the branch is clean, detects the work |
-| `engineering-discipline` | Apply senior-level software engineering discipline including design patterns, SOLID principles, architectural reasoning, |
 | `forge-plan` | Use after blueprint design approval to produce a task-by-task implementation plan grounded in MCP-verified API calls. No |
 | `lab` | Use when designing or revamping a frontend section or whole page and you want to explore real-React variants in an isola |
 | `optimizer` | Teaches runtime analysis - deriving Big-O straight from code - and how to derive a better algorithm by removing redundan |
@@ -38,7 +38,6 @@ Categories:
 |---|---|
 | `behaviour-analysis` | Systematic UI/UX behaviour analysis for interactive applications. Audits every user action, state transition, view mode, |
 | `bro` | The generalist persona engine - "bro", "bro mode", or any end-to-end task spanning ui-ux, design, coding, marketing, sal |
-| `design-patterns-skill` | Apply core programming principles and design patterns from Clean Code, The Pragmatic Programmer, Code Complete, Refactor |
 | `designer` |  |
 | `marketing` | Use to do product marketing for any brand - position it, find the message, write the copy ("marketing words"), set brand |
 | `python-pro-coder` | Staff-level Python API engineering discipline for FastAPI + Pydantic v2 + SQLAlchemy 2.0 - 60 enforced rules across proj |

skills/engineering-discipline/SKILL.md → skills/best-practices/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: engineering-discipline
+name: best-practices
 category: core
-description: Apply senior-level software engineering discipline including design patterns, SOLID principles, architectural reasoning, systematic verification, and safety gates. Use when writing production code, complex features, reviewing code, refactoring systems, or when engineering rigor and correctness are required. Supports both quick reference lookup and full step-by-step process mode.
+description: The language-agnostic engineering rulebook - Clean Code and Gang of Four patterns, SOLID, architectural reasoning, coupling and abstraction limits, change and review hygiene, architecture-at-scale decisions, an operations baseline, systematic verification, and safety gates. Use when writing production code, choosing an abstraction or design pattern, reviewing code, refactoring systems, deciding where a boundary goes, or when engineering rigor and correctness are required. Supports both quick reference lookup and full step-by-step process mode.
 triggers:
   - "build production code"
   - "design architecture"
@@ -13,6 +13,10 @@ triggers:
   - "safety gates"
   - "design pattern"
   - "SOLID principles"
+  - "clean code"
+  - "code quality"
+  - "best practices"
+  - "coding standards"
 activation:
   mode: fuzzy
   priority: normal
@@ -27,24 +31,36 @@ activation:
     - "safety gates"
     - "design pattern"
     - "SOLID principles"
+    - "clean code"
+    - "code quality"
+    - "best practices"
+    - "coding standards"
 compatibility: ">=2.0.0"
 metadata:
-  version: "2.0.0"
+  version: "3.0.0"
+  supersedes: ["engineering-discipline", "design-patterns-skill"]
 references:
   - references/patterns/readability.md
   - references/patterns/simplicity.md
   - references/patterns/design-architecture.md
   - references/patterns/testing.md
   - references/patterns/error-handling.md
   - references/patterns/maintainability.md
+  - references/practices/coupling-and-abstraction.md
+  - references/practices/change-hygiene.md
+  - references/practices/architecture-scale.md
+  - references/practices/operations-baseline.md
   - references/architecture/task-classification.md
   - references/architecture/architecture-reasoning.md
   - references/architecture/verification-gates.md
   - references/architecture/negative-doubt.md
   - references/architecture/output-format.md
 ---
 
-# Engineering Discipline - Senior SDE-3 Framework
+# Best Practices - Senior SDE-3 Engineering Rulebook
+
+Absorbs the former `engineering-discipline` and `design-patterns-skill`. One source for how code is
+written, reviewed, and shipped in a Hyperstack-governed repository.
 
 ## Two Modes
 
@@ -92,12 +108,18 @@ These connect outward, they are not an island: Laws 1, 2, and 5 are the same fam
 
 ### Patterns & Principles
 - Readability & Clarity → `references/patterns/readability.md`
-- Simplicity & Efficiency → `references/patterns/simplicity.md`
-- Design & Architecture → `references/patterns/design-architecture.md`
+- Simplicity & Efficiency (KISS, DRY, YAGNI) → `references/patterns/simplicity.md`
+- Design & Architecture (SRP, composition, GoF patterns) → `references/patterns/design-architecture.md`
 - Testing & Quality → `references/patterns/testing.md`
 - Error Handling → `references/patterns/error-handling.md`
 - Maintainability → `references/patterns/maintainability.md`
 
+### Practices
+- Coupling & Abstraction (Demeter, CQS, flag args, rule of three, leaky abstractions) → `references/practices/coupling-and-abstraction.md`
+- Change Hygiene (commits, branches, PR size, review conduct, tracked debt) → `references/practices/change-hygiene.md`
+- Architecture at Scale (modular monolith, dependency direction, 12 factors, ADRs) → `references/practices/architecture-scale.md`
+- Operations Baseline (structured logs, metrics, health, degradation, N+1) → `references/practices/operations-baseline.md`
+
 ### Architecture & Process
 - Task Classification → `references/architecture/task-classification.md`
 - Architecture Reasoning → `references/architecture/architecture-reasoning.md`
@@ -114,7 +136,7 @@ Verify runtime, package manager, dependencies. Do NOT proceed without valid envi
 Classify as exactly one: New feature | Refactor (behavior preserved) | Bug fix | Review/audit | Documentation only.
 Unclear → STOP and request clarification.
 
-**Visual/UX gate:** Task changes how something looks, feels, moves, or is interacted with → STOP, invoke `hyperstack:designer` first. Designer → DESIGN.md → input to `hyperstack:forge-plan`. Return to engineering-discipline only during execution of forge-plan tasks.
+**Visual/UX gate:** Task changes how something looks, feels, moves, or is interacted with → STOP, invoke `hyperstack:designer` first. Designer → DESIGN.md → input to `hyperstack:forge-plan`. Return to best-practices only during execution of forge-plan tasks.
 
 ### Step 2: Load Engineering Constraints 📋
 Hard rules: clear naming, single responsibility, explicit module boundaries, no circular dependencies, folder structure reflects architecture, tests before refactor, YAGNI, patterns only when forces are named.
@@ -161,6 +183,40 @@ Critical issue unaddressed → HARD STOP.
 | Error handling unclear | `references/patterns/error-handling.md` |
 | Architecture decisions | `references/architecture/architecture-reasoning.md` |
 | Standard response format | `references/architecture/output-format.md` |
+| Boundary, coupling, or "should this be abstracted" | `references/practices/coupling-and-abstraction.md` |
+| Commits, PR size, how to give review feedback | `references/practices/change-hygiene.md` |
+| Monolith vs services, dependency direction, ADR | `references/practices/architecture-scale.md` |
+| Logging, health checks, timeouts, degradation | `references/practices/operations-baseline.md` |
+
+## Pattern Selection Quick Reference
+
+| Situation | Apply |
+|-----------|-------|
+| Function > 20 lines | Split into smaller functions (SRP) |
+| Repeated code blocks, third occurrence | Extract to function or constant (DRY, rule of three) |
+| Complex conditionals | Strategy or State pattern |
+| Object creation logic | Factory pattern |
+| Cross-cutting concerns | Decorator or Observer pattern |
+| Incompatible interfaces | Adapter pattern |
+| Need undo or an audit log | Command pattern |
+| Global access point | Singleton, sparingly, and name the force |
+| Chained calls through another object's internals | Move the behavior (Law of Demeter) |
+| A boolean parameter selecting behavior | Two functions, no flag argument |
+
+Every row is subject to the Pattern Gate in Step 5. A row matching is not a reason; the named force is.
+
+## AI-Specific Guidance
+
+When generating or reviewing code, the failure modes are predictable:
+
+| Bias | Counter |
+|---|---|
+| Pattern prediction: reaching for the pattern that appears most in training data | Name the force first, then pick. No force, no pattern |
+| Generic naming: `data`, `temp`, `result`, `handler` | Name the concept, not the container |
+| Skipping edge cases because the happy path compiles | Null, empty, zero, max, negative, unicode, concurrent |
+| Combining unrelated operations into one function | One reason to change per unit |
+| Importing a convention from another project | Match the conventions already in this repository |
+| Over-commenting generated code | A comment explains a non-obvious why, never the what |
 
 ## Red Flags - STOP
 
@@ -197,7 +253,7 @@ Something cannot be done safely → say so and explain why.
 
 **Manual execution with phase gates:**
 ```
-forge-plan → engineering-discipline (THIS) → ship-gate → deliver
+forge-plan → best-practices (THIS) → ship-gate → deliver
                       ↓
          [8-step framework per task]
                       ↓
@@ -221,3 +277,24 @@ forge-plan → engineering-discipline (THIS) → ship-gate → deliver
 | Discovery | Escalate to | Action |
 |---|---|---|
 | Task changes look/feel/motion/interaction | `designer` | STOP, get DESIGN.md, return to forge-plan |
+
+### Owned Elsewhere - Route, Do Not Restate
+
+| Concern | Skill |
+|---|---|
+| Vulnerability hunting, OWASP mapping | `security-review` |
+| Complexity analysis, algorithmic wins | `optimizer` |
+| Dispatching a reviewer and handling feedback | `code-review` (this skill supplies the review conduct rules it applies) |
+| React and Next.js specifics | `react-pro-coder` |
+| FastAPI, Pydantic, SQLAlchemy specifics | `python-pro-coder` |
+| Visual and interaction design | `designer`, `ui-ux`, `design-tokens` |
+
+## Sources
+
+- *Clean Code* - Robert C. Martin
+- *A Philosophy of Software Design* - John Ousterhout
+- *The Pragmatic Programmer* - Hunt and Thomas
+- *Code Complete* - Steve McConnell
+- *Refactoring* - Martin Fowler
+- *Design Patterns* - Gang of Four
+- *The Twelve-Factor App* - 12factor.net