aigroup-workflow 2.1.1 → 2.2.0

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

@@ -0,0 +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

package/skills/backend/code-documenter/references/api-docs-fastapi-django.md

@@ -0,0 +1,166 @@
+# API Documentation: FastAPI & Django
+
+## FastAPI (Auto-generates from types)
+
+FastAPI automatically generates OpenAPI documentation from type hints and docstrings.
+
+### Endpoint Documentation
+
+```python
+from fastapi import FastAPI, HTTPException, status
+from pydantic import BaseModel, Field
+
+class UserCreate(BaseModel):
+    """User creation request body."""
+
+    name: str = Field(..., min_length=1, max_length=100, example="John Doe")
+    email: str = Field(..., example="john@example.com")
+
+class UserResponse(BaseModel):
+    """User response with generated ID."""
+
+    id: int = Field(..., example=1)
+    name: str
+    email: str
+
+@app.post(
+    "/users",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new user",
+    tags=["Users"],
+)
+async def create_user(user: UserCreate) -> UserResponse:
+    """Create a new user account.
+
+    Args:
+        user: User creation data including name and email.
+
+    Returns:
+        Created user with generated ID.
+
+    Raises:
+        HTTPException: 400 if email already exists.
+    """
+```
+
+### Router with Tags
+
+```python
+from fastapi import APIRouter
+
+router = APIRouter(
+    prefix="/users",
+    tags=["Users"],
+    responses={404: {"description": "Not found"}},
+)
+
+@router.get(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Get user by ID",
+)
+async def get_user(user_id: int) -> UserResponse:
+    """Retrieve a user by their unique identifier."""
+```
+
+## Django REST Framework (drf-spectacular)
+
+### ViewSet Documentation
+
+```python
+from rest_framework import viewsets, status
+from rest_framework.decorators import action
+from drf_spectacular.utils import extend_schema, OpenApiParameter
+
+class UserViewSet(viewsets.ModelViewSet):
+    """
+    ViewSet for managing user accounts.
+
+    list: Get all users with pagination.
+    create: Create a new user account.
+    retrieve: Get a specific user by ID.
+    update: Update all user fields.
+    partial_update: Update specific user fields.
+    destroy: Delete a user account.
+    """
+
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+
+    @extend_schema(
+        summary="Get current user",
+        description="Returns the authenticated user's profile",
+        responses={200: UserSerializer},
+    )
+    @action(detail=False, methods=["get"])
+    def me(self, request):
+        """Get the authenticated user's profile."""
+        serializer = self.get_serializer(request.user)
+        return Response(serializer.data)
+```
+
+### Serializer Documentation
+
+```python
+from rest_framework import serializers
+
+class UserSerializer(serializers.ModelSerializer):
+    """Serializer for user model with validation."""
+
+    class Meta:
+        model = User
+        fields = ["id", "name", "email", "created_at"]
+        read_only_fields = ["id", "created_at"]
+
+    name = serializers.CharField(
+        help_text="User's display name",
+        max_length=100,
+    )
+    email = serializers.EmailField(
+        help_text="User's email address (unique)",
+    )
+```
+
+### Custom Schema
+
+```python
+from drf_spectacular.utils import extend_schema, OpenApiExample
+
+@extend_schema(
+    request=UserCreateSerializer,
+    responses={
+        201: UserSerializer,
+        400: OpenApiTypes.OBJECT,
+    },
+    examples=[
+        OpenApiExample(
+            "Valid request",
+            value={"name": "John", "email": "john@example.com"},
+        ),
+    ],
+)
+def create(self, request):
+    """Create a new user."""
+```
+
+## Quick Reference
+
+| Framework | Documentation Source | Output |
+|-----------|---------------------|--------|
+| FastAPI | Type hints + docstrings | Auto Swagger UI |
+| DRF | Serializers + drf-spectacular | Auto Swagger UI |
+
+| FastAPI Decorator | Purpose |
+|-------------------|---------|
+| `summary` | Short endpoint description |
+| `description` | Detailed description |
+| `tags` | Group endpoints |
+| `response_model` | Response schema |
+| `responses` | Additional response codes |
+
+| DRF Decorator | Purpose |
+|---------------|---------|
+| `@extend_schema` | Customize schema |
+| `OpenApiParameter` | Query/path params |
+| `OpenApiExample` | Request examples |

package/skills/backend/code-documenter/references/api-docs-nestjs-express.md

@@ -0,0 +1,220 @@
+# API Documentation: NestJS & Express
+
+## NestJS (@nestjs/swagger)
+
+NestJS requires explicit decorators for OpenAPI documentation.
+
+### Controller Documentation
+
+```typescript
+import { Controller, Post, Body, Get, Param } from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiParam,
+  ApiBearerAuth,
+} from '@nestjs/swagger';
+
+@ApiTags('Users')
+@ApiBearerAuth()
+@Controller('users')
+export class UsersController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({
+    status: 201,
+    description: 'User created successfully',
+    type: UserDto,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid input data',
+  })
+  async create(@Body() dto: CreateUserDto): Promise<UserDto> {
+    return this.usersService.create(dto);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiParam({
+    name: 'id',
+    description: 'User unique identifier',
+    example: '123',
+  })
+  @ApiResponse({ status: 200, type: UserDto })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async findOne(@Param('id') id: string): Promise<UserDto> {
+    return this.usersService.findOne(id);
+  }
+}
+```
+
+### DTO Documentation
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsString, MinLength } from 'class-validator';
+
+export class CreateUserDto {
+  @ApiProperty({
+    description: "User's display name",
+    example: 'John Doe',
+    minLength: 1,
+    maxLength: 100,
+  })
+  @IsString()
+  @MinLength(1)
+  name: string;
+
+  @ApiProperty({
+    description: "User's email address",
+    example: 'john@example.com',
+  })
+  @IsEmail()
+  email: string;
+
+  @ApiPropertyOptional({
+    description: 'Profile picture URL',
+    example: 'https://example.com/avatar.jpg',
+  })
+  avatarUrl?: string;
+}
+```
+
+## Express (swagger-jsdoc)
+
+Express uses JSDoc comments with swagger annotations.
+
+### Setup
+
+```javascript
+const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerUi = require('swagger-ui-express');
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API Documentation',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./routes/*.js'],
+};
+
+const specs = swaggerJsdoc(options);
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
+```
+
+### Route Documentation
+
+```javascript
+/**
+ * @swagger
+ * /users:
+ *   post:
+ *     summary: Create a new user
+ *     tags: [Users]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/CreateUser'
+ *     responses:
+ *       201:
+ *         description: User created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User'
+ *       400:
+ *         description: Invalid input
+ */
+router.post('/users', createUser);
+
+/**
+ * @swagger
+ * /users/{id}:
+ *   get:
+ *     summary: Get user by ID
+ *     tags: [Users]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: User ID
+ *     responses:
+ *       200:
+ *         description: User found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User'
+ *       404:
+ *         description: User not found
+ */
+router.get('/users/:id', getUser);
+```
+
+### Schema Documentation
+
+```javascript
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CreateUser:
+ *       type: object
+ *       required:
+ *         - name
+ *         - email
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: User's display name
+ *           example: John Doe
+ *         email:
+ *           type: string
+ *           format: email
+ *           description: User's email address
+ *           example: john@example.com
+ *     User:
+ *       allOf:
+ *         - $ref: '#/components/schemas/CreateUser'
+ *         - type: object
+ *           properties:
+ *             id:
+ *               type: string
+ *               description: Unique identifier
+ *             createdAt:
+ *               type: string
+ *               format: date-time
+ */
+```
+
+## Quick Reference
+
+| NestJS Decorator | Purpose |
+|------------------|---------|
+| `@ApiTags()` | Group endpoints |
+| `@ApiOperation()` | Endpoint summary |
+| `@ApiResponse()` | Response documentation |
+| `@ApiParam()` | Path parameter |
+| `@ApiQuery()` | Query parameter |
+| `@ApiBody()` | Request body |
+| `@ApiBearerAuth()` | Auth requirement |
+| `@ApiProperty()` | DTO property |
+
+| Express swagger-jsdoc | Purpose |
+|-----------------------|---------|
+| `@swagger` | Start swagger block |
+| `tags` | Group endpoints |
+| `summary` | Short description |
+| `parameters` | Path/query params |
+| `requestBody` | Request body schema |
+| `responses` | Response schemas |
+| `$ref` | Reference schema |

package/skills/backend/code-documenter/references/coverage-reports.md

@@ -0,0 +1,125 @@
+# Coverage Reports
+
+## Documentation Coverage Report Template
+
+```markdown
+# Documentation Report: {project_name}
+
+## Summary
+- **Files analyzed**: 45
+- **Functions documented**: 120/150 (80%)
+- **Classes documented**: 25/25 (100%)
+- **API endpoints documented**: 30/30 (100%)
+
+## Coverage Before/After
+- Before: 45%
+- After: 92%
+
+## Files Modified
+
+| File | Functions Added | Notes |
+|------|-----------------|-------|
+| src/services/user.ts | 8 | All public methods |
+| src/services/auth.ts | 5 | Added examples |
+| src/controllers/users.ts | 6 | Added @Api decorators |
+| src/dto/user.dto.ts | 4 | Added @ApiProperty |
+
+## API Documentation
+
+- **Framework**: NestJS
+- **Strategy**: @nestjs/swagger decorators
+- **Swagger UI**: /api/docs
+- **OpenAPI spec**: /api-json
+
+## Documentation Style
+
+- **Python**: Google style docstrings
+- **TypeScript**: JSDoc with @param, @returns
+- **API**: OpenAPI 3.0 via decorators
+
+## Next Steps
+
+### Recommendations
+1. Run `npm run docs:lint` to validate JSDoc
+2. Add `eslint-plugin-jsdoc` to enforce documentation
+3. Consider adding examples for complex functions
+4. Set up documentation CI checks
+
+### Missing Documentation
+| File | Missing | Priority |
+|------|---------|----------|
+| src/utils/crypto.ts | 3 functions | High |
+| src/helpers/date.ts | 2 functions | Medium |
+
+### CI Integration
+```yaml
+# Add to CI pipeline
+- name: Check documentation
+  run: npm run docs:check
+
+- name: Generate API docs
+  run: npm run docs:generate
+```
+```
+
+## Checklist During Documentation
+
+```markdown
+## Documentation Checklist
+
+### Before Starting
+- [ ] Confirmed format preference (Google/JSDoc/etc.)
+- [ ] Identified files to exclude (tests, generated)
+- [ ] Detected framework for API docs
+
+### Functions/Methods
+- [ ] All public functions documented
+- [ ] Parameters described with types
+- [ ] Return values documented
+- [ ] Exceptions/errors documented
+- [ ] Examples added for complex functions
+
+### Classes
+- [ ] Class purpose described
+- [ ] Constructor parameters documented
+- [ ] Public methods documented
+- [ ] Important attributes explained
+
+### API Endpoints
+- [ ] All endpoints have summaries
+- [ ] Request bodies documented
+- [ ] Response schemas defined
+- [ ] Error responses documented
+- [ ] Authentication requirements noted
+
+### Final Checks
+- [ ] Ran documentation linter
+- [ ] Verified Swagger UI renders correctly
+- [ ] No inaccurate documentation
+- [ ] Coverage report generated
+```
+
+## Framework-Specific Linting
+
+```bash
+# JavaScript/TypeScript - ESLint
+npm install eslint-plugin-jsdoc --save-dev
+# Add to .eslintrc: "plugins": ["jsdoc"]
+
+# Python - pydocstyle
+pip install pydocstyle
+pydocstyle --convention=google src/
+
+# Python - interrogate (coverage)
+pip install interrogate
+interrogate -v src/
+```
+
+## Quick Reference
+
+| Metric | Good | Acceptable | Poor |
+|--------|------|------------|------|
+| Function coverage | >90% | 70-90% | <70% |
+| Class coverage | 100% | >90% | <90% |
+| API endpoint coverage | 100% | 100% | <100% |
+| Example coverage | >50% | 30-50% | <30% |