@yaawn/workflow 0.0.0-stage → 0.4.0

package/agents/skills/yaawn-clean-code/references/meaningful-names.md

@@ -0,0 +1,234 @@
+# Meaningful Names
+
+Rules for creating good names in code. Names are everywhere — variables, functions, arguments, classes, files, directories. Good names make code self-documenting.
+
+> Source: Robert C. Martin, _Clean Code_ — Chapter 2: Meaningful Names
+
+## Rules
+
+### Use intention-revealing names
+
+The name should tell you **why it exists**, **what it does**, and **how it is used**. If a name requires a comment, it does not reveal its intent.
+
+```typescript
+// Bad
+const d: number; // elapsed time in days
+
+// Good
+const elapsedTimeInDays: number;
+```
+
+```typescript
+// Bad
+const theList: User[];
+
+// Good
+const users: User[];
+```
+
+### Avoid disinformation
+
+Do not leave false clues that obscure meaning. Avoid words whose established meanings differ from your intended meaning.
+
+```typescript
+// Bad — "List" implies a specific data structure
+const accountList: Account[]; // is it really a List?
+
+// Good
+const accounts: Account[];
+```
+
+### Avoid similar shapes
+
+Names that look almost identical force readers to slow down and compare character-by-character.
+
+```typescript
+// Bad
+class ControllerForEfficientHandlingOfStrings {}
+class ControllerForEfficientStorageOfStrings {}
+```
+
+### Make meaningful distinctions
+
+If names must be different, they should mean something different.
+
+```typescript
+// Bad — what's the difference?
+interface Product {}
+interface ProductInfo {}
+interface ProductData {}
+
+// Good — names convey different purposes
+interface Product {}
+interface ProductSummary {}
+interface ProductDetails {}
+```
+
+### Use pronounceable names
+
+If you can't pronounce it, you can't discuss it without sounding like an idiot.
+
+```typescript
+// Bad
+interface CstmrRcrd {}
+
+// Good
+interface CustomerRecord {}
+```
+
+### Use searchable names
+
+Single-letter names and numeric constants are hard to locate across a codebase. The length of a name should correspond to the size of its scope.
+
+```typescript
+// Bad
+for (let j = 0; j < 34; j++) {
+  s += (t[j] * 4) / 5;
+}
+
+// Good
+const realDaysPerIdealDay = 4;
+const workDaysPerWeek = 5;
+const numberOfTasks = 34;
+
+for (let j = 0; j < numberOfTasks; j++) {
+  const realTaskDays = taskEstimates[j] * realDaysPerIdealDay;
+  const realTaskWeeks = realTaskDays / workDaysPerWeek;
+  sum += realTaskWeeks;
+}
+```
+
+### Avoid encodings and member prefixes
+
+Don't prefix member variables with `m_`, `_`, or Hungarian notation. Classes and functions should be small enough that prefixes are unnecessary.
+
+```typescript
+// Bad
+class Part {
+  private m_dsc: string; // The textual description
+}
+
+// Good
+class Part {
+  private description: string;
+}
+```
+
+> **Note (project convention):** This codebase uses **camelCase** for all variables and constants — never snake_case or UPPER_SNAKE_CASE. See `AGENTS.md` for details.
+
+### Don't prefix interfaces with "I"
+
+Let the user work with the interface without knowing it's an interface. If you must encode, encode the implementation.
+
+```typescript
+// Bad
+interface IShapeFactory {}
+
+// Good
+interface ShapeFactory {}
+class ShapeFactoryImpl implements ShapeFactory {}
+```
+
+### Avoid mental mapping
+
+Readers shouldn't have to mentally translate your names. Single-letter names are only acceptable for tiny loop counters (`i`, `j`, `k`).
+
+```typescript
+// Bad
+const l = getStudents();
+for (const i of l) {
+  i.doSomething();
+}
+
+// Good
+const students = getStudents();
+for (const student of students) {
+  student.doSomething();
+}
+```
+
+### Class names should be nouns
+
+Classes and objects should have noun or noun phrase names. Avoid vague names like `Manager`, `Processor`, `Data`, `Info`, `Helper`, `Common`, `Utilities`.
+
+```typescript
+// Bad — too vague, does more than one thing
+class CommonUtils {}
+
+// Good — specific purpose
+class JsonUtils {}
+class StringUtils {}
+```
+
+### Method names should be verbs
+
+Methods should have verb or verb phrase names. Accessors, mutators, and predicates should be prefixed with `get`, `set`, and `is`/`has`.
+
+```typescript
+// Good
+postPayment();
+deletePage();
+save();
+isActive();
+hasPermission();
+```
+
+### Adjust name length to scope size
+
+Short names for small scopes, longer descriptive names for larger scopes.
+
+```typescript
+// Bad — acronym unclear outside this context
+const wd = 5;
+
+// Good
+const workDaysPerWeek = 5;
+```
+
+### Don't use the same name for different purposes
+
+The word `add` could mean concatenate strings, insert a record, or append to an array. Be specific.
+
+```typescript
+// Bad
+function add(value: string): void; // which kind of "add"?
+
+// Good
+function concatenate(value: string): string;
+function insert(value: string): void;
+function append(value: string): void;
+```
+
+### Add meaningful context, but don't add gratuitous context
+
+Use context to disambiguate names, but don't add more context than is necessary.
+
+```typescript
+// Bad — what does "state" mean?
+let state: string;
+
+// Good — context disambiguates
+let addressState: string;
+```
+
+```typescript
+// Bad — package already provides context
+// in module: obnk
+class ObnkConsentEntity {}
+
+// Good
+class ConsentEntity {}
+```
+
+### Use solution domain names
+
+Use CS terms, algorithm names, pattern names freely — your readers are programmers.
+
+```typescript
+// Good — recognizable to developers familiar with the Visitor pattern
+class AccountVisitor {}
+```
+
+### Use problem domain names
+
+When there is no CS term, use names from the problem domain so domain experts can verify the code.

package/agents/skills/yaawn-clean-code/references/objects-and-data-structures.md

@@ -0,0 +1,130 @@
+# Objects and Data Structures
+
+> Source: Robert C. Martin, _Clean Code_ — Chapter 6: Objects and Data Structures
+
+## Rules
+
+### Data abstraction
+
+Don't expose the details of your data. Express data in abstract terms. Hiding implementation is about **abstractions**, not just putting a layer of getters/setters between the variables.
+
+```typescript
+// Bad — exposes raw data
+class Point {
+  x: number;
+  y: number;
+}
+
+// Good — abstracts the implementation
+class Point {
+  private x: number;
+  private y: number;
+
+  getX(): number {
+    return this.x;
+  }
+  getY(): number {
+    return this.y;
+  }
+
+  setCartesian(x: number, y: number): void {
+    this.x = x;
+    this.y = y;
+  }
+}
+```
+
+In TypeScript, prefer **interfaces** and **readonly** properties for data that doesn't need encapsulation. Use classes with private state only when behavior is attached.
+
+### Data/Object anti-symmetry
+
+This is a fundamental trade-off:
+
+|                                                | Adding new functions                 | Adding new data types                       |
+| ---------------------------------------------- | ------------------------------------ | ------------------------------------------- |
+| **Data structures** (expose data, no behavior) | Easy — add function, no data changes | Hard — all functions must change            |
+| **Objects** (hide data, expose behavior)       | Hard — all classes must change       | Easy — add new class implementing interface |
+
+Choose based on what's more likely to change:
+
+- **Expect new data types?** Use objects/interfaces (polymorphism)
+- **Expect new functions?** Use data structures
+
+### Avoid hybrids
+
+Hybrid structures that are half object and half data structure have the **worst of both worlds** — hard to add new functions AND hard to add new data types.
+
+```typescript
+// Bad — hybrid: has both behavior and instanceof checks
+abstract class Shape {
+  draw(): void {
+    if (this instanceof Square) {
+      /* ... */
+    } else if (this instanceof Rectangle) {
+      /* ... */
+    }
+  }
+}
+
+// Good — pure object with polymorphism
+interface Shape {
+  draw(): void;
+}
+
+class Square implements Shape {
+  draw(): void {
+    /* square-specific drawing */
+  }
+}
+
+class Rectangle implements Shape {
+  draw(): void {
+    /* rectangle-specific drawing */
+  }
+}
+```
+
+### The Law of Demeter
+
+A method should only call methods on:
+
+1. Its own object (`this`)
+2. Objects passed as parameters
+3. Objects it creates
+4. Its direct component objects
+
+**Don't chain calls through collaborators** (train wrecks):
+
+```typescript
+// Bad — reaches deep into collaborator structure
+const outputDir = context.getOptions().getScratchDir().getAbsolutePath();
+
+// Good — ask, don't reach
+const outputDir = context.getOutputDirectory();
+```
+
+### Data Transfer Objects (DTOs)
+
+A DTO is a class with public data and no behavior — used for transferring data between layers or processes.
+
+Use DTOs to separate the data that crosses boundaries from your internal domain model.
+
+```typescript
+// Bad — using the domain entity directly as input
+function createUser(firstName: string, lastName: string, email: string, birthday: Date, role: Role): void {}
+
+// Good — DTO wraps the input data
+interface CreateUserDto {
+  firstName: string;
+  lastName: string;
+  email: string;
+  birthday: Date;
+  role: Role;
+}
+
+function createUser(dto: CreateUserDto): void {
+  const user = mapToUser(dto);
+  user.createdAt = new Date();
+  userRepository.save(user);
+}
+```

package/agents/skills/yaawn-clean-code/references/principles.md

@@ -0,0 +1,76 @@
+# Principles
+
+Core software design principles referenced throughout Clean Code.
+
+> Source: Robert C. Martin, _Clean Code_ + [gpcoder gitbook bonus chapters](https://gpcoder.gitbook.io/clean-code/bonus)
+
+## SOLID
+
+### SRP — Single Responsibility Principle
+
+A class should have **one, and only one, reason to change**. If you can think of more than one motive for changing a class, it has more than one responsibility.
+
+### OCP — Open-Closed Principle
+
+Software entities should be **open for extension** but **closed for modification**. Add new behavior by adding new code, not changing existing code. Use interfaces, abstract classes, and polymorphism.
+
+### LSP — Liskov Substitution Principle
+
+Objects of a superclass should be replaceable with objects of its subclasses **without breaking** the application. Subclasses must honor the contract of their parent.
+
+### ISP — Interface Segregation Principle
+
+No client should be forced to depend on methods it does not use. Prefer **many small, specific interfaces** over one large general-purpose interface.
+
+### DIP — Dependency Inversion Principle
+
+High-level modules should not depend on low-level modules. Both should depend on **abstractions**. Abstractions should not depend on details — details should depend on abstractions.
+
+Use dependency injection to provide implementations of abstract services.
+
+---
+
+## KISS — Keep It Simple Stupid
+
+Simplicity should be a key goal in design. Unnecessary complexity should be avoided. Ask: "Can this be written in a simpler way?"
+
+## DRY — Don't Repeat Yourself
+
+Each piece of knowledge must have a **single, unambiguous, authoritative representation** in a system. When DRY is applied successfully, changing one thing doesn't require changes in unrelated places.
+
+## YAGNI — You Aren't Gonna Need It
+
+Don't add functionality unless it's **actually needed now**. Never implement things when you just foresee that you might need them.
+
+## Boy Scout Rule
+
+> Always leave the code better than you found it.
+
+If you touch a file, leave it a little cleaner than you found it — better names, removed dead code, simplified logic. Over time, the codebase improves.
+
+## Don't Reinvent the Wheel
+
+Check if a well-tested library or framework already solves the problem before writing a custom solution.
+
+## Design Patterns
+
+Use established design patterns (Strategy, Observer, Factory, Decorator, etc.) when they simplify the design. Don't force patterns where they don't fit.
+
+## Coding Conventions
+
+Follow the team's established conventions consistently. Inconsistent style makes code appear to be written by disagreeing individuals and increases cognitive load.
+
+> **Project convention:** This codebase follows the conventions defined in `AGENTS.md`, `.editorconfig`, and `eslint.config.mjs`.
+
+## Fail Fast
+
+Detect and report problems as early as possible. Validate inputs at system boundaries. A clear, immediate failure is better than a silent, delayed corruption.
+
+## Law of Demeter (LoD)
+
+A method should only talk to its immediate friends — not to strangers reached through a chain of calls. See [objects-and-data-structures.md](./objects-and-data-structures.md) for details.
+
+## Coupling and Cohesion
+
+- **Low coupling**: Modules should have minimal dependencies on each other. Changes in one module shouldn't require changes in others.
+- **High cohesion**: A module's internal elements should be strongly related. If a class has methods that don't use the same instance variables, it may need to be split.

package/agents/skills/yaawn-clean-code/references/simple-design-and-code-smells.md

@@ -0,0 +1,130 @@
+# Simple Design Rules and Code Smells
+
+> Source: Robert C. Martin, _Clean Code_ — Chapters 12 (Emergent Design) and 17 (Smells and Heuristics)
+
+## Four Rules of Simple Design
+
+A design is "simple" if it follows these rules in priority order:
+
+### Rule 1: Runs all the tests
+
+A system that cannot be verified should never be deployed. Writing tests drives better design:
+
+- Classes conform to SRP (easier to test)
+- Tight coupling is eliminated (hard to test → fix the design)
+- Tests enable safe refactoring
+
+### Rule 2: No duplication
+
+Duplication is the primary enemy of a well-designed system. It represents additional work, risk, and complexity. Forms of duplication:
+
+- Lines of code that look exactly the same
+- Lines of code that are similar (same structure, different details)
+- Duplication of implementation (same concept expressed differently)
+
+Use the DRY principle, Template Method pattern, or Strategy pattern to eliminate duplication.
+
+### Rule 3: Ensure expressiveness
+
+Code should clearly express the intent of its author. Spend time choosing better names, splitting large functions, and using patterns. Well-written tests also serve as documentation.
+
+> The most important way to be expressive is to **try**. Don't just get code working and move on — make it easy for the next reader.
+
+### Rule 4: Minimal classes and methods
+
+Keep function and class counts low. But this is the **lowest priority** rule — don't sacrifice tests, duplication removal, or expressiveness to minimize count.
+
+---
+
+## Code Smells
+
+Indicators that something may be wrong in the code:
+
+| Smell                   | Description                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| **Rigidity**            | Software is difficult to change; a small change causes a cascade of subsequent changes |
+| **Fragility**           | Software breaks in many places due to a single change                                  |
+| **Immobility**          | Cannot reuse parts of the code in other contexts                                       |
+| **Needless complexity** | Over-engineering, speculative generality                                               |
+| **Needless repetition** | Two code fragments look almost identical                                               |
+| **Opacity**             | Code is hard to understand                                                             |
+
+### Comment smells
+
+- Inappropriate information (author, dates — belongs in source control)
+- Obsolete comments
+- Redundant comments
+- Poorly written comments
+- Commented-out code
+
+### Function smells
+
+- **Long function**: More than ~15 lines — start asking questions
+- **Too many arguments**: More than 3 parameters
+- **Output arguments**: Readers expect arguments to be inputs
+- **Flag arguments**: Boolean that selects behavior → split the function
+- **Selector arguments**: Any type used to switch behavior (enum, int, etc.)
+- **Dead function**: Methods that are never called — delete them
+- **Feature envy**: A method that accesses another object's data more than its own
+
+### Class smells
+
+- **Large class**: Too many fields, methods, or lines
+- **God class**: Concentrates too many responsibilities
+- **Alternative classes with different interfaces**: Duplicate functionality, different API
+- **Refused bequest**: Subclass doesn't use inherited methods → hierarchy is wrong
+- **Change preventers**: Changing one class requires changes in many unrelated classes
+- **Speculative generality**: Code created "just in case" for features never implemented
+- **Dead code**: Variables, parameters, methods, or classes no longer used
+
+### General smells
+
+- **Multiple languages in one source file**
+- **Obvious behavior not implemented** (Principle of Least Surprise)
+- **Incorrect behavior at boundaries** — test every boundary condition
+- **Duplication** — the DRY violation, in all its forms
+- **Code at wrong abstraction level** — don't mix high-level and low-level concepts
+- **Base classes depending on derivatives**
+- **Too much information** — keep interfaces tight and small
+- **Dead code** — code that isn't executed
+- **Vertical separation** — define variables and functions near where they are used
+- **Inconsistency** — if you do something one way, do all similar things the same way
+- **Clutter** — unused variables, uncalled functions, uninformative comments
+- **Artificial coupling** — a variable/function placed in a convenient but wrong location
+- **Feature envy** — a method uses another class's data more than its own
+- **Inappropriate static** — prefer instance methods that can be polymorphic
+- **Use explanatory variables** — break complex expressions into named intermediates
+- **Function names should say what they do**
+- **Understand the algorithm** — don't just make it pass tests, understand **why** it works
+- **Prefer polymorphism to if/else or switch/case**
+- **Follow standard conventions**
+- **Replace magic numbers with named constants**
+- **Be precise** — make decisions deliberately, handle exceptions
+- **Structure over convention** — enforce design with types, not naming rules
+- **Encapsulate conditionals** — extract boolean expressions into named functions
+- **Avoid negative conditionals**
+- **Functions should do one thing**
+- **Hidden temporal couplings** — make call ordering explicit through function signatures
+- **Encapsulate boundary conditions** — handle edge cases in one place
+- **Functions should descend one level of abstraction**
+- **Keep configurable data at high levels** — don't bury config in low-level functions
+- **Avoid transitive navigation** — Law of Demeter: don't reach through collaborators
+
+### Name smells
+
+- Choose descriptive names at the appropriate abstraction level
+- Use standard nomenclature (e.g., `Decorator`, `Factory`, `Observer`)
+- Use unambiguous names
+- Use long names for long scopes
+- Avoid encodings (Hungarian notation, prefixes)
+- Names should describe side effects
+
+### Test smells
+
+- **Insufficient tests** — test everything that could break
+- **Don't skip trivial tests** — their documentary value exceeds their cost
+- **Ignored tests are questions about ambiguity**
+- **Test boundary conditions**
+- **Exhaustively test near bugs** — bugs congregate
+- **Patterns of failure are revealing** — complete, well-ordered tests expose patterns
+- **Tests should be fast**

package/agents/skills/yaawn-clean-code/references/unit-tests.md

@@ -0,0 +1,114 @@
+# Unit Tests
+
+Test code should be maintained to the same standards of quality as production code.
+
+> Source: Robert C. Martin, _Clean Code_ — Chapter 9: Unit Tests
+
+## Rules
+
+### Keep tests clean
+
+Dirty tests are worse than no tests. If tests are hard to maintain, developers stop maintaining them. When tests rot, production code rots with it.
+
+### Focus on readability
+
+Readability is **even more important** in tests than in production code. Say a lot with as few expressions as possible. Extract helpers for setup, execution, and verification.
+
+```typescript
+// Bad — setup, execution, and assertion all mixed together
+it('should save a user', () => {
+  const jsonFile = 'path/to/file/user-dto.json';
+  const dto = JSON.parse(readFileSync(jsonFile, 'utf-8'));
+  const actual = userRepository.save(dto);
+  const expectedFile = 'path/to/file/user.json';
+  const expected = JSON.parse(readFileSync(expectedFile, 'utf-8'));
+  expect(actual).not.toBeNull();
+  expect(actual.id).not.toBeNull();
+  expect(actual.email).toBe(expected.email);
+});
+
+// Good — clear AAA structure with helpers
+it('should save user successfully', () => {
+  // Arrange
+  const dto = createUserDto();
+
+  // Act
+  const actual = userRepository.save(dto);
+
+  // Assert
+  const expected = createExpectedUser();
+  verifySavedUser(expected, actual);
+});
+```
+
+### One assert per test
+
+Each test should verify **one specific behavior**. Multiple asserts testing different behaviors in one test hide failures and make diagnosis harder.
+
+### Use a single concept per test
+
+Don't combine multiple scenarios in one test function. Split boundary conditions, happy paths, and error cases into separate tests.
+
+```typescript
+// Bad — tests both in-range and out-of-range in one test
+it('should check range', () => {
+  expect(isInRange(9)).toBe(false);
+  expect(isInRange(10)).toBe(true);
+  expect(isInRange(100)).toBe(true);
+  expect(isInRange(101)).toBe(false);
+});
+
+// Good — separate tests per concept
+it('should return true for values in range', () => {
+  expect(isInRange(10)).toBe(true);
+  expect(isInRange(50)).toBe(true);
+  expect(isInRange(100)).toBe(true);
+});
+
+it('should return false for values out of range', () => {
+  expect(isInRange(9)).toBe(false);
+  expect(isInRange(101)).toBe(false);
+});
+```
+
+### Use the given-when-then / AAA convention
+
+Structure every test with three phases:
+
+1. **Arrange** (Given): Set up the test data and preconditions
+2. **Act** (When): Execute the behavior under test
+3. **Assert** (Then): Verify the expected outcome
+
+Use descriptive test names that communicate the scenario:
+
+```typescript
+// Good naming patterns
+it('should return empty array when no users exist', () => {});
+it('should throw AuthError when password is invalid', () => {});
+```
+
+### Follow the F.I.R.S.T. principles
+
+| Principle           | Rule                                                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Fast**            | Tests should run quickly. Slow tests won't be run frequently. If you don't run them, you won't find problems early enough.   |
+| **Independent**     | Tests should not depend on each other. No test should set up conditions for the next test. Run in any order.                 |
+| **Repeatable**      | Tests should work in any environment — CI, local, offline. No external dependencies that make tests flaky.                   |
+| **Self-Validating** | Tests have a boolean output: pass or fail. No manual inspection of log files to determine success.                           |
+| **Timely**          | Write tests **before** (TDD) or **alongside** the production code. Writing tests after makes production code harder to test. |
+
+### Test boundary conditions
+
+Take special care to test boundaries. We often get the middle of an algorithm right but misjudge the edges.
+
+### Exhaustively test near bugs
+
+Bugs tend to congregate. When you find a bug in a function, do an exhaustive test of that function. The bug was probably not alone.
+
+### Tests should be fast
+
+If tests are slow, they won't be run often. Long feedback loops lead to code rot.
+
+### Use a coverage tool
+
+Find modules, classes, and functions that are insufficiently tested. Don't skip trivial tests — their documentary value exceeds their cost.