aigroup-workflow 1.0.0

package/skills/jarvis/engineering-team/engineering/agenthub/skills/run/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: "run"
+description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation."
+command: /hub:run
+---
+
+# /hub:run — One-Shot Lifecycle
+
+Run the full AgentHub lifecycle in one command: initialize, capture baseline, spawn agents, evaluate results, and merge the winner.
+
+## Usage
+
+```
+/hub:run --task "Reduce p50 latency" --agents 3 \
+  --eval "pytest bench.py --json" --metric p50_ms --direction lower \
+  --template optimizer
+
+/hub:run --task "Refactor auth module" --agents 2 --template refactorer
+
+/hub:run --task "Cover untested utils" --agents 3 \
+  --eval "pytest --cov=utils --cov-report=json" --metric coverage_pct --direction higher \
+  --template test-writer
+
+/hub:run --task "Write 3 email subject lines for spring sale campaign" --agents 3 --judge
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--task` | Yes | Task description for agents |
+| `--agents` | No | Number of parallel agents (default: 3) |
+| `--eval` | No | Eval command to measure results (skip for LLM judge mode) |
+| `--metric` | No | Metric name to extract from eval output (required if `--eval` given) |
+| `--direction` | No | `lower` or `higher` — which direction is better (required if `--metric` given) |
+| `--template` | No | Agent template: `optimizer`, `refactorer`, `test-writer`, `bug-fixer` |
+
+## What It Does
+
+Execute these steps sequentially:
+
+### Step 1: Initialize
+
+Run `/hub:init` with the provided arguments:
+
+```bash
+python {skill_path}/scripts/hub_init.py \
+  --task "{task}" --agents {N} \
+  [--eval "{eval_cmd}"] [--metric {metric}] [--direction {direction}]
+```
+
+Display the session ID to the user.
+
+### Step 2: Capture Baseline
+
+If `--eval` was provided:
+
+1. Run the eval command in the current working directory
+2. Extract the metric value from stdout
+3. Display: `Baseline captured: {metric} = {value}`
+4. Append `baseline: {value}` to `.agenthub/sessions/{session-id}/config.yaml`
+
+If no `--eval` was provided, skip this step.
+
+### Step 3: Spawn Agents
+
+Run `/hub:spawn` with the session ID.
+
+If `--template` was provided, use the template dispatch prompt from `references/agent-templates.md` instead of the default dispatch prompt. Pass the eval command, metric, and baseline to the template variables.
+
+Launch all agents in a single message with multiple Agent tool calls (true parallelism).
+
+### Step 4: Wait and Monitor
+
+After spawning, inform the user that agents are running. When all agents complete (Agent tool returns results):
+
+1. Display a brief summary of each agent's work
+2. Proceed to evaluation
+
+### Step 5: Evaluate
+
+Run `/hub:eval` with the session ID:
+
+- If `--eval` was provided: metric-based ranking with `result_ranker.py`
+- If no `--eval`: LLM judge mode (coordinator reads diffs and ranks)
+
+If baseline was captured, pass `--baseline {value}` to `result_ranker.py` so deltas are shown.
+
+Display the ranked results table.
+
+### Step 6: Confirm and Merge
+
+Present the results to the user and ask for confirmation:
+
+```
+Agent-2 is the winner (128ms, -52ms from baseline).
+Merge agent-2's branch? [Y/n]
+```
+
+If confirmed, run `/hub:merge`. If declined, inform the user they can:
+- `/hub:merge --agent agent-{N}` to pick a different winner
+- `/hub:eval --judge` to re-evaluate with LLM judge
+- Inspect branches manually
+
+## Critical Rules
+
+- **Sequential execution** — each step depends on the previous
+- **Stop on failure** — if any step fails, report the error and stop
+- **User confirms merge** — never auto-merge without asking
+- **Template is optional** — without `--template`, agents use the default dispatch prompt from `/hub:spawn`

package/skills/jarvis/engineering-team/engineering/agenthub/skills/spawn/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: "spawn"
+description: "Launch N parallel subagents in isolated git worktrees to compete on the session task."
+command: /hub:spawn
+---
+
+# /hub:spawn — Launch Parallel Agents
+
+Spawn N subagents that work on the same task in parallel, each in an isolated git worktree.
+
+## Usage
+
+```
+/hub:spawn                                    # Spawn agents for the latest session
+/hub:spawn 20260317-143022                    # Spawn agents for a specific session
+/hub:spawn --template optimizer               # Use optimizer template for dispatch prompts
+/hub:spawn --template refactorer              # Use refactorer template
+```
+
+## Templates
+
+When `--template <name>` is provided, use the dispatch prompt from `references/agent-templates.md` instead of the default prompt below. Available templates:
+
+| Template | Pattern | Use Case |
+|----------|---------|----------|
+| `optimizer` | Edit → eval → keep/discard → repeat x10 | Performance, latency, size reduction |
+| `refactorer` | Restructure → test → iterate until green | Code quality, tech debt |
+| `test-writer` | Write tests → measure coverage → repeat | Test coverage gaps |
+| `bug-fixer` | Reproduce → diagnose → fix → verify | Bug fix with competing approaches |
+
+When using a template, replace all `{variables}` with values from the session config. Assign each agent a **different strategy** appropriate to the template and task — diverse strategies maximize the value of parallel exploration.
+
+## What It Does
+
+1. Load session config from `.agenthub/sessions/{session-id}/config.yaml`
+2. For each agent 1..N:
+   - Write task assignment to `.agenthub/board/dispatch/`
+   - Build agent prompt with task, constraints, and board write instructions
+3. Launch ALL agents in a **single message** with multiple Agent tool calls:
+
+```
+Agent(
+  prompt: "You are agent-{i} in hub session {session-id}.
+
+Your task: {task}
+
+Read your full assignment at .agenthub/board/dispatch/{seq}-agent-{i}.md
+
+Instructions:
+1. Work in your worktree — make changes, run tests, iterate
+2. Commit all changes with descriptive messages
+3. Write your result summary to .agenthub/board/results/agent-{i}-result.md
+   Include: approach taken, files changed, metric if available, confidence level
+4. Exit when done
+
+Constraints:
+- Do NOT read or modify other agents' work
+- Do NOT access .agenthub/board/results/ for other agents
+- Commit early and often with descriptive messages
+- If you hit a dead end, commit what you have and explain in your result",
+  isolation: "worktree"
+)
+```
+
+4. Update session state to `running` via:
+```bash
+python {skill_path}/scripts/session_manager.py --update {session-id} --state running
+```
+
+## Critical Rules
+
+- **All agents in ONE message** — spawn all Agent tool calls simultaneously for true parallelism
+- **isolation: "worktree"** is mandatory — each agent needs its own filesystem
+- **Never modify session config** after spawn — agents rely on stable configuration
+- **Each agent gets a unique board post** — dispatch posts are numbered sequentially
+
+## After Spawn
+
+Tell the user:
+- {N} agents launched in parallel
+- Each working in an isolated worktree
+- Monitor with `/hub:status`
+- Evaluate when done with `/hub:eval`

package/skills/jarvis/engineering-team/engineering/agenthub/skills/status/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: "status"
+description: "Show DAG state, agent progress, and branch status for an AgentHub session."
+command: /hub:status
+---
+
+# /hub:status — Session Status
+
+Display the current state of an AgentHub session: agent branches, commit counts, frontier status, and board updates.
+
+## Usage
+
+```
+/hub:status                        # Status for latest session
+/hub:status 20260317-143022        # Status for specific session
+```
+
+## What It Does
+
+1. Run session overview:
+```bash
+python {skill_path}/scripts/session_manager.py --status {session-id}
+```
+
+2. Run DAG analysis:
+```bash
+python {skill_path}/scripts/dag_analyzer.py --status --session {session-id}
+```
+
+3. Read recent board updates:
+```bash
+python {skill_path}/scripts/board_manager.py --read progress
+```
+
+## Output Format
+
+```
+Session: 20260317-143022 (running)
+Task: Optimize API response time below 100ms
+Agents: 3 | Base: dev
+
+AGENT    BRANCH                                        COMMITS  STATUS     LAST UPDATE
+agent-1  hub/20260317-143022/agent-1/attempt-1         3        frontier   2026-03-17 14:35:10
+agent-2  hub/20260317-143022/agent-2/attempt-1         5        frontier   2026-03-17 14:36:45
+agent-3  hub/20260317-143022/agent-3/attempt-1         2        frontier   2026-03-17 14:34:22
+
+Recent Board Activity:
+  [progress] agent-1: Implemented caching, running tests
+  [progress] agent-2: Hash map approach working, benchmarking
+  [results]  agent-2: Final result posted
+```
+
+Example output for a content task:
+
+```
+Session: 20260317-151200 (running)
+Task: Draft 3 competing taglines for product launch
+Agents: 3 | Base: dev
+
+AGENT    BRANCH                                        COMMITS  STATUS     LAST UPDATE
+agent-1  hub/20260317-151200/agent-1/attempt-1         2        frontier   2026-03-17 15:18:30
+agent-2  hub/20260317-151200/agent-2/attempt-1         2        frontier   2026-03-17 15:19:12
+agent-3  hub/20260317-151200/agent-3/attempt-1         1        frontier   2026-03-17 15:17:55
+
+Recent Board Activity:
+  [progress] agent-1: Storytelling angle draft complete, refining CTA
+  [progress] agent-2: Benefit-led draft done, testing urgency variant
+  [results]  agent-3: Final result posted
+```
+
+## After Status
+
+If all agents have posted results:
+- Suggest `/hub:eval` to rank results
+
+If some agents are still running:
+- Show which are done vs in-progress
+- Suggest waiting or checking again later

package/skills/jarvis/engineering-team/engineering/api-design-reviewer/SKILL.md

@@ -0,0 +1,421 @@
+---
+name: "api-design-reviewer"
+description: "API Design Reviewer"
+---
+
+# API Design Reviewer
+
+**Tier:** POWERFUL  
+**Category:** Engineering / Architecture  
+**Maintainer:** Claude Skills Team  
+
+## Overview
+
+The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards.
+
+## Core Capabilities
+
+### 1. API Linting and Convention Analysis
+- **Resource Naming Conventions**: Enforces kebab-case for resources, camelCase for fields
+- **HTTP Method Usage**: Validates proper use of GET, POST, PUT, PATCH, DELETE
+- **URL Structure**: Analyzes endpoint patterns for consistency and RESTful design
+- **Status Code Compliance**: Ensures appropriate HTTP status codes are used
+- **Error Response Formats**: Validates consistent error response structures
+- **Documentation Coverage**: Checks for missing descriptions and documentation gaps
+
+### 2. Breaking Change Detection
+- **Endpoint Removal**: Detects removed or deprecated endpoints
+- **Response Shape Changes**: Identifies modifications to response structures
+- **Field Removal**: Tracks removed or renamed fields in API responses
+- **Type Changes**: Catches field type modifications that could break clients
+- **Required Field Additions**: Flags new required fields that could break existing integrations
+- **Status Code Changes**: Detects changes to expected status codes
+
+### 3. API Design Scoring and Assessment
+- **Consistency Analysis** (30%): Evaluates naming conventions, response patterns, and structural consistency
+- **Documentation Quality** (20%): Assesses completeness and clarity of API documentation
+- **Security Implementation** (20%): Reviews authentication, authorization, and security headers
+- **Usability Design** (15%): Analyzes ease of use, discoverability, and developer experience
+- **Performance Patterns** (15%): Evaluates caching, pagination, and efficiency patterns
+
+## REST Design Principles
+
+### Resource Naming Conventions
+```
+✅ Good Examples:
+- /api/v1/users
+- /api/v1/user-profiles
+- /api/v1/orders/123/line-items
+
+❌ Bad Examples:
+- /api/v1/getUsers
+- /api/v1/user_profiles
+- /api/v1/orders/123/lineItems
+```
+
+### HTTP Method Usage
+- **GET**: Retrieve resources (safe, idempotent)
+- **POST**: Create new resources (not idempotent)
+- **PUT**: Replace entire resources (idempotent)
+- **PATCH**: Partial resource updates (not necessarily idempotent)
+- **DELETE**: Remove resources (idempotent)
+
+### URL Structure Best Practices
+```
+Collection Resources: /api/v1/users
+Individual Resources: /api/v1/users/123
+Nested Resources: /api/v1/users/123/orders
+Actions: /api/v1/users/123/activate (POST)
+Filtering: /api/v1/users?status=active&role=admin
+```
+
+## Versioning Strategies
+
+### 1. URL Versioning (Recommended)
+```
+/api/v1/users
+/api/v2/users
+```
+**Pros**: Clear, explicit, easy to route  
+**Cons**: URL proliferation, caching complexity
+
+### 2. Header Versioning
+```
+GET /api/users
+Accept: application/vnd.api+json;version=1
+```
+**Pros**: Clean URLs, content negotiation  
+**Cons**: Less visible, harder to test manually
+
+### 3. Media Type Versioning
+```
+GET /api/users
+Accept: application/vnd.myapi.v1+json
+```
+**Pros**: RESTful, supports multiple representations  
+**Cons**: Complex, harder to implement
+
+### 4. Query Parameter Versioning
+```
+/api/users?version=1
+```
+**Pros**: Simple to implement  
+**Cons**: Not RESTful, can be ignored
+
+## Pagination Patterns
+
+### Offset-Based Pagination
+```json
+{
+  "data": [...],
+  "pagination": {
+    "offset": 20,
+    "limit": 10,
+    "total": 150,
+    "hasMore": true
+  }
+}
+```
+
+### Cursor-Based Pagination
+```json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTIzfQ==",
+    "hasMore": true
+  }
+}
+```
+
+### Page-Based Pagination
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 3,
+    "pageSize": 10,
+    "totalPages": 15,
+    "totalItems": 150
+  }
+}
+```
+
+## Error Response Formats
+
+### Standard Error Structure
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "The request contains invalid parameters",
+    "details": [
+      {
+        "field": "email",
+        "code": "INVALID_FORMAT",
+        "message": "Email address is not valid"
+      }
+    ],
+    "requestId": "req-123456",
+    "timestamp": "2024-02-16T13:00:00Z"
+  }
+}
+```
+
+### HTTP Status Code Usage
+- **400 Bad Request**: Invalid request syntax or parameters
+- **401 Unauthorized**: Authentication required
+- **403 Forbidden**: Access denied (authenticated but not authorized)
+- **404 Not Found**: Resource not found
+- **409 Conflict**: Resource conflict (duplicate, version mismatch)
+- **422 Unprocessable Entity**: Valid syntax but semantic errors
+- **429 Too Many Requests**: Rate limit exceeded
+- **500 Internal Server Error**: Unexpected server error
+
+## Authentication and Authorization Patterns
+
+### Bearer Token Authentication
+```
+Authorization: Bearer <token>
+```
+
+### API Key Authentication
+```
+X-API-Key: <api-key>
+Authorization: Api-Key <api-key>
+```
+
+### OAuth 2.0 Flow
+```
+Authorization: Bearer <oauth-access-token>
+```
+
+### Role-Based Access Control (RBAC)
+```json
+{
+  "user": {
+    "id": "123",
+    "roles": ["admin", "editor"],
+    "permissions": ["read:users", "write:orders"]
+  }
+}
+```
+
+## Rate Limiting Implementation
+
+### Headers
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1640995200
+```
+
+### Response on Limit Exceeded
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Too many requests",
+    "retryAfter": 3600
+  }
+}
+```
+
+## HATEOAS (Hypermedia as the Engine of Application State)
+
+### Example Implementation
+```json
+{
+  "id": "123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "_links": {
+    "self": { "href": "/api/v1/users/123" },
+    "orders": { "href": "/api/v1/users/123/orders" },
+    "profile": { "href": "/api/v1/users/123/profile" },
+    "deactivate": { 
+      "href": "/api/v1/users/123/deactivate",
+      "method": "POST"
+    }
+  }
+}
+```
+
+## Idempotency
+
+### Idempotent Methods
+- **GET**: Always safe and idempotent
+- **PUT**: Should be idempotent (replace entire resource)
+- **DELETE**: Should be idempotent (same result)
+- **PATCH**: May or may not be idempotent
+
+### Idempotency Keys
+```
+POST /api/v1/payments
+Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
+```
+
+## Backward Compatibility Guidelines
+
+### Safe Changes (Non-Breaking)
+- Adding optional fields to requests
+- Adding fields to responses
+- Adding new endpoints
+- Making required fields optional
+- Adding new enum values (with graceful handling)
+
+### Breaking Changes (Require Version Bump)
+- Removing fields from responses
+- Making optional fields required
+- Changing field types
+- Removing endpoints
+- Changing URL structures
+- Modifying error response formats
+
+## OpenAPI/Swagger Validation
+
+### Required Components
+- **API Information**: Title, description, version
+- **Server Information**: Base URLs and descriptions
+- **Path Definitions**: All endpoints with methods
+- **Parameter Definitions**: Query, path, header parameters
+- **Request/Response Schemas**: Complete data models
+- **Security Definitions**: Authentication schemes
+- **Error Responses**: Standard error formats
+
+### Best Practices
+- Use consistent naming conventions
+- Provide detailed descriptions for all components
+- Include examples for complex objects
+- Define reusable components and schemas
+- Validate against OpenAPI specification
+
+## Performance Considerations
+
+### Caching Strategies
+```
+Cache-Control: public, max-age=3600
+ETag: "123456789"
+Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT
+```
+
+### Efficient Data Transfer
+- Use appropriate HTTP methods
+- Implement field selection (`?fields=id,name,email`)
+- Support compression (gzip)
+- Implement efficient pagination
+- Use ETags for conditional requests
+
+### Resource Optimization
+- Avoid N+1 queries
+- Implement batch operations
+- Use async processing for heavy operations
+- Support partial updates (PATCH)
+
+## Security Best Practices
+
+### Input Validation
+- Validate all input parameters
+- Sanitize user data
+- Use parameterized queries
+- Implement request size limits
+
+### Authentication Security
+- Use HTTPS everywhere
+- Implement secure token storage
+- Support token expiration and refresh
+- Use strong authentication mechanisms
+
+### Authorization Controls
+- Implement principle of least privilege
+- Use resource-based permissions
+- Support fine-grained access control
+- Audit access patterns
+
+## Tools and Scripts
+
+### api_linter.py
+Analyzes API specifications for compliance with REST conventions and best practices.
+
+**Features:**
+- OpenAPI/Swagger spec validation
+- Naming convention checks
+- HTTP method usage validation
+- Error format consistency
+- Documentation completeness analysis
+
+### breaking_change_detector.py
+Compares API specification versions to identify breaking changes.
+
+**Features:**
+- Endpoint comparison
+- Schema change detection
+- Field removal/modification tracking
+- Migration guide generation
+- Impact severity assessment
+
+### api_scorecard.py
+Provides comprehensive scoring of API design quality.
+
+**Features:**
+- Multi-dimensional scoring
+- Detailed improvement recommendations
+- Letter grade assessment (A-F)
+- Benchmark comparisons
+- Progress tracking
+
+## Integration Examples
+
+### CI/CD Integration
+```yaml
+- name: "api-linting"
+  run: python scripts/api_linter.py openapi.json
+
+- name: "breaking-change-detection"
+  run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json
+
+- name: "api-scorecard"
+  run: python scripts/api_scorecard.py openapi.json
+```
+
+### Pre-commit Hooks
+```bash
+#!/bin/bash
+python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json
+if [ $? -ne 0 ]; then
+  echo "API linting failed. Please fix the issues before committing."
+  exit 1
+fi
+```
+
+## Best Practices Summary
+
+1. **Consistency First**: Maintain consistent naming, response formats, and patterns
+2. **Documentation**: Provide comprehensive, up-to-date API documentation
+3. **Versioning**: Plan for evolution with clear versioning strategies
+4. **Error Handling**: Implement consistent, informative error responses
+5. **Security**: Build security into every layer of the API
+6. **Performance**: Design for scale and efficiency from the start
+7. **Backward Compatibility**: Minimize breaking changes and provide migration paths
+8. **Testing**: Implement comprehensive testing including contract testing
+9. **Monitoring**: Add observability for API usage and performance
+10. **Developer Experience**: Prioritize ease of use and clear documentation
+
+## Common Anti-Patterns to Avoid
+
+1. **Verb-based URLs**: Use nouns for resources, not actions
+2. **Inconsistent Response Formats**: Maintain standard response structures
+3. **Over-nesting**: Avoid deeply nested resource hierarchies
+4. **Ignoring HTTP Status Codes**: Use appropriate status codes for different scenarios
+5. **Poor Error Messages**: Provide actionable, specific error information
+6. **Missing Pagination**: Always paginate list endpoints
+7. **No Versioning Strategy**: Plan for API evolution from day one
+8. **Exposing Internal Structure**: Design APIs for external consumption, not internal convenience
+9. **Missing Rate Limiting**: Protect your API from abuse and overload
+10. **Inadequate Testing**: Test all aspects including error cases and edge conditions
+
+## Conclusion
+
+The API Design Reviewer skill provides a comprehensive framework for building, reviewing, and maintaining high-quality REST APIs. By following these guidelines and using the provided tools, development teams can create APIs that are consistent, well-documented, secure, and maintainable.
+
+Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle.