agents-united 1.0.0 → 1.2.0

package/registry/skills/docker-deployment/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: docker-deployment
+description: Production-grade Docker Deployment playbook for minimal footprint, rootless execution, and multi-stage builds.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Containerization, Dockerfile Hardening & Multi-Stage Deployment
+
+## Overview & Purpose
+The Containerization, Dockerfile Hardening & Multi-Stage Deployment skill provides a deterministic, battle-tested framework for executing docker-deployment processes across the Agents United multi-agent ecosystem.
+
+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 docker-deployment.
+- Auditing, implementing, or standardizing docker-deployment 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/docker-deployment/spec.md` | Full technical specification and architectural plan |
+| Implementation Files | `src/docker-deployment/*` | Production-ready source code, tests, and configurations |
+| Execution Report | `reports/docker-deployment/summary.json` | Verification metrics, test results, and audit summary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Application Workload & Architecture Profiling
+1. Analyze application runtime requirements: Node.js version, native C++ bindings, static assets.
+2. Define required environment variables, secret mounts, and volume persistent storage paths.
+3. Establish container memory limits, CPU quotas, and networking port requirements.
+4. Select minimal base image: node:24-alpine or distroless/nodejs24-debian12.
+5. Draft containerization strategy document.
+
+### Phase 2: Multi-Stage Dockerfile Construction & Hardening
+1. Structure multi-stage build separating compile dependencies from final production runtime.
+2. Optimize Docker layer caching: copy package*.json and run npm ci before copying source code.
+3. Implement non-root user execution (USER appuser) to prevent container breakout exploits.
+4. Add .dockerignore file excluding .git, node_modules, .env, and test artifacts.
+5. Configure explicit HEALTHCHECK directive testing HTTP endpoint readiness.
+
+### Phase 3: Image Build, Linting & Vulnerability Scanning
+1. Lint Dockerfile using Hadolint to catch syntax and security anti-patterns.
+2. Build container image: docker build -t app:latest .
+3. Scan image for CVEs using Trivy / Docker Scout: trivy image app:latest.
+4. Assert zero critical or high vulnerabilities in base OS and application packages.
+5. Verify final image size is minimal (<150MB for Node.js workloads).
+
+### Phase 4: Local Container Testing & Compose Verification
+1. Launch container in isolated bridge network using docker run or docker compose up.
+2. Execute HTTP smoke tests against healthcheck and API endpoints.
+3. Verify graceful shutdown handling on SIGTERM and SIGINT signals.
+4. Inspect container stdout/stderr logs to ensure structured JSON output formatting.
+5. Confirm volume mount persistence across container restarts.
+
+### Phase 5: Registry Publishing & Orchestrator Deployment
+1. Tag image with semantic version and git commit SHA: app:v2.0.0-sha123.
+2. Push image to container registry (ECR, GCR, Docker Hub) over TLS.
+3. Update Kubernetes deployment manifests / ECS task definitions with immutable image digest.
+4. Execute rolling deployment with automated rollback on healthcheck failure.
+5. Verify production workload stability.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Containerization, Dockerfile Hardening & Multi-Stage Deployment Configuration & Specification
+```yaml
+# Multi-stage hardened Dockerfile
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:24-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+COPY package*.json ./
+RUN npm ci --only=production && npm cache clean --force
+COPY --from=builder /app/dist ./dist
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+### Exemplar 2: Containerization, Dockerfile Hardening & Multi-Stage Deployment TypeScript Type Contract
+```typescript
+export interface ContainerSpec {
+  imageName: string;
+  tag: string;
+  baseImage: string;
+  multiStage: boolean;
+  nonRootUser: boolean;
+  exposedPorts: number[];
+  healthCheckEndpoint: string;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Containerization, Dockerfile Hardening & Multi-Stage Deployment
+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/domain-modeling/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: domain-modeling
+description: Build and sharpen project domain terminology, entity relationships, and ubiquitous language documented in CONTEXT.md.
+metadata:
+  author: "Matt Pocock (mattpocock/skills)"
+  version: "1.0.0"
+  source: "https://github.com/mattpocock/skills"
+---
+
+# Domain Modeling & Ubiquitous Language
+
+## Overview & Purpose
+`domain-modeling` builds a shared vocabulary between human developers and AI orchestrators. By recording domain entities, terminology, and key domain rules in `CONTEXT.md`, agents can communicate with precision, reducing context bloat and misunderstandings.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Introduction of new domain concepts, data models, or business logic.
+- Agent output using verbose or inconsistent terminology.
+
+### Prerequisites
+- Access to `CONTEXT.md` in repository root.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `terms` | Array | Yes | List of terms, entities, or rules to define or refine |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Domain Specification | `CONTEXT.md` | Single source of truth for domain vocabulary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Term Extraction
+1. Extract candidate terms from user prompts, design docs, or existing code.
+2. Identify ambiguous words that have multiple meanings across sub-domains.
+
+### Phase 2 — Definition & Boundary Mapping
+1. Formulate clear 1-to-2 sentence definitions for each domain primitive.
+2. Note explicit terms to avoid (anti-patterns / deprecated jargon).
+
+### Phase 3 — CONTEXT.md Sync
+1. Append or update section in `CONTEXT.md`.
+2. Verify formatting matches repository conventions.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter contains author attribution to Matt Pocock.
+- [ ] `CONTEXT.md` updated with concise term definitions.

package/registry/skills/email-drip-sequences/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: email-drip-sequences
+description: Production-grade Email Drip Sequences playbook for automated lifecycle nurturing, behavioral trigger branching, deliverability optimization (DKIM/DMARC), and trial-to-paid conversion.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Automated Lifecycle Email Drip Sequences & Behavioral Nurturing
+
+## Overview & Purpose
+The Email Drip Sequences skill provides an automated framework for designing, authoring, and deploying multi-stage lifecycle email campaigns.
+
+Following this skill structures behavioral trigger sequences (Welcome Onboarding, Feature Adoption Boost, Trial-to-Paid Upgrade, Inactivity Nurture, Abandoned Checkout), dynamic personalization merge tokens, spam filter avoidance, and technical deliverability compliance (SPF, DKIM, DMARC, BIMI, one-click List-Unsubscribe headers).
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Designing automated onboarding or product education email drip series for new signups.
+- Nurturing free trial users through automated milestones to maximize paid conversion.
+- Re-engaging dormant user accounts prior to churn.
+- Auditing email deliverability to resolve inboxing issues and spam complaints.
+
+### Prerequisites
+- Email Service Provider (ESP) API configured (Resend, SendGrid, Postmark, Customer.io).
+- Verified sending domain with configured SPF, DKIM, and DMARC DNS records.
+- Responsive HTML / React Email template components.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `sequence_type` | String | Yes | `welcome_onboarding`, `trial_conversion`, `feature_boost`, `winback` |
+| `sending_domain` | String | Yes | Authenticated sending domain (e.g. `mail.example.com`) |
+| `cadence_schedule` | Array<Object> | Yes | Step delay intervals (e.g. Day 0, Day 2, Day 5, Day 10) |
+| `behavioral_triggers`| Array<Object> | Optional | Conditional branches based on user product activity |
+| `template_engine` | String | Optional | `react-email`, `handlebars`, `mjml` |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Sequence Flowchart Spec | `docs/email-drip-sequences/sequence-spec.md` | Cadence timing, branching tree, and copy brief |
+| Email Templates | `src/emails/templates/*.tsx` | Responsive React Email components |
+| Deliverability Report | `reports/email-drip-sequences/deliverability.json` | DKIM, SPF, DMARC, and spam score audit results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Lifecycle Stage Mapping & Behavioral Trigger Logic Design
+1. Map customer lifecycle journey into discrete communication stages (Welcome, Activation, Upgrade, Retention).
+2. Define event triggers (e.g. `user_signed_up`, `first_project_created`, `trial_day_10_no_payment`).
+3. Formulate branching rules: if user activates in product on Day 1, bypass generic setup emails and send advanced power-user tips.
+4. Establish sequence exit conditions: instantly cancel onboarding drips upon subscription purchase or account deactivation.
+
+### Phase 2: Copywriting, Dynamic Tokenization & React Email Templating
+1. Author high-converting email copy for each cadence touchpoint:
+   - Email 1 (Day 0, Immediate): Welcome + single clear activation CTA.
+   - Email 2 (Day 2): Case study / customer spotlight demonstrating tangible ROI.
+   - Email 3 (Day 5): Overcoming common setup objections + invitation to live Q&A/office hours.
+   - Email 4 (Day 10): Urgent trial expiration notice + personalized upgrade discount.
+2. Build responsive templates using React Email / MJML ensuring 100% rendering parity across Apple Mail, Gmail, and Outlook.
+3. Inject dynamic personalization tokens (`{{firstName}}`, `{{workspaceName}}`, `{{daysRemaining}}`) with fallback defaults.
+
+### Phase 3: Delivery Delay & Smart Branching Workflow Automation
+1. Implement step delay scheduler handling timezone-aware delivery (send at 09:30 AM in recipient's local timezone).
+2. Configure webhook ingestion pipeline updating user state and triggering real-time branch decisions.
+3. Add frequency capping: ensure a user never receives more than 1 marketing email in a 24-hour window.
+4. Integrate unsubscribe event handler to guarantee immediate global suppression list synchronization.
+
+### Phase 4: Technical Deliverability Auditing (DKIM/DMARC/BIMI) & Spam Testing
+1. Verify DNS records: SPF (`v=spf1 include:... ~all`), DKIM (2048-bit key), and DMARC (`v=DMARC1; p=reject; rua=mailto:...`).
+2. Include RFC-8058 compliant `List-Unsubscribe: <https://example.com/unsub>, <mailto:unsub@example.com>` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click` headers.
+3. Run spam filter scanner (Mail-Tester / Litmus) ensuring score >= 9.5/10 with zero spam trigger words.
+4. Verify all transactional and promotional emails include valid physical mailing address and copyright notice.
+
+### Phase 5: A/B Subject Line Testing & Cohort Engagement Metrics
+1. Configure automated A/B test on subject lines across initial 20% of cohort before sending winner to remaining 80%.
+2. Track deliverability metrics: Delivery Rate (>99%), Open Rate (>40%), Click-to-Open Rate (>15%), Unsubscribe Rate (<0.3%).
+3. Compile sequence performance audit at `reports/email-drip-sequences/deliverability.json`.
+4. Commit email drip sequence components to repository.
+   ```bash
+   git add src/emails/ docs/email-drip-sequences/
+   git commit -m "feat(email-drip-sequences): implement automated lifecycle email drip engine"
+   ```
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Automated Email Drip Sequence State Machine Specification
+```json
+{
+  "version": "2.0.0",
+  "sequenceId": "trial-to-paid-nurture-v1",
+  "triggerEvent": "user.trial_started",
+  "exitEvents": ["subscription.created", "account.cancelled"],
+  "steps": [
+    {
+      "stepNumber": 1,
+      "delayHours": 0,
+      "templateId": "welcome-activation",
+      "subjectA": "Welcome to Agents United - Let's build your first team",
+      "subjectB": "Quick start: Deploy your AI team in 2 minutes"
+    },
+    {
+      "stepNumber": 2,
+      "delayHours": 48,
+      "templateId": "case-study-showcase",
+      "branchCondition": { "userHasCreatedProject": false },
+      "subjectA": "How Acme Corp scaled engineering velocity with Agents United"
+    },
+    {
+      "stepNumber": 3,
+      "delayHours": 240,
+      "templateId": "trial-ending-urgency",
+      "subjectA": "Your free trial ends in 48 hours - keep your workflows active"
+    }
+  ]
+}
+```
+
+### Exemplar 2: TypeScript React Email Responsive Component
+```typescript
+import React from 'react';
+
+export interface TrialEmailProps {
+  firstName: string;
+  daysRemaining: number;
+  upgradeUrl: string;
+}
+
+export function TrialEndingEmail({ firstName, daysRemaining, upgradeUrl }: TrialEmailProps): React.JSX.Element {
+  return (
+    <div style={{ fontFamily: 'Inter, Arial, sans-serif', maxWidth: '600px', margin: '0 auto', color: '#1E293B' }}>
+      <h2 style={{ fontSize: '20px', fontWeight: 700 }}>Hey {firstName || 'there'}, your trial expires in {daysRemaining} days</h2>
+      <p style={{ fontSize: '15px', lineHeight: '1.6' }}>
+        We hope you’ve enjoyed orchestrating autonomous multi-agent teams. Upgrade today to preserve your active workflows and avoid disruption.
+      </p>
+      <div style={{ margin: '24px 0' }}>
+        <a
+          href={upgradeUrl}
+          style={{ backgroundColor: '#2563EB', color: '#FFFFFF', padding: '12px 24px', borderRadius: '6px', textDecoration: 'none', fontWeight: 600 }}
+        >
+          Upgrade Your Plan Now
+        </a>
+      </div>
+      <p style={{ fontSize: '12px', color: '#64748B' }}>
+        Agents United Inc. • 100 Innovation Way, Suite 400 • San Francisco, CA 94105<br />
+        <a href="https://example.com/unsubscribe" style={{ color: '#64748B' }}>Unsubscribe instantly</a>
+      </p>
+    </div>
+  );
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Drip Emails Landing in Gmail Spam / Promotions Folders
+1. **Diagnosis**: Domain reputation dip or spam filter trigger caused by high link density or unverified DMARC record.
+2. **Recovery Protocol**:
+   - Step 1: Run SPF/DKIM/DMARC diagnostic checker to verify 100% authentication alignment.
+   - Step 2: Reduce image-to-text ratio and remove URL redirect shorteners from email body.
+   - Step 3: Implement domain warm-up schedule throttling daily send volume (50 -> 100 -> 250 -> 500 -> 1000).
+
+### Scenario B: User Receives Conflicting Emails Due to Overlapping Trigger Events
+1. **Diagnosis**: User triggers both "Trial Ending" and "Feature Adoption" drips simultaneously, causing inbox spam.
+2. **Recovery Protocol**:
+   - Step 1: Implement global priority queue suppressing lower-priority educational drips when high-priority transactional/billing drips are active.
+   - Step 2: Enforce strict minimum 24-hour spacing window between automated marketing messages.
+   - Step 3: Re-evaluate sequence enrollment state before each dispatch worker 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.
+- [ ] Deliverability standards (SPF, DKIM, DMARC, List-Unsubscribe) documented.
+- [ ] React Email / responsive template component exemplar provided.
+- [ ] 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/email-marketing-automation/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: email-marketing-automation
+description: Production-grade Email Marketing Automation playbook for design operations, UX systems, and growth strategy.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
+---
+
+# Email Marketing Automation
+
+## Overview & Purpose
+The Email Marketing Automation skill provides a deterministic framework for executing email marketing automation 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 Email Marketing Automation tasks.
+- Auditing existing product assets or workflows.
+- Standardizing email-marketing-automation 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/email-marketing-automation/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/email-marketing-automation/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/email-marketing-automation/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/email-marketing-automation/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/email-marketing-automation/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/email-marketing-automation/ reports/email-marketing-automation/
+   git commit -m "feat(email-marketing-automation): implement Email Marketing Automation playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Email Marketing Automation Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "email-marketing-automation"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/email-marketing-automation/summary.json"
+```
+
+### Exemplar 2: Email Marketing Automation Helper Module
+```typescript
+export function runEmailMarketingAutomation(scope: string): boolean {
+  console.log('Running Email Marketing Automation on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Email Marketing Automation
+1. **Diagnosis**: Specification or code asset fails validation rules in email-marketing-automation.
+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 Email Marketing Automation
+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/finishing-a-development-branch/SKILL.md

@@ -1,13 +1,129 @@
 ---
 name: finishing-a-development-branch
-description: Official Finishing A Development Branch skill for Agents United ecosystem providing runbooks and guidelines.
+description: Production-grade Branch Finalization playbook for clean git history, squash hygiene, and automated release validation.
+metadata:
+  author: "agents-united"
+  version: "2.0.0"
 ---
 
-# Finishing A Development Branch
+# Development Branch Finalization, Cleanup & PR Readiness
 
-This skill provides comprehensive instructions, runbooks, and guidelines for Finishing A Development Branch.
+## Overview & Purpose
+The Development Branch Finalization, Cleanup & PR Readiness skill provides a deterministic, battle-tested framework for executing finishing-a-development-branch 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 finishing-a-development-branch.
+- Auditing, implementing, or standardizing finishing-a-development-branch 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/finishing-a-development-branch/spec.md` | Full technical specification and architectural plan |
+| Implementation Files | `src/finishing-a-development-branch/*` | Production-ready source code, tests, and configurations |
+| Execution Report | `reports/finishing-a-development-branch/summary.json` | Verification metrics, test results, and audit summary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Working Tree Audit & Temporary File Cleanup
+1. Check git working directory status: git status --short.
+2. Remove temporary debug files, scratch scripts, and editor artifacts.
+3. Search for stray console.log, debugger, and unresolved TODO statements.
+4. Verify no sensitive secrets, API keys, or .env files are tracked in git.
+5. Ensure all modified files are properly staged.
+
+### Phase 2: Synchronization & Rebase against Target Branch
+1. Fetch latest changes from upstream remote: git fetch origin main.
+2. Rebase development branch onto latest main: git rebase origin/main.
+3. Resolve any merge conflicts cleanly, validating code logic after each resolved chunk.
+4. Run interactive rebase (git rebase -i) to squash messy WIP and fixup commits.
+5. Ensure all commit messages adhere to Conventional Commits specification.
+
+### Phase 3: Verification & Quality Gate Execution
+1. Run complete TypeScript typecheck: npm run typecheck.
+2. Execute full test suite: npm test.
+3. Execute production build: npm run build.
+4. Execute workspace doctor check: node dist/cli.js doctor.
+5. Confirm 100% test pass rate with zero lint or build errors.
+
+### Phase 4: Pull Request Description & Documentation Assembly
+1. Generate structured PR description covering Summary, Motivation, Changes, and Testing.
+2. Attach visual evidence (before/after screenshots or terminal recordings) for UI/CLI changes.
+3. Link related issue tickets and architecture decision records.
+4. Update project README and documentation files if features or flags were modified.
+5. Verify CI workflow requirements and reviewer assignments.
+
+### Phase 5: Push & PR Submission
+1. Push clean rebased branch to remote repository: git push -u origin branch-name --force-with-lease.
+2. Open Pull Request on GitHub / GitLab.
+3. Verify all automated GitHub Actions CI checks pass green.
+4. Request code review from designated subagents or human maintainers.
+5. Prepare for automated merge upon approval.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Development Branch Finalization, Cleanup & PR Readiness Configuration & Specification
+```yaml
+# Interactive rebase against main branch
+git fetch origin main
+git rebase -i origin/main
+# Ensure all commits follow Conventional Commits standard:
+# feat(scope): add feature description
+# fix(scope): resolve issue description
+```
+
+### Exemplar 2: Development Branch Finalization, Cleanup & PR Readiness TypeScript Type Contract
+```typescript
+export interface BranchChecklist {
+  branchName: string;
+  isRebasedOnMain: boolean;
+  cleanWorkingTree: boolean;
+  testsPassing: boolean;
+  typecheckPassing: boolean;
+  buildPassing: boolean;
+  conventionalCommits: boolean;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Development Branch Finalization, Cleanup & PR Readiness
+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.