0 Fork 0

Files

T

ZacharyZhang-NY e74dafcd36 Silence render-disposed spam, unbreak bundled skills, drop board wake

Three independently ugly bugs that all fed the same log flood:

* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
  to stderr via `console.error`. When the worker fans a second
  agent-event past a reloading renderer, we produced thousands of
  identical lines and stalled the main loop on stderr I/O. Added a
  `mainFrame.detached` guard so the send is short-circuited before
  Electron's own catch block fires, and installed a targeted filter in
  `suppress-warnings.ts` (now actually imported from the entry point)
  so the specific `console.error("Error sending from webFrameMain:"…)`
  noise never reaches the terminal. Any other payload still surfaces.

* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
  target when an agent replied to `__board__` — `wakeAgentIfPossible`
  then called `db.getAgent("__board__")`, threw, and the dispatcher
  kept repeating on every send. Strip `HUMAN_SENDER_ID` at
  `resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
  heartbeat so a stray caller (future automation fan-out) cannot
  reintroduce the crash.

* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
  diverges from its parent directory. The four bundled `my-writing-style`
  copies declared `name: writing-style-skill`, so every install emitted
  a warning and dropped the skill. They also lived as orphan gitlinks
  (mode 160000 without .gitmodules), and the global `*.md` gitignore
  hid every other SKILL.md from version control. Fixed the frontmatter
  to match the dir, converted the dangling submodules to plain trees,
  and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
  catalogue instead of silently losing it.

2026-04-20 08:13:48 -04:00

7.2 KiB

Raw Blame History

name, description

name	description
clean-architecture	Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.

Clean Architecture Best Practices

Comprehensive guide to Clean Architecture principles for designing maintainable, testable software systems. Based on Robert C. Martin's "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Contains 42 rules across 8 categories, prioritized by architectural impact.

When to Apply

Reference these guidelines when:

Designing new software systems or modules
Structuring dependencies between layers
Defining boundaries between business logic and infrastructure
Reviewing code for architectural violations
Refactoring coupled systems toward cleaner structure

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Dependency Direction	CRITICAL	`dep-`
2	Entity Design	CRITICAL	`entity-`
3	Use Case Isolation	HIGH	`usecase-`
4	Component Cohesion	HIGH	`comp-`
5	Boundary Definition	MEDIUM-HIGH	`bound-`
6	Interface Adapters	MEDIUM	`adapt-`
7	Framework Isolation	MEDIUM	`frame-`
8	Testing Architecture	LOW-MEDIUM	`test-`

Quick Reference

1. Dependency Direction (CRITICAL)

dep-inward-only - Source dependencies point inward only
dep-interface-ownership - Interfaces belong to clients not implementers
dep-no-framework-imports - Avoid framework imports in inner layers
dep-data-crossing-boundaries - Use simple data structures across boundaries
dep-acyclic-dependencies - Eliminate cyclic dependencies between components
dep-stable-abstractions - Depend on stable abstractions not volatile concretions

2. Entity Design (CRITICAL)

entity-pure-business-rules - Entities contain only enterprise business rules
entity-no-persistence-awareness - Entities must not know how they are persisted
entity-encapsulate-invariants - Encapsulate business invariants within entities
entity-value-objects - Use value objects for domain concepts
entity-rich-not-anemic - Build rich domain models not anemic data structures

3. Use Case Isolation (HIGH)

usecase-single-responsibility - Each use case has one reason to change
usecase-input-output-ports - Define input and output ports for use cases
usecase-orchestrates-not-implements - Use cases orchestrate entities not implement business rules
usecase-no-presentation-logic - Use cases must not contain presentation logic
usecase-explicit-dependencies - Declare all dependencies explicitly in constructor
usecase-transaction-boundary - Use case defines the transaction boundary

4. Component Cohesion (HIGH)

comp-screaming-architecture - Structure should scream the domain not the framework
comp-common-closure - Group classes that change together
comp-common-reuse - Avoid forcing clients to depend on unused code
comp-reuse-release-equivalence - Release components as cohesive units
comp-stable-dependencies - Depend in the direction of stability

5. Boundary Definition (MEDIUM-HIGH)

bound-humble-object - Use humble objects at architectural boundaries
bound-partial-boundaries - Use partial boundaries when full separation is premature
bound-boundary-cost-awareness - Weigh boundary cost against ignorance cost
bound-main-component - Treat main as a plugin to the application
bound-defer-decisions - Defer framework and database decisions
bound-service-internal-architecture - Services must have internal clean architecture

6. Interface Adapters (MEDIUM)

adapt-controller-thin - Keep controllers thin
adapt-presenter-formats - Presenters format data for the view
adapt-gateway-abstraction - Gateways hide external system details
adapt-mapper-translation - Use mappers to translate between layers
adapt-anti-corruption-layer - Build anti-corruption layers for external systems

7. Framework Isolation (MEDIUM)

frame-domain-purity - Domain layer has zero framework dependencies
frame-orm-in-infrastructure - Keep ORM usage in infrastructure layer
frame-web-in-infrastructure - Web framework concerns stay in interface layer
frame-di-container-edge - Dependency injection containers live at the edge
frame-logging-abstraction - Abstract logging behind domain interfaces

8. Testing Architecture (LOW-MEDIUM)

test-tests-are-architecture - Tests are part of the system architecture
test-testable-design - Design for testability from the start
test-layer-isolation - Test each layer in isolation
test-boundary-verification - Verify architectural boundaries with tests

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

7.2 KiB Raw Blame History