agents-united 0.5.0

package/registry/skills/product-launch-playbook/SKILL.md

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

@@ -0,0 +1,213 @@
+---
+name: programmatic-seo
+description: Production-grade Programmatic SEO playbook for data-driven landing
+  page templates, dynamic URL routing, database seeding, schema JSON-LD, and
+  anti-thin-content guardrails.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 🤖
+disable-slash-command: true
+---
+
+# Programmatic SEO & Data-Driven Landing Page Generation Architecture
+
+## Overview & Purpose
+The Programmatic SEO skill provides a robust architectural framework for generating hundreds or thousands of high-intent, indexable landing pages from structured databases while rigorously avoiding Google search engine penalties for thin, low-value, or duplicate content.
+
+Following this skill establishes dynamic URL path hierarchies, high-value data-enriched page templates, automated internal linking meshes, XML sitemap indexing partitions, dynamic JSON-LD schema injection, and programmatic quality auditing.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Designing and deploying programmatic directory, comparison, or integration landing pages.
+- Scaling organic search traffic for long-tail keyword permutations (e.g. `{tool} vs {alternative}`, `best {category} for {platform}`).
+- Automating XML sitemap generation and indexation workflows for large-scale dynamic routes.
+- Auditing existing programmatic pages to eliminate thin content and cannibalization risks.
+
+### Prerequisites
+- Structured dataset or database table containing entity records, features, pricing, and pros/cons.
+- Framework supporting dynamic static site generation (Next.js App Router, Astro, SvelteKit).
+- Search Console / SEO crawling tools (Screaming Frog, Sitebulb) for pre-deployment validation.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `dataset_path` | String | Yes | Path to JSON, CSV, or database connection for page entities |
+| `url_pattern` | String | Yes | Dynamic route pattern (e.g. `/compare/[competitor]-alternatives`) |
+| `target_keyword_template` | String | Yes | Pattern for title and H1 tags (e.g. `Top 10 {competitor} Alternatives in 2026`) |
+| `min_unique_content_ratio` | Number | Optional | Minimum unique text ratio per page (default: 0.60) |
+| `max_urls_per_sitemap` | Number | Optional | Sitemap chunking limit (default: 10000) |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Programmatic Spec Spec | `docs/programmatic-seo/programmatic-spec.md` | Architecture, data schema, and template rules |
+| Dynamic Route Component | `src/app/compare/[slug]/page.tsx` | Next.js dynamic static generation template |
+| Dataset Seeder Module | `src/services/seo/dataset-seeder.ts` | Data validation, enrichment, and normalization |
+| Sitemap Generator | `src/services/seo/sitemap-generator.ts` | Chunked XML sitemap index and file builder |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Keyword Opportunity Modeling & Database Schema Design
+1. Conduct keyword permutation research identifying head terms and modifier facets (`[entity] + [modifier] + [location/use-case]`).
+2. Construct the underlying database or JSON schema. Every entity record must include:
+   - Primary identifier, display name, category, and slug.
+   - Unique value proposition paragraph (minimum 150 unique words per record).
+   - Structured comparison metrics (feature flags, pricing tiers, benchmarks).
+   - Curated user review snippets, pros/cons bullet points, and verified screenshots.
+3. Validate dataset integrity: assert that no two records share identical descriptions or duplicate slugs.
+
+### Phase 2: Dynamic URL Hierarchy & Template Modularization
+1. Author canonical URL routing schemas ensuring shallow directory depth (e.g. `/tools/{slug}` or `/alternatives-to/{slug}`).
+2. Build modular page template combining static anchor sections with dynamic, data-driven components:
+   - Dynamic Hero with keyword-optimized H1 and metadata summary.
+   - Interactive Comparison Matrix component rendering tabular feature differences.
+   - Dynamic FAQ Accordion populated from entity-specific Q&A data.
+   - User Review & Sentiment Breakdown visualization.
+3. Ensure every page includes unique, dynamically computed insights (e.g. price per seat calculations or latency benchmarks).
+
+### Phase 3: Automated Internal Linking Mesh & Breadcrumbs
+1. Implement contextual breadcrumb navigation on every programmatic page with Schema.org `BreadcrumbList` markup.
+2. Build related-entity recommendation algorithms linking each programmatic page to 5-8 contextually relevant sibling pages within the same category.
+3. Construct hub pages (category index hubs) that aggregate and distribute PageRank across programmatic leaf nodes.
+4. Verify that no page becomes an orphan node unreachable from the root site navigation graph.
+
+### Phase 4: Anti-Thin-Content Auditing & Duplicate Content Guardrails
+1. Execute algorithmic lexical similarity check (Jaccard similarity / TF-IDF cosine distance) across generated page outputs.
+2. Enforce minimum uniqueness threshold: reject any generated page where boilerplate exceeds 40% of total page content.
+3. If data is sparse for a specific entity record, automatically redirect or return `404/410` status rather than publishing a thin page.
+4. Dynamically inject unique user-generated or API-fetched data points (real-time uptime, changelog dates) to continuously differentiate pages.
+
+### Phase 5: XML Sitemap Partitioning, Static Generation & Indexation Monitoring
+1. Generate chunked XML sitemaps partitioned into subsets of <= 10,000 URLs with `<lastmod>` timestamps reflecting data updates.
+2. Create a master `sitemap_index.xml` referencing all partition files.
+3. Execute static build (`next build` / `astro build`) to pre-render static HTML pages for sub-millisecond TTFB.
+4. Run crawler audit asserting 100% of generated URLs return HTTP 200 with valid canonical tags matching target URLs.
+5. Commit programmatic SEO architecture to repository.
+   ```bash
+   git add src/app/ src/services/seo/ docs/programmatic-seo/
+   git commit -m "feat(programmatic-seo): implement scalable programmatic page generation engine"
+   ```
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Dynamic Static Page Generation Template (Next.js App Router)
+```typescript
+import { notFound } from 'next/navigation';
+import { getEntityBySlug, getAllEntitySlugs } from '@/services/seo/dataset-seeder';
+import { JsonLd } from '@/components/seo/JsonLd';
+
+export async function generateStaticParams() {
+  const slugs = await getAllEntitySlugs();
+  return slugs.map(slug => ({ slug }));
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entity = await getEntityBySlug(slug);
+  if (!entity) return {};
+
+  return {
+    title: `Top 10 ${entity.name} Alternatives & Competitors (2026)`,
+    description: `Compare ${entity.name} with leading competitors. In-depth pricing, feature analysis, and benchmarks.`,
+    alternates: {
+      canonical: `https://agents-united.dev/compare/${entity.slug}-alternatives`,
+    },
+  };
+}
+
+export default async function ComparePage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entity = await getEntityBySlug(slug);
+  if (!entity) notFound();
+
+  return (
+    <main className="max-w-5xl mx-auto px-4 py-8">
+      <h1 className="text-4xl font-extrabold mb-4">Top {entity.name} Alternatives & Competitors</h1>
+      <p className="text-lg text-slate-700 mb-8">{entity.customSummary}</p>
+      {/* Dynamic Data-Driven Comparison Matrix */}
+      <section className="border rounded-xl p-6 bg-slate-50 mb-8">
+        <h2 className="text-2xl font-bold mb-4">Feature Comparison Matrix</h2>
+        <div className="overflow-x-auto">
+          <table className="w-full text-left text-sm">
+            <thead>
+              <tr className="border-b">
+                <th className="py-2">Feature</th>
+                <th className="py-2">{entity.name}</th>
+                <th className="py-2">Agents United</th>
+              </tr>
+            </thead>
+            <tbody>
+              {entity.features.map((feat: any) => (
+                <tr key={feat.name} className="border-b">
+                  <td className="py-2 font-medium">{feat.name}</td>
+                  <td className="py-2">{feat.value}</td>
+                  <td className="py-2 text-emerald-600 font-semibold">{feat.ourValue}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </section>
+      <JsonLd data={{
+        '@context': 'https://schema.org',
+        '@type': 'WebPage',
+        name: `Top ${entity.name} Alternatives`,
+        description: entity.customSummary,
+      }} />
+    </main>
+  );
+}
+```
+
+### Exemplar 2: Chunked XML Sitemap Generator
+```typescript
+export interface SitemapUrlEntry {
+  loc: string;
+  lastmod: string;
+  changefreq: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  priority: number;
+}
+
+export function generateSitemapXml(urls: SitemapUrlEntry[]): string {
+  const entries = urls.map(u => `  <url>
+    <loc>${u.loc}</loc>
+    <lastmod>${u.lastmod}</lastmod>
+    <changefreq>${u.changefreq}</changefreq>
+    <priority>${u.priority.toFixed(1)}</priority>
+  </url>`).join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>`;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Google Flags Programmatic URLs as Thin / Soft 404
+1. **Diagnosis**: Google Search Console reports pages as "Crawled - currently not indexed" or "Soft 404" due to low unique content density.
+2. **Recovery Protocol**:
+   - Step 1: Run lexical similarity scanner identifying duplicate paragraph fragments across pages.
+   - Step 2: Enrich dataset with additional bespoke fields (user feedback quotes, automated API performance benchmarks).
+   - Step 3: Add `noindex, follow` tags to pages below the minimum content threshold until enrichment is completed.
+
+### Scenario B: Dynamic Parameter Slugs Conflict with Static Routes
+1. **Diagnosis**: Dynamic slug `/compare/[slug]` clashes with static system routes like `/compare/pricing` or `/compare/settings`.
+2. **Recovery Protocol**:
+   - Step 1: Implement reserved route blacklist in `dataset-seeder.ts` preventing slug generation for system keywords.
+   - Step 2: Use distinct subdirectory pathing for programmatic templates (e.g. `/compare/tools/[slug]`).
+   - Step 3: Add automated unit test asserting zero collision between dynamic dataset slugs and static app routes.
+
+## 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.
+- [ ] Next.js / framework static generation code exemplar provided with valid syntax fencing.
+- [ ] Lexical similarity threshold and anti-thin-content guardrails documented.
+- [ ] Chunked XML sitemap generation architecture detailed.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/rag-vector-pipeline/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: rag-vector-pipeline
+description: Advanced Retrieval-Augmented Generation (RAG) pipelines with
+  LangChain, LlamaIndex, hybrid search (dense + sparse), and cross-encoder
+  re-ranking.
+metadata:
+  author: LangChain & LlamaIndex / agents-united
+  version: 2.0.0
+  license: MIT
+  icon: 🧠
+disable-slash-command: true
+---
+
+# RAG Vector Pipeline Playbook
+
+## Overview & Purpose
+`rag-vector-pipeline` establishes architectural standards for building high-accuracy, hallucination-resistant Retrieval-Augmented Generation systems using LangChain and LlamaIndex.
+
+## When to Trigger
+Trigger this skill whenever:
+- Designing end-to-end RAG question-answering systems over unstructured documents.
+- Implementing semantic chunking, metadata enrichment, and vector embedding pipelines.
+- Building hybrid search combining sparse BM25 keyword matching and dense vector embeddings.
+- Integrating cross-encoder re-ranking models (Cohere, BGE) to improve context precision.
+
+## Input & Output Requirements
+- **Inputs**: Raw documents (Markdown, PDF, HTML), embedding model configuration, vector database credentials, and top-K query parameters.
+- **Outputs**: Indexed vector collections, query retrieval engines, grounded context passages with line citations, and answer synthesis pipelines.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Document Ingestion & Chunking Optimization
+- Partition raw documents using recursive character splitting (500-1000 tokens, 15% overlap).
+- Attach rich metadata tags (document ID, header hierarchy, URL, timestamp).
+
+### Phase 2 — Embedding Generation & Hybrid Indexing
+- Generate vector embeddings using dense models (OpenAI, BGE, Voyage).
+- Store vectors in vector collections alongside sparse inverted token indexes.
+
+### Phase 3 — Retrieval & Re-Ranking Execution
+- Retrieve top-20 candidate passages via Reciprocal Rank Fusion (RRF).
+- Re-rank candidates through cross-encoder models to yield top-5 high-relevance chunks.
+
+### Phase 4 — Answer Synthesis & Grounding Verification
+- Synthesize response with strict system prompts requiring source citations.
+- Verify context grounding score to block hallucinations before delivery.
+
+## Edge Cases & Boundary Conditions
+- **Missing Knowledge / Out-of-Domain Queries**: If retrieved context similarity score falls below threshold (< 0.70), return an explicit "information not found" answer rather than improvising.
+- **Contradictory Context Passages**: Use document recency timestamps and source priority weights to resolve conflicting claims.
+- **Large Context Exceeding LLM Window**: Implement summarization or hierarchical map-reduce retrieval chains.
+
+## Error Recovery & Fallbacks
+- When vector database connection drops, fall back to cached local vector index or keyword search.
+- If primary embedding API experiences rate limiting, switch to local embedding model (e.g. BAAI/bge-small-en-v1.5).
+
+## Code Exemplars & Patterns
+
+```python
+from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, StorageContext
+from llama_index.core.node_parser import SentenceSplitter
+from llama_index.core.postprocessor import SentenceTransformerRerank
+
+# 1. Load and partition documents
+documents = SimpleDirectoryReader("./docs").load_data()
+node_parser = SentenceSplitter(chunk_size=512, chunk_overlap=64)
+nodes = node_parser.get_nodes_from_documents(documents)
+
+# 2. Build index
+index = VectorStoreIndex(nodes)
+
+# 3. Configure query engine with cross-encoder re-ranking
+reranker = SentenceTransformerRerank(
+    model="BAAI/bge-reranker-large",
+    top_n=5
+)
+query_engine = index.as_query_engine(
+    similarity_top_k=20,
+    node_postprocessors=[reranker]
+)
+
+response = query_engine.query("What are the architectural guardrails for deployment?")
+print(str(response))
+```

package/registry/skills/react-best-practices/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: react-best-practices
+description: Modern React 19 and Next.js App Router performance patterns, Server
+  Components, streaming SSR, and client state boundaries.
+metadata:
+  author: Vercel Engineering (vercel-labs/agent-skills)
+  version: 1.0.0
+  source: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+  icon: ⚛️
+disable-slash-command: true
+---
+
+# React & Next.js Best Practices Playbook
+
+## Overview & Purpose
+`react-best-practices` enforces state-of-the-art frontend development standards for React and Next.js applications, prioritizing Core Web Vitals, minimal client bundle sizes, and clean architectural separation.
+
+## Rules & Constraints
+1. **Server Components by Default** — Keep components as Server Components unless interactive hooks (`useState`, `useEffect`, event handlers) are strictly required (`"use client"`).
+2. **Push Client Boundaries Down** — Isolate `"use client"` directives to the smallest interactive leaf nodes to minimize JavaScript shipped to browsers.
+3. **Suspense & Streaming SSR** — Wrap asynchronous data-fetching components in `<Suspense fallback={<Skeleton />}>` for progressive rendering.
+4. **Optimized Image & Font Loading** — Always use `next/image` with explicit aspect ratios and `next/font` for zero layout shift (CLS: 0).
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Component Architecture Review
+- Audit component tree to identify opportunities to hoist data fetching into Server Components.
+- Eliminate client-side `useEffect` waterfall fetching patterns in favor of direct server async/await.
+
+### Phase 2 — State Management & Transitions
+- Use React 19 `useActionState` and `useOptimistic` for form mutations.
+- Wrap non-urgent state updates in `startTransition` to maintain responsive user input (INP < 100ms).
+
+### Phase 3 — Verification
+- Audit Next.js production build bundle sizes with `@next/bundle-analyzer`.
+
+## Verification Checklist
+- [ ] Minimal client-side JavaScript bundle footprint.
+- [ ] No layout shift (CLS = 0) during page load.
+- [ ] Fast Interaction to Next Paint (INP < 100ms).

package/registry/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: receiving-code-review
+description: Production-grade Receiving Code Review playbook for processing
+  feedback, addressing revisions, and maintaining codebase standards.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 👀
+disable-slash-command: true
+---
+
+# Receiving Code Review Feedback & Constructive Revision
+
+## Overview & Purpose
+The Receiving Code Review Feedback & Constructive Revision skill provides a deterministic, battle-tested framework for executing receiving-code-review 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 receiving-code-review.
+- Auditing, implementing, or standardizing receiving-code-review 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/receiving-code-review/spec.md` | Full technical specification and architectural plan |
+| Implementation Files | `src/receiving-code-review/*` | Production-ready source code, tests, and configurations |
+| Execution Report | `reports/receiving-code-review/summary.json` | Verification metrics, test results, and audit summary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Feedback Ingestion & Categorization
+1. Read all pull request review comments completely before writing any code.
+2. Categorize feedback items: Security blockers, correctness issues, performance concerns, stylistic suggestions.
+3. Separate objective bugs and standard violations from subjective design preferences.
+4. Adopt an egoless mindset: focus on code quality, user impact, and team collective ownership.
+5. Create a checklist of actionable changes from review comments.
+
+### Phase 2: Clarification & Constructive Discussion
+1. If a comment is ambiguous, ask specific clarifying questions with proposed alternatives.
+2. If proposing an alternative approach, provide data, benchmarks, or documentation citations.
+3. Keep technical discussions focused on tradeoffs, constraints, and architecture standards.
+4. Reach clear consensus on contentious points before implementing complex refactors.
+5. Document agreed-upon resolution on the PR thread.
+
+### Phase 3: Targeted Implementation & Test Coverage
+1. Implement requested changes incrementally in clean, focused commits.
+2. Write or update automated tests that verify the requested behavior and prevent regression.
+3. Run full local verification: npm run typecheck && npm test && npm run build.
+4. Verify that addressing one comment did not inadvertently break unrelated modules.
+5. Confirm all automated CI tests pass.
+
+### Phase 4: Thread Resolution & Reviewer Notification
+1. Reply to each PR comment thread with a concise summary and reference to the commit SHA.
+2. Mark resolved conversation threads on GitHub / GitLab.
+3. If a suggestion was intentionally omitted, explain the technical rationale respectfully.
+4. Push updated commits to the PR branch.
+5. Re-request review from original reviewers.
+
+### Phase 5: Approval Verification & Merge Finalization
+1. Verify all required reviewer approvals are received.
+2. Ensure branch is up-to-date with base branch without conflicts.
+3. Squash and merge pull request following repository commit conventions.
+4. Delete merged feature branch from remote.
+5. Verify deployment pipeline completes successfully.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Receiving Code Review Feedback & Constructive Revision Configuration & Specification
+```yaml
+// Code review revision workflow
+// 1. Acknowledge comment and clarify intent
+// 2. Apply requested changes with targeted test coverage
+// 3. Reply with commit SHA and re-request review
+```
+
+### Exemplar 2: Receiving Code Review Feedback & Constructive Revision TypeScript Type Contract
+```typescript
+export interface ReviewFeedbackItem {
+  id: string;
+  reviewer: string;
+  file: string;
+  line: number;
+  category: 'security' | 'correctness' | 'performance' | 'style' | 'question';
+  status: 'pending' | 'addressed' | 'clarification-needed' | 'wont-fix';
+  resolutionCommitSha?: string;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Receiving Code Review Feedback & Constructive Revision
+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.