@ai-content-space/loopx 0.2.9 → 0.2.10

package/plugins/loopx/skills/sql-style/references/window-functions.md

@@ -0,0 +1,328 @@
+# Window Functions
+
+## Ranking Functions
+
+```sql
+-- ROW_NUMBER: Sequential numbering within partition
+SELECT
+    customer_id,
+    order_date,
+    total,
+    ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY order_date DESC) as row_num
+FROM orders;
+
+-- Get most recent order per customer
+SELECT *
+FROM (
+    SELECT
+        customer_id,
+        order_id,
+        order_date,
+        total,
+        ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY order_date DESC) as rn
+    FROM orders
+) ranked
+WHERE rn = 1;
+
+-- RANK: Same values get same rank, gaps in sequence
+SELECT
+    student_id,
+    score,
+    RANK() OVER (ORDER BY score DESC) as rank,
+    DENSE_RANK() OVER (ORDER BY score DESC) as dense_rank,
+    ROW_NUMBER() OVER (ORDER BY score DESC) as row_num
+FROM exam_results;
+/*
+score=100: rank=1, dense_rank=1, row_num=1
+score=100: rank=1, dense_rank=1, row_num=2
+score=95:  rank=3, dense_rank=2, row_num=3
+*/
+
+-- NTILE: Divide into N buckets
+SELECT
+    customer_id,
+    total_spent,
+    NTILE(4) OVER (ORDER BY total_spent DESC) as quartile
+FROM customer_lifetime_value;
+```
+
+## Aggregate Window Functions
+
+```sql
+-- Running totals and cumulative sums
+SELECT
+    order_date,
+    daily_revenue,
+    SUM(daily_revenue) OVER (ORDER BY order_date) as cumulative_revenue,
+    AVG(daily_revenue) OVER (
+        ORDER BY order_date
+        ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
+    ) as rolling_7day_avg
+FROM daily_sales;
+
+-- Moving average with RANGE
+SELECT
+    sale_date,
+    amount,
+    AVG(amount) OVER (
+        ORDER BY sale_date
+        RANGE BETWEEN INTERVAL '7 days' PRECEDING AND CURRENT ROW
+    ) as avg_last_7_days
+FROM sales;
+
+-- Partition-specific aggregates
+SELECT
+    product_id,
+    sale_date,
+    quantity,
+    SUM(quantity) OVER (PARTITION BY product_id ORDER BY sale_date) as cumulative_qty,
+    AVG(quantity) OVER (PARTITION BY product_id) as avg_qty_for_product,
+    quantity::FLOAT / SUM(quantity) OVER (PARTITION BY product_id) as pct_of_total
+FROM product_sales;
+```
+
+## LAG and LEAD Functions
+
+```sql
+-- Compare with previous/next row
+SELECT
+    order_date,
+    total,
+    LAG(total) OVER (ORDER BY order_date) as previous_day_total,
+    LEAD(total) OVER (ORDER BY order_date) as next_day_total,
+    total - LAG(total) OVER (ORDER BY order_date) as day_over_day_change
+FROM daily_orders;
+
+-- Find gaps in time series
+SELECT
+    event_date,
+    LAG(event_date) OVER (ORDER BY event_date) as prev_date,
+    event_date - LAG(event_date) OVER (ORDER BY event_date) as days_since_last
+FROM events
+WHERE event_date - LAG(event_date) OVER (ORDER BY event_date) > 7;
+
+-- Session analysis with time gaps
+SELECT
+    user_id,
+    action_time,
+    LAG(action_time) OVER (PARTITION BY user_id ORDER BY action_time) as prev_action,
+    EXTRACT(EPOCH FROM (
+        action_time - LAG(action_time) OVER (PARTITION BY user_id ORDER BY action_time)
+    )) / 60 as minutes_since_last_action,
+    CASE
+        WHEN EXTRACT(EPOCH FROM (
+            action_time - LAG(action_time) OVER (PARTITION BY user_id ORDER BY action_time)
+        )) / 60 > 30 THEN 1
+        ELSE 0
+    END as new_session
+FROM user_actions;
+```
+
+## FIRST_VALUE and LAST_VALUE
+
+```sql
+-- Compare each row to first/last in partition
+SELECT
+    product_id,
+    price_date,
+    price,
+    FIRST_VALUE(price) OVER (
+        PARTITION BY product_id
+        ORDER BY price_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as initial_price,
+    LAST_VALUE(price) OVER (
+        PARTITION BY product_id
+        ORDER BY price_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as current_price,
+    price - FIRST_VALUE(price) OVER (
+        PARTITION BY product_id
+        ORDER BY price_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as price_change_from_start
+FROM product_price_history;
+
+-- NTH_VALUE: Get specific positioned value
+SELECT
+    sale_date,
+    amount,
+    NTH_VALUE(amount, 2) OVER (
+        ORDER BY sale_date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) as second_day_amount
+FROM daily_sales;
+```
+
+## Frame Specifications
+
+```sql
+-- ROWS vs RANGE difference
+SELECT
+    order_date,
+    amount,
+    -- ROWS: Physical row offset
+    SUM(amount) OVER (
+        ORDER BY order_date
+        ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING
+    ) as sum_5_rows,
+    -- RANGE: Logical value range
+    SUM(amount) OVER (
+        ORDER BY order_date
+        RANGE BETWEEN INTERVAL '2 days' PRECEDING AND INTERVAL '2 days' FOLLOWING
+    ) as sum_5_day_range
+FROM orders;
+
+-- Common frame patterns
+SELECT
+    sale_date,
+    revenue,
+    -- All preceding rows
+    SUM(revenue) OVER (
+        ORDER BY sale_date
+        ROWS UNBOUNDED PRECEDING
+    ) as running_total,
+    -- Last 3 rows including current
+    AVG(revenue) OVER (
+        ORDER BY sale_date
+        ROWS BETWEEN 2 PRECEDING AND CURRENT ROW
+    ) as ma_3,
+    -- Entire partition
+    SUM(revenue) OVER (
+        PARTITION BY EXTRACT(YEAR FROM sale_date)
+    ) as yearly_total,
+    -- Centered window
+    AVG(revenue) OVER (
+        ORDER BY sale_date
+        ROWS BETWEEN 3 PRECEDING AND 3 FOLLOWING
+    ) as centered_ma_7
+FROM sales;
+```
+
+## Advanced Analytics
+
+```sql
+-- Percentile calculations
+SELECT
+    employee_id,
+    salary,
+    PERCENT_RANK() OVER (ORDER BY salary) as pct_rank,
+    CUME_DIST() OVER (ORDER BY salary) as cumulative_dist,
+    PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY salary) OVER () as median_salary,
+    PERCENTILE_DISC(0.9) WITHIN GROUP (ORDER BY salary) OVER () as p90_salary
+FROM employees;
+
+-- Cohort retention analysis
+WITH user_cohorts AS (
+    SELECT
+        user_id,
+        DATE_TRUNC('month', signup_date) as cohort_month,
+        DATE_TRUNC('month', activity_date) as activity_month
+    FROM user_activity
+),
+cohort_sizes AS (
+    SELECT
+        cohort_month,
+        COUNT(DISTINCT user_id) as cohort_size
+    FROM user_cohorts
+    GROUP BY cohort_month
+)
+SELECT
+    uc.cohort_month,
+    uc.activity_month,
+    EXTRACT(MONTH FROM AGE(uc.activity_month, uc.cohort_month)) as months_since_signup,
+    COUNT(DISTINCT uc.user_id) as active_users,
+    cs.cohort_size,
+    ROUND(100.0 * COUNT(DISTINCT uc.user_id) / cs.cohort_size, 2) as retention_pct
+FROM user_cohorts uc
+JOIN cohort_sizes cs ON uc.cohort_month = cs.cohort_month
+GROUP BY uc.cohort_month, uc.activity_month, cs.cohort_size
+ORDER BY uc.cohort_month, months_since_signup;
+
+-- Time-series gap filling
+SELECT
+    date_series.date,
+    COALESCE(s.revenue, 0) as revenue,
+    AVG(s.revenue) OVER (
+        ORDER BY date_series.date
+        ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
+    ) as ma_7day
+FROM generate_series(
+    '2024-01-01'::DATE,
+    '2024-12-31'::DATE,
+    '1 day'::INTERVAL
+) AS date_series(date)
+LEFT JOIN sales s ON date_series.date = s.sale_date;
+```
+
+## Conditional Aggregation with Windows
+
+```sql
+-- Filter within window function
+SELECT
+    product_id,
+    sale_date,
+    quantity,
+    SUM(quantity) FILTER (WHERE quantity > 10) OVER (
+        PARTITION BY product_id
+        ORDER BY sale_date
+    ) as cumulative_large_orders,
+    COUNT(*) FILTER (WHERE quantity > 100) OVER (
+        PARTITION BY product_id
+    ) as total_bulk_orders
+FROM sales;
+
+-- Multiple conditions
+SELECT
+    customer_id,
+    order_date,
+    total,
+    COUNT(*) FILTER (WHERE total > 1000) OVER (
+        PARTITION BY customer_id
+    ) as high_value_order_count,
+    AVG(total) FILTER (WHERE total < 100) OVER (
+        PARTITION BY customer_id
+    ) as avg_small_order_value
+FROM orders;
+```
+
+## Performance Considerations
+
+```sql
+-- Avoid multiple window passes - combine into one
+-- Bad: Multiple scans
+SELECT
+    product_id,
+    (SELECT AVG(price) FROM products) as avg_price,
+    (SELECT MAX(price) FROM products) as max_price
+FROM products;
+
+-- Good: Single window pass
+SELECT DISTINCT
+    AVG(price) OVER () as avg_price,
+    MAX(price) OVER () as max_price
+FROM products;
+
+-- Materialize expensive windows
+CREATE MATERIALIZED VIEW product_rankings AS
+SELECT
+    product_id,
+    category,
+    sales_count,
+    RANK() OVER (PARTITION BY category ORDER BY sales_count DESC) as category_rank,
+    PERCENT_RANK() OVER (ORDER BY sales_count DESC) as overall_percentile
+FROM product_sales_summary;
+
+CREATE INDEX idx_product_rankings_category ON product_rankings(category, category_rank);
+```
+
+## Common Patterns
+
+1. **Top N per Group**: Use ROW_NUMBER() with WHERE rn <= N
+2. **Running Totals**: SUM() OVER (ORDER BY date)
+3. **Moving Averages**: AVG() with ROWS BETWEEN N PRECEDING
+4. **Session Analysis**: LAG() to detect time gaps
+5. **Deduplication**: ROW_NUMBER() OVER (PARTITION BY key ORDER BY priority) WHERE rn = 1
+6. **Percentiles**: PERCENT_RANK() or PERCENTILE_CONT()
+7. **Year-over-Year**: LAG(value, 12) OVER (ORDER BY month)
+8. **Cohort Analysis**: PARTITION BY cohort_date, aggregate over activity periods

package/plugins/loopx/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.9"
+  version: "0.2.10"
 ---
 
 # Subagent Exec

package/plugins/loopx/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.9"
+  version: "0.2.10"
 ---
 
 # Test-Driven Development (TDD)

package/plugins/loopx/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.9"
+  version: "0.2.10"
 ---
 
 # Verification Before Completion

package/scripts/verify-skills.mjs

@@ -176,7 +176,6 @@ async function assertPublicDocsAligned() {
     'LOOPX_SKIP_POSTINSTALL=1',
     'LOOPX_POSTINSTALL=0',
     'LOOPX_HOOKS=0',
-    'Archive compatibility',
   ]) {
     assertContains(readme, required, 'README.md');
   }
@@ -187,7 +186,6 @@ async function assertPublicDocsAligned() {
     'LOOPX_SKIP_POSTINSTALL=1',
     'LOOPX_POSTINSTALL=0',
     'LOOPX_HOOKS=0',
-    'Archive 兼容性',
   ]) {
     assertContains(readmeZh, required, 'README.zh-CN.md');
   }

package/skills/RESOLVER.md

@@ -27,8 +27,13 @@ Read the selected skill file before acting. If multiple skills match, read every
 | Bug, test failure, build failure, regression, unexpected behavior, root-cause investigation | `skills/debug/SKILL.md` |
 | Completion, fixed, passing, review-ready, commit, or handoff claims need fresh evidence | `skills/verify/SKILL.md` |
 | Document readability, PRD assessment, requirements gaps, unclear viewpoint, AI-like prose, or document rewriting | `skills/doc-readability/SKILL.md` |
+| Existing requirement, PRD, spec, or feature brief needs ambiguity, gap, impact, feasibility, or readiness analysis | `skills/requirement-analyzer/SKILL.md` |
 | Editing `.go` files or reviewing Go style | `skills/go-style/SKILL.md` |
 | Go-Kratos proto, service, biz, data, middleware, auth, config, or troubleshooting | `skills/kratos/SKILL.md` |
+| REST/GraphQL API design, resource modeling, OpenAPI, pagination, versioning, or API error model discipline | `skills/api-designer/SKILL.md` |
+| System architecture, ADRs, NFRs, scalability, failure modes, or technology tradeoff discipline | `skills/architecture-designer/SKILL.md` |
+| SQL queries, schema changes, indexes, migrations, database dialects, or query performance discipline | `skills/sql-style/SKILL.md` |
+| CLI command design, flags, human/JSON output, interactive vs non-interactive behavior, help text, or CLI UX discipline | `skills/cli-developer/SKILL.md` |
 
 ## Disambiguation
 
@@ -44,7 +49,9 @@ Read the selected skill file before acting. If multiple skills match, read every
 10. Use `finish` only after implementation, final review, and verification are complete.
 11. Use `refactor-plan` for behavior-preserving refactor planning. If the refactor changes external behavior or contracts, route to `clarify` or `spec`.
 12. Use `doc-readability` for document assessment or rewriting, especially PRDs, requirements docs, specs, meeting notes, and AI-like prose. If the document is a source artifact for implementation, assess or rewrite it first, then route clarified implementation work back through `clarify`, `spec`, or `plan-to-exec`.
-13. Treat `tdd`, `debug`, `verify`, `doc-readability`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
+13. Treat `tdd`, `debug`, `verify`, `doc-readability`, `requirement-analyzer`, `go-style`, `kratos`, `api-designer`, `architecture-designer`, `sql-style`, and `cli-developer` as support lenses unless the user explicitly invokes them directly.
+14. `requirement-analyzer` may produce a requirements gap report, but it must not advance loopx workflow state. Use its output as source material for a later `clarify`, `spec`, or `plan-to-exec` step only when the user asks.
+15. `api-designer`, `architecture-designer`, `sql-style`, and `cli-developer` add domain discipline to `spec`, `exec`, `review`, and `final-review`; they do not replace workflow skills or create workflow states.
 
 ## Deterministic Guard
 

package/skills/api-designer/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: api-designer
+description: "Applies loopx API design discipline for REST, GraphQL, OpenAPI, resource modeling, pagination, versioning, compatibility, and error models. Not for replacing clarify, spec, implementation planning, code review, or workflow state transitions."
+when_to_use: "api-designer, API design, REST, GraphQL, OpenAPI, resource modeling, pagination, versioning, API errors, compatibility, 接口设计"
+license: MIT
+metadata:
+  version: "0.2.10"
+  forked_from: https://github.com/Jeffallan/claude-skills/tree/main/skills/api-designer
+  maintained_by: loopx
+---
+
+# API Designer
+
+API design discipline for REST, GraphQL, and OpenAPI 3.1 contracts.
+
+## loopx Boundary
+
+`api-designer` is a support lens, not a workflow state. Use it directly when the user asks for API design help, and use it from `spec`, `exec`, `review`, or `final-review` when work touches API contracts.
+
+This skill does not replace `clarify`, `spec`, `plan-to-exec`, `review`, or `final-review`. If product behavior, permissions, compatibility, migration, or client contract decisions are unresolved, route those decisions through `clarify` or `spec` instead of deciding them inside this skill.
+
+## Core Workflow
+
+1. **Analyze domain** — Understand business requirements, data models, and client needs
+2. **Choose API style** — State whether the contract is REST, GraphQL, or mixed, and why that style fits the client and evolution needs
+3. **Model contract surface** — For REST, identify resources, relationships, URI patterns, HTTP methods, and request/response schemas. For GraphQL, identify object types, operations, inputs, resolver boundaries, and schema evolution rules.
+4. **Specify contract** — For REST, create OpenAPI 3.1 and validate with `npx @redocly/cli lint openapi.yaml`. For GraphQL, define the schema and run the project's schema validation or code generation checks.
+5. **Mock and verify** — For REST, use a mock server such as `npx @stoplight/prism-cli mock openapi.yaml`. For GraphQL, exercise representative operations against the project schema or a local GraphQL test server.
+6. **Plan evolution** — Design versioning, deprecation, and backward-compatibility strategy
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| REST Patterns | `references/rest-patterns.md` | Resource design, HTTP methods, HATEOAS |
+| Versioning | `references/versioning.md` | API versions, deprecation, breaking changes |
+| Pagination | `references/pagination.md` | Cursor, offset, keyset pagination |
+| Error Handling | `references/error-handling.md` | Error responses, RFC 7807, status codes |
+| OpenAPI | `references/openapi.md` | OpenAPI 3.1, documentation, code generation |
+
+## Constraints
+
+### MUST DO
+- For REST contracts, follow REST principles: resource-oriented URIs, proper HTTP methods, and HTTP status semantics.
+- For REST contracts, include a comprehensive OpenAPI 3.1 specification.
+- For GraphQL contracts, include schema definitions, resolver boundaries, operation examples, and validation or code generation checks.
+- Use consistent naming conventions within each contract style.
+- Design proper error responses with actionable messages: RFC 7807 for REST, and explicit GraphQL error shape and partial-success rules for GraphQL.
+- Implement pagination for all collection endpoints or collection fields.
+- Version APIs with clear deprecation policies
+- Document authentication and authorization
+- Provide request/response examples
+
+### MUST NOT DO
+- For REST contracts, use verb-style resource URIs (use `/users/{id}`, not `/getUser/{id}`)
+- Return inconsistent response structures
+- Skip error code documentation
+- For REST contracts, ignore HTTP status code semantics.
+- Design APIs without a versioning strategy
+- Expose implementation details in the API surface
+- Create breaking changes without a migration path
+- Omit rate limiting considerations
+
+## GraphQL Discipline
+
+When designing GraphQL APIs, provide the same contract rigor as REST:
+
+- Model object types, input types, mutations, queries, and subscriptions around client use cases, not database tables.
+- Define nullability, pagination, filtering, sorting, and authorization rules explicitly in the schema.
+- Use stable node identifiers and connection-style pagination when clients need cursor traversal.
+- Avoid unbounded nested queries; plan depth, complexity, batching, and caching controls.
+- Version by additive schema evolution and documented deprecation, not parallel endpoint versions unless the product contract requires it.
+- Specify error shape, partial-success behavior, and resolver-level authorization failures.
+
+## Templates
+
+### OpenAPI 3.1 Resource Endpoint (copy-paste starter)
+
+```yaml
+openapi: "3.1.0"
+info:
+  title: Example API
+  version: "1.1.0"
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags: [Users]
+      parameters:
+        - name: cursor
+          in: query
+          schema: { type: string }
+          description: Opaque cursor for pagination
+        - name: limit
+          in: query
+          schema: { type: integer, default: 20, maximum: 100 }
+      responses:
+        "200":
+          description: Paginated list of users
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, pagination]
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/User" }
+                  pagination:
+                    $ref: "#/components/schemas/CursorPage"
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+  /users/{id}:
+    get:
+      summary: Get a user
+      operationId: getUser
+      tags: [Users]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: User found
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/User" }
+        "404": { $ref: "#/components/responses/NotFound" }
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, created_at]
+      properties:
+        id:    { type: string, format: uuid, readOnly: true }
+        email: { type: string, format: email }
+        name:  { type: string }
+        created_at: { type: string, format: date-time, readOnly: true }
+
+    CursorPage:
+      type: object
+      required: [next_cursor, has_more]
+      properties:
+        next_cursor: { type: string, nullable: true }
+        has_more:    { type: boolean }
+
+    Problem:                       # RFC 7807 Problem Details
+      type: object
+      required: [type, title, status]
+      properties:
+        type:     { type: string, format: uri, example: "https://api.example.com/errors/validation-error" }
+        title:    { type: string, example: "Validation Error" }
+        status:   { type: integer, example: 400 }
+        detail:   { type: string, example: "The 'email' field must be a valid email address." }
+        instance: { type: string, format: uri, example: "/users/req-abc123" }
+
+  responses:
+    BadRequest:
+      description: Invalid request parameters
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+    Unauthorized:
+      description: Missing or invalid authentication
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+    NotFound:
+      description: Resource not found
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+    TooManyRequests:
+      description: Rate limit exceeded
+      headers:
+        Retry-After: { schema: { type: integer } }
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []
+```
+
+### RFC 7807 Error Response (copy-paste)
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "The 'email' field must be a valid email address.",
+  "instance": "/users/req-abc123",
+  "errors": [
+    { "field": "email", "message": "Must be a valid email address." }
+  ]
+}
+```
+
+- Always use `Content-Type: application/problem+json` for error responses.
+- `type` must be a stable, documented URI — never a generic string.
+- `detail` must be human-readable and actionable.
+- Extend with `errors[]` for field-level validation failures.
+
+## Output Checklist
+
+When delivering an API design, provide:
+1. Resource model and relationships (diagram or table)
+2. API style decision: REST, GraphQL, or mixed
+3. For REST, endpoint specifications with URIs, HTTP methods, and OpenAPI 3.1 YAML
+4. For GraphQL, schema types, operations, resolver boundaries, authorization rules, query limits, and deprecation policy
+5. Authentication and authorization flows
+6. Error response catalog: 4xx/5xx responses with stable `type` URIs for REST, or GraphQL error shape, partial-success behavior, and resolver authorization failures
+7. Pagination and filtering patterns
+8. Versioning and deprecation strategy
+9. Validation result: `npx @redocly/cli lint openapi.yaml` passes with no errors for OpenAPI contracts, or project GraphQL schema validation passes for GraphQL contracts
+
+## Knowledge Reference
+
+REST architecture, OpenAPI 3.1, GraphQL, HTTP semantics, JSON:API, HATEOAS, OAuth 2.0, JWT, RFC 7807 Problem Details, API versioning patterns, pagination strategies, rate limiting, webhook design, SDK generation