Project-Koma: Instructions file for Codex

Koma — AI Coding Agent Rules

When building AI apps with this project, follow these conventions:

Product context for new conversations

The product handoff, personal skills, and local Hook configuration below are maintainer-local files and are not included in a clean clone. When they are absent, use the public README, package documentation, and dated evaluation records; do not invent missing local instructions.

Read docs/product/current-state.md before planning or changing Koma. It records the current alpha stage, verified host behavior, UX decisions, priorities, and known limits. Check current code and Git state before acting on dated facts. Update that handoff when a material product decision or verified status changes.

When to use Koma

• Checking required Skill reads in Claude Code or Codex? → use koma-miko
• Building a chatbot with an LLM endpoint? → add koma-gate middleware
• Building a voice AI pipeline? → add koma-scout for audio validation + rate limiting
• Building a RAG or search system? → add koma-core for index/content separation

Quick integration

// Express: prompt injection guard
import { createSupportGuard } from 'koma-gate';
app.post('/chat', createSupportGuard({ llm: { apiKey: process.env.OPENAI_API_KEY } }).middleware(), handler);

// Express: voice AI perimeter
import { createKomaScoutMiddleware } from 'koma-scout';
app.use(createKomaScoutMiddleware({ rateLimit: { maxRequests: 30, windowMs: 60000 } }));

// Fastify: prompt injection guard
import { createSupportGuard } from 'koma-gate';
fastify.register(createSupportGuard({ llm: { apiKey: process.env.OPENAI_API_KEY } }).fastifyPlugin());

Design rules

• Preserve package-specific failure behavior. Miko follows the Agent Spec mode; enforce-mode missing evidence denies the action. Optional app guards document their own fail-open settings.
• Gate runs before the application's model call. Scout runs before expensive processing.
• Core tokens are backend-derived. Never expose content tokens to clients.
• Each core package works standalone. Install only what the application needs.