@poolzin/plcode 2.1.1 → 3.0.1

package/.plcode/skill/core/agents-md-generator/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: agents-md-generator
+description: Generate hierarchical AGENTS.md structures for codebases. Use when user asks to create AGENTS.md files, analyze codebase for AI agent documentation, set up AI-friendly project documentation, or generate context files for AI coding assistants. Triggers on "create AGENTS.md", "generate agents", "analyze codebase for AI", "AI documentation setup", "hierarchical agents".
+category: documents
+---
+
+# AGENTS.md Generator
+
+Generate hierarchical AGENTS.md structures optimized for AI coding agents with minimal token usage.
+
+## Core Principles
+
+1. **Root AGENTS.md is LIGHTWEIGHT** - Only universal guidance, links to sub-files (~100-200 lines max)
+2. **Nearest-wins hierarchy** - Agents read closest AGENTS.md to file being edited
+3. **JIT indexing** - Provide paths/globs/commands, NOT full content
+4. **Token efficiency** - Small, actionable guidance over encyclopedic docs
+5. **Sub-folder files have MORE detail** - Specific patterns, examples, commands
+
+## Workflow
+
+### Phase 1: Repository Analysis
+
+Analyze and report:
+
+1. **Repository type**: Monorepo, multi-package, or simple?
+2. **Tech stack**: Languages, frameworks, key tools
+3. **Major directories** needing own AGENTS.md:
+   - Apps (`apps/web`, `apps/api`, `apps/mobile`)
+   - Services (`services/auth`, `services/transcribe`)
+   - Packages (`packages/ui`, `packages/shared`)
+   - Workers (`workers/queue`, `workers/cron`)
+4. **Build system**: pnpm/npm/yarn workspaces? Turborepo? Lerna?
+5. **Testing setup**: Jest, Vitest, Playwright, pytest?
+6. **Key patterns**: Organization, conventions, examples, anti-patterns
+
+Present as structured map before generating files.
+
+### Phase 2: Root AGENTS.md
+
+Create lightweight root (~100-200 lines):
+
+```markdown
+# Project Name
+
+## Project Snapshot
+
+[3-5 lines: repo type, tech stack, note about sub-AGENTS.md files]
+
+## Root Setup Commands
+
+[5-10 lines: install, build all, typecheck all, test all]
+
+## Universal Conventions
+
+[5-10 lines: code style, commit format, branch strategy, PR requirements]
+
+## Security & Secrets
+
+[3-5 lines: never commit tokens, .env patterns, PII handling]
+
+## JIT Index
+
+### Package Structure
+
+- Web UI: `apps/web/` -> [see apps/web/AGENTS.md](apps/web/AGENTS.md)
+- API: `apps/api/` -> [see apps/api/AGENTS.md](apps/api/AGENTS.md)
+
+### Quick Find Commands
+
+- Search function: `rg -n "functionName" apps/** packages/**`
+- Find component: `rg -n "export.*ComponentName" apps/web/src`
+- Find API routes: `rg -n "export const (GET|POST)" apps/api`
+
+## Definition of Done
+
+[3-5 lines: what must pass before PR]
+```
+
+### Phase 3: Sub-Folder AGENTS.md
+
+For each major package, create detailed AGENTS.md:
+
+```markdown
+# Package Name
+
+## Package Identity
+
+[2-3 lines: what it does, primary tech]
+
+## Setup & Run
+
+[5-10 lines: install, dev, build, test, lint commands]
+
+## Patterns & Conventions
+
+[10-20 lines - MOST IMPORTANT SECTION]
+
+- File organization rules
+- Naming conventions
+- Examples with actual file paths:
+  - DO: Use pattern from `src/components/Button.tsx`
+  - DON'T: Class components like `src/legacy/OldButton.tsx`
+  - Forms: Copy `src/components/forms/ContactForm.tsx`
+  - API calls: See `src/hooks/useUser.ts`
+
+## Key Files
+
+[5-10 lines: important files to understand package]
+
+- Auth: `src/auth/provider.tsx`
+- API client: `src/lib/api.ts`
+- Types: `src/types/index.ts`
+
+## JIT Index Hints
+
+[5-10 lines: search commands for this package]
+
+- Find component: `rg -n "export function .*" src/components`
+- Find hook: `rg -n "export const use" src/hooks`
+- Find tests: `find . -name "*.test.ts"`
+
+## Common Gotchas
+
+[3-5 lines if applicable]
+
+- "Auth requires NEXT*PUBLIC* prefix for client-side"
+- "Always use @/ imports for absolute paths"
+
+## Pre-PR Checks
+
+[2-3 lines: copy-paste command]
+pnpm --filter @repo/web typecheck && pnpm --filter @repo/web test
+```
+
+### Phase 4: Special Templates
+
+#### Design System / UI Package
+
+```markdown
+## Design System
+
+- Components: `packages/ui/src/components/**`
+- Use design tokens from `packages/ui/src/tokens.ts`
+- Component gallery: `pnpm --filter @repo/ui storybook`
+- Examples:
+  - Buttons: `packages/ui/src/components/Button/Button.tsx`
+  - Forms: `packages/ui/src/components/Input/Input.tsx`
+```
+
+#### Database / Data Layer
+
+```markdown
+## Database
+
+- ORM: Prisma / Drizzle / TypeORM
+- Schema: `prisma/schema.prisma`
+- Migrations: `pnpm db:migrate`
+- Connection: via `src/lib/db.ts` singleton
+- NEVER run migrations in tests
+```
+
+#### API / Backend Service
+
+```markdown
+## API Patterns
+
+- REST routes: `src/routes/**/*.ts`
+- Auth middleware: `src/middleware/auth.ts`
+- Validation: Zod schemas in `src/schemas/**`
+- Errors: `ApiError` from `src/lib/errors.ts`
+- Example: `src/routes/users/get.ts`
+```
+
+#### Testing
+
+```markdown
+## Testing
+
+- Unit: `*.test.ts` colocated
+- Integration: `tests/integration/**`
+- E2E: `tests/e2e/**` (Playwright)
+- Single test: `pnpm test -- path/to/file.test.ts`
+- Mocks: `src/test/mocks/**`
+```
+
+## Output Format
+
+Provide files in order:
+
+1. Analysis Summary
+2. Root AGENTS.md (complete)
+3. Each Sub-Folder AGENTS.md (with file path)
+
+Format:
+
+```
+---
+File: `AGENTS.md` (root)
+---
+[content]
+
+---
+File: `apps/web/AGENTS.md`
+---
+[content]
+```
+
+## Quality Checklist
+
+Before generating, verify:
+
+- [ ] Root AGENTS.md under 200 lines
+- [ ] Root links to all sub-AGENTS.md files
+- [ ] Each sub-file has concrete examples (actual paths)
+- [ ] Commands are copy-paste ready
+- [ ] No duplication between root and sub-files
+- [ ] JIT hints use actual patterns (ripgrep, find, glob)
+- [ ] Every "DO" has real file example
+- [ ] Every "DON'T" references real anti-pattern
+- [ ] Pre-PR checks are single commands

package/.plcode/skill/core/api-design-principles/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: api-design-principles
+description: "Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing..."
+category: backend
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# API Design Principles
+
+Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
+
+## Use this skill when
+
+- Designing new REST or GraphQL APIs
+- Refactoring existing APIs for better usability
+- Establishing API design standards for your team
+- Reviewing API specifications before implementation
+- Migrating between API paradigms (REST to GraphQL, etc.)
+- Creating developer-friendly API documentation
+- Optimizing APIs for specific use cases (mobile, third-party integrations)
+
+## Do not use this skill when
+
+- You only need implementation guidance for a specific framework
+- You are doing infrastructure-only work without API contracts
+- You cannot change or version public interfaces
+
+## Instructions
+
+1. Define consumers, use cases, and constraints.
+2. Choose API style and model resources or types.
+3. Specify errors, versioning, pagination, and auth strategy.
+4. Validate with examples and review for consistency.
+
+Refer to `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

package/.plcode/skill/core/api-design-principles/assets/api-design-checklist.md

@@ -0,0 +1,155 @@
+# API Design Checklist
+
+## Pre-Implementation Review
+
+### Resource Design
+
+- [ ] Resources are nouns, not verbs
+- [ ] Plural names for collections
+- [ ] Consistent naming across all endpoints
+- [ ] Clear resource hierarchy (avoid deep nesting >2 levels)
+- [ ] All CRUD operations properly mapped to HTTP methods
+
+### HTTP Methods
+
+- [ ] GET for retrieval (safe, idempotent)
+- [ ] POST for creation
+- [ ] PUT for full replacement (idempotent)
+- [ ] PATCH for partial updates
+- [ ] DELETE for removal (idempotent)
+
+### Status Codes
+
+- [ ] 200 OK for successful GET/PATCH/PUT
+- [ ] 201 Created for POST
+- [ ] 204 No Content for DELETE
+- [ ] 400 Bad Request for malformed requests
+- [ ] 401 Unauthorized for missing auth
+- [ ] 403 Forbidden for insufficient permissions
+- [ ] 404 Not Found for missing resources
+- [ ] 422 Unprocessable Entity for validation errors
+- [ ] 429 Too Many Requests for rate limiting
+- [ ] 500 Internal Server Error for server issues
+
+### Pagination
+
+- [ ] All collection endpoints paginated
+- [ ] Default page size defined (e.g., 20)
+- [ ] Maximum page size enforced (e.g., 100)
+- [ ] Pagination metadata included (total, pages, etc.)
+- [ ] Cursor-based or offset-based pattern chosen
+
+### Filtering & Sorting
+
+- [ ] Query parameters for filtering
+- [ ] Sort parameter supported
+- [ ] Search parameter for full-text search
+- [ ] Field selection supported (sparse fieldsets)
+
+### Versioning
+
+- [ ] Versioning strategy defined (URL/header/query)
+- [ ] Version included in all endpoints
+- [ ] Deprecation policy documented
+
+### Error Handling
+
+- [ ] Consistent error response format
+- [ ] Detailed error messages
+- [ ] Field-level validation errors
+- [ ] Error codes for client handling
+- [ ] Timestamps in error responses
+
+### Authentication & Authorization
+
+- [ ] Authentication method defined (Bearer token, API key)
+- [ ] Authorization checks on all endpoints
+- [ ] 401 vs 403 used correctly
+- [ ] Token expiration handled
+
+### Rate Limiting
+
+- [ ] Rate limits defined per endpoint/user
+- [ ] Rate limit headers included
+- [ ] 429 status code for exceeded limits
+- [ ] Retry-After header provided
+
+### Documentation
+
+- [ ] OpenAPI/Swagger spec generated
+- [ ] All endpoints documented
+- [ ] Request/response examples provided
+- [ ] Error responses documented
+- [ ] Authentication flow documented
+
+### Testing
+
+- [ ] Unit tests for business logic
+- [ ] Integration tests for endpoints
+- [ ] Error scenarios tested
+- [ ] Edge cases covered
+- [ ] Performance tests for heavy endpoints
+
+### Security
+
+- [ ] Input validation on all fields
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] CORS configured correctly
+- [ ] HTTPS enforced
+- [ ] Sensitive data not in URLs
+- [ ] No secrets in responses
+
+### Performance
+
+- [ ] Database queries optimized
+- [ ] N+1 queries prevented
+- [ ] Caching strategy defined
+- [ ] Cache headers set appropriately
+- [ ] Large responses paginated
+
+### Monitoring
+
+- [ ] Logging implemented
+- [ ] Error tracking configured
+- [ ] Performance metrics collected
+- [ ] Health check endpoint available
+- [ ] Alerts configured for errors
+
+## GraphQL-Specific Checks
+
+### Schema Design
+
+- [ ] Schema-first approach used
+- [ ] Types properly defined
+- [ ] Non-null vs nullable decided
+- [ ] Interfaces/unions used appropriately
+- [ ] Custom scalars defined
+
+### Queries
+
+- [ ] Query depth limiting
+- [ ] Query complexity analysis
+- [ ] DataLoaders prevent N+1
+- [ ] Pagination pattern chosen (Relay/offset)
+
+### Mutations
+
+- [ ] Input types defined
+- [ ] Payload types with errors
+- [ ] Optimistic response support
+- [ ] Idempotency considered
+
+### Performance
+
+- [ ] DataLoader for all relationships
+- [ ] Query batching enabled
+- [ ] Persisted queries considered
+- [ ] Response caching implemented
+
+### Documentation
+
+- [ ] All fields documented
+- [ ] Deprecations marked
+- [ ] Examples provided
+- [ ] Schema introspection enabled

package/.plcode/skill/core/api-design-principles/assets/rest-api-template.py

@@ -0,0 +1,182 @@
+"""
+Production-ready REST API template using FastAPI.
+Includes pagination, filtering, error handling, and best practices.
+"""
+
+from fastapi import FastAPI, HTTPException, Query, Path, Depends, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, EmailStr, ConfigDict
+from typing import Optional, List, Any
+from datetime import datetime
+from enum import Enum
+
+app = FastAPI(
+    title="API Template",
+    version="1.0.0",
+    docs_url="/api/docs"
+)
+
+# Security Middleware
+# Trusted Host: Prevents HTTP Host Header attacks
+app.add_middleware(
+    TrustedHostMiddleware,
+    allowed_hosts=["*"] # TODO: Configure this in production, e.g. ["api.example.com"]
+)
+
+# CORS: Configures Cross-Origin Resource Sharing
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"], # TODO: Update this with specific origins in production
+    allow_credentials=False, # TODO: Set to True if you need cookies/auth headers, but restrict origins
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Models
+class UserStatus(str, Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    SUSPENDED = "suspended"
+
+class UserBase(BaseModel):
+    email: EmailStr
+    name: str = Field(..., min_length=1, max_length=100)
+    status: UserStatus = UserStatus.ACTIVE
+
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8)
+
+class UserUpdate(BaseModel):
+    email: Optional[EmailStr] = None
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    status: Optional[UserStatus] = None
+
+class User(UserBase):
+    id: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+# Pagination
+class PaginationParams(BaseModel):
+    page: int = Field(1, ge=1)
+    page_size: int = Field(20, ge=1, le=100)
+
+class PaginatedResponse(BaseModel):
+    items: List[Any]
+    total: int
+    page: int
+    page_size: int
+    pages: int
+
+# Error handling
+class ErrorDetail(BaseModel):
+    field: Optional[str] = None
+    message: str
+    code: str
+
+class ErrorResponse(BaseModel):
+    error: str
+    message: str
+    details: Optional[List[ErrorDetail]] = None
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=ErrorResponse(
+            error=exc.__class__.__name__,
+            message=exc.detail if isinstance(exc.detail, str) else exc.detail.get("message", "Error"),
+            details=exc.detail.get("details") if isinstance(exc.detail, dict) else None
+        ).model_dump()
+    )
+
+# Endpoints
+@app.get("/api/users", response_model=PaginatedResponse, tags=["Users"])
+async def list_users(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    status: Optional[UserStatus] = Query(None),
+    search: Optional[str] = Query(None)
+):
+    """List users with pagination and filtering."""
+    # Mock implementation
+    total = 100
+    items = [
+        User(
+            id=str(i),
+            email=f"user{i}@example.com",
+            name=f"User {i}",
+            status=UserStatus.ACTIVE,
+            created_at=datetime.now(),
+            updated_at=datetime.now()
+        ).model_dump()
+        for i in range((page-1)*page_size, min(page*page_size, total))
+    ]
+
+    return PaginatedResponse(
+        items=items,
+        total=total,
+        page=page,
+        page_size=page_size,
+        pages=(total + page_size - 1) // page_size
+    )
+
+@app.post("/api/users", response_model=User, status_code=status.HTTP_201_CREATED, tags=["Users"])
+async def create_user(user: UserCreate):
+    """Create a new user."""
+    # Mock implementation
+    return User(
+        id="123",
+        email=user.email,
+        name=user.name,
+        status=user.status,
+        created_at=datetime.now(),
+        updated_at=datetime.now()
+    )
+
+@app.get("/api/users/{user_id}", response_model=User, tags=["Users"])
+async def get_user(user_id: str = Path(..., description="User ID")):
+    """Get user by ID."""
+    # Mock: Check if exists
+    if user_id == "999":
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"message": "User not found", "details": {"id": user_id}}
+        )
+
+    return User(
+        id=user_id,
+        email="user@example.com",
+        name="User Name",
+        status=UserStatus.ACTIVE,
+        created_at=datetime.now(),
+        updated_at=datetime.now()
+    )
+
+@app.patch("/api/users/{user_id}", response_model=User, tags=["Users"])
+async def update_user(user_id: str, update: UserUpdate):
+    """Partially update user."""
+    # Validate user exists
+    existing = await get_user(user_id)
+
+    # Apply updates
+    update_data = update.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(existing, field, value)
+
+    existing.updated_at = datetime.now()
+    return existing
+
+@app.delete("/api/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT, tags=["Users"])
+async def delete_user(user_id: str):
+    """Delete user."""
+    await get_user(user_id)  # Verify exists
+    return None
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)