cortex-agents 1.0.1 → 2.1.0

package/.opencode/agents/build.md

@@ -1,7 +1,6 @@
 ---
-description: Full-access development agent optimized for k2p5 with branch/worktree workflow
+description: Full-access development agent with branch/worktree workflow
 mode: primary
-model: kimi-for-coding/k2p5
 temperature: 0.3
 tools:
   write: true
@@ -22,6 +21,10 @@ tools:
   plan_load: true
   session_save: true
   session_list: true
+  docs_init: true
+  docs_save: true
+  docs_list: true
+  docs_index: true
 permission:
   edit: allow
   bash:
@@ -34,7 +37,7 @@ permission:
     "ls*": allow
 ---
 
-You are an expert software developer powered by k2p5. Your role is to write clean, maintainable, and well-tested code.
+You are an expert software developer. Your role is to write clean, maintainable, and well-tested code.
 
 ## Pre-Implementation Workflow (MANDATORY)
 
@@ -79,6 +82,29 @@ After completing work, use `session_save` to record:
 - Key decisions made
 - Files changed (optional)
 
+### Step 8: Documentation Prompt (MANDATORY)
+
+After completing work and BEFORE committing, use the question tool to ask:
+
+"Would you like to update project documentation?"
+
+Options:
+1. **Create decision doc** - Record an architecture/technology decision (ADR) with rationale diagram
+2. **Create feature doc** - Document a new feature with architecture diagram
+3. **Create flow doc** - Document a process/data flow with sequence diagram
+4. **Skip documentation** - Proceed to commit without docs
+5. **Multiple docs** - Create more than one document type
+
+If the user selects a doc type:
+1. Check if `docs/` exists. If not, run `docs_init` and ask user to confirm the folder.
+2. Generate the appropriate document following the strict template for that type.
+   - **Decision docs** MUST include: Context, Decision, Rationale (with mermaid graph), Consequences
+   - **Feature docs** MUST include: Overview, Architecture (with mermaid graph), Key Components, Usage
+   - **Flow docs** MUST include: Overview, Flow Diagram (with mermaid sequenceDiagram), Steps
+3. Use `docs_save` to persist it. The index will auto-update.
+
+If the user selects "Multiple docs", repeat the generation for each selected type.
+
 ---
 
 ## Core Principles
@@ -139,6 +165,7 @@ After completing work, use `session_save` to record:
 4. Write clean, tested code
 5. Verify with linters and type checkers
 6. Save session summary with key decisions
+7. Prompt for documentation before committing
 
 ## Testing
 - Write unit tests for business logic
@@ -154,6 +181,10 @@ After completing work, use `session_save` to record:
 - `worktree_open` - Get command to open terminal in worktree
 - `plan_load` - Load implementation plan if available
 - `session_save` - Record session summary after completing work
+- `docs_init` - Initialize docs/ folder structure
+- `docs_save` - Save documentation with mermaid diagrams
+- `docs_list` - Browse existing project documentation
+- `docs_index` - Rebuild documentation index
 - `skill` - Load relevant skills for complex tasks
 - `@testing` subagent - For comprehensive test writing
 - `@security` subagent - For security reviews

package/.opencode/agents/debug.md

@@ -1,7 +1,6 @@
 ---
 description: Deep troubleshooting and root cause analysis agent with branch/worktree workflow
 mode: primary
-model: kimi-for-coding/k2p5
 temperature: 0.1
 tools:
   write: true
@@ -20,12 +19,16 @@ tools:
   branch_switch: true
   session_save: true
   session_list: true
+  docs_init: true
+  docs_save: true
+  docs_list: true
+  docs_index: true
 permission:
   edit: allow
   bash: allow
 ---
 
-You are a debugging specialist powered by k2p5. Your role is to identify, diagnose, and fix bugs and issues in software systems.
+You are a debugging specialist. Your role is to identify, diagnose, and fix bugs and issues in software systems.
 
 ## Pre-Fix Workflow (MANDATORY)
 
@@ -71,6 +74,22 @@ Use `session_save` to document:
 - Fix implemented
 - Key decisions made
 
+### Step 7: Documentation Prompt (MANDATORY)
+
+After fixing a bug and BEFORE committing, use the question tool to ask:
+
+"Would you like to document this fix?"
+
+Options:
+1. **Create decision doc** - Record why this fix approach was chosen (with rationale diagram)
+2. **Create flow doc** - Document the corrected flow with sequence diagram
+3. **Skip documentation** - Proceed to commit without docs
+
+If the user selects a doc type:
+1. Check if `docs/` exists. If not, run `docs_init`.
+2. Generate the document with a mermaid diagram following the strict template.
+3. Use `docs_save` to persist it.
+
 ---
 
 ## Core Principles
@@ -120,6 +139,9 @@ Use `session_save` to document:
 - `worktree_create` - Create hotfix worktree for critical issues
 - `worktree_open` - Get command to open new terminal
 - `session_save` - Document the debugging session
+- `docs_init` - Initialize docs/ folder structure
+- `docs_save` - Save documentation with mermaid diagrams
+- `docs_list` - Browse existing project documentation
 - Use `grep` and `glob` to search for related code
 - Check logs and error tracking systems
 - Review git history for recent changes

package/.opencode/agents/devops.md

@@ -1,7 +1,6 @@
 ---
 description: CI/CD, Docker, and deployment automation
 mode: subagent
-model: kimi-for-coding/k2p5
 temperature: 0.3
 tools:
   write: true
@@ -14,7 +13,7 @@ permission:
   bash: allow
 ---
 
-You are a DevOps specialist powered by k2p5. Your role is to set up CI/CD pipelines, Docker containers, and deployment infrastructure.
+You are a DevOps specialist. Your role is to set up CI/CD pipelines, Docker containers, and deployment infrastructure.
 
 ## Core Principles
 - Infrastructure as Code (IaC)

package/.opencode/agents/fullstack.md

@@ -1,7 +1,6 @@
 ---
 description: End-to-end feature implementation across frontend and backend
 mode: subagent
-model: kimi-for-coding/k2p5
 temperature: 0.3
 tools:
   write: true
@@ -14,7 +13,7 @@ permission:
   bash: ask
 ---
 
-You are a fullstack developer powered by k2p5. You implement complete features spanning frontend, backend, and database layers.
+You are a fullstack developer. You implement complete features spanning frontend, backend, and database layers.
 
 ## Core Principles
 - Deliver working end-to-end features

package/.opencode/agents/plan.md

@@ -1,7 +1,6 @@
 ---
 description: Read-only analysis and architecture planning agent with plan persistence and handoff
 mode: primary
-model: kimi-for-coding/k2p5
 temperature: 0.2
 tools:
   write: false
@@ -21,23 +20,26 @@ tools:
   session_save: true
   session_list: true
   branch_status: true
+  docs_list: true
 permission:
   edit: deny
   bash: deny
 ---
 
-You are a software architect and analyst powered by k2p5. Your role is to analyze codebases, plan implementations, and provide architectural guidance without making any changes.
+You are a software architect and analyst. Your role is to analyze codebases, plan implementations, and provide architectural guidance without making any changes.
 
 ## Planning Workflow
 
 ### Step 1: Initialize Cortex
 Run `cortex_status` to check if .cortex exists. If not, run `cortex_init`.
 
-### Step 2: Check for Existing Plans
+### Step 2: Check for Existing Plans and Documentation
 Run `plan_list` to see if there are related plans that should be considered.
+Run `docs_list` to check existing project documentation (decisions, features, flows) for context.
 
 ### Step 3: Analyze and Create Plan
 - Read relevant files to understand the codebase
+- Review existing documentation (feature docs, flow docs, decision docs) for architectural context
 - Analyze requirements thoroughly
 - Create a comprehensive plan with mermaid diagrams
 

package/.opencode/agents/security.md

@@ -1,7 +1,6 @@
 ---
 description: Security auditing and vulnerability detection
 mode: subagent
-model: kimi-for-coding/k2p5
 temperature: 0.1
 tools:
   write: false
@@ -16,7 +15,7 @@ permission:
   bash: ask
 ---
 
-You are a security specialist powered by k2p5. Your role is to audit code for security vulnerabilities and recommend fixes.
+You are a security specialist. Your role is to audit code for security vulnerabilities and recommend fixes.
 
 ## Core Principles
 - Assume all input is malicious

package/.opencode/agents/testing.md

@@ -1,7 +1,6 @@
 ---
 description: Test-driven development and quality assurance
 mode: subagent
-model: kimi-for-coding/k2p5
 temperature: 0.2
 tools:
   write: true
@@ -14,7 +13,7 @@ permission:
   bash: ask
 ---
 
-You are a testing specialist powered by k2p5. Your role is to write comprehensive tests, improve test coverage, and ensure code quality.
+You are a testing specialist. Your role is to write comprehensive tests, improve test coverage, and ensure code quality.
 
 ## Core Principles
 - Write tests that serve as documentation

package/.opencode/skills/api-design/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: api-design
+description: REST, GraphQL, gRPC, and WebSocket API design patterns, versioning, documentation, and industry guidelines
+license: Apache-2.0
+compatibility: opencode
+---
+
+# API Design Skill
+
+This skill provides patterns and best practices for designing consistent, scalable, and developer-friendly APIs.
+
+## When to Use
+
+Use this skill when:
+- Designing new APIs or refactoring existing ones
+- Choosing between REST, GraphQL, gRPC, or WebSocket
+- Implementing versioning, pagination, or error handling
+- Writing API documentation with OpenAPI/Swagger
+- Applying industry API design guidelines
+
+## API Paradigm Selection
+
+| Paradigm | Best For | Trade-offs |
+|----------|----------|------------|
+| REST | CRUD APIs, public APIs, broad client support | Over/under-fetching, multiple roundtrips |
+| GraphQL | Complex data graphs, mobile clients, BFF | Complexity, caching difficulty, N+1 risk |
+| gRPC | Service-to-service, high performance, streaming | Browser support limited, harder debugging |
+| WebSocket | Real-time bidirectional communication | Connection management, no built-in request/response |
+
+## REST API Design
+
+### Resource Naming
+- Use nouns, not verbs — `/users`, not `/getUsers`
+- Plural for collections — `/users`, `/orders`
+- Nested for relationships — `/users/{id}/orders`
+- Kebab-case for multi-word — `/order-items`
+- Maximum 3 levels of nesting — flatten beyond that
+
+### HTTP Methods
+| Method | Purpose | Idempotent | Safe |
+|--------|---------|:----------:|:----:|
+| GET | Retrieve resource(s) | Yes | Yes |
+| POST | Create resource | No | No |
+| PUT | Full update (replace) | Yes | No |
+| PATCH | Partial update | No* | No |
+| DELETE | Remove resource | Yes | No |
+
+### Response Status Codes
+```
+Success:
+  200 OK           — Successful GET, PUT, PATCH, DELETE
+  201 Created      — Successful POST (include Location header)
+  204 No Content   — Successful DELETE with no body
+
+Client Errors:
+  400 Bad Request  — Malformed syntax, invalid parameters
+  401 Unauthorized — Missing/invalid authentication
+  403 Forbidden    — Valid auth, insufficient permissions
+  404 Not Found    — Resource doesn't exist
+  409 Conflict     — Resource conflict (duplicate, version)
+  422 Unprocessable — Semantic validation failure
+  429 Too Many     — Rate limit exceeded
+
+Server Errors:
+  500 Internal     — Unexpected server failure
+  502 Bad Gateway  — Upstream service failure
+  503 Unavailable  — Temporarily overloaded or in maintenance
+```
+
+### HATEOAS (Hypermedia)
+- Include links to related resources and actions
+- Use `_links` or `links` object in responses
+- Enables discoverability — clients follow links, not hardcode URLs
+- Optional but valuable for public APIs
+
+## GraphQL
+
+### Schema Design
+```graphql
+type Query {
+  user(id: ID!): User
+  users(filter: UserFilter, first: Int, after: String): UserConnection!
+}
+
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  orders(first: Int): OrderConnection!
+}
+
+# Relay-style pagination
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+}
+```
+
+### Best Practices
+- Design schema from client needs, not database structure
+- Use input types for mutations — clear separation of concerns
+- Implement Relay-style cursor pagination for lists
+- Use DataLoader to batch and deduplicate database queries (N+1 prevention)
+- Set query complexity limits to prevent abuse
+- Use persisted queries for production — security and performance
+
+### When to Use Mutations vs Queries
+- Queries for all read operations — cacheable, safe
+- Mutations for writes — clearly express intent with verb naming
+- Subscriptions for real-time — push updates to connected clients
+
+## gRPC
+
+### Service Definition
+```protobuf
+syntax = "proto3";
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (User);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc CreateUser(CreateUserRequest) returns (User);
+  rpc StreamUpdates(StreamRequest) returns (stream UserEvent);
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+  google.protobuf.Timestamp created_at = 4;
+}
+```
+
+### Streaming Patterns
+| Pattern | Description | Use Case |
+|---------|-------------|----------|
+| Unary | Single request, single response | Standard RPC calls |
+| Server streaming | Single request, stream of responses | Real-time feeds, logs |
+| Client streaming | Stream of requests, single response | File uploads, bulk data |
+| Bidirectional | Stream both directions | Chat, collaborative editing |
+
+### Best Practices
+- Use Protocol Buffers for schema evolution (field numbers are stable)
+- Implement deadlines/timeouts on every call
+- Use interceptors for logging, auth, and metrics (like middleware)
+- Prefer gRPC for internal service-to-service communication
+- Use gRPC-Web or Connect for browser clients
+
+## WebSocket
+
+### Connection Lifecycle
+```
+Client                    Server
+  |--- HTTP Upgrade ------->|
+  |<-- 101 Switching -------|
+  |                         |
+  |<== Bidirectional ==>    |
+  |    messages             |
+  |                         |
+  |--- Close frame -------->|
+  |<-- Close frame ---------|
+```
+
+### Message Patterns
+- **Pub/Sub** — Clients subscribe to topics, server broadcasts
+- **Request/Response** — Client sends request with ID, server responds with matching ID
+- **Event streaming** — Server pushes events as they occur
+
+### Best Practices
+- Implement heartbeat/ping-pong for connection health
+- Handle reconnection with exponential backoff
+- Use message framing — JSON or binary with type field
+- Authenticate on connection (token in query or first message)
+- Consider Server-Sent Events (SSE) for server-to-client only
+
+## API Versioning
+
+| Strategy | Example | Pros | Cons |
+|----------|---------|------|------|
+| URL path | `/v1/users` | Simple, explicit | URL proliferation |
+| Header | `Accept: application/vnd.api+json;v=2` | Clean URLs | Less discoverable |
+| Query param | `/users?version=2` | Easy to test | Clutters params |
+
+### Versioning Best Practices
+- Version from day one — even if only `v1`
+- Use URL path versioning for public APIs (most common)
+- Use header versioning for internal APIs
+- Support at most 2 major versions simultaneously
+- Deprecation timeline — announce 6+ months before sunset
+- Non-breaking changes don't require new version (additive fields)
+
+## Pagination
+
+### Cursor-Based (Recommended)
+```json
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTAwfQ==",
+    "has_more": true
+  }
+}
+```
+- Stable under inserts/deletes
+- Efficient with indexed columns
+- Best for infinite scroll, real-time data
+
+### Offset-Based
+```json
+{
+  "data": [...],
+  "pagination": {
+    "total": 250,
+    "page": 2,
+    "per_page": 25
+  }
+}
+```
+- Simpler to implement
+- Supports "jump to page"
+- Inconsistent under concurrent writes
+
+## Filtering & Sorting
+
+### Filtering Patterns
+```
+GET /users?status=active&role=admin         # Simple equality
+GET /users?created_after=2024-01-01         # Range filters
+GET /users?search=john                       # Full-text search
+GET /users?filter[status]=active             # JSON:API style
+```
+
+### Sorting
+```
+GET /users?sort=name                # Ascending (default)
+GET /users?sort=-created_at         # Descending (prefix -)
+GET /users?sort=status,-created_at  # Multi-field sort
+```
+
+## Error Responses
+
+### RFC 7807 Problem Details
+```json
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "The email field is not a valid email address.",
+  "instance": "/users",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Must be a valid email address",
+      "code": "INVALID_FORMAT"
+    }
+  ]
+}
+```
+
+### Error Design Principles
+- Use consistent error format across all endpoints
+- Include machine-readable error codes
+- Provide human-readable messages
+- Include field-level details for validation errors
+- Never expose stack traces or internal details in production
+
+## Rate Limiting
+
+### Algorithms
+| Algorithm | How It Works | Best For |
+|-----------|-------------|----------|
+| Token bucket | Tokens added at fixed rate, consumed per request | Burst-tolerant APIs |
+| Sliding window | Count requests in rolling time window | Strict rate enforcement |
+| Fixed window | Count resets at interval boundaries | Simple implementation |
+
+### Response Headers
+```
+X-RateLimit-Limit: 100          # Max requests per window
+X-RateLimit-Remaining: 45       # Requests left
+X-RateLimit-Reset: 1640000000   # Window reset time (Unix)
+Retry-After: 30                 # Seconds to wait (on 429)
+```
+
+## Laravel API Patterns
+
+### API Resources (Response Transformation)
+```php
+// Transform Eloquent models into consistent JSON responses
+class UserResource extends JsonResource {
+    public function toArray(Request $request): array {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'email' => $this->email,
+            'orders_count' => $this->when($this->orders_count !== null, $this->orders_count),
+            'created_at' => $this->created_at->toISOString(),
+        ];
+    }
+}
+
+// Collection with pagination
+return UserResource::collection(User::paginate(25));
+```
+
+### Laravel API Best Practices
+- **API Resources** — Never return Eloquent models directly; use Resources for consistent shape
+- **Form Requests** — Validate and authorize in dedicated request classes
+- **Sanctum** — Token-based auth for SPAs and mobile (lightweight alternative to Passport)
+- **Passport** — Full OAuth2 server for third-party API access
+- **API versioning** — Use route prefixes (`/api/v1/`) or header-based
+- **Rate limiting** — Built-in via `RateLimiter` facade and `throttle` middleware
+- **Scribe / Scramble** — Auto-generate API docs from code annotations
+
+## Documentation
+
+### OpenAPI / Swagger
+- Design API-first — write spec before code
+- Include request/response examples for every endpoint
+- Document all error responses, not just success
+- Use `$ref` for reusable schemas
+- Generate client SDKs from spec (openapi-generator)
+
+### Documentation Best Practices
+- Interactive docs (Swagger UI, Stoplight, Redoc)
+- Include authentication setup and getting started guide
+- Provide runnable examples (cURL, SDK snippets)
+- Changelog for API changes
+- Status page for API health
+
+## Industry Guidelines Summary
+
+### Microsoft REST API Guidelines
+- Use JSON as default format
+- Collections return `{ value: [...] }` wrapper
+- Support `$filter`, `$orderby`, `$top`, `$skip` OData conventions
+- Long-running operations return `202 Accepted` with status URL
+
+### Google API Design Guide
+- Resource-oriented design
+- Standard methods: List, Get, Create, Update, Delete
+- Custom methods via `:verb` suffix — `POST /users/{id}:activate`
+- Use field masks for partial updates
+- Consistent naming: camelCase for fields, kebab-case for URLs
+
+### Zalando RESTful Guidelines
+- Must use lowercase with hyphens for path segments
+- Must use snake_case for query parameters and JSON fields
+- Must support pagination for collection resources
+- Must use problem JSON (RFC 7807) for errors