mumucc 0.4.4 → 0.4.10

package/defaults/plugin-seed/marketplaces/claude-code-workflows/plugins/documentation-generation/skills/openapi-spec-generation/references/code-first-and-tooling.md

@@ -0,0 +1,491 @@
+# OpenAPI Code-First Generation and Tooling
+
+Advanced patterns for generating OpenAPI specs from code (Python/FastAPI, TypeScript/tsoa), validation, linting, and SDK generation.
+
+## Template 2: Code-First Generation (Python/FastAPI)
+
+```python
+# FastAPI with automatic OpenAPI generation
+from fastapi import FastAPI, HTTPException, Query, Path, Depends
+from pydantic import BaseModel, Field, EmailStr
+from typing import Optional, List
+from datetime import datetime
+from uuid import UUID
+from enum import Enum
+
+app = FastAPI(
+    title="User Management API",
+    description="API for managing users and profiles",
+    version="2.0.0",
+    openapi_tags=[
+        {"name": "Users", "description": "User operations"},
+        {"name": "Profiles", "description": "Profile operations"},
+    ],
+    servers=[
+        {"url": "https://api.example.com/v2", "description": "Production"},
+        {"url": "http://localhost:8000", "description": "Development"},
+    ],
+)
+
+# Enums
+class UserStatus(str, Enum):
+    active = "active"
+    inactive = "inactive"
+    suspended = "suspended"
+    pending = "pending"
+
+class UserRole(str, Enum):
+    user = "user"
+    moderator = "moderator"
+    admin = "admin"
+
+# Models
+class UserBase(BaseModel):
+    email: EmailStr = Field(..., description="User email address")
+    name: str = Field(..., min_length=1, max_length=100, description="Display name")
+
+class UserCreate(UserBase):
+    role: UserRole = Field(default=UserRole.user)
+    metadata: Optional[dict] = Field(default=None, description="Custom metadata")
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "email": "user@example.com",
+                    "name": "John Doe",
+                    "role": "user"
+                }
+            ]
+        }
+    }
+
+class UserUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    status: Optional[UserStatus] = None
+    role: Optional[UserRole] = None
+    metadata: Optional[dict] = None
+
+class User(UserBase):
+    id: UUID = Field(..., description="Unique identifier")
+    status: UserStatus
+    role: UserRole
+    avatar: Optional[str] = Field(None, description="Avatar URL")
+    metadata: Optional[dict] = None
+    created_at: datetime = Field(..., alias="createdAt")
+    updated_at: Optional[datetime] = Field(None, alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+class Pagination(BaseModel):
+    page: int = Field(..., ge=1)
+    limit: int = Field(..., ge=1, le=100)
+    total: int = Field(..., ge=0)
+    total_pages: int = Field(..., ge=0, alias="totalPages")
+    has_next: bool = Field(..., alias="hasNext")
+    has_prev: bool = Field(..., alias="hasPrev")
+
+class UserListResponse(BaseModel):
+    data: List[User]
+    pagination: Pagination
+
+class ErrorDetail(BaseModel):
+    field: str
+    message: str
+
+class ErrorResponse(BaseModel):
+    code: str = Field(..., description="Error code")
+    message: str = Field(..., description="Error message")
+    details: Optional[List[ErrorDetail]] = None
+    request_id: Optional[str] = Field(None, alias="requestId")
+
+# Endpoints
+@app.get(
+    "/users",
+    response_model=UserListResponse,
+    tags=["Users"],
+    summary="List all users",
+    description="Returns a paginated list of users with optional filtering.",
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid request"},
+        401: {"model": ErrorResponse, "description": "Unauthorized"},
+    },
+)
+async def list_users(
+    page: int = Query(1, ge=1, description="Page number"),
+    limit: int = Query(20, ge=1, le=100, description="Items per page"),
+    status: Optional[UserStatus] = Query(None, description="Filter by status"),
+    search: Optional[str] = Query(None, min_length=2, max_length=100),
+):
+    """
+    List users with pagination and filtering.
+
+    - **page**: Page number (1-based)
+    - **limit**: Number of items per page (max 100)
+    - **status**: Filter by user status
+    - **search**: Search by name or email
+    """
+    # Implementation
+    pass
+
+@app.post(
+    "/users",
+    response_model=User,
+    status_code=201,
+    tags=["Users"],
+    summary="Create a new user",
+    responses={
+        400: {"model": ErrorResponse},
+        409: {"model": ErrorResponse, "description": "Email already exists"},
+    },
+)
+async def create_user(user: UserCreate):
+    """Create a new user and send welcome email."""
+    pass
+
+@app.get(
+    "/users/{user_id}",
+    response_model=User,
+    tags=["Users"],
+    summary="Get user by ID",
+    responses={404: {"model": ErrorResponse}},
+)
+async def get_user(
+    user_id: UUID = Path(..., description="User ID"),
+):
+    """Retrieve a specific user by their ID."""
+    pass
+
+@app.patch(
+    "/users/{user_id}",
+    response_model=User,
+    tags=["Users"],
+    summary="Update user",
+    responses={
+        400: {"model": ErrorResponse},
+        404: {"model": ErrorResponse},
+    },
+)
+async def update_user(
+    user_id: UUID = Path(..., description="User ID"),
+    user: UserUpdate = ...,
+):
+    """Update user attributes."""
+    pass
+
+@app.delete(
+    "/users/{user_id}",
+    status_code=204,
+    tags=["Users", "Admin"],
+    summary="Delete user",
+    responses={404: {"model": ErrorResponse}},
+)
+async def delete_user(
+    user_id: UUID = Path(..., description="User ID"),
+):
+    """Permanently delete a user."""
+    pass
+
+# Export OpenAPI spec
+if __name__ == "__main__":
+    import json
+    print(json.dumps(app.openapi(), indent=2))
+```
+
+## Template 3: Code-First (TypeScript/Express with tsoa)
+
+```typescript
+// tsoa generates OpenAPI from TypeScript decorators
+
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  Delete,
+  Route,
+  Path,
+  Query,
+  Body,
+  Response,
+  SuccessResponse,
+  Tags,
+  Security,
+  Example,
+} from "tsoa";
+
+// Models
+interface User {
+  /** Unique identifier */
+  id: string;
+  /** User email address */
+  email: string;
+  /** Display name */
+  name: string;
+  status: UserStatus;
+  role: UserRole;
+  /** Avatar URL */
+  avatar?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt?: Date;
+}
+
+enum UserStatus {
+  Active = "active",
+  Inactive = "inactive",
+  Suspended = "suspended",
+  Pending = "pending",
+}
+
+enum UserRole {
+  User = "user",
+  Moderator = "moderator",
+  Admin = "admin",
+}
+
+interface CreateUserRequest {
+  email: string;
+  name: string;
+  role?: UserRole;
+  metadata?: Record<string, unknown>;
+}
+
+interface UpdateUserRequest {
+  name?: string;
+  status?: UserStatus;
+  role?: UserRole;
+  metadata?: Record<string, unknown>;
+}
+
+interface Pagination {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+interface UserListResponse {
+  data: User[];
+  pagination: Pagination;
+}
+
+interface ErrorResponse {
+  code: string;
+  message: string;
+  details?: { field: string; message: string }[];
+  requestId?: string;
+}
+
+@Route("users")
+@Tags("Users")
+export class UsersController extends Controller {
+  /**
+   * List all users with pagination and filtering
+   * @param page Page number (1-based)
+   * @param limit Items per page (max 100)
+   * @param status Filter by user status
+   * @param search Search by name or email
+   */
+  @Get()
+  @Security("bearerAuth")
+  @Response<ErrorResponse>(400, "Invalid request")
+  @Response<ErrorResponse>(401, "Unauthorized")
+  @Example<UserListResponse>({
+    data: [
+      {
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        email: "john@example.com",
+        name: "John Doe",
+        status: UserStatus.Active,
+        role: UserRole.User,
+        createdAt: new Date("2024-01-15T10:30:00Z"),
+      },
+    ],
+    pagination: {
+      page: 1,
+      limit: 20,
+      total: 1,
+      totalPages: 1,
+      hasNext: false,
+      hasPrev: false,
+    },
+  })
+  public async listUsers(
+    @Query() page: number = 1,
+    @Query() limit: number = 20,
+    @Query() status?: UserStatus,
+    @Query() search?: string,
+  ): Promise<UserListResponse> {
+    // Implementation
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Create a new user
+   */
+  @Post()
+  @Security("bearerAuth")
+  @SuccessResponse(201, "Created")
+  @Response<ErrorResponse>(400, "Invalid request")
+  @Response<ErrorResponse>(409, "Email already exists")
+  public async createUser(@Body() body: CreateUserRequest): Promise<User> {
+    this.setStatus(201);
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Get user by ID
+   * @param userId User ID
+   */
+  @Get("{userId}")
+  @Security("bearerAuth")
+  @Response<ErrorResponse>(404, "User not found")
+  public async getUser(@Path() userId: string): Promise<User> {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Update user attributes
+   * @param userId User ID
+   */
+  @Patch("{userId}")
+  @Security("bearerAuth")
+  @Response<ErrorResponse>(400, "Invalid request")
+  @Response<ErrorResponse>(404, "User not found")
+  public async updateUser(
+    @Path() userId: string,
+    @Body() body: UpdateUserRequest,
+  ): Promise<User> {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Delete user
+   * @param userId User ID
+   */
+  @Delete("{userId}")
+  @Tags("Users", "Admin")
+  @Security("bearerAuth")
+  @SuccessResponse(204, "Deleted")
+  @Response<ErrorResponse>(404, "User not found")
+  public async deleteUser(@Path() userId: string): Promise<void> {
+    this.setStatus(204);
+  }
+}
+```
+
+## Template 4: Validation & Linting
+
+```bash
+# Install validation tools
+npm install -g @stoplight/spectral-cli
+npm install -g @redocly/cli
+
+# Spectral ruleset (.spectral.yaml)
+cat > .spectral.yaml << 'EOF'
+extends: ["spectral:oas", "spectral:asyncapi"]
+
+rules:
+  # Enforce operation IDs
+  operation-operationId: error
+
+  # Require descriptions
+  operation-description: warn
+  info-description: error
+
+  # Naming conventions
+  operation-operationId-valid-in-url: true
+
+  # Security
+  operation-security-defined: error
+
+  # Response codes
+  operation-success-response: error
+
+  # Custom rules
+  path-params-snake-case:
+    description: Path parameters should be snake_case
+    severity: warn
+    given: "$.paths[*].parameters[?(@.in == 'path')].name"
+    then:
+      function: pattern
+      functionOptions:
+        match: "^[a-z][a-z0-9_]*$"
+
+  schema-properties-camelCase:
+    description: Schema properties should be camelCase
+    severity: warn
+    given: "$.components.schemas[*].properties[*]~"
+    then:
+      function: casing
+      functionOptions:
+        type: camel
+EOF
+
+# Run Spectral
+spectral lint openapi.yaml
+
+# Redocly config (redocly.yaml)
+cat > redocly.yaml << 'EOF'
+extends:
+  - recommended
+
+rules:
+  no-invalid-media-type-examples: error
+  no-invalid-schema-examples: error
+  operation-4xx-response: warn
+  request-mime-type:
+    severity: error
+    allowedValues:
+      - application/json
+  response-mime-type:
+    severity: error
+    allowedValues:
+      - application/json
+      - application/problem+json
+
+theme:
+  openapi:
+    generateCodeSamples:
+      languages:
+        - lang: curl
+        - lang: python
+        - lang: javascript
+EOF
+
+# Run Redocly
+redocly lint openapi.yaml
+redocly bundle openapi.yaml -o bundled.yaml
+redocly preview-docs openapi.yaml
+```
+
+## SDK Generation
+
+```bash
+# OpenAPI Generator
+npm install -g @openapitools/openapi-generator-cli
+
+# Generate TypeScript client
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g typescript-fetch \
+  -o ./generated/typescript-client \
+  --additional-properties=supportsES6=true,npmName=@myorg/api-client
+
+# Generate Python client
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g python \
+  -o ./generated/python-client \
+  --additional-properties=packageName=api_client
+
+# Generate Go client
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g go \
+  -o ./generated/go-client
+```

package/defaults/plugin-seed/marketplaces/claude-code-workflows/plugins/documentation-standards/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "documentation-standards",
+  "version": "1.0.0",
+  "description": "HADS (Human-AI Document Standard) — semantic tagging convention for writing documentation that works efficiently for both human readers and AI models. Reduces token consumption and hallucination risk by separating machine-critical facts from human context.",
+  "author": {
+    "name": "Niksa Barlovic",
+    "email": "catcam@gmail.com"
+  },
+  "license": "MIT"
+}

package/defaults/plugin-seed/marketplaces/claude-code-workflows/plugins/documentation-standards/skills/hads/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: hads
+description: Use when writing technical documentation that needs to be readable by both humans and AI models, converting existing docs to HADS format, validating a HADS document, or optimizing documentation for token-efficient AI consumption.
+---
+
+# HADS Claude Skill
+**Version 1.0.0** · Human-AI Document Standard · 2026 · HADS 1.0.0
+
+---
+
+## AI READING INSTRUCTION
+
+This skill teaches Claude how to read, generate, and validate HADS documents.
+Read all `[SPEC]` blocks before responding to any HADS-related request.
+Read `[NOTE]` blocks if you need context on intent or edge cases.
+
+---
+
+## 1. WHAT IS HADS
+
+**[SPEC]**
+- HADS = Human-AI Document Standard
+- Convention for Markdown technical documentation
+- Four block types: `**[SPEC]**`, `**[NOTE]**`, `**[BUG]**`, `**[?]**`
+- Every HADS document requires: H1 title, version declaration, AI manifest
+- AI manifest appears before first content section, tells AI what to read/skip
+- File extension: `.md` — standard Markdown, no tooling required
+
+---
+
+## 2. BLOCK TYPES
+
+**[SPEC]**
+```
+**[SPEC]**   Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
+**[NOTE]**   Human context, history, examples. AI may skip.
+**[BUG]**    Verified failure + fix. Required fields: symptom, cause, fix. Always read.
+**[?]**      Unverified / inferred. Lower confidence. Always flagged.
+```
+
+Block tag rules:
+- Bold, on its own line: `**[SPEC]**`
+- Content follows immediately (no blank line between tag and content)
+- Multiple blocks of different types allowed per section
+- Titled BUG blocks allowed: `**[BUG] Short description**`
+- No nesting of blocks inside blocks
+
+---
+
+## 3. REQUIRED DOCUMENT STRUCTURE
+
+**[SPEC]**
+```markdown
+# Document Title
+**Version X.Y.Z** · Author · Date · [metadata]
+
+---
+
+## AI READING INSTRUCTION
+
+Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
+Read `[NOTE]` only if additional context is needed.
+`[?]` blocks are unverified — treat with lower confidence.
+
+---
+
+## 1. First Section
+
+**[SPEC]**
+...
+```
+
+Required elements in order:
+1. H1 title
+2. `**Version X.Y.Z**` in header (first 20 lines)
+3. AI manifest section before first content section
+4. Content sections (H2), subsections (H3)
+
+---
+
+## 4. HOW CLAUDE READS HADS
+
+**[SPEC]**
+When encountering a HADS document:
+1. Find and read the AI manifest first
+2. Read all `[SPEC]` blocks — these are ground truth
+3. Read all `[BUG]` blocks — always, before generating any code or config
+4. Read `[NOTE]` blocks only if `[SPEC]` is insufficient to answer the query
+5. Treat `[?]` content as hypothesis — note uncertainty in response
+
+Token optimization: for large documents, scan section headings first, then read only `[SPEC]` and `[BUG]` blocks in relevant sections.
+
+---
+
+## 5. HOW CLAUDE GENERATES HADS
+
+**[SPEC]**
+When asked to write documentation in HADS format:
+
+1. Start with header block (title, version, metadata)
+2. Add AI manifest — always include, never skip
+3. Organize content into numbered H2 sections
+4. For each fact: write as `[SPEC]` — terse, bullet or table or code
+5. For each "why" or context: write as `[NOTE]`
+6. For each known failure mode with confirmed fix: write as `[BUG]`
+7. For each unverified claim: write as `[?]`
+8. End with changelog section
+
+Content rules for `[SPEC]`:
+- Prefer bullet lists over prose
+- Prefer tables for multi-field facts
+- Prefer code blocks for syntax, formats, examples
+- Maximum 2 sentences of prose — if more needed, move to `[NOTE]`
+
+Content rules for `[BUG]`:
+- Always include: symptom, cause, fix
+- Optional: affected versions, workaround
+- Title on same line: `**[BUG] Short description**`
+
+**[NOTE]**
+When converting existing documentation to HADS: extract facts into `[SPEC]`, move narrative and history to `[NOTE]`, surface all known issues as `[BUG]`. Do not duplicate content between block types.
+
+---
+
+## 6. VALIDATION RULES
+
+**[SPEC]**
+A valid HADS document must have:
+- H1 title
+- `**Version X.Y.Z**` in first 20 lines
+- AI manifest before first content section
+- All block tags bold: `**[SPEC]**` not `[SPEC]` not *[SPEC]*
+- `[BUG]` blocks contain at minimum symptom + fix
+
+Validator: *(planned — not yet included in this release)*
+
+---
+
+## 7. EXAMPLE INTERACTIONS
+
+**[SPEC]**
+
+User: *"Write HADS documentation for this REST API"*
+→ Generate full HADS document: header, manifest, sections with [SPEC]/[NOTE]/[BUG] blocks
+
+User: *"Convert this README to HADS format"*
+→ Restructure existing content into HADS blocks, preserve all facts, add manifest
+
+User: *"Is this document valid HADS?"*
+→ Check: H1 title, version, manifest, block tag formatting, BUG block completeness
+
+User: *"Summarize this HADS document"*
+→ Read only [SPEC] and [BUG] blocks, return structured summary
+
+User: *"What does this API do?"* (HADS doc provided)
+→ Read manifest, read [SPEC] blocks in relevant sections, answer directly
+
+---
+
+## 8. DESIGN INTENT
+
+**[NOTE]**
+HADS exists because AI models increasingly read documentation before humans do. The format optimizes for this reality without sacrificing human readability.
+
+Key insight: the AI manifest is the core innovation. It lets even small (7B) models know what to read and what to skip — without requiring them to reason about document structure. Explicit is better than implicit for model consumption.
+
+When generating HADS, think of `[SPEC]` as the API surface and `[NOTE]` as the comments. `[BUG]` blocks are the most valuable content — they represent hard-won knowledge that saves others from hitting the same wall.
+
+---
+
+## 9. QUICK REFERENCE
+
+**[SPEC]**
+```
+Tag       | Bold format    | Reader  | Required content
+----------|----------------|---------|------------------
+[SPEC]    | **[SPEC]**     | AI      | Facts, terse
+[NOTE]    | **[NOTE]**     | Human   | Context, narrative
+[BUG]     | **[BUG] ...**  | Both    | Symptom + fix
+[?]       | **[?]**        | Both    | Unverified claims
+```
+
+Manifest minimum:
+```markdown
+## AI READING INSTRUCTION
+Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
+Read `[NOTE]` only if additional context is needed.
+`[?]` blocks are unverified.
+```

package/defaults/plugin-seed/marketplaces/claude-code-workflows/plugins/dotnet-contribution/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "dotnet-contribution",
+  "version": "1.0.1",
+  "description": "Comprehensive .NET backend development with C#, ASP.NET Core, Entity Framework Core, and Dapper for production-grade applications",
+  "author": {
+    "name": "Seth Hobson",
+    "email": "seth@major7apps.com"
+  },
+  "license": "MIT"
+}