agents-united 1.0.0 → 1.2.0

package/registry/skills/test-driven-development/SKILL.md

@@ -1,13 +1,133 @@
 ---
 name: test-driven-development
-description: Official Test Driven Development skill for Agents United ecosystem providing runbooks and guidelines.
+description: Production-grade Test-Driven Development playbook for Red-Green-Refactor discipline, unit testing, and contract assertions.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
 ---
 
-# Test Driven Development
+# Test-Driven Development (TDD) Red-Green-Refactor Protocol
 
-This skill provides comprehensive instructions, runbooks, and guidelines for Test Driven Development.
+## Overview & Purpose
+The Test-Driven Development (TDD) Red-Green-Refactor Protocol skill provides a deterministic, battle-tested framework for executing test-driven-development processes across the Agents United multi-agent ecosystem.
 
-## Procedure & Guidelines
-1. Review domain requirements and constraints.
-2. Execute step-by-step procedures test-first.
-3. Validate results against acceptance criteria.
+Following this skill ensures high quality, zero-regression execution, rigorous testing gates, and seamless cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request or workflow step invoking test-driven-development.
+- Auditing, implementing, or standardizing test-driven-development procedures.
+- Addressing technical debt, architectural reviews, or production readiness gates.
+- Preparing pull requests or automated release validations.
+
+### Prerequisites
+- Active project repository workspace with version control configured.
+- Operational testing, typechecking, and build toolchains.
+- Domain requirements, architectural constraints, or user stories defined.
+- Clean git working tree before beginning execution.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target module, service, component, or file path |
+| `config` | Object | Optional | Specific domain configurations, thresholds, and options |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts and reports |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation and high test coverage |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/test-driven-development/spec.md` | Full technical specification and architectural plan |
+| Implementation Files | `src/test-driven-development/*` | Production-ready source code, tests, and configurations |
+| Execution Report | `reports/test-driven-development/summary.json` | Verification metrics, test results, and audit summary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Specification Ingestion & Test Case Design
+1. Deconstruct user story or requirement into discrete, testable behavioral assertions.
+2. Design test cases following Arrange-Act-Assert (AAA) or Given-When-Then structure.
+3. Name tests expressively: should [expected behavior] when [condition / input].
+4. Identify edge cases: empty inputs, zero/negative values, null pointers, boundary limits.
+5. Verify test runner (npm test / Vitest / Jest) is active in watch mode.
+
+### Phase 2: RED Phase — Author Failing Test First
+1. Author the test case BEFORE writing any production implementation code.
+2. Define clean, intuitive API interfaces directly inside the test invocation.
+3. Run test runner and verify the test fails for the EXACT expected reason (assertion failure, not syntax error).
+4. Confirm that zero production code exists that satisfies the new test.
+5. Record RED status.
+
+### Phase 3: GREEN Phase — Minimal Implementation to Pass
+1. Write the absolute minimum production code required to make the failing test pass.
+2. Resist the temptation to over-engineer, generalize, or implement future requirements prematurely.
+3. Run test runner and confirm the test turns GREEN.
+4. Verify that all previously existing tests continue to pass GREEN without regressions.
+5. Commit working GREEN state to git history.
+
+### Phase 4: REFACTOR Phase — Eliminate Duplication & Optimize
+1. Inspect code for duplication, awkward naming, or structural code smells.
+2. Extract helper utilities, refine class/function abstractions, and improve readability.
+3. Ensure tests remain 100% GREEN throughout every refactoring step.
+4. Optimize algorithmic performance where necessary while preserving exact behavior.
+5. Re-verify all tests pass cleanly.
+
+### Phase 5: Coverage Validation & Suite Finalization
+1. Run test suite with code coverage analysis (npm test -- --coverage).
+2. Verify line and branch coverage targets (>90%) are met on new modules.
+3. Run full project verification: npm run typecheck && npm test && npm run build.
+4. Ensure all test suites execute in under 5 seconds to maintain high development velocity.
+5. Commit completed TDD cycle to version control.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Test-Driven Development (TDD) Red-Green-Refactor Protocol Configuration & Specification
+```yaml
+// Step 1 (RED): Write failing test capturing specification
+describe('ShoppingCart', () => {
+  it('should apply 10% discount when promo code SAVE10 is applied', () => {
+    const cart = new ShoppingCart();
+    cart.addItem({ name: 'Book', priceCents: 2000 });
+    cart.applyPromoCode('SAVE10');
+    expect(cart.getTotalCents()).toBe(1800);
+  });
+});
+
+// Step 2 (GREEN): Minimal implementation to pass
+// Step 3 (REFACTOR): Clean up without breaking tests
+```
+
+### Exemplar 2: Test-Driven Development (TDD) Red-Green-Refactor Protocol TypeScript Type Contract
+```typescript
+export interface TddCycleState {
+  featureName: string;
+  currentPhase: 'RED' | 'GREEN' | 'REFACTOR';
+  failingTestName: string;
+  testRunnerCommand: string;
+  codeCoverageTarget: number;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Test-Driven Development (TDD) Red-Green-Refactor Protocol
+1. **Diagnosis**: Static analysis, typechecking, or unit tests fail validation rules during execution.
+2. **Recovery Protocol**:
+   - Step 1: Inspect detailed error log output in test/build terminal.
+   - Step 2: Formulate targeted hypothesis and isolate failing line or assertion.
+   - Step 3: Implement surgical code fix and re-run verification suite.
+
+### Scenario B: Missing or Incompatible Dependency
+1. **Diagnosis**: Required toolchain binary or library dependency is missing from the environment.
+2. **Recovery Protocol**:
+   - Step 1: Verify `package.json` engine requirements and local environment versions.
+   - Step 2: Install required peer dependencies cleanly with lockfile sync.
+   - Step 3: Resume runbook from Phase 1.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/to-spec/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: to-spec
+description: Transform raw notes, grilling output, or informal user feature requests into structured technical specifications and PRDs.
+metadata:
+  author: "Matt Pocock (mattpocock/skills)"
+  version: "1.0.0"
+  source: "https://github.com/mattpocock/skills"
+---
+
+# Technical Specification & PRD Generator
+
+## Overview & Purpose
+`to-spec` converts high-level ideas, notes, or grilling interview outcomes into comprehensive, production-ready Product Requirement Documents (PRDs) and technical specs.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `notes` | String | Yes | Conversation notes or raw feature requirements |
+| `spec_dir` | Path | Optional | Output path (default: `docs/specs/`) |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| PRD Document | `docs/specs/<feature-name>.md` | Formal technical specification |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Structural Framing
+1. Gather core goals, target personas, technical constraints, and user flows.
+2. Outline key components: Problem Statement, Success Metrics, Technical Architecture, Data Schema, Edge Cases, Out of Scope.
+
+### Phase 2 — Specification Drafting
+1. Draft detailed spec file using standard markdown template.
+2. Include explicit acceptance criteria for each requirement.
+
+### Phase 3 — Review & Refinement
+1. Highlight open questions or unresolved dependencies.
+2. Store artifact in `docs/specs/<feature-name>.md`.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter contains author attribution to Matt Pocock.
+- [ ] Spec includes Problem, Architecture, Acceptance Criteria, and Non-Goals.

package/registry/skills/to-tickets/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: to-tickets
+description: Decompose technical specifications and PRDs into actionable, prioritized backlog issues and task tickets.
+metadata:
+  author: "Matt Pocock (mattpocock/skills)"
+  version: "1.0.0"
+  source: "https://github.com/mattpocock/skills"
+---
+
+# Ticket & Work Breakdown Generator
+
+## Overview & Purpose
+`to-tickets` takes technical specs or PRDs and breaks them down into atomic, self-contained implementation tickets ready for development.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `spec_file` | Path | Yes | Path to specification or PRD markdown file |
+| `target_format` | String | Optional | Format (`github`, `linear`, or `markdown`) |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Ticket Breakdown | Inline / Issues | List of structured, actionable tickets |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Work Decomposition
+1. Analyze specification dependencies and identify milestone steps.
+2. Group tasks into sequential phases (Foundation -> Core Logic -> UI/Integration -> Verification).
+
+### Phase 2 — Ticket Writing
+For each task, define:
+- Title: Clear, action-oriented verb phrase.
+- Context & Motivation.
+- Concrete Acceptance Criteria (checkable checkboxes).
+- Verification command.
+
+### Phase 3 — Export
+1. Format for GitHub CLI (`gh issue create`), Linear, or append to `docs/tickets/`.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter contains author attribution to Matt Pocock.
+- [ ] Tickets are atomic and contain explicit acceptance criteria.

package/registry/skills/turso-distributed-sqlite/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: turso-distributed-sqlite
+description: Edge-distributed SQLite databases with LibSQL, embedded replicas, multi-tenant database-per-user architectures, and low-latency replication on Turso.
+metadata:
+  author: "Agents United Backend Group"
+  version: "1.0.0"
+  license: "MIT"
+---
+
+# Turso Distributed SQLite Playbook
+
+## Overview & Purpose
+`turso-distributed-sqlite` guides developers in leveraging LibSQL and Turso for distributed SQLite architectures with sub-millisecond edge reads and serverless scale.
+
+## Core Directives & Standards
+1. **Embedded Replicas for Edge Reads** — Configure `@libsql/client` with local file sync (`syncUrl`, `authToken`) for local microsecond read queries synchronized with remote Turso primary.
+2. **Multi-Tenant Database-per-Tenant Pattern** — Use the Turso Platform API to dynamically provision lightweight, isolated SQLite databases per customer organization.
+3. **Schema Migrations with Drizzle ORM** — Manage LibSQL migrations using Drizzle ORM (`drizzle-kit generate` & `drizzle-kit push`).
+4. **Connection Pooling & Batching** — Use LibSQL batch transactions (`client.batch([...])`) to execute multiple queries in a single HTTP roundtrip.
+
+## Verification Checklist
+- [ ] Database authentication tokens configured securely via environment variables.
+- [ ] Read replica synchronization verified under concurrent write loads.

package/registry/skills/ui-component-spec/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: ui-component-spec
+description: Production-grade Ui Component Spec playbook for design operations, UX systems, and growth strategy.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Ui Component Spec
+
+## Overview & Purpose
+The Ui Component Spec skill provides a deterministic framework for executing ui component spec processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute Ui Component Spec tasks.
+- Auditing existing product assets or workflows.
+- Standardizing ui-component-spec procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/ui-component-spec/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/ui-component-spec/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/ui-component-spec/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/ui-component-spec/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/ui-component-spec/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/ui-component-spec/ reports/ui-component-spec/
+   git commit -m "feat(ui-component-spec): implement Ui Component Spec playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Ui Component Spec Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "ui-component-spec"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/ui-component-spec/summary.json"
+```
+
+### Exemplar 2: Ui Component Spec Helper Module
+```typescript
+export function runUiComponentSpec(scope: string): boolean {
+  console.log('Running Ui Component Spec on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Ui Component Spec
+1. **Diagnosis**: Specification or code asset fails validation rules in ui-component-spec.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for Ui Component Spec
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/usability-testing-protocol/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: usability-testing-protocol
+description: Production-grade Usability Testing Protocol playbook for design operations, UX systems, and growth strategy.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Usability Testing Protocol
+
+## Overview & Purpose
+The Usability Testing Protocol skill provides a deterministic framework for executing usability testing protocol processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute Usability Testing Protocol tasks.
+- Auditing existing product assets or workflows.
+- Standardizing usability-testing-protocol procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/usability-testing-protocol/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/usability-testing-protocol/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/usability-testing-protocol/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/usability-testing-protocol/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/usability-testing-protocol/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/usability-testing-protocol/ reports/usability-testing-protocol/
+   git commit -m "feat(usability-testing-protocol): implement Usability Testing Protocol playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Usability Testing Protocol Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "usability-testing-protocol"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/usability-testing-protocol/summary.json"
+```
+
+### Exemplar 2: Usability Testing Protocol Helper Module
+```typescript
+export function runUsabilityTestingProtocol(scope: string): boolean {
+  console.log('Running Usability Testing Protocol on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Usability Testing Protocol
+1. **Diagnosis**: Specification or code asset fails validation rules in usability-testing-protocol.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for Usability Testing Protocol
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.