@mytechtoday/augment-extensions 0.1.0 → 0.1.2

package/augment-extensions/examples/design-patterns/examples/creational-patterns.md

@@ -0,0 +1,250 @@
+# Creational Design Patterns
+
+Patterns for object creation mechanisms.
+
+## Singleton Pattern
+
+Ensure a class has only one instance and provide a global access point.
+
+### Implementation
+
+```typescript
+class Database {
+  private static instance: Database;
+  private connection: any;
+
+  private constructor() {
+    // Private constructor prevents direct instantiation
+    this.connection = this.connect();
+  }
+
+  public static getInstance(): Database {
+    if (!Database.instance) {
+      Database.instance = new Database();
+    }
+    return Database.instance;
+  }
+
+  private connect() {
+    console.log('Connecting to database...');
+    return { connected: true };
+  }
+
+  public query(sql: string) {
+    console.log(`Executing: ${sql}`);
+    return this.connection;
+  }
+}
+
+// Usage
+const db1 = Database.getInstance();
+const db2 = Database.getInstance();
+console.log(db1 === db2); // true - same instance
+```
+
+### Use Cases
+
+- Database connections
+- Configuration managers
+- Logging services
+- Cache managers
+
+### Pitfalls
+
+- Difficult to test (global state)
+- Can hide dependencies
+- Thread safety issues (in multi-threaded environments)
+
+---
+
+## Factory Pattern
+
+Create objects without specifying exact class.
+
+### Implementation
+
+```typescript
+interface Animal {
+  speak(): string;
+}
+
+class Dog implements Animal {
+  speak(): string {
+    return 'Woof!';
+  }
+}
+
+class Cat implements Animal {
+  speak(): string {
+    return 'Meow!';
+  }
+}
+
+class AnimalFactory {
+  static createAnimal(type: 'dog' | 'cat'): Animal {
+    switch (type) {
+      case 'dog':
+        return new Dog();
+      case 'cat':
+        return new Cat();
+      default:
+        throw new Error(`Unknown animal type: ${type}`);
+    }
+  }
+}
+
+// Usage
+const dog = AnimalFactory.createAnimal('dog');
+console.log(dog.speak()); // "Woof!"
+
+const cat = AnimalFactory.createAnimal('cat');
+console.log(cat.speak()); // "Meow!"
+```
+
+### Use Cases
+
+- Creating UI components based on configuration
+- Database connection factories (MySQL, PostgreSQL, etc.)
+- Document parsers (JSON, XML, CSV)
+- Payment processors (Stripe, PayPal, etc.)
+
+---
+
+## Builder Pattern
+
+Construct complex objects step by step.
+
+### Implementation
+
+```typescript
+class User {
+  constructor(
+    public name: string,
+    public email: string,
+    public age?: number,
+    public address?: string,
+    public phone?: string
+  ) {}
+}
+
+class UserBuilder {
+  private name: string = '';
+  private email: string = '';
+  private age?: number;
+  private address?: string;
+  private phone?: string;
+
+  setName(name: string): UserBuilder {
+    this.name = name;
+    return this;
+  }
+
+  setEmail(email: string): UserBuilder {
+    this.email = email;
+    return this;
+  }
+
+  setAge(age: number): UserBuilder {
+    this.age = age;
+    return this;
+  }
+
+  setAddress(address: string): UserBuilder {
+    this.address = address;
+    return this;
+  }
+
+  setPhone(phone: string): UserBuilder {
+    this.phone = phone;
+    return this;
+  }
+
+  build(): User {
+    if (!this.name || !this.email) {
+      throw new Error('Name and email are required');
+    }
+    return new User(this.name, this.email, this.age, this.address, this.phone);
+  }
+}
+
+// Usage
+const user = new UserBuilder()
+  .setName('John Doe')
+  .setEmail('john@example.com')
+  .setAge(30)
+  .setAddress('123 Main St')
+  .build();
+```
+
+### Use Cases
+
+- Building complex configuration objects
+- Creating HTTP requests
+- Constructing SQL queries
+- Building UI components with many options
+
+---
+
+## Prototype Pattern
+
+Create new objects by cloning existing ones.
+
+### Implementation
+
+```typescript
+interface Cloneable<T> {
+  clone(): T;
+}
+
+class Shape implements Cloneable<Shape> {
+  constructor(
+    public x: number,
+    public y: number,
+    public color: string
+  ) {}
+
+  clone(): Shape {
+    return new Shape(this.x, this.y, this.color);
+  }
+}
+
+class Circle extends Shape {
+  constructor(
+    x: number,
+    y: number,
+    color: string,
+    public radius: number
+  ) {
+    super(x, y, color);
+  }
+
+  clone(): Circle {
+    return new Circle(this.x, this.y, this.color, this.radius);
+  }
+}
+
+// Usage
+const originalCircle = new Circle(10, 20, 'red', 5);
+const clonedCircle = originalCircle.clone();
+
+clonedCircle.x = 30;
+clonedCircle.color = 'blue';
+
+console.log(originalCircle); // Circle { x: 10, y: 20, color: 'red', radius: 5 }
+console.log(clonedCircle);   // Circle { x: 30, y: 20, color: 'blue', radius: 5 }
+```
+
+### Use Cases
+
+- Cloning game objects
+- Creating template objects
+- Avoiding expensive initialization
+- Creating variations of objects
+
+### Best Practices
+
+1. **Singleton**: Use sparingly, prefer dependency injection
+2. **Factory**: Use when object creation logic is complex
+3. **Builder**: Use for objects with many optional parameters
+4. **Prototype**: Use when cloning is cheaper than creating new
+

package/augment-extensions/examples/design-patterns/examples/structural-patterns.md

@@ -0,0 +1,264 @@
+# Structural Design Patterns
+
+Patterns for composing classes and objects.
+
+## Adapter Pattern
+
+Convert interface of a class into another interface clients expect.
+
+### Implementation
+
+```typescript
+// Old API
+class OldPaymentProcessor {
+  processPayment(amount: number): void {
+    console.log(`Processing $${amount} via old system`);
+  }
+}
+
+// New API interface
+interface PaymentGateway {
+  pay(amount: number, currency: string): void;
+}
+
+// Adapter
+class PaymentAdapter implements PaymentGateway {
+  constructor(private oldProcessor: OldPaymentProcessor) {}
+
+  pay(amount: number, currency: string): void {
+    // Convert new API call to old API call
+    console.log(`Converting ${currency} payment`);
+    this.oldProcessor.processPayment(amount);
+  }
+}
+
+// Usage
+const oldProcessor = new OldPaymentProcessor();
+const adapter = new PaymentAdapter(oldProcessor);
+adapter.pay(100, 'USD');
+```
+
+### Use Cases
+
+- Integrating third-party libraries
+- Working with legacy code
+- API versioning
+- Database adapters
+
+---
+
+## Decorator Pattern
+
+Add new functionality to objects dynamically.
+
+### Implementation
+
+```typescript
+interface Coffee {
+  cost(): number;
+  description(): string;
+}
+
+class SimpleCoffee implements Coffee {
+  cost(): number {
+    return 5;
+  }
+
+  description(): string {
+    return 'Simple coffee';
+  }
+}
+
+// Decorator base class
+abstract class CoffeeDecorator implements Coffee {
+  constructor(protected coffee: Coffee) {}
+
+  abstract cost(): number;
+  abstract description(): string;
+}
+
+class MilkDecorator extends CoffeeDecorator {
+  cost(): number {
+    return this.coffee.cost() + 1;
+  }
+
+  description(): string {
+    return this.coffee.description() + ', milk';
+  }
+}
+
+class SugarDecorator extends CoffeeDecorator {
+  cost(): number {
+    return this.coffee.cost() + 0.5;
+  }
+
+  description(): string {
+    return this.coffee.description() + ', sugar';
+  }
+}
+
+// Usage
+let coffee: Coffee = new SimpleCoffee();
+console.log(`${coffee.description()}: $${coffee.cost()}`);
+// "Simple coffee: $5"
+
+coffee = new MilkDecorator(coffee);
+console.log(`${coffee.description()}: $${coffee.cost()}`);
+// "Simple coffee, milk: $6"
+
+coffee = new SugarDecorator(coffee);
+console.log(`${coffee.description()}: $${coffee.cost()}`);
+// "Simple coffee, milk, sugar: $6.5"
+```
+
+### Use Cases
+
+- Adding features to objects at runtime
+- Middleware in web frameworks
+- Stream processing (compression, encryption)
+- UI component enhancement
+
+---
+
+## Facade Pattern
+
+Provide simplified interface to complex subsystem.
+
+### Implementation
+
+```typescript
+// Complex subsystems
+class CPU {
+  freeze(): void {
+    console.log('CPU: Freezing...');
+  }
+  jump(position: number): void {
+    console.log(`CPU: Jumping to ${position}`);
+  }
+  execute(): void {
+    console.log('CPU: Executing...');
+  }
+}
+
+class Memory {
+  load(position: number, data: string): void {
+    console.log(`Memory: Loading ${data} at ${position}`);
+  }
+}
+
+class HardDrive {
+  read(sector: number, size: number): string {
+    console.log(`HardDrive: Reading sector ${sector}, size ${size}`);
+    return 'boot data';
+  }
+}
+
+// Facade
+class ComputerFacade {
+  private cpu: CPU;
+  private memory: Memory;
+  private hardDrive: HardDrive;
+
+  constructor() {
+    this.cpu = new CPU();
+    this.memory = new Memory();
+    this.hardDrive = new HardDrive();
+  }
+
+  start(): void {
+    console.log('Computer: Starting...');
+    this.cpu.freeze();
+    const bootData = this.hardDrive.read(0, 1024);
+    this.memory.load(0, bootData);
+    this.cpu.jump(0);
+    this.cpu.execute();
+    console.log('Computer: Started!');
+  }
+}
+
+// Usage
+const computer = new ComputerFacade();
+computer.start(); // Simple interface hides complexity
+```
+
+### Use Cases
+
+- Simplifying complex libraries
+- API wrappers
+- Database access layers
+- Service orchestration
+
+---
+
+## Proxy Pattern
+
+Provide placeholder for another object to control access.
+
+### Implementation
+
+```typescript
+interface Image {
+  display(): void;
+}
+
+class RealImage implements Image {
+  constructor(private filename: string) {
+    this.loadFromDisk();
+  }
+
+  private loadFromDisk(): void {
+    console.log(`Loading image: ${this.filename}`);
+  }
+
+  display(): void {
+    console.log(`Displaying image: ${this.filename}`);
+  }
+}
+
+class ImageProxy implements Image {
+  private realImage: RealImage | null = null;
+
+  constructor(private filename: string) {}
+
+  display(): void {
+    // Lazy loading - only create real image when needed
+    if (!this.realImage) {
+      this.realImage = new RealImage(this.filename);
+    }
+    this.realImage.display();
+  }
+}
+
+// Usage
+const image1 = new ImageProxy('photo1.jpg');
+const image2 = new ImageProxy('photo2.jpg');
+
+// Images not loaded yet
+console.log('Images created');
+
+// Load and display only when needed
+image1.display(); // Loads and displays
+image1.display(); // Just displays (already loaded)
+```
+
+### Types of Proxies
+
+1. **Virtual Proxy**: Lazy initialization (example above)
+2. **Protection Proxy**: Access control
+3. **Remote Proxy**: Remote object representation
+4. **Caching Proxy**: Cache results
+
+### Use Cases
+
+- Lazy loading of resources
+- Access control and authentication
+- Logging and monitoring
+- Caching expensive operations
+
+### Best Practices
+
+1. **Adapter**: Use when interfaces are incompatible
+2. **Decorator**: Use to add responsibilities dynamically
+3. **Facade**: Use to simplify complex subsystems
+4. **Proxy**: Use to control access or add lazy loading
+

package/augment-extensions/examples/design-patterns/module.json

@@ -0,0 +1,27 @@
+{
+  "name": "design-patterns",
+  "version": "1.0.0",
+  "displayName": "Design Patterns Examples",
+  "description": "Common design patterns with TypeScript/JavaScript implementations and use cases",
+  "type": "examples",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "augment": {
+    "characterCount": 42000,
+    "priority": "medium",
+    "category": "examples"
+  },
+  "installation": {
+    "required": false,
+    "dependencies": []
+  },
+  "tags": [
+    "design-patterns",
+    "typescript",
+    "javascript",
+    "oop",
+    "architecture",
+    "examples"
+  ]
+}
+

package/{modules → augment-extensions}/workflows/beads/examples/complete-workflow-example.md

@@ -29,7 +29,7 @@ bd create "User Authentication System" -p 0
 **Without CLI** - Append to `.beads/issues.jsonl`:
 
 ```json
-{"id":"bd-a3f8","title":"User Authentication System","status":"open","priority":0,"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
+{"id":"bd-a3f8","title":"User Authentication System","status":"open","priority":0,"spec":"features/authentication","rules":["security-guidelines.md"],"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
 ```
 
 ## Step 3: Create Tasks
@@ -52,10 +52,10 @@ bd create "Add login endpoint" -p 1 --parent bd-a3f8
 **Without CLI** - Append to `.beads/issues.jsonl`:
 
 ```jsonl
-{"id":"bd-a3f8.1","title":"Add database schema","status":"open","priority":0,"parent":"bd-a3f8","created":"2024-01-20T10:01:00Z","updated":"2024-01-20T10:01:00Z"}
-{"id":"bd-a3f8.2","title":"Add password hashing","status":"open","priority":1,"parent":"bd-a3f8","created":"2024-01-20T10:02:00Z","updated":"2024-01-20T10:02:00Z"}
-{"id":"bd-a3f8.3","title":"Add JWT generation","status":"open","priority":1,"parent":"bd-a3f8","created":"2024-01-20T10:03:00Z","updated":"2024-01-20T10:03:00Z"}
-{"id":"bd-a3f8.4","title":"Add login endpoint","status":"open","priority":1,"parent":"bd-a3f8","created":"2024-01-20T10:04:00Z","updated":"2024-01-20T10:04:00Z"}
+{"id":"bd-a3f8.1","title":"Add database schema","status":"open","priority":0,"parent":"bd-a3f8","spec":"features/authentication","rules":["module-development.md"],"created":"2024-01-20T10:01:00Z","updated":"2024-01-20T10:01:00Z"}
+{"id":"bd-a3f8.2","title":"Add password hashing","status":"open","priority":1,"parent":"bd-a3f8","spec":"features/authentication","rules":["security-guidelines.md"],"created":"2024-01-20T10:02:00Z","updated":"2024-01-20T10:02:00Z"}
+{"id":"bd-a3f8.3","title":"Add JWT generation","status":"open","priority":1,"parent":"bd-a3f8","spec":"features/authentication","rules":["security-guidelines.md"],"created":"2024-01-20T10:03:00Z","updated":"2024-01-20T10:03:00Z"}
+{"id":"bd-a3f8.4","title":"Add login endpoint","status":"open","priority":1,"parent":"bd-a3f8","spec":"features/authentication","rules":["module-development.md","security-guidelines.md"],"created":"2024-01-20T10:04:00Z","updated":"2024-01-20T10:04:00Z"}
 ```
 
 ## Step 4: Add Dependencies

package/{modules → augment-extensions}/workflows/beads/rules/file-format.md

@@ -43,6 +43,8 @@ Beads stores issues in `.beads/issues.jsonl` using JSONL (JSON Lines) format. Ea
   "blocked_by": [],
   "related": ["bd-d4e5"],
   "parent": null,
+  "spec": "features/authentication",
+  "rules": ["module-development.md", "security-guidelines.md"],
   "comments": [
     {
       "text": "Started implementation",
@@ -78,6 +80,8 @@ Beads stores issues in `.beads/issues.jsonl` using JSONL (JSON Lines) format. Ea
 - **parent** (string): ID of parent task (for hierarchical IDs)
 - **comments** (array of objects): Comments and updates
 - **closed** (string): ISO 8601 timestamp when closed
+- **spec** (string): OpenSpec specification ID this task implements (e.g., "features/authentication")
+- **rules** (array of strings): `.augment/` rule files that apply to this task (e.g., ["module-development.md"])
 
 ## ID Format
 
@@ -116,6 +120,46 @@ bd-a3f8.2      # Another task under epic
 - **2** - Medium (P2) - default
 - **3** - Low (P3)
 
+## Coordination Fields
+
+### spec
+
+References an OpenSpec specification that this task implements:
+
+```json
+{
+  "id": "bd-a1b2",
+  "title": "Add authentication API",
+  "spec": "features/authentication"
+}
+```
+
+The `spec` field links the task to an OpenSpec specification file (e.g., `openspec/specs/features/authentication.md`). This enables:
+- Automatic traceability from spec to implementation
+- Discovery of all tasks implementing a spec
+- Coordination manifest integration
+
+### rules
+
+Lists `.augment/` rule files that apply to this task:
+
+```json
+{
+  "id": "bd-a1b2",
+  "title": "Add authentication API",
+  "rules": ["module-development.md", "security-guidelines.md"]
+}
+```
+
+The `rules` field helps AI agents:
+- Load relevant coding standards and guidelines
+- Apply appropriate validation rules
+- Maintain consistency across tasks
+
+**Note**: These fields are optional and backward compatible. Existing tasks without these fields continue to work normally.
+
+---
+
 ## Dependency Types
 
 ### blocks
@@ -254,7 +298,7 @@ echo '{"id":"bd-a1b2","title":"New task","status":"open","created":"2024-01-20T1
 ### Create Task
 
 ```jsonl
-{"id":"bd-a1b2","title":"Add authentication","status":"open","priority":0,"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
+{"id":"bd-a1b2","title":"Add authentication","status":"open","priority":0,"spec":"features/authentication","rules":["module-development.md"],"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
 ```
 
 ### Add Dependency

package/{modules → augment-extensions}/workflows/beads/rules/workflow.md

@@ -4,6 +4,27 @@
 
 Beads provides a git-backed issue tracker optimized for AI agents. Issues are stored as JSONL (JSON Lines) in `.beads/issues.jsonl`, making them version-controlled, mergeable, and agent-readable.
 
+## Naming Convention
+
+All Beads issues in this project use the **"bd-" prefix**.
+
+### Standard Format
+
+- `bd-<hash>` - Standard hash-based ID (e.g., `bd-a1b2`)
+- `bd-<name>` - Named ID for important tasks (e.g., `bd-init`, `bd-rename1`)
+- `bd-<hash>.<number>` - Hierarchical ID (e.g., `bd-a1b2.1`)
+
+### Why "bd"?
+
+- **Brevity**: Short and memorable (2 characters)
+- **Clarity**: Clearly identifies Beads issues
+- **Consistency**: Single prefix across all issues
+- **Git-Friendly**: Reduces commit message length
+
+### Validation
+
+All new issues are validated to ensure they use the "bd-" prefix. See `openspec/specs/beads/naming-convention.md` for complete specification.
+
 ## Core Workflow
 
 ```
@@ -37,6 +58,26 @@ Beads provides a git-backed issue tracker optimized for AI agents. Issues are st
 └─────────────────┘
 ```
 
+## Coordination with OpenSpec and .augment/
+
+Beads tasks can reference OpenSpec specifications and `.augment/` rules for better coordination:
+
+```bash
+# Create task with spec and rules
+bd create "Implement authentication" -p 1
+# Then manually add spec and rules fields to .beads/issues.jsonl:
+# {"id":"bd-xyz","spec":"features/authentication","rules":["security-guidelines.md"],"updated":"..."}
+```
+
+**Benefits**:
+- **Traceability**: Link tasks to specifications
+- **Context**: AI agents load relevant rules automatically
+- **Coordination**: Integration with coordination manifest
+
+See `.augment/rules/coordination-system.md` for details.
+
+---
+
 ## Step 1: Initialize Beads
 
 ### With CLI