siclaw: Instructions file for Codex

Siclaw Project Instructions

This file is the project-level Codex guide for siclaw_dp_cleanup. Keep it limited to stable Siclaw facts and constraints. General collaboration style belongs in ~/.codex/AGENTS.md; CLAUDE.md is the larger legacy reference when deeper background is needed.

Project Shape

Siclaw is an AI-powered SRE copilot for Kubernetes diagnostics.

One agent core supports three runtime shapes:

Headless CLI: non-interactive diagnostic invocation, optionally paired with local Portal
Gateway + LocalSpawner: local multi-user dev, one process/shared filesystem
Gateway + K8sSpawner: production, one isolated pod per user

Before Risky Edits

• Preserve user changes and unrelated dirty work.
• For security, tool execution, database, Portal snapshot, guards, memory, Docker, Helm, or K8s behavior, read the nearby code plus relevant docs/design/* or CLAUDE.md before editing.
• Ask before editing src/core/prompt.ts; it affects core agent behavior and product tone.
• Do not add production dependencies unless explicitly requested.

Verification

Use targeted checks first, then broaden when touching shared behavior:

npm test
npx tsc --noEmit
npm run build

Broaden verification for database schema, tool execution, guards, Portal snapshot, K8s/Docker/Helm, or user-facing workflows.

Stable Boundaries

• LocalSpawner runs all local AgentBox instances in one process with a shared filesystem. Local skill sync must stay user-scoped and must not wipe shared skill directories such as global/skillset/user trees.
• Core skills are baked into the Docker image. Workspace skill bundles should include only selected global/dev/personal skills.
• Headless CLI uses local Portal as a read-only snapshot source. Unscoped invocations tolerate unavailable snapshot access; a selected agent must load successfully. Snapshot caches are private to each invocation, including empty resource sets, and cleanup must never touch another invocation.
• Shell execution security is layered: OS-level isolation first, whitelist-only command validation second, plus pre/post execution sanitization.
• Portal/Gateway DB and Memory DB are separate persistence domains. Do not mix user/session config with embedding/chunk/investigation storage.
• AgentBox and Runtime are separate processes in K8s mode. Code under src/agentbox/** must not import Gateway or Portal persistence modules such as src/gateway/chat-repo.ts; LocalSpawner's shared process can hide this. AgentBox background work should call Runtime internal APIs through GatewayClient, with Runtime owning Portal RPC and database persistence.
• src/portal/migrate.ts must stay compatible with both MySQL and SQLite.
• mTLS is for K8s mode only; do not pull mTLS requirements into local mode.