opencode-agent-kit 1.0.0

package/template/.opencode/rules/python/coding-style.md

@@ -0,0 +1,37 @@
+# Python Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content.
+
+## Standards
+
+- Follow **PEP 8** conventions
+- Use **type annotations** on all function signatures
+
+## Immutability
+
+Prefer immutable data structures:
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class User:
+    name: str
+    email: str
+
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    x: float
+    y: float
+```
+
+## Formatting
+
+- **black** for code formatting
+- **isort** for import sorting
+- **ruff** for linting
+
+## Reference
+
+See skill: `python-patterns` for comprehensive Python idioms and patterns.

package/template/.opencode/rules/python/hooks.md

@@ -0,0 +1,14 @@
+# Python Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Python specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **black/ruff**: Auto-format `.py` files after edit
+- **mypy/pyright**: Run type checking after editing `.py` files
+
+## Warnings
+
+- Warn about `print()` statements in edited files (use `logging` module instead)

package/template/.opencode/rules/python/patterns.md

@@ -0,0 +1,34 @@
+# Python Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Python specific content.
+
+## Protocol (Duck Typing)
+
+```python
+from typing import Protocol
+
+class Repository(Protocol):
+    def find_by_id(self, id: str) -> dict | None: ...
+    def save(self, entity: dict) -> dict: ...
+```
+
+## Dataclasses as DTOs
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class CreateUserRequest:
+    name: str
+    email: str
+    age: int | None = None
+```
+
+## Context Managers & Generators
+
+- Use context managers (`with` statement) for resource management
+- Use generators for lazy evaluation and memory-efficient iteration
+
+## Reference
+
+See skill: `python-patterns` for comprehensive patterns including decorators, concurrency, and package organization.

package/template/.opencode/rules/python/security.md

@@ -0,0 +1,25 @@
+# Python Security
+
+> This file extends [common/security.md](../common/security.md) with Python specific content.
+
+## Secret Management
+
+```python
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+api_key = os.environ["OPENAI_API_KEY"]  # Raises KeyError if missing
+```
+
+## Security Scanning
+
+- Use **bandit** for static security analysis:
+  ```bash
+  bandit -r src/
+  ```
+
+## Reference
+
+See skill: `django-security` for Django-specific security guidelines (if applicable).

package/template/.opencode/rules/python/testing.md

@@ -0,0 +1,33 @@
+# Python Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Python specific content.
+
+## Framework
+
+Use **pytest** as the testing framework.
+
+## Coverage
+
+```bash
+pytest --cov=src --cov-report=term-missing
+```
+
+## Test Organization
+
+Use `pytest.mark` for test categorization:
+
+```python
+import pytest
+
+@pytest.mark.unit
+def test_calculate_total():
+    ...
+
+@pytest.mark.integration
+def test_database_connection():
+    ...
+```
+
+## Reference
+
+See skill: `python-testing` for detailed pytest patterns and fixtures.

package/template/.opencode/rules/typescript/coding-style.md

@@ -0,0 +1,58 @@
+# TypeScript/JavaScript Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with TypeScript/JavaScript specific content.
+
+## Immutability
+
+Use spread operator for immutable updates:
+
+```typescript
+// WRONG: Mutation
+function updateUser(user, name) {
+  user.name = name  // MUTATION!
+  return user
+}
+
+// CORRECT: Immutability
+function updateUser(user, name) {
+  return {
+    ...user,
+    name
+  }
+}
+```
+
+## Error Handling
+
+Use async/await with try-catch:
+
+```typescript
+try {
+  const result = await riskyOperation()
+  return result
+} catch (error) {
+  console.error('Operation failed:', error)
+  throw new Error('Detailed user-friendly message')
+}
+```
+
+## Input Validation
+
+Use Zod for schema-based validation:
+
+```typescript
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+const validated = schema.parse(input)
+```
+
+## Console.log
+
+- No `console.log` statements in production code
+- Use proper logging libraries instead
+- See hooks for automatic detection

package/template/.opencode/rules/typescript/hooks.md

@@ -0,0 +1,15 @@
+# TypeScript/JavaScript Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with TypeScript/JavaScript specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **Prettier**: Auto-format JS/TS files after edit
+- **TypeScript check**: Run `tsc` after editing `.ts`/`.tsx` files
+- **console.log warning**: Warn about `console.log` in edited files
+
+## Stop Hooks
+
+- **console.log audit**: Check all modified files for `console.log` before session ends

package/template/.opencode/rules/typescript/patterns.md

@@ -0,0 +1,45 @@
+# TypeScript/JavaScript Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with TypeScript/JavaScript specific content.
+
+## API Response Format
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Custom Hooks Pattern
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```

package/template/.opencode/rules/typescript/security.md

@@ -0,0 +1,21 @@
+# TypeScript/JavaScript Security
+
+> This file extends [common/security.md](../common/security.md) with TypeScript/JavaScript specific content.
+
+## Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-proj-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.OPENAI_API_KEY
+
+if (!apiKey) {
+  throw new Error('OPENAI_API_KEY not configured')
+}
+```
+
+## Agent Support
+
+- Use **security-reviewer** skill for comprehensive security audits

package/template/.opencode/rules/typescript/testing.md

@@ -0,0 +1,11 @@
+# TypeScript/JavaScript Testing
+
+> This file extends [common/testing.md](../common/testing.md) with TypeScript/JavaScript specific content.
+
+## E2E Testing
+
+Use **Playwright** as the E2E testing framework for critical user flows.
+
+## Agent Support
+
+- **e2e-runner** - Playwright E2E testing specialist

package/template/.opencode/skills/api-documentation/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: api-documentation
+description: API documentation generation with Postman sync workflow. Use when defining API contracts, creating endpoints, or designing API documentation.
+---
+
+# API Documentation & Postman Sync
+
+Workflow for generating API documentation and optionally syncing to Postman collections.
+
+## When to Activate
+
+- Defining API contracts (endpoints, request/response schemas)
+- Creating new API endpoints or modules
+- Generating API documentation from code
+- After completing backend endpoint implementation
+
+## Confirmation Flow (User Must Approve)
+
+Before any Postman sync, ALWAYS ask the user using the `question` tool:
+
+```markdown
+questions: [
+  {
+    header: "Postman Sync",
+    question: "Do you also want to create/update this API in Postman?",
+    options: [
+      { label: "Yes (Recommended)", description: "Create/update Postman collection with all endpoints, requests, and response examples" },
+      { label: "No", description: "Skip Postman sync, continue without" },
+      { label: "Custom answer", description: "Type your own response" }
+    ]
+  }
+]
+```
+
+Default fallback: If user doesn't select, pick "Yes (Recommended)".
+
+## Postman Sync Workflow
+
+### Prerequisites
+- Postman MCP server enabled
+- `POSTMAN_API_KEY` configured
+- Postman workspace ID (ask user if not known)
+
+### Step 1: Prepare API Contract Data
+
+Before calling Postman tools, compile:
+
+```json
+{
+  "collectionName": "My API - v1",
+  "workspaceId": "ws-xxxxx",
+  "baseUrl": "https://api.example.com",
+  "endpoints": [
+    {
+      "name": "List Users",
+      "method": "GET",
+      "path": "/api/users",
+      "description": "Get paginated list of users",
+      "headers": { "Content-Type": "application/json", "Authorization": "Bearer {{token}}" },
+      "queryParams": [
+        { "key": "limit", "value": "10", "description": "Max results" },
+        { "key": "offset", "value": "0", "description": "Pagination offset" }
+      ],
+      "responses": [
+        { "code": 200, "name": "Success", "body": "{ \"users\": [], \"total\": 0 }" },
+        { "code": 401, "name": "Unauthorized", "body": "{ \"error\": \"Unauthorized\" }" }
+      ]
+    }
+  ]
+}
+```
+
+### Step 2: Resolve Workspace
+
+```markdown
+1. Call `postman_getWorkspaces` to list available workspaces
+2. If workspace ID known, use it directly
+3. If unknown, ask user: "Which Postman workspace should this collection be created in?"
+4. Use question tool with workspace list as options
+```
+
+### Step 3: Check Existing Collection
+
+```markdown
+1. Call `postman_getCollections(workspace)` to list collections
+2. Search for collection by name match
+3. If found: Ask user to merge/update or create new:
+   - "Collection 'X' already exists. Update it or create a new one?"
+   - Options: Update existing, Create new with suffix, Cancel
+4. If not found: Create new collection
+```
+
+### Step 4: Create or Update Collection
+
+**New Collection:**
+```markdown
+Call `postman_createCollection` with:
+- workspace: the target workspace ID
+- collection: full collection object with:
+  - info: { name, schema }
+  - item: array of endpoint items (can be nested in folders)
+```
+
+**Update Existing:**
+```markdown
+Call `postman_patchCollection` with:
+- collectionId: existing collection ID
+- collection: { info: { name, description }, variable: [...] }
+```
+
+### Step 5: Add Requests
+
+For each endpoint, call `postman_createCollectionRequest`:
+
+```markdown
+Parameters:
+- collectionId: the collection ID
+- folderId: (optional) folder to place request in
+- name: endpoint name (e.g., "List Users")
+- method: GET/POST/PUT/PATCH/DELETE
+- url: full URL (e.g., "{{baseUrl}}/api/users")
+- headerData: array of { key, value, description }
+- queryParams: array of { key, value, description, enabled }
+- dataMode: raw / urlencoded / formdata / graphql
+- rawModeData: raw JSON body (for POST/PUT/PATCH)
+```
+
+### Step 6: Add Response Examples
+
+For each response variant, call `postman_createCollectionResponse`:
+
+```markdown
+Parameters:
+- collectionId: the collection ID
+- request: the request ID (from step 5 output)
+- name: response name (e.g., "200 Success", "401 Unauthorized")
+- responseCode: { code: 200, name: "OK" }
+- text: response body string
+- headers: array of response headers
+- mime: "application/json"
+```
+
+### Step 7: Organize with Folders (Optional)
+
+For multi-module APIs, group related endpoints:
+
+```markdown
+1. Call `postman_createCollectionFolder(collectionId, name)` for each module
+2. Pass folderId when creating requests in step 5
+```
+
+## Postman MCP Tool Reference
+
+| Tool | Purpose |
+|------|---------|
+| `postman_getWorkspaces` | List available workspaces |
+| `postman_getCollections(workspace)` | List collections in workspace |
+| `postman_getCollection(collectionId)` | Get collection details |
+| `postman_createCollection(workspace, collection)` | Create new collection |
+| `postman_patchCollection(collectionId, collection)` | Update collection |
+| `postman_createCollectionFolder(collectionId, name)` | Create folder |
+| `postman_createCollectionRequest(collectionId, ...)` | Create request |
+| `postman_createCollectionResponse(collectionId, request, ...)` | Add response example |
+| `postman_getCollectionContext(collectionId)` | Get collection summary |
+| `postman_getRequestCodeContext(collectionId, requestId)` | Get request details for code gen |
+
+## Security Notes
+
+- Do NOT include real API keys or tokens in Postman collection variables
+- Use Postman variables (`{{variableName}}`) for sensitive values
+- Set `"disabled": true` for query parameters that should not be sent
+- For auth headers, prefer Bearer token pattern with `{{token}}` variable
+- Never commit Postman API key to source control
+
+## Example Workflow
+
+```
+1. Define API contract: GET /api/users, POST /api/users
+2. Ask user: "Sync to Postman?" → Yes
+3. Get workspace list → user selects "My Project Workspace"
+4. Check existing collections → "My API" doesn't exist
+5. Create collection "My API - v1" in workspace
+6. Create folder "Users" in collection
+7. Create request "List Users" (GET) in folder
+8. Create request "Create User" (POST) in folder
+9. Add success/error response examples for each
+10. Report: "Postman collection 'My API - v1' created with 2 endpoints"
+```