@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/gof-state-pattern/SKILL.md

@@ -0,0 +1,220 @@
+# GOF State Pattern
+
+> Replace conditional logic with state objects that delegate behavior to the current state.
+
+## When to Use
+
+- An object's behavior changes dramatically based on its internal state
+- You have large `if/else` or `switch` chains that check state and choose behavior
+- You're modeling a state machine (order lifecycle, connection states, traffic lights, vending machines)
+- Adding a new state shouldn't require modifying existing state logic
+
+## Instructions
+
+**State interface + concrete states:**
+
+```typescript
+// State interface
+interface OrderState {
+  pay(order: Order): void;
+  ship(order: Order): void;
+  cancel(order: Order): void;
+  getLabel(): string;
+}
+
+// Context — delegates behavior to current state
+class Order {
+  private state: OrderState;
+
+  constructor(public readonly id: string) {
+    this.state = new PendingState();
+  }
+
+  // Delegate all behavior to the current state
+  pay(): void {
+    this.state.pay(this);
+  }
+  ship(): void {
+    this.state.ship(this);
+  }
+  cancel(): void {
+    this.state.cancel(this);
+  }
+  getLabel(): string {
+    return this.state.getLabel();
+  }
+
+  // State transitions are initiated by state objects
+  setState(state: OrderState): void {
+    console.log(`Order ${this.id}: ${this.state.getLabel()} → ${state.getLabel()}`);
+    this.state = state;
+  }
+}
+
+// Concrete states
+class PendingState implements OrderState {
+  pay(order: Order): void {
+    console.log(`Processing payment for order ${order.id}`);
+    order.setState(new PaidState());
+  }
+
+  ship(order: Order): void {
+    throw new Error('Cannot ship: order not paid');
+  }
+
+  cancel(order: Order): void {
+    console.log(`Cancelling order ${order.id}`);
+    order.setState(new CancelledState());
+  }
+
+  getLabel(): string {
+    return 'Pending';
+  }
+}
+
+class PaidState implements OrderState {
+  pay(order: Order): void {
+    throw new Error('Order is already paid');
+  }
+
+  ship(order: Order): void {
+    console.log(`Shipping order ${order.id}`);
+    order.setState(new ShippedState());
+  }
+
+  cancel(order: Order): void {
+    console.log(`Refunding payment for order ${order.id}`);
+    order.setState(new CancelledState());
+  }
+
+  getLabel(): string {
+    return 'Paid';
+  }
+}
+
+class ShippedState implements OrderState {
+  pay(order: Order): void {
+    throw new Error('Already paid and shipped');
+  }
+  ship(order: Order): void {
+    throw new Error('Already shipped');
+  }
+  cancel(order: Order): void {
+    throw new Error('Cannot cancel: already shipped');
+  }
+  getLabel(): string {
+    return 'Shipped';
+  }
+}
+
+class CancelledState implements OrderState {
+  pay(order: Order): void {
+    throw new Error('Order is cancelled');
+  }
+  ship(order: Order): void {
+    throw new Error('Order is cancelled');
+  }
+  cancel(order: Order): void {
+    throw new Error('Already cancelled');
+  }
+  getLabel(): string {
+    return 'Cancelled';
+  }
+}
+
+// Usage
+const order = new Order('ORD-001');
+order.pay(); // Pending → Paid
+order.ship(); // Paid → Shipped
+```
+
+**Discriminated union state machine (TypeScript-idiomatic):**
+
+```typescript
+type ConnectionState =
+  | { status: 'disconnected' }
+  | { status: 'connecting'; attempt: number }
+  | { status: 'connected'; sessionId: string; connectedAt: Date }
+  | { status: 'error'; reason: string; lastAttempt: Date };
+
+class Connection {
+  private state: ConnectionState = { status: 'disconnected' };
+
+  async connect(): Promise<void> {
+    if (this.state.status === 'connected') return;
+    this.state = { status: 'connecting', attempt: 1 };
+
+    try {
+      const sessionId = await this.doConnect();
+      this.state = { status: 'connected', sessionId, connectedAt: new Date() };
+    } catch (err) {
+      this.state = { status: 'error', reason: (err as Error).message, lastAttempt: new Date() };
+    }
+  }
+
+  getState(): ConnectionState {
+    return this.state;
+  }
+
+  // TypeScript narrows the type in each branch
+  getSessionId(): string {
+    if (this.state.status !== 'connected') throw new Error('Not connected');
+    return this.state.sessionId; // TypeScript knows this exists
+  }
+
+  private async doConnect(): Promise<string> {
+    return 'session-' + Math.random();
+  }
+}
+```
+
+## Details
+
+**State vs. Strategy:** Both replace conditionals with polymorphism. State: the state object controls transitions and the context changes its own state. Strategy: the strategy is set externally and doesn't change itself. If the object decides when to change behavior, use State. If an external caller decides, use Strategy.
+
+**Where to put transition logic:** States can transition the context directly (`order.setState(new PaidState())`) or return the new state for the context to apply. Prefer direct transitions when states are simple; prefer returning state when you want to prevent circular dependencies.
+
+**Anti-patterns:**
+
+- States that access context internals excessively — keep context's public API minimal
+- Transitions in both the context and the states — pick one place
+- States that are singletons when they carry per-instance data — states with no internal data can be shared; states with data should be created fresh
+
+**Persistence:** When serializing an object with state, store the state label (`'Pending'`, `'Paid'`) and restore the state object on load:
+
+```typescript
+function restoreState(label: string): OrderState {
+  switch (label) {
+    case 'Pending':
+      return new PendingState();
+    case 'Paid':
+      return new PaidState();
+    case 'Shipped':
+      return new ShippedState();
+    case 'Cancelled':
+      return new CancelledState();
+    default:
+      throw new Error(`Unknown state: ${label}`);
+  }
+}
+```
+
+## Source
+
+refactoring.guru/design-patterns/state
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/gof-state-pattern/skill.yaml

@@ -0,0 +1,36 @@
+name: gof-state-pattern
+version: "1.0.0"
+description: Replace conditional logic with state objects that delegate behavior to the current state
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "tsconfig.json"
+related_skills:
+  - ts-discriminated-unions
+  - ts-class-patterns
+  - gof-strategy-pattern
+stack_signals:
+  - typescript
+keywords:
+  - state-pattern
+  - state-machine
+  - context-delegation
+  - eliminating-conditionals
+metadata:
+  author: community
+  upstream: refactoring.guru/design-patterns/state
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/gof-strategy-pattern/SKILL.md

@@ -0,0 +1,179 @@
+# GOF Strategy Pattern
+
+> Encapsulate interchangeable algorithms behind a common interface for runtime selection.
+
+## When to Use
+
+- You have multiple algorithms that do the same job but differently (sorting, pricing, routing, formatting)
+- You want to switch algorithms at runtime without changing the client
+- You're eliminating large `if/else` chains where each branch implements a different algorithm
+- You want algorithms to be testable in isolation from the context that uses them
+
+## Instructions
+
+**Interface + concrete strategies:**
+
+```typescript
+// Strategy interface
+interface PricingStrategy {
+  calculate(basePrice: number, quantity: number, customer: Customer): number;
+}
+
+// Concrete strategies
+class StandardPricing implements PricingStrategy {
+  calculate(basePrice: number, quantity: number): number {
+    return basePrice * quantity;
+  }
+}
+
+class BulkDiscountPricing implements PricingStrategy {
+  constructor(
+    private readonly threshold: number,
+    private readonly discount: number
+  ) {}
+
+  calculate(basePrice: number, quantity: number): number {
+    if (quantity >= this.threshold) {
+      return basePrice * quantity * (1 - this.discount);
+    }
+    return basePrice * quantity;
+  }
+}
+
+class MemberPricing implements PricingStrategy {
+  calculate(basePrice: number, quantity: number, customer: Customer): number {
+    const rate = customer.memberTier === 'gold' ? 0.8 : 0.9;
+    return basePrice * quantity * rate;
+  }
+}
+
+// Context — uses a strategy
+class ShoppingCart {
+  private strategy: PricingStrategy = new StandardPricing();
+  private items: { name: string; price: number; qty: number }[] = [];
+
+  setStrategy(strategy: PricingStrategy): void {
+    this.strategy = strategy;
+  }
+
+  addItem(name: string, price: number, qty: number): void {
+    this.items.push({ name, price, qty });
+  }
+
+  calculateTotal(customer: Customer): number {
+    return this.items.reduce((total, item) => {
+      return total + this.strategy.calculate(item.price, item.qty, customer);
+    }, 0);
+  }
+}
+
+// Runtime selection
+const cart = new ShoppingCart();
+cart.addItem('Widget', 10.0, 5);
+
+const customer: Customer = { id: 'u1', memberTier: 'gold' };
+
+// Default
+console.log(cart.calculateTotal(customer)); // 50.00
+
+// Switch to member pricing
+cart.setStrategy(new MemberPricing());
+console.log(cart.calculateTotal(customer)); // 40.00
+
+// Switch to bulk discount (20% off 10+)
+cart.setStrategy(new BulkDiscountPricing(10, 0.2));
+cart.addItem('Widget', 10.0, 6); // now 11 total
+console.log(cart.calculateTotal(customer)); // 88.00 (20% off all)
+```
+
+**Function-based strategies (TypeScript idiomatic — skip the class):**
+
+```typescript
+type SortStrategy<T> = (a: T, b: T) => number;
+
+const sortByName: SortStrategy<{ name: string }> = (a, b) => a.name.localeCompare(b.name);
+
+const sortByDate: SortStrategy<{ createdAt: Date }> = (a, b) =>
+  a.createdAt.getTime() - b.createdAt.getTime();
+
+const sortByScore: SortStrategy<{ score: number }> = (a, b) => b.score - a.score; // descending
+
+function sortItems<T>(items: T[], strategy: SortStrategy<T>): T[] {
+  return [...items].sort(strategy);
+}
+
+// No strategy objects needed — functions are the strategies
+const sortedByName = sortItems(users, sortByName);
+const sortedByDate = sortItems(users, sortByDate);
+```
+
+**Strategy map for configuration-driven selection:**
+
+```typescript
+type CompressionType = 'gzip' | 'brotli' | 'zstd' | 'none';
+
+interface Compressor {
+  compress(data: Buffer): Promise<Buffer>;
+  decompress(data: Buffer): Promise<Buffer>;
+}
+
+const compressionStrategies: Record<CompressionType, Compressor> = {
+  gzip: new GzipCompressor(),
+  brotli: new BrotliCompressor(),
+  zstd: new ZstdCompressor(),
+  none: new NoopCompressor(),
+};
+
+function getCompressor(type: CompressionType): Compressor {
+  return compressionStrategies[type];
+}
+
+const compressor = getCompressor((process.env.COMPRESSION_TYPE as CompressionType) ?? 'gzip');
+const compressed = await compressor.compress(data);
+```
+
+## Details
+
+**Strategy vs. State:** Both use polymorphism to replace conditionals. Strategy: the algorithm is chosen externally and remains stable during execution. State: the context transitions between states internally. Ask "who decides when to switch?" — external caller → Strategy, object itself → State.
+
+**Strategy vs. Template Method:** Template Method uses inheritance — the base class defines the algorithm skeleton and subclasses fill in steps. Strategy uses composition — the algorithm is injected. Prefer Strategy (composition) over Template Method (inheritance) in modern TypeScript.
+
+**Anti-patterns:**
+
+- Strategy that needs to access private context state — if it needs too much context data, consider making it a method on the context instead
+- Context that exposes its internals specifically for strategies — the strategy interface should only receive what it needs to do its job
+- One-off strategies that are never swapped — if you'll never switch the algorithm, don't introduce the indirection
+
+**Testing strategies:** Each strategy can be tested in isolation without a context:
+
+```typescript
+describe('BulkDiscountPricing', () => {
+  const strategy = new BulkDiscountPricing(10, 0.2);
+  it('applies discount when quantity >= threshold', () => {
+    expect(strategy.calculate(10, 10, mockCustomer)).toBe(80);
+  });
+  it('does not apply discount below threshold', () => {
+    expect(strategy.calculate(10, 9, mockCustomer)).toBe(90);
+  });
+});
+```
+
+## Source
+
+refactoring.guru/design-patterns/strategy
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/gof-strategy-pattern/skill.yaml

@@ -0,0 +1,36 @@
+name: gof-strategy-pattern
+version: "1.0.0"
+description: Encapsulate interchangeable algorithms behind a common interface for runtime selection
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "tsconfig.json"
+related_skills:
+  - ts-class-patterns
+  - ts-generics-pattern
+  - gof-state-pattern
+stack_signals:
+  - typescript
+keywords:
+  - strategy
+  - algorithm-encapsulation
+  - runtime-selection
+  - function-based-strategies
+metadata:
+  author: community
+  upstream: refactoring.guru/design-patterns/strategy
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/gof-template-method/SKILL.md

@@ -0,0 +1,189 @@
+# GOF Template Method
+
+> Define an algorithm skeleton in a base class with abstract steps filled by subclasses.
+
+## When to Use
+
+- Multiple classes share the same algorithm skeleton but differ in specific steps
+- You want to enforce a fixed sequence of steps while allowing customization of each step
+- You're building parsers, report generators, data importers, or test frameworks where the overall flow is fixed
+- You want to avoid code duplication when variations follow the same high-level process
+
+## Instructions
+
+**Classic abstract base class with template method:**
+
+```typescript
+abstract class DataImporter {
+  // Template method — defines the algorithm skeleton
+  async import(source: string): Promise<ImportResult> {
+    await this.connect(source);
+    try {
+      const raw = await this.extract();
+      const validated = this.validate(raw);
+      const transformed = this.transform(validated);
+      const count = await this.load(transformed);
+      await this.notify(count);
+      return { success: true, count };
+    } catch (err) {
+      await this.onError(err as Error);
+      return { success: false, count: 0, error: (err as Error).message };
+    } finally {
+      await this.disconnect();
+    }
+  }
+
+  // Abstract steps — subclasses must implement
+  protected abstract connect(source: string): Promise<void>;
+  protected abstract extract(): Promise<unknown[]>;
+  protected abstract transform(records: unknown[]): Record<string, unknown>[];
+
+  // Hooks — subclasses can override (have defaults)
+  protected validate(records: unknown[]): unknown[] {
+    return records;
+  }
+  protected async load(records: Record<string, unknown>[]): Promise<number> {
+    // Default load implementation
+    console.log(`Loading ${records.length} records`);
+    return records.length;
+  }
+  protected async notify(count: number): Promise<void> {
+    console.log(`Import complete: ${count} records`);
+  }
+  protected async onError(err: Error): Promise<void> {
+    console.error('Import failed:', err.message);
+  }
+  protected async disconnect(): Promise<void> {} // no-op by default
+}
+
+// Concrete implementation — CSV importer
+class CSVImporter extends DataImporter {
+  private connection: string = '';
+
+  protected async connect(source: string): Promise<void> {
+    this.connection = source;
+    console.log(`Opening CSV file: ${source}`);
+  }
+
+  protected async extract(): Promise<unknown[]> {
+    // Parse CSV rows
+    return [{ name: 'Alice', email: 'alice@example.com' }];
+  }
+
+  protected override validate(records: unknown[]): unknown[] {
+    return records.filter((r) => (r as Record<string, string>).email?.includes('@'));
+  }
+
+  protected transform(records: unknown[]): Record<string, unknown>[] {
+    return records.map((r) => ({
+      ...(r as Record<string, unknown>),
+      importedAt: new Date(),
+      source: 'csv',
+    }));
+  }
+}
+
+// Another concrete implementation — JSON API importer
+class APIImporter extends DataImporter {
+  private baseUrl: string = '';
+
+  protected async connect(source: string): Promise<void> {
+    this.baseUrl = source;
+  }
+
+  protected async extract(): Promise<unknown[]> {
+    const response = await fetch(`${this.baseUrl}/data`);
+    return response.json();
+  }
+
+  protected transform(records: unknown[]): Record<string, unknown>[] {
+    return records.map((r) => ({
+      ...(r as Record<string, unknown>),
+      importedAt: new Date(),
+      source: 'api',
+    }));
+  }
+
+  protected override async notify(count: number): Promise<void> {
+    await fetch(`${this.baseUrl}/ack`, { method: 'POST', body: JSON.stringify({ count }) });
+  }
+}
+
+// Usage — call the template method, not the individual steps
+const csvImporter = new CSVImporter();
+await csvImporter.import('/data/users.csv');
+```
+
+**Hook methods for optional extension points:**
+
+```typescript
+abstract class ReportGenerator {
+  generate(data: unknown[]): string {
+    const header = this.renderHeader();
+    const body = this.renderBody(data);
+    const footer = this.renderFooter();
+
+    // Hook — subclasses can add custom sections
+    const custom = this.renderCustomSection();
+
+    return [header, body, custom, footer].filter(Boolean).join('\n');
+  }
+
+  protected abstract renderHeader(): string;
+  protected abstract renderBody(data: unknown[]): string;
+  protected renderFooter(): string {
+    return '--- End of Report ---';
+  }
+  protected renderCustomSection(): string {
+    return '';
+  } // hook — optional override
+}
+```
+
+## Details
+
+**Template Method vs. Strategy:** Template Method uses inheritance — the base class controls the algorithm; subclasses override steps. Strategy uses composition — the algorithm is injected from outside. Prefer Strategy when: you want to swap algorithms at runtime, or you want to avoid deep inheritance chains. Use Template Method when: the overall structure rarely changes but specific steps vary by subclass.
+
+**Hooks vs. abstract methods:** Abstract methods must be overridden — they enforce required customization. Hooks are optional — they provide extension points with sensible defaults. Use abstract for mandatory steps, hooks for optional customization.
+
+**Anti-patterns:**
+
+- Template method that calls abstract methods in constructors — the subclass might not be fully initialized
+- Too many abstract methods — if every step is abstract, the base class provides no value; use a plain interface instead
+- Subclasses that override the template method itself — this breaks the invariant; mark the template method as `final` (or just document it clearly)
+
+**TypeScript enforcement:** TypeScript doesn't have a `final` keyword for methods. Document non-overridable template methods with a comment or use the protected pattern:
+
+```typescript
+// Convention: prefix with _ to signal "do not override"
+// Or use a wrapper:
+class Base {
+  process(): void {
+    // callers use this
+    this._doProcess(); // not intended to be overridden
+  }
+  protected _doProcess(): void {
+    /* ... */
+  }
+}
+```
+
+## Source
+
+refactoring.guru/design-patterns/template-method
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/gof-template-method/skill.yaml

@@ -0,0 +1,36 @@
+name: gof-template-method
+version: "1.0.0"
+description: Define an algorithm skeleton in a base class with abstract steps filled by subclasses
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "tsconfig.json"
+related_skills:
+  - ts-class-patterns
+  - gof-strategy-pattern
+stack_signals:
+  - typescript
+keywords:
+  - template-method
+  - algorithm-skeleton
+  - abstract-steps
+  - hooks
+  - inversion-of-control
+metadata:
+  author: community
+  upstream: refactoring.guru/design-patterns/template-method
+state:
+  persistent: false
+  files: []
+depends_on: []