@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/cli-developer/steering/ux-patterns.md

@@ -0,0 +1,447 @@
+# CLI UX Patterns
+
+## Progress Indicators
+
+### When to Use Each Type
+
+| Type                           | When to Use          | Example                                        |
+| ------------------------------ | -------------------- | ---------------------------------------------- |
+| **Determinate** (progress bar) | Total count is known | Downloading 50 files, processing 200 records   |
+| **Indeterminate** (spinner)    | Duration unknown     | Connecting to server, waiting for API response |
+| **Multi-step** (sequential)    | Ordered pipeline     | Build → Test → Deploy                          |
+
+### Progress Bar Components
+
+```
+  Downloading |████████████░░░░░░░░| 60% | 30/50 files | 2.3 MB/s | ETA: 12s
+               ↑ visual bar          ↑ %    ↑ current/total  ↑ rate    ↑ ETA
+```
+
+| Component     | Include When                                     |
+| ------------- | ------------------------------------------------ |
+| Visual bar    | Always — gives immediate sense of progress       |
+| Percentage    | Always — precise progress indication             |
+| Current/Total | When count is meaningful (files, records, items) |
+| Rate          | For data transfer or long operations             |
+| ETA           | For operations > 10 seconds                      |
+
+### Spinner Styles
+
+Use spinners for operations where you can't predict completion:
+
+```
+⠋ Connecting to server...       # Braille dots (smooth, modern)
+⣾ Building project...           # Braille dots (alternative)
+◐ Running health checks...      # Circle quarters
+⠸ Uploading artifacts...        # Dots
+```
+
+**Rules:**
+
+- Update spinner text as the operation progresses through stages
+- Stop the spinner before printing other output
+- On success: replace with `✓` in green
+- On failure: replace with `✗` in red
+
+---
+
+## Color Usage
+
+### Semantic Colors
+
+| Color        | Meaning                | Symbol | Usage                                     |
+| ------------ | ---------------------- | ------ | ----------------------------------------- |
+| **Red**      | Error, failure, danger | `✗`    | Fatal errors, destructive actions         |
+| **Green**    | Success, completion    | `✓`    | Completed operations, confirmations       |
+| **Yellow**   | Warning, caution       | `⚠`    | Non-fatal issues, deprecation notices     |
+| **Blue**     | Info, neutral          | `ℹ`    | Status updates, informational messages    |
+| **Cyan**     | Highlight, accent      |        | Commands, paths, important values         |
+| **Dim/Gray** | Secondary, hint        |        | Timestamps, hints, less important details |
+| **Bold**     | Emphasis               |        | Key values, headings, important names     |
+
+### When to Disable Color
+
+```javascript
+function shouldUseColor() {
+  // Respect NO_COLOR standard (https://no-color.org/)
+  if (process.env.NO_COLOR !== undefined) return false;
+
+  // Disable in CI environments
+  if (process.env.CI) return false;
+
+  // Disable when not a TTY (piped output)
+  if (!process.stdout.isTTY) return false;
+
+  // Disable if TERM is "dumb"
+  if (process.env.TERM === "dumb") return false;
+
+  return true;
+}
+```
+
+### Accessibility: Symbols + Color, Not Color Alone
+
+```
+# GOOD — meaning conveyed by both symbol and color
+✓ Tests passed                    (green + checkmark)
+✗ Build failed                    (red + X)
+⚠ Deprecated API version          (yellow + warning symbol)
+ℹ Using default configuration     (blue + info symbol)
+
+# BAD — meaning conveyed by color only
+Tests passed                      (green text only)
+Build failed                      (red text only)
+```
+
+**Rule:** Every colored message must also have a symbol or text prefix that conveys the same meaning. Users with color blindness or monochrome terminals must still understand the output.
+
+---
+
+## Help Text Design
+
+### Command Help
+
+```
+USAGE
+  $ mycli <command> [options]
+
+COMMANDS
+  init <name>       Create a new project from a template
+  deploy            Deploy to target environment
+  config            Manage configuration settings
+  plugin            Manage CLI plugins
+
+OPTIONS
+  -v, --verbose     Enable verbose output
+  -q, --quiet       Suppress all output except errors
+  --no-color        Disable colored output
+  --version         Show version number
+  -h, --help        Show this help message
+
+EXAMPLES
+  $ mycli init my-app --template react
+  $ mycli deploy --env production --dry-run
+  $ mycli config set apiKey sk-1234
+```
+
+### Subcommand Help
+
+```
+USAGE
+  $ mycli deploy [options]
+
+DESCRIPTION
+  Deploy the current project to the specified environment.
+  Runs build, upload, and health check steps automatically.
+
+OPTIONS
+  -e, --env <name>        Target environment (required)
+                           Allowed: staging, production
+  --dry-run               Preview changes without deploying
+  --tag <tag>             Deploy a specific version tag
+  --timeout <seconds>     Deployment timeout (default: 300)
+  --skip-health-check     Skip post-deploy health check
+  --rollback-on-failure   Auto-rollback if health check fails
+
+EXAMPLES
+  # Deploy to staging
+  $ mycli deploy --env staging
+
+  # Dry run for production
+  $ mycli deploy --env production --dry-run
+
+  # Deploy specific version with auto-rollback
+  $ mycli deploy --env production --tag v1.2.0 --rollback-on-failure
+```
+
+**Rules:**
+
+- USAGE first, then DESCRIPTION (for subcommands), then OPTIONS, then EXAMPLES
+- Align option descriptions in columns
+- Show default values inline: `(default: 300)`
+- Show allowed values inline: `Allowed: staging, production`
+- Include 2-3 practical examples with comments
+
+---
+
+## Error Messages
+
+### Good Pattern: Context → Problem → Solution
+
+**Example 1: Missing configuration**
+
+```
+✗ Cannot deploy to production
+
+  Configuration file not found at ~/.mycli/config.yaml
+  This file is required for deployment credentials.
+
+  To fix this:
+    $ mycli config init
+    $ mycli config set deploy.token <your-token>
+```
+
+**Example 2: Network failure**
+
+```
+✗ Failed to connect to registry
+
+  Could not reach https://registry.example.com (connection timed out after 30s)
+
+  Possible fixes:
+    • Check your internet connection
+    • Verify the registry URL: mycli config get registry.url
+    • Try again with a longer timeout: --timeout 60
+    • If behind a proxy, set HTTPS_PROXY environment variable
+```
+
+**Example 3: Validation error**
+
+```
+✗ Invalid project name: "My Project"
+
+  Project names must be lowercase alphanumeric with hyphens only.
+  Examples: my-project, api-v2, hello-world
+
+  Try:
+    $ mycli init my-project
+```
+
+### Error Message Guidelines
+
+**DO:**
+
+- Be specific about what failed and where
+- Include the actual value that caused the error
+- Suggest concrete fixes (commands, flags, config changes)
+- Use plain language, not technical jargon
+- Show the relevant file path or URL
+
+**DON'T:**
+
+- Show raw stack traces to end users (use `--verbose` for debug info)
+- Use error codes without explanation (`Error: E4012`)
+- Be vague (`Something went wrong`, `An error occurred`)
+- Use technical jargon (`ECONNREFUSED`, `EPERM`, `segfault`)
+- Blame the user (`You did something wrong`)
+
+---
+
+## Interactive Prompts
+
+### Prompt Types
+
+| Type         | When to Use             | Example                   |
+| ------------ | ----------------------- | ------------------------- |
+| **Text**     | Free-form input         | Project name, description |
+| **Select**   | Single choice from list | Template, environment     |
+| **Checkbox** | Multiple choices        | Features, plugins         |
+| **Confirm**  | Yes/no decision         | Overwrite, deploy, delete |
+| **Password** | Sensitive input         | API keys, tokens          |
+
+### Prompt Guidelines
+
+- **Show keyboard hints:** `↑/↓: navigate • space: toggle • enter: confirm`
+- **Provide defaults:** Pre-fill with sensible values (current directory name, common choices)
+- **Handle Ctrl+C gracefully:** Print "Operation cancelled." and exit with code 130
+- **Never prompt in CI:** Detect non-interactive mode and use defaults or fail with a clear message
+- **Every prompt must have a flag equivalent:** `--name`, `--template`, `--yes` for confirm-all
+
+```
+? Project name: (my-project) █
+  ↑ question      ↑ default    ↑ cursor
+
+? Select a template: (Use arrow keys)
+❯ Default — Minimal starter template
+  React — React with Vite
+  Vue — Vue 3 with Vite
+  Node API — Express REST API
+
+? Select features: (Press <space> to select, <enter> to confirm)
+ ◉ TypeScript
+ ◉ ESLint
+ ◯ Prettier
+ ◯ Testing (Vitest)
+ ◯ Docker
+
+? Initialize git repository? (Y/n) █
+
+? Enter your API key: ********█
+```
+
+---
+
+## Output Formatting
+
+### Tables
+
+**Fancy (default for TTY):**
+
+```
+┌─────────────┬───────────┬─────────┬──────────────────┐
+│ Environment │ Status    │ Version │ Last Deploy      │
+├─────────────┼───────────┼─────────┼──────────────────┤
+│ production  │ ✓ healthy │ v2.1.0  │ 2024-01-15 14:30 │
+│ staging     │ ✓ healthy │ v2.2.0  │ 2024-01-16 09:15 │
+│ development │ ⚠ degraded│ v2.2.0  │ 2024-01-16 11:00 │
+└─────────────┴───────────┴─────────┴──────────────────┘
+```
+
+**Minimal (for piped output or `--plain`):**
+
+```
+ENVIRONMENT  STATUS     VERSION  LAST DEPLOY
+production   healthy    v2.1.0   2024-01-15 14:30
+staging      healthy    v2.2.0   2024-01-16 09:15
+development  degraded   v2.2.0   2024-01-16 11:00
+```
+
+**JSON (for `--json` flag):**
+
+```json
+[
+  {
+    "environment": "production",
+    "status": "healthy",
+    "version": "v2.1.0",
+    "lastDeploy": "2024-01-15T14:30:00Z"
+  },
+  {
+    "environment": "staging",
+    "status": "healthy",
+    "version": "v2.2.0",
+    "lastDeploy": "2024-01-16T09:15:00Z"
+  }
+]
+```
+
+### Lists
+
+**Bulleted:**
+
+```
+  Installed plugins:
+    • mycli-plugin-docker (v1.2.0)
+    • mycli-plugin-aws (v0.8.3)
+    • mycli-plugin-monitoring (v2.0.1)
+```
+
+**Numbered:**
+
+```
+  Migration steps:
+    1. Back up database
+    2. Run schema migration
+    3. Deploy new version
+    4. Verify health checks
+    5. Update DNS records
+```
+
+**Tree:**
+
+```
+  my-project/
+  ├── src/
+  │   ├── index.ts
+  │   ├── config.ts
+  │   └── routes/
+  │       ├── auth.ts
+  │       └── users.ts
+  ├── tests/
+  │   └── index.test.ts
+  ├── package.json
+  └── tsconfig.json
+```
+
+---
+
+## Status Messages
+
+### Real-Time Multi-Step Updates
+
+```
+  ℹ Deploying to production...
+
+  ✓ Building application          3.2s
+  ✓ Running tests                 12.1s
+  ✓ Uploading artifacts           1.8s
+  ⠸ Running health checks...
+```
+
+Each step transitions from spinner → checkmark (or X on failure):
+
+```
+  ⠸ Building application...       # In progress (spinner)
+  ✓ Building application  3.2s    # Complete (green check + duration)
+  ✗ Running tests                  # Failed (red X)
+```
+
+### Summary / Completion
+
+```
+  ┌──────────────────────────────────────┐
+  │                                      │
+  │   ✓ Deployed to production           │
+  │                                      │
+  │   Version:  v2.1.0                   │
+  │   URL:      https://app.example.com  │
+  │   Duration: 17.1s                    │
+  │                                      │
+  └──────────────────────────────────────┘
+```
+
+Or simpler:
+
+```
+  ✓ Done! Deployed v2.1.0 to production in 17.1s
+
+    URL: https://app.example.com
+    Dashboard: https://dashboard.example.com/deploys/abc123
+```
+
+---
+
+## Debugging & Verbose Mode
+
+### Output Levels
+
+**Normal (default):**
+
+```
+  ✓ Project created at ./my-project
+```
+
+**Verbose (`--verbose` or `-v`):**
+
+```
+  ℹ Creating project directory: /Users/dev/projects/my-project
+  ℹ Using template: react (v3.2.0)
+  ℹ Copying 23 template files...
+  ℹ Installing 15 dependencies...
+  ℹ Initializing git repository
+  ✓ Project created at ./my-project
+```
+
+**Debug (`--debug` or `MYCLI_DEBUG=1`):**
+
+```
+  [DEBUG 14:30:01.123] Config loaded from: /Users/dev/.mycli/config.yaml
+  [DEBUG 14:30:01.124] Template registry: https://registry.example.com/v2
+  [DEBUG 14:30:01.125] GET https://registry.example.com/v2/templates/react
+  [DEBUG 14:30:01.340] Response: 200 OK (215ms) — 4.2KB
+  [DEBUG 14:30:01.341] Template version: 3.2.0 (latest)
+  [DEBUG 14:30:01.342] Target directory: /Users/dev/projects/my-project
+  [DEBUG 14:30:01.342] Directory created: /Users/dev/projects/my-project
+  [DEBUG 14:30:01.345] Copying template files (23 files, 48KB)...
+  ℹ Creating project directory: /Users/dev/projects/my-project
+  ℹ Using template: react (v3.2.0)
+  ...
+```
+
+**Rules:**
+
+- Normal: Only results and errors. Minimal noise.
+- Verbose: Add step-by-step progress. Useful for understanding what happened.
+- Debug: Add timestamps, HTTP requests/responses, file paths, config values. Useful for bug reports.
+- Debug output goes to stderr so stdout remains parseable.
+- Never log secrets (API keys, tokens) even in debug mode.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/code-documenter/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: "code-documenter"
+description: "Use when adding docstrings, creating API documentation, or building documentation sites. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, tutorials, user guides."
+---
+
+
+# Code Documenter
+
+## Overview
+
+Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
+
+## Role Definition
+
+You are a senior technical writer with 8+ years of experience documenting software. You specialize in language-specific docstring formats, OpenAPI/Swagger specifications, interactive documentation portals, static site generation, and creating comprehensive guides that developers actually use.
+
+## When to Use This Skill
+
+- Adding docstrings to functions and classes
+- Creating OpenAPI/Swagger documentation
+- Building documentation sites (Docusaurus, MkDocs, VitePress)
+- Documenting APIs with framework-specific patterns
+- Creating interactive API portals (Swagger UI, Redoc, Stoplight)
+- Writing getting started guides and tutorials
+- Documenting multi-protocol APIs (REST, GraphQL, WebSocket, gRPC)
+- Generating documentation reports and coverage metrics
+
+## 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. **Report** - Generate coverage summary
+
+## Available Steering Files
+
+Load detailed guidance on-demand:
+
+| 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/workflows/workflows/agent-environment-setup/platforms/claude/skills/code-documenter/references/api-docs-fastapi-django.md

@@ -0,0 +1,169 @@
+# API Documentation: FastAPI & Django
+
+> Reference for: Code Documenter
+> Load when: Documenting Python API frameworks
+
+## 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 |