aigroup-workflow 2.2.1 → 2.2.2

package/skills/backend/architecture-designer/references/system-design.md

@@ -1,100 +1,100 @@
-# System Design Template
-
-## Design Template
-
-```markdown
-# System: {System Name}
-
-## Requirements
-
-### Functional
-- [What the system must do]
-- [Core features and capabilities]
-
-### Non-Functional
-- **Performance**: Response time < 200ms p95
-- **Availability**: 99.9% uptime (8.76 hours downtime/year)
-- **Scalability**: Support 10,000 concurrent users
-- **Security**: PCI DSS compliance required
-
-### Constraints
-- Budget: $X/month for infrastructure
-- Timeline: MVP in 3 months
-- Team: 5 backend, 3 frontend engineers
-
-## High-Level Architecture
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   Client    │────▶│  API Gateway │────▶│  Service    │
-│   (Web)     │     │   (Kong)    │     │  (Node.js)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                           │                   │
-                           ▼                   ▼
-                    ┌─────────────┐     ┌─────────────┐
-                    │    Auth     │     │  Database   │
-                    │  (Auth0)    │     │ (PostgreSQL)│
-                    └─────────────┘     └─────────────┘
-```
-
-## Component Details
-
-### API Layer
-- Technology: Node.js with Express/NestJS
-- Responsibilities: Request routing, validation, auth
-- Scaling: Horizontal via load balancer
-
-### Data Layer
-- Primary: PostgreSQL (transactions, relationships)
-- Cache: Redis (sessions, hot data)
-- Storage: S3 (files, images)
-
-### External Services
-- Auth: Auth0 (SSO, MFA)
-- Email: SendGrid (transactional)
-- Monitoring: Datadog (APM, logs)
-
-## Key Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| PostgreSQL over MongoDB | Relational data, ACID needed |
-| Redis for caching | Sub-ms latency required |
-| Auth0 over custom | Reduce security risk |
-
-## Scaling Strategy
-
-### Current (MVP)
-- Single region deployment
-- 2 API instances behind ALB
-- Single RDS instance
-
-### Future (10x growth)
-- Multi-region with CDN
-- Auto-scaling API (2-10 instances)
-- RDS read replicas
-
-## Security Considerations
-- All traffic over TLS 1.3
-- JWT tokens with 15-min expiry
-- Rate limiting: 100 req/min per user
-- WAF for common attacks
-
-## Failure Modes
-
-| Failure | Impact | Mitigation |
-|---------|--------|------------|
-| DB down | Full outage | Multi-AZ failover |
-| Cache down | Degraded perf | Fallback to DB |
-| Auth down | No new logins | Cache valid tokens |
-```
-
-## Quick Reference
-
-| Section | Key Questions |
-|---------|---------------|
-| Requirements | What must it do? How well? |
-| Architecture | What components? How connected? |
-| Decisions | Why these choices? |
-| Scaling | How to grow? |
-| Failures | What can break? How to recover? |
+# System Design Template
+
+## Design Template
+
+```markdown
+# System: {System Name}
+
+## Requirements
+
+### Functional
+- [What the system must do]
+- [Core features and capabilities]
+
+### Non-Functional
+- **Performance**: Response time < 200ms p95
+- **Availability**: 99.9% uptime (8.76 hours downtime/year)
+- **Scalability**: Support 10,000 concurrent users
+- **Security**: PCI DSS compliance required
+
+### Constraints
+- Budget: $X/month for infrastructure
+- Timeline: MVP in 3 months
+- Team: 5 backend, 3 frontend engineers
+
+## High-Level Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│  API Gateway │────▶│  Service    │
+│   (Web)     │     │   (Kong)    │     │  (Node.js)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                           │                   │
+                           ▼                   ▼
+                    ┌─────────────┐     ┌─────────────┐
+                    │    Auth     │     │  Database   │
+                    │  (Auth0)    │     │ (PostgreSQL)│
+                    └─────────────┘     └─────────────┘
+```
+
+## Component Details
+
+### API Layer
+- Technology: Node.js with Express/NestJS
+- Responsibilities: Request routing, validation, auth
+- Scaling: Horizontal via load balancer
+
+### Data Layer
+- Primary: PostgreSQL (transactions, relationships)
+- Cache: Redis (sessions, hot data)
+- Storage: S3 (files, images)
+
+### External Services
+- Auth: Auth0 (SSO, MFA)
+- Email: SendGrid (transactional)
+- Monitoring: Datadog (APM, logs)
+
+## Key Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| PostgreSQL over MongoDB | Relational data, ACID needed |
+| Redis for caching | Sub-ms latency required |
+| Auth0 over custom | Reduce security risk |
+
+## Scaling Strategy
+
+### Current (MVP)
+- Single region deployment
+- 2 API instances behind ALB
+- Single RDS instance
+
+### Future (10x growth)
+- Multi-region with CDN
+- Auto-scaling API (2-10 instances)
+- RDS read replicas
+
+## Security Considerations
+- All traffic over TLS 1.3
+- JWT tokens with 15-min expiry
+- Rate limiting: 100 req/min per user
+- WAF for common attacks
+
+## Failure Modes
+
+| Failure | Impact | Mitigation |
+|---------|--------|------------|
+| DB down | Full outage | Multi-AZ failover |
+| Cache down | Degraded perf | Fallback to DB |
+| Auth down | No new logins | Cache valid tokens |
+```
+
+## Quick Reference
+
+| Section | Key Questions |
+|---------|---------------|
+| Requirements | What must it do? How well? |
+| Architecture | What components? How connected? |
+| Decisions | Why these choices? |
+| Scaling | How to grow? |
+| Failures | What can break? How to recover? |

package/skills/backend/code-documenter/SKILL.md

@@ -1,147 +1,147 @@
----
-name: code-documenter
-description: Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: quality
-  triggers: documentation, docstrings, OpenAPI, Swagger, JSDoc, comments, API docs, tutorials, user guides, doc site
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: spec-miner, fullstack-guardian, code-reviewer
----
-
-# Code Documenter
-
-Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
-
-## When to Use This Skill
-
-Applies to any task involving code documentation, API specs, or developer-facing guides. See the reference table below for specific sub-topics.
-
-## Core Workflow
-
-1. **Discover** - Ask for format preference and exclusions
-2. **Detect** - Identify language and framework
-3. **Analyze** - Find undocumented code
-4. **Document** - Apply consistent format
-5. **Validate** - Test all code examples compile/run:
-   - Python: `python -m doctest file.py` for doctest blocks; `pytest --doctest-modules` for module-wide checks
-   - TypeScript/JavaScript: `tsc --noEmit` to confirm typed examples compile
-   - OpenAPI: validate spec with `npx @redocly/cli lint openapi.yaml`
-   - If validation fails: fix examples and re-validate before proceeding to the Report step
-6. **Report** - Generate coverage summary
-
-## Quick-Reference Examples
-
-### Google-style Docstring (Python)
-```python
-def fetch_user(user_id: int, active_only: bool = True) -> dict:
-    """Fetch a single user record by ID.
-
-    Args:
-        user_id: Unique identifier for the user.
-        active_only: When True, raise an error for inactive users.
-
-    Returns:
-        A dict containing user fields (id, name, email, created_at).
-
-    Raises:
-        ValueError: If user_id is not a positive integer.
-        UserNotFoundError: If no matching user exists.
-    """
-```
-
-### NumPy-style Docstring (Python)
-```python
-def compute_similarity(vec_a: np.ndarray, vec_b: np.ndarray) -> float:
-    """Compute cosine similarity between two vectors.
-
-    Parameters
-    ----------
-    vec_a : np.ndarray
-        First input vector, shape (n,).
-    vec_b : np.ndarray
-        Second input vector, shape (n,).
-
-    Returns
-    -------
-    float
-        Cosine similarity in the range [-1, 1].
-
-    Raises
-    ------
-    ValueError
-        If vectors have different lengths.
-    """
-```
-
-### JSDoc (TypeScript)
-```typescript
-/**
- * Fetches a paginated list of products from the catalog.
- *
- * @param {string} categoryId - The category to filter by.
- * @param {number} [page=1] - Page number (1-indexed).
- * @param {number} [limit=20] - Maximum items per page.
- * @returns {Promise<ProductPage>} Resolves to a page of product records.
- * @throws {NotFoundError} If the category does not exist.
- *
- * @example
- * const page = await fetchProducts('electronics', 2, 10);
- * console.log(page.items);
- */
-async function fetchProducts(
-  categoryId: string,
-  page = 1,
-  limit = 20
-): Promise<ProductPage> { ... }
-```
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Python Docstrings | `references/python-docstrings.md` | Google, NumPy, Sphinx styles |
-| TypeScript JSDoc | `references/typescript-jsdoc.md` | JSDoc patterns, TypeScript |
-| FastAPI/Django API | `references/api-docs-fastapi-django.md` | Python API documentation |
-| NestJS/Express API | `references/api-docs-nestjs-express.md` | Node.js API documentation |
-| Coverage Reports | `references/coverage-reports.md` | Generating documentation reports |
-| Documentation Systems | `references/documentation-systems.md` | Doc sites, static generators, search, testing |
-| Interactive API Docs | `references/interactive-api-docs.md` | OpenAPI 3.1, portals, GraphQL, WebSocket, gRPC, SDKs |
-| User Guides & Tutorials | `references/user-guides-tutorials.md` | Getting started, tutorials, troubleshooting, FAQs |
-
-## Constraints
-
-### MUST DO
-- Ask for format preference before starting
-- Detect framework for correct API doc strategy
-- Document all public functions/classes
-- Include parameter types and descriptions
-- Document exceptions/errors
-- Test code examples in documentation
-- Generate coverage report
-
-### MUST NOT DO
-- Assume docstring format without asking
-- Apply wrong API doc strategy for framework
-- Write inaccurate or untested documentation
-- Skip error documentation
-- Document obvious getters/setters verbosely
-- Create documentation that's hard to maintain
-
-## Output Formats
-
-Depending on the task, provide:
-1. **Code Documentation:** Documented files + coverage report
-2. **API Docs:** OpenAPI specs + portal configuration
-3. **Doc Sites:** Site configuration + content structure + build instructions
-4. **Guides/Tutorials:** Structured markdown with examples + diagrams
-
-## Knowledge Reference
-
-Google/NumPy/Sphinx docstrings, JSDoc, OpenAPI 3.0/3.1, AsyncAPI, gRPC/protobuf, FastAPI, Django, NestJS, Express, GraphQL, Docusaurus, MkDocs, VitePress, Swagger UI, Redoc, Stoplight
+---
+name: code-documenter
+description: Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: quality
+  triggers: documentation, docstrings, OpenAPI, Swagger, JSDoc, comments, API docs, tutorials, user guides, doc site
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: spec-miner, fullstack-guardian, code-reviewer
+---
+
+# Code Documenter
+
+Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
+
+## When to Use This Skill
+
+Applies to any task involving code documentation, API specs, or developer-facing guides. See the reference table below for specific sub-topics.
+
+## Core Workflow
+
+1. **Discover** - Ask for format preference and exclusions
+2. **Detect** - Identify language and framework
+3. **Analyze** - Find undocumented code
+4. **Document** - Apply consistent format
+5. **Validate** - Test all code examples compile/run:
+   - Python: `python -m doctest file.py` for doctest blocks; `pytest --doctest-modules` for module-wide checks
+   - TypeScript/JavaScript: `tsc --noEmit` to confirm typed examples compile
+   - OpenAPI: validate spec with `npx @redocly/cli lint openapi.yaml`
+   - If validation fails: fix examples and re-validate before proceeding to the Report step
+6. **Report** - Generate coverage summary
+
+## Quick-Reference Examples
+
+### Google-style Docstring (Python)
+```python
+def fetch_user(user_id: int, active_only: bool = True) -> dict:
+    """Fetch a single user record by ID.
+
+    Args:
+        user_id: Unique identifier for the user.
+        active_only: When True, raise an error for inactive users.
+
+    Returns:
+        A dict containing user fields (id, name, email, created_at).
+
+    Raises:
+        ValueError: If user_id is not a positive integer.
+        UserNotFoundError: If no matching user exists.
+    """
+```
+
+### NumPy-style Docstring (Python)
+```python
+def compute_similarity(vec_a: np.ndarray, vec_b: np.ndarray) -> float:
+    """Compute cosine similarity between two vectors.
+
+    Parameters
+    ----------
+    vec_a : np.ndarray
+        First input vector, shape (n,).
+    vec_b : np.ndarray
+        Second input vector, shape (n,).
+
+    Returns
+    -------
+    float
+        Cosine similarity in the range [-1, 1].
+
+    Raises
+    ------
+    ValueError
+        If vectors have different lengths.
+    """
+```
+
+### JSDoc (TypeScript)
+```typescript
+/**
+ * Fetches a paginated list of products from the catalog.
+ *
+ * @param {string} categoryId - The category to filter by.
+ * @param {number} [page=1] - Page number (1-indexed).
+ * @param {number} [limit=20] - Maximum items per page.
+ * @returns {Promise<ProductPage>} Resolves to a page of product records.
+ * @throws {NotFoundError} If the category does not exist.
+ *
+ * @example
+ * const page = await fetchProducts('electronics', 2, 10);
+ * console.log(page.items);
+ */
+async function fetchProducts(
+  categoryId: string,
+  page = 1,
+  limit = 20
+): Promise<ProductPage> { ... }
+```
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Python Docstrings | `references/python-docstrings.md` | Google, NumPy, Sphinx styles |
+| TypeScript JSDoc | `references/typescript-jsdoc.md` | JSDoc patterns, TypeScript |
+| FastAPI/Django API | `references/api-docs-fastapi-django.md` | Python API documentation |
+| NestJS/Express API | `references/api-docs-nestjs-express.md` | Node.js API documentation |
+| Coverage Reports | `references/coverage-reports.md` | Generating documentation reports |
+| Documentation Systems | `references/documentation-systems.md` | Doc sites, static generators, search, testing |
+| Interactive API Docs | `references/interactive-api-docs.md` | OpenAPI 3.1, portals, GraphQL, WebSocket, gRPC, SDKs |
+| User Guides & Tutorials | `references/user-guides-tutorials.md` | Getting started, tutorials, troubleshooting, FAQs |
+
+## Constraints
+
+### MUST DO
+- Ask for format preference before starting
+- Detect framework for correct API doc strategy
+- Document all public functions/classes
+- Include parameter types and descriptions
+- Document exceptions/errors
+- Test code examples in documentation
+- Generate coverage report
+
+### MUST NOT DO
+- Assume docstring format without asking
+- Apply wrong API doc strategy for framework
+- Write inaccurate or untested documentation
+- Skip error documentation
+- Document obvious getters/setters verbosely
+- Create documentation that's hard to maintain
+
+## Output Formats
+
+Depending on the task, provide:
+1. **Code Documentation:** Documented files + coverage report
+2. **API Docs:** OpenAPI specs + portal configuration
+3. **Doc Sites:** Site configuration + content structure + build instructions
+4. **Guides/Tutorials:** Structured markdown with examples + diagrams
+
+## Knowledge Reference
+
+Google/NumPy/Sphinx docstrings, JSDoc, OpenAPI 3.0/3.1, AsyncAPI, gRPC/protobuf, FastAPI, Django, NestJS, Express, GraphQL, Docusaurus, MkDocs, VitePress, Swagger UI, Redoc, Stoplight