synaptiai/agent-capability-standard/generate

content: string | object  # The generated artifact
metadata:  # Generation metadata
  type: string  # text, code, plan, config, schema, etc.
  format: string  # markdown, json, yaml, typescript, etc.
constraints_used:
  - constraint: string  # Constraint description
    satisfied: boolean  # Was it met?
    notes: string  # How it was satisfied or why not
rationale: string  # Why this design/approach
alternatives_considered: array[string]  # Other approaches evaluated
quality_signals:
  - metric: string  # Quality dimension
    value: number | string  # Assessment
confidence: number  # 0.0-1.0 in artifact quality
evidence_anchors: array[string]  # References to source material
assumptions: array[string]  # Conditions affecting the artifact
safety_notes: array[string]  # Security/reliability considerations
next_actions: array[string]  # Suggested follow-ups

specification:
  artifact_type: "code"
  endpoint: "POST /api/users"
  schema: "{ name: string, email: string, role: 'admin' | 'user' }"
constraints:
  must_have:
    - "TypeScript with strict mode"
    - "Express.js middleware pattern"
    - "Input validation with Zod"
    - "Return 200 on success, 400 on validation error, 500 on server error"
format: "typescript"

content: |
  import { Request, Response, NextFunction } from 'express';
  import { z } from 'zod';
 
  const CreateUserSchema = z.object({
    name: z.string().min(1).max(100),
    email: z.string().email(),
    role: z.enum(['admin', 'user'])
  });
 
  type CreateUserInput = z.infer<typeof CreateUserSchema>;
 
  export async function createUser(
    req: Request,
    res: Response,
    next: NextFunction
  ): Promise<void> {
    try {
      const parsed = CreateUserSchema.safeParse(req.body);
 
      if (!parsed.success) {
        res.status(400).json({
          error: 'Validation failed',
          details: parsed.error.issues
        });
        return;
      }
 
      const userData: CreateUserInput = parsed.data;
 
      // TODO: Implement actual user creation logic
      const user = await userService.create(userData);
 
      res.status(200).json({ user });
    } catch (error) {
      next(error);
    }
  }
metadata:
  type: "code"
  format: "typescript"
constraints_used:
  - constraint: "TypeScript with strict mode"
    satisfied: true
    notes: "All types explicit, strict null checks compatible"
  - constraint: "Express.js middleware pattern"
    satisfied: true
    notes: "Standard (req, res, next) signature with async handler"
  - constraint: "Input validation with Zod"
    satisfied: true
    notes: "Zod schema with safeParse for type-safe validation"
  - constraint: "HTTP status codes"
    satisfied: true
    notes: "200 success, 400 validation error, 500 via error middleware"
rationale: "Used safeParse over parse for explicit error handling without exceptions. Separated schema definition for reuse in tests. Left business logic as TODO for service layer."
alternatives_considered:
  - "class-validator with decorators - rejected for runtime overhead"
  - "Manual validation - rejected for type safety"
quality_signals:
  - metric: "type_safety"
    value: "high"
  - metric: "error_handling"
    value: "comprehensive"
  - metric: "testability"
    value: "high"
confidence: 0.9
evidence_anchors:
  - "zod:docs:safeParse"
  - "express:docs:error-handling"
assumptions:
  - "userService exists and is imported"
  - "Error middleware handles uncaught exceptions"
safety_notes:
  - "Email validation does not prevent all injection attacks"
  - "Consider rate limiting for user creation endpoint"
next_actions:
  - "Implement userService.create method"
  - "Add authentication middleware"
  - "Write unit tests for validation logic"

specification:
  artifact_type: "schema"
  description: "Database connection configuration"
constraints:
  must_have:
    - "JSON Schema draft-07"
    - "Required fields: host, port, database"
    - "Optional: ssl, poolSize, timeout"
  should_have:
    - "Sensible defaults where appropriate"
format: "json"

content:
  $schema: "http://json-schema.org/draft-07/schema#"
  title: "DatabaseConfig"
  type: "object"
  required: ["host", "port", "database"]
  properties:
    host:
      type: "string"
      description: "Database server hostname"
      examples: ["localhost", "db.example.com"]
    port:
      type: "integer"
      minimum: 1
      maximum: 65535
      description: "Database server port"
      default: 5432
    database:
      type: "string"
      description: "Database name"
      minLength: 1
    ssl:
      type: "boolean"
      description: "Enable SSL/TLS connection"
      default: true
    poolSize:
      type: "integer"
      minimum: 1
      maximum: 100
      description: "Connection pool size"
      default: 10
    timeout:
      type: "integer"
      minimum: 0
      description: "Connection timeout in milliseconds"
      default: 30000
  additionalProperties: false
metadata:
  type: "schema"
  format: "json"
constraints_used:
  - constraint: "JSON Schema draft-07"
    satisfied: true
    notes: "$schema declaration included"
  - constraint: "Required fields: host, port, database"
    satisfied: true
    notes: "Listed in required array"
  - constraint: "Optional: ssl, poolSize, timeout"
    satisfied: true
    notes: "Not in required, have defaults"
  - constraint: "Sensible defaults"
    satisfied: true
    notes: "port=5432 (PostgreSQL), ssl=true, poolSize=10, timeout=30s"
rationale: "Used PostgreSQL port as default assuming most common use case. SSL enabled by default for security. Pool size 10 balances resource usage with concurrency."
alternatives_considered:
  - "MySQL port 3306 - rejected, PostgreSQL more common in modern stacks"
quality_signals:
  - metric: "completeness"
    value: "high"
  - metric: "documentation"
    value: "descriptions and examples included"
confidence: 0.95
evidence_anchors:
  - "json-schema:draft-07:spec"
assumptions:
  - "PostgreSQL is the target database"
  - "Production deployment expects SSL"
safety_notes:
  - "Consider encrypting credentials in actual config files"
  - "poolSize limits should match database max_connections"
next_actions:
  - "Add validation for connection string format"
  - "Consider environment variable substitution"