@geraldmaron/construct 1.0.0

package/skills/ai/ml-ops.md

@@ -0,0 +1,169 @@
+<!--
+skills/ai/ml-ops.md — ML Operations (MLOps) — ```
+
+## The MLOps Lifecycle ```
+-->
+# ML Operations (MLOps)
+
+## The MLOps Lifecycle
+
+```
+Data → Feature Engineering → Training → Evaluation → Registry → Deployment → Monitoring → (loop)
+```
+
+Each stage should be reproducible, versioned, and automated.
+
+## Data Management
+
+### Data versioning
+
+Use **DVC** (Data Version Control) alongside git to version datasets and models:
+
+```bash
+dvc add data/training.csv        # track large file outside git
+dvc push                         # push to remote storage (S3, GCS, Azure)
+git add data/training.csv.dvc    # commit the pointer
+```
+
+### Feature stores
+
+For team-shared features or online serving:
+- **Feast** (open source): offline (data warehouse) + online (Redis/DynamoDB) store
+- **Tecton**, **Hopsworks** for managed options
+
+Feature pipelines should be:
+1. Deterministic (same input → same output)
+2. Backfillable (can recompute historical features)
+3. Point-in-time correct (no future data leakage)
+
+## Experiment Tracking
+
+Use **MLflow** or **Weights & Biases** to log:
+
+```python
+import mlflow
+
+with mlflow.start_run(run_name="baseline-xgb"):
+  mlflow.log_params({"max_depth": 6, "n_estimators": 100})
+  model.fit(X_train, y_train)
+  metrics = evaluate(model, X_val, y_val)
+  mlflow.log_metrics(metrics)
+  mlflow.sklearn.log_model(model, "model")
+```
+
+Minimum to log per experiment: hyperparameters, dataset version/hash, evaluation metrics, model artifact.
+
+## Training Pipelines
+
+### Pipeline orchestration
+
+Use **Kubeflow Pipelines**, **Prefect**, **Airflow**, or **ZenML**:
+
+```python
+@pipeline
+def training_pipeline():
+  data = ingest_data()
+  features = engineer_features(data)
+  model = train_model(features)
+  evaluate_model(model, features)
+  push_to_registry(model)
+```
+
+- Each step is a containerized function with explicit inputs/outputs
+- Cache step outputs to avoid re-running expensive transformations
+- Use hardware-specific steps (GPU) only where necessary
+
+### Reproducibility requirements
+
+- Pin library versions (`requirements.txt` or `conda.yml` locked)
+- Log random seeds
+- Log git commit hash with the run
+- Use deterministic data splits (fixed random seed, or pre-split stored files)
+
+## Model Registry
+
+Central store for model versions and deployment state:
+
+| Stage | Meaning |
+|---|---|
+| Staging | Candidate — passes evaluation, not yet in production |
+| Production | Currently serving |
+| Archived | Superseded |
+
+MLflow Model Registry, SageMaker Model Registry, or Vertex AI Model Registry all follow this pattern.
+
+## Deployment Patterns
+
+### Online serving (real-time inference)
+
+- **Containerize** the model + serving code: `docker build -t model-server .`
+- **Serve** via FastAPI / Triton Inference Server / TorchServe
+- **Deploy** to Kubernetes with horizontal pod autoscaling on GPU/CPU utilization
+
+```python
+# FastAPI serving example
+@app.post("/predict")
+async def predict(req: PredictRequest) -> PredictResponse:
+  features = feature_pipeline(req.input)
+  score = model.predict(features)
+  return PredictResponse(score=score)
+```
+
+### Batch inference
+
+- Schedule periodic jobs (Airflow, Prefect) to score datasets
+- Write results to a data warehouse or feature store
+- Use Spark for large-scale batch scoring
+
+### A/B testing / Shadow mode
+
+- **Shadow mode**: new model receives traffic and logs predictions but does not serve users — validate before switching
+- **A/B test**: split traffic (e.g., 10% new model) and measure business metrics, not just accuracy
+- Use a feature flag system to control routing
+
+## Monitoring
+
+### What to monitor
+
+| Signal | Why |
+|---|---|
+| Prediction distribution | Detect output drift |
+| Feature distribution | Detect input drift (data pipeline change) |
+| Model latency (p50, p95, p99) | SLO compliance |
+| Error rate / null predictions | Serving failures |
+| Business metric (CTR, revenue) | Downstream impact |
+
+### Drift detection
+
+```python
+from evidently.report import Report
+from evidently.metric_preset import DataDriftPreset
+
+report = Report(metrics=[DataDriftPreset()])
+report.run(reference_data=reference_df, current_data=production_df)
+report.save_html("drift_report.html")
+```
+
+Tools: **Evidently**, **WhyLogs**, **Seldon Alibi Detect**.
+
+Trigger retraining when:
+- Statistical drift test fails (KS test, PSI > 0.2)
+- Business metric degrades below threshold for N consecutive periods
+- Scheduled periodic retraining cadence (baseline)
+
+## Infrastructure
+
+- **Container registry**: ECR, GCR, GHCR
+- **Object storage**: S3/GCS for datasets, model artifacts, logs
+- **Feature store**: Redis (online), BigQuery/Snowflake (offline)
+- **Orchestration**: Kubeflow, Airflow, Prefect, Vertex Pipelines
+- **Serving**: Kubernetes + Knative / SageMaker Endpoints / Vertex AI Endpoints
+- **Monitoring**: Prometheus + Grafana for infrastructure; Evidently/WhyLogs for model health
+
+## Common Pitfalls
+
+- **Training-serving skew**: feature engineering in training differs from serving — solve with a shared feature pipeline
+- **Data leakage**: future information in training features inflates metrics — use strict temporal splits
+- **Model staleness without detection**: set up drift monitoring day 1, not after the model degrades
+- **No rollback plan**: always keep N-1 model version in registry and test rollback procedure
+- **GPU waste**: jobs that could run on CPU scheduled on GPU — profile resource usage

package/skills/ai/orchestration-workflow.md

@@ -0,0 +1,87 @@
+<!--
+skills/ai/orchestration-workflow.md — Construct Orchestration Workflow — Use this skill when the request involves agent orchestration, phase transitions,
+
+Use this skill when the request involves agent orchestration, phase transitions, task keys, handoff quality, workflow state, or project alignment. ## Core Model
+-->
+# Construct Orchestration Workflow
+
+Use this skill when the request involves agent orchestration, phase transitions, task keys, handoff quality, workflow state, or project alignment.
+
+## Core Model
+
+Construct is an executive-aligned, control-plane workflow:
+
+- **Universal Orchestrator**: **Construct** is the single point of entry. It owns the outcome from strategy to production, dispatching specialists autonomously.
+- **Executive Checkpoints**: High-gate phases (Planning and Verification) require explicit Customer/Executive sign-off via the dashboard or CLI.
+- **Specialists**: `cx-*` agents own bounded work packages.
+- **Skills**: Reusable execution playbooks (searched via `search_skills`).
+- **Hooks**: Enforce continuity and system integrity (e.g. `pre-push-gate`, `dep-audit`).
+- **Resumption Protocol**: Every new session MUST begin with `workflow_status` and `project_context` to prevent "state amnesia."
+- **.cx/workflow.json**: The authoritative local task graph (Beads pattern).
+- **Cass (Memory MCP)**: Preserves durable project context across sessions and platforms.
+
+## Required State
+
+For non-trivial work, create or update `.cx/workflow.json` with:
+
+- `phase`: current phase (research, plan, implement, validate, operate)
+- `currentTaskKey`: active task
+- `tasks[].key`: stable `todo:N` key
+- `tasks[].phase`: corresponding phase
+- `tasks[].owner`: persona or cx-specialist
+- `tasks[].status`: todo, in-progress, blocked, blocked_needs_user, blocked_needs_executive, done, or skipped
+- `tasks[].readFirst`: files, docs, or memory queries to inspect first
+- `tasks[].doNotChange`: protected files or surfaces
+- `tasks[].acceptanceCriteria`: binary pass/fail checks
+- `tasks[].verification`: evidence proving completion
+
+## Commands
+
+```bash
+construct do "Goal"              # Unified natural language entry point
+construct workflow approve       # Executive sign-off on current phase
+construct workflow status        # Check alignment and progress
+construct workflow align         # Sync state and identify drift
+```
+
+## Worker Packets
+
+Specialists do not run open-ended conversations with the user. They return one terminal state:
+
+- `DONE`: changed files, decisions, verification evidence
+- `BLOCKED`: blocker, attempted steps, safest next action
+- `NEEDS_MAIN_INPUT`: `{ taskKey, worker, blocker, question, safeDefault, context }`
+
+When a worker needs user input, mark the task `blocked_needs_user`, return the `NEEDS_MAIN_INPUT` packet, and let the active persona ask the user in the main session.
+
+## Phase Gates
+
+Plan -> Implement:
+- Requirements are explicit.
+- Risks have been challenged.
+- Tasks have TASK_KEY, owner, readFirst, doNotChange, and acceptance criteria.
+
+Implement -> Validate:
+- Implementation is complete.
+- Verification evidence is recorded.
+- Changed files are listed.
+
+Validate -> Operate:
+- CRITICAL and HIGH findings are resolved.
+- Remaining risks are explicitly accepted.
+
+Operate -> Done:
+- Health checks pass.
+- Rollback path is documented.
+- Release or deployment status is recorded.
+
+## Output Discipline
+
+Keep orchestration mechanics mostly internal. The user should see:
+
+- current phase
+- current task or blocker
+- decisions that changed the plan
+- verification results
+
+Do not dump full handoff templates unless the host cannot dispatch the next phase or the user asks to see the handoff.

package/skills/ai/prompt-and-eval.md

@@ -0,0 +1,114 @@
+<!--
+skills/ai/prompt-and-eval.md — Prompt Engineering and Evaluation — Use this skill when designing prompts, evaluating model performance, or optimizi
+
+Use this skill when designing prompts, evaluating model performance, or optimizing LLM behavior. ## Prompt Structure
+-->
+# Prompt Engineering and Evaluation
+
+Use this skill when designing prompts, evaluating model performance, or optimizing LLM behavior.
+
+## Prompt Structure
+
+### System Prompt
+- Define the role and persona
+- State capabilities and constraints
+- Specify output format and style
+- Include examples of correct behavior
+- Keep stable across conversations; parameterize the variable parts
+
+### User Prompt
+- Be specific: state the task, context, and expected output
+- Provide relevant context; omit irrelevant information
+- Break complex tasks into steps
+- Use delimiters to separate instructions from data
+
+### Few-Shot Examples
+- a small set of examples is typically sufficient (often 3-7)
+- Cover the range of expected inputs and edge cases
+- Order examples from simple to complex
+- Use consistent formatting across examples
+- Include examples of correct refusal or uncertainty
+
+## Techniques
+
+### Chain of Thought
+- "Think step by step" or explicit reasoning scaffolding
+- Improves accuracy on math, logic, and multi-step reasoning
+- Increases token usage; use when accuracy justifies cost
+- Can be made invisible to users with structured output parsing
+
+### Self-Consistency
+- Generate multiple responses with temperature >0
+- Select the most common answer (majority vote)
+- Improves reliability on ambiguous or difficult tasks
+- Cost multiplied by number of samples
+
+### Structured Output
+- Request JSON, YAML, or XML with a defined schema
+- Provide the schema in the prompt
+- Validate outputs programmatically
+- Use constrained decoding when available
+
+### Retrieval-Augmented Generation
+- Include retrieved context with clear source attribution
+- Instruct the model to answer only from provided context
+- See `skills/ai/rag-system.md` for full RAG guidance
+
+## Anti-Patterns
+
+- Vague instructions ("do your best", "be creative")
+- Conflicting constraints in the same prompt
+- Excessive context that buries the actual task
+- Over-relying on temperature to fix prompt quality issues
+- Not testing prompts against edge cases before deployment
+
+## Evaluation Framework
+
+### Offline Evaluation
+1. Build a labeled dataset: input + expected output
+2. Define metrics per task type (see below)
+3. Run the full pipeline on the eval set
+4. Track metrics over time; catch regressions
+5. Automate eval on every prompt or model change
+
+### Online Evaluation
+- A/B test prompt variants on live traffic
+- Collect user feedback: thumbs up/down, corrections
+- Monitor: latency, cost, user satisfaction, task completion
+
+### Metrics by Task Type
+
+| Task | Primary Metrics |
+|---|---|
+| Classification | Precision, recall, F1, confusion matrix |
+| Generation | Faithfulness, relevance, fluency, human preference |
+| Extraction | Exact match, field-level accuracy, hallucination rate |
+| Summarization | ROUGE, faithfulness, compression ratio, human eval |
+| Code generation | Pass rate on test cases, correctness, security |
+| Conversation | Task completion, turns to resolution, user satisfaction |
+
+### Human Evaluation
+- Use when automated metrics are insufficient
+- Blind evaluation: evaluators do not know which variant they rate
+- Inter-annotator agreement to measure consistency
+- Rubric-based scoring with clear criteria
+- Sample size sufficient for statistical significance
+
+## Model Selection
+
+| Consideration | Guidance |
+|---|---|
+| Latency | Smaller models for real-time; larger for batch |
+| Cost | Price per token varies 10-100x across model tiers |
+| Accuracy | Benchmark on your specific task, not general leaderboards |
+| Context window | Match to your typical input + output size |
+| Fine-tuning | When prompting alone cannot capture domain patterns |
+
+## Optimization Workflow
+
+1. Start with a clear prompt on the strongest available model
+2. Evaluate on a representative dataset
+3. Iterate on the prompt to fix failure modes
+4. Once prompt is stable, test on smaller/cheaper models
+5. Fine-tune only when prompt engineering plateaus
+6. Continuously monitor and re-evaluate after deployment

package/skills/ai/prompt-optimizer.md

@@ -0,0 +1,114 @@
+<!--
+skills/ai/prompt-optimizer.md — Closed-loop prompt auto-optimization guide.
+
+Uses Langfuse traces and quality scores as the feedback signal, Claude as the optimizer,
+and the agent registry + construct sync as the deployment layer.
+-->
+# Prompt Auto-Optimization Loop
+
+Construct's prompt improvement system uses Langfuse traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`agents/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
+
+## Running the optimizer
+
+```bash
+# Analyze and push staging version
+construct optimize cx-engineer
+
+# Dry run — see failure patterns without pushing
+construct optimize cx-engineer --dry-run
+
+# List all agents with current quality scores
+construct optimize --list
+
+# Tune parameters
+construct optimize cx-debugger --threshold=0.65 --days=14 --min-traces=15
+```
+
+The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-install `dspy-ai` and `requests` on first run. Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in `.env`. DSPy uses the same LLM key Construct uses — no separate setup.
+
+## When to run
+
+- Triggered by `/work:optimize-prompts` (manual) or the scheduled task `prompt-optimization-weekly`
+- Automatically suggested when `cx-trace-reviewer` finds an agent with median quality score below 0.65 over the past 7 days
+- Never run optimization on prompts with fewer than 20 scored traces — insufficient signal
+
+## Step 1 — Gather signal
+
+Retrieve the current production prompt for the target agent from `agents/registry.json` (or the corresponding `promptFile` if using extracted prompts).
+
+Then retrieve recent traces via the Langfuse REST API:
+
+```
+GET {LANGFUSE_BASEURL}/api/public/traces?tags={agentName}&limit=50
+# Auth: Basic base64(LANGFUSE_PUBLIC_KEY:LANGFUSE_SECRET_KEY)
+```
+
+To fetch quality scores for traces:
+```
+GET {LANGFUSE_BASEURL}/api/public/scores?traceId={id}&name=quality
+```
+
+Filter to scores where `value < 0.7`. For each low-scoring trace, extract: the prompt used, the user input, the model output, the quality score, and any human comments.
+
+## Step 2 — Diagnose failure patterns
+
+Analyze the low-scoring traces as a batch. Identify recurring failure modes. Common patterns:
+
+| Pattern | Diagnostic signal |
+|---|---|
+| Output too verbose | Long outputs consistently score low; user messages are short questions |
+| Missing context | Outputs lack specific file/line references; traces show no Read tool calls |
+| Wrong routing | Agent performs work outside its stated role |
+| Hallucination risk | Outputs assert facts not present in tool results |
+| Format drift | Output format varies; scoring is inconsistent on structure |
+| Insufficient depth | Outputs are correct but shallow; scored down for missing detail |
+
+Write a failure summary: top 3 patterns with supporting trace count and representative examples.
+
+## Step 3 — Generate improved prompt
+
+Write an improved prompt that directly addresses the diagnosed failures. Rules:
+
+1. **Keep what works** — compare high-scoring traces (>0.8) to low-scoring ones. Only change what's associated with failures.
+2. **Surgical edits, not rewrites** — changing everything risks breaking current strengths. Identify the specific clauses that correlate with failures.
+3. **Be explicit, not vague** — if the failure is "too verbose", add a concrete rule ("respond in under 150 words for questions that fit on one line") not a general note ("be concise").
+4. **Add a self-check instruction** — append a brief checklist the agent runs before responding, derived from the top failure patterns.
+
+## Step 4 — Push to staging
+
+Update the agent's prompt in `agents/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
+
+Log the candidate prompt as a span attribute on a test run batch using `cx_trace`. Tag spans with `promptVersion: staging-{timestamp}` and score them with `cx_score` as traces complete.
+
+Do not overwrite the production prompt in the registry until promotion is confirmed.
+
+## Step 5 — Monitor staging
+
+After at least 20 scored traces on the staging version:
+- Compare median quality score: staging vs production
+- If staging median > production median + 0.05: promote
+- If staging median ≤ production median: rollback (restore previous prompt, document why)
+
+To promote: update the agent registry with the accepted prompt and run `construct sync`.
+
+## Step 6 — Document the optimization
+
+Write to `.cx/decisions/` with:
+- Which agent was optimized
+- Previous vs new median quality score
+- Top 3 failure patterns addressed
+- What changed in the prompt (diff summary)
+- Date and version numbers
+
+This becomes the audit trail for future optimizations and regression analysis.
+
+## Regression detection
+
+Run `cx-trace-reviewer` after every promotion. If the newly promoted prompt shows worse performance after 48 hours of production traffic:
+1. Revert to the previous prompt in the registry and run `construct sync`
+2. Start a new optimization cycle with the regression as the primary failure signal
+
+## What this does not replace
+
+- **DSPy**: If you need algorithmic optimization over large datasets with measurable metrics (classification, structured output), DSPy is the right tool and integrates with Langfuse for tracing. This skill is for natural-language agent prompts where the metric is quality score.
+- **Human review**: Always read the generated prompt before pushing to staging. The LLM optimizer can introduce subtle regressions. Automated promotion should only happen after confirming the diff makes sense.

package/skills/ai/rag-system.md

@@ -0,0 +1,104 @@
+<!--
+skills/ai/rag-system.md — RAG System Design — Use this skill when building retrieval-augmented generation pipelines, vector se
+
+Use this skill when building retrieval-augmented generation pipelines, vector search, or knowledge-grounded AI systems. ## Document Processing
+-->
+# RAG System Design
+
+Use this skill when building retrieval-augmented generation pipelines, vector search, or knowledge-grounded AI systems.
+
+## Document Processing
+
+### Chunking Strategies
+- Fixed size: 512-1024 tokens with 10-20% overlap; simple, predictable
+- Semantic: split on paragraph, section, or topic boundaries; preserves coherence
+- Recursive: try large chunks, split smaller only when needed
+- Document-aware: respect headers, tables, code blocks as atomic units
+- Always preserve metadata: source, page, section, timestamp
+
+### Preprocessing
+- Extract text from PDFs, DOCX, HTML; preserve structure
+- Normalize whitespace, encoding, and character sets
+- Strip boilerplate (headers, footers, navigation) from web pages
+- Deduplicate identical or near-identical chunks
+- Handle tables and images: extract text, generate descriptions
+
+## Embedding
+
+- Choose embedding model based on retrieval quality, not just speed
+- Match embedding model to chunk size (most optimize for 256-512 tokens)
+- Normalize vectors if using cosine similarity
+- Benchmark retrieval accuracy on a representative eval set before deploying
+- Consider late-interaction models (ColBERT) for higher accuracy at more compute
+
+## Vector Database
+
+| System | Strength |
+|---|---|
+| Pinecone | Managed, serverless scaling |
+| Weaviate | Hybrid search, multi-modal |
+| Qdrant | Filtering, payload storage |
+| pgvector | Postgres-native, simple deployment |
+| Chroma | Local development, lightweight |
+
+### Indexing
+- HNSW for high recall with reasonable memory
+- IVF for large-scale with memory constraints
+- Tune `ef_construction` and `M` parameters for recall vs build time
+- Partition by tenant or document collection for isolation
+
+## Retrieval
+
+### Hybrid Search
+- Combine dense vector search with sparse keyword search (BM25)
+- Use reciprocal rank fusion to merge result lists
+- Keyword search catches exact matches that embeddings miss
+- Dense search captures semantic similarity that keywords miss
+
+### Reranking
+- Cross-encoder reranker on top-k candidates (k=20-50)
+- Improves precision significantly at moderate latency cost
+- Use a smaller, faster model than the generation LLM
+
+### Query Processing
+- Query expansion: rephrase user query into multiple search queries
+- HyDE: generate a hypothetical answer, embed it, search with that vector
+- Decomposition: break complex queries into sub-queries, retrieve for each
+- Filter by metadata when the query implies scope (date, source, category)
+
+## Context Assembly
+
+- Order retrieved chunks by relevance
+- Deduplicate overlapping content
+- Include source attribution for each chunk
+- Respect context window limits; prioritize quality over quantity
+- Typical prompt structure: system instructions, retrieved context, user query
+
+## Evaluation
+
+### Retrieval Metrics
+- Recall@k: did the relevant chunks appear in top-k results?
+- MRR: how high is the first relevant result?
+- NDCG: overall ranking quality of returned results
+
+### Generation Metrics
+- Faithfulness: does the answer stay grounded in retrieved context?
+- Relevance: does the answer address the user's question?
+- Completeness: does the answer cover all aspects of the query?
+- Hallucination rate: percentage of claims not supported by context
+
+### Eval Process
+1. Build a labeled dataset: query + relevant passages + expected answer
+2. Measure retrieval quality independent of generation
+3. Measure generation quality with gold-standard context
+4. Measure end-to-end with the full pipeline
+5. Automate eval runs on every pipeline change
+
+## Common Failures
+
+- Chunk too large: dilutes relevance signal
+- Chunk too small: loses context needed for coherent answers
+- Missing metadata: cannot filter or attribute sources
+- No reranking: first-stage retrieval alone has low precision
+- No eval: impossible to know if changes improve or degrade quality
+- Stale index: documents updated but embeddings not refreshed

package/skills/architecture/api-design.md

@@ -0,0 +1,100 @@
+<!--
+skills/architecture/api-design.md — API Design — Use this skill when designing REST, GraphQL, or gRPC APIs.
+
+Use this skill when designing REST, GraphQL, or gRPC APIs. ## REST Design Principles
+-->
+# API Design
+
+Use this skill when designing REST, GraphQL, or gRPC APIs.
+
+## REST Design Principles
+
+### Resource Naming
+- Use plural nouns: `/users`, `/orders`, `/products`
+- Nest for relationships: `/users/{id}/orders`
+- Limit nesting to two levels; use query params for deeper filtering
+- Use kebab-case for multi-word paths: `/order-items`
+- Avoid verbs in URLs; let HTTP methods express the action
+
+### HTTP Methods
+- GET: read, idempotent, cacheable
+- POST: create, not idempotent
+- PUT: full replace, idempotent
+- PATCH: partial update, idempotent
+- DELETE: remove, idempotent
+
+### Status Codes
+- 200 OK: successful read or update
+- 201 Created: successful creation, include Location header
+- 204 No Content: successful delete
+- 400 Bad Request: validation failure
+- 401 Unauthorized: missing or invalid authentication
+- 403 Forbidden: authenticated but not authorized
+- 404 Not Found: resource does not exist
+- 409 Conflict: state conflict (duplicate, version mismatch)
+- 429 Too Many Requests: rate limited
+- 500 Internal Server Error: unhandled server failure
+
+### Versioning
+- URL path versioning (`/v1/users`) for major breaking changes
+- Header versioning for minor variations
+- Support at most two major versions concurrently
+- Deprecation period: minimum 6 months with Sunset header
+
+## Response Envelope
+
+```json
+{
+  "data": {},
+  "error": null,
+  "meta": { "page": 1, "limit": 20, "total": 142 }
+}
+```
+
+- Consistent structure across all endpoints
+- Paginate all list endpoints; default limit 20, max 100
+- Use cursor-based pagination for large or real-time datasets
+- Include total count only when it is cheap to compute
+
+## GraphQL Design
+
+- Separate queries and mutations clearly
+- Use input types for mutation arguments
+- Implement connection-based pagination (Relay spec)
+- Set query depth and complexity limits
+- Disable introspection in production
+- Use DataLoader to batch and deduplicate database queries
+- Version via schema evolution, not URL versioning
+
+## gRPC Design
+
+- Define services and messages in `.proto` files
+- Use streaming for large datasets or real-time updates
+- Implement health checking service
+- Set deadlines on all RPCs
+- Use interceptors for auth, logging, and metrics
+- Version via package namespacing
+
+## Error Design
+
+- Machine-readable error code (string enum, not just HTTP status)
+- Human-readable message
+- Field-level validation errors as an array
+- Request ID for correlation
+- Do not expose internal details (stack traces, SQL errors)
+
+## Rate Limiting
+
+- Per-user and per-IP limits
+- Return `Retry-After` header with 429 responses
+- Use sliding window or token bucket algorithm
+- Higher limits for authenticated requests
+- Separate limits for read and write operations
+
+## Documentation
+
+- OpenAPI 3.x spec for REST; keep it as the source of truth
+- Auto-generate client SDKs from the spec
+- Include request/response examples for every endpoint
+- Document authentication requirements per endpoint
+- Migration or upgrade note for every breaking change, reflected in the project's canonical docs surface