ziran: Instructions file for Claude Code

ziran Development Guidelines

Auto-generated from all feature plans. Last updated: 2026-10-04

Active Technologies

• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + asyncio, dataclasses, logging, OpenTelemetry (tracing) (003-split-agent-scanner)
• N/A (in-memory knowledge graph via NetworkX) (003-split-agent-scanner)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + Pydantic (config models), re (stdlib regex) (003-precompile-regex-patterns)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + PyYAML (scenario loading), Pydantic (schema validation) (007-ground-truth-business-impact)
• YAML files (ground truth scenarios and agent archetypes) (007-ground-truth-business-impact)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + TypeScript 5.x (frontend) + FastAPI, SQLAlchemy (async), asyncpg, Alembic, uvicorn (backend); React 18, Vite, TanStack Query, shadcn/ui, Tailwind CSS, vis-network (frontend) (008-web-ui-foundation)
• PostgreSQL via asyncpg (configurable via ZIRAN_DATABASE_URL env var) (008-web-ui-foundation)
• Python 3.11+ (backend), TypeScript 5.x (frontend) + FastAPI, SQLAlchemy 2.0 (async), Alembic, Pydantic v2 (backend); React 18, Vite, TanStack Query, TanStack Table, shadcn/ui, Tailwind CSS (frontend) (009-ui-findings-compliance)
• PostgreSQL via asyncpg (existing ZIRAN_DATABASE_URL) (009-ui-findings-compliance)
• Python 3.11+ (backend), TypeScript 5.x (frontend) + FastAPI, SQLAlchemy 2.0 (async), Pydantic v2 (backend); React 18, Vite, TanStack Query/Table, shadcn/ui, Tailwind CSS, vis-network (frontend) (010-ui-polish-pages)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + click (CLI), httpx (async HTTP), pydantic (models), networkx (graph), pyyaml (config), rich (output), mdutils (reports). New optional: langfuse (trace pull). (011-runtime-bridge-v0-8)
• Local JSON files for registry snapshots (.ziran/snapshots/); no database. (011-runtime-bridge-v0-8)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + pydantic (models), PyYAML (vector loader), click (CLI), rich (reports), networkx (graph — unchanged). No new dependencies. (012-benchmark-maturity)
• YAML vector files under ziran/application/attacks/vectors/; benchmark result JSON under benchmarks/results/; docs under docs/reference/benchmarks/. (012-benchmark-maturity)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + re (stdlib), existing ziran.application.detectors module (013-multilingual-refusal-detection)
• N/A (in-memory pattern matching) (013-multilingual-refusal-detection)
• Python 3.11+ (CI matrix: 3.11, 3.12, 3.13) + httpx (async HTTP — Slack + GitHub REST), Pydantic v2 (config + entity models), PyYAML (config + new !env tag), Click (CLI). Composite GitHub Action uses gh CLI + bash, no new runtime deps. (017-runtime-loop-alerting)
• None new. Dedup is stateless via GitHub-side issue markers; existing registry snapshots stay in .ziran/snapshots/ (local JSON). (017-runtime-loop-alerting)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (threshold + dataset models), PyYAML (dataset + config loading, reusing load_yaml_with_env), Click (benchmark CLI entry point), existing ziran.application.detectors pipeline. No new runtime dependencies. (021-detection-accuracy-benchmark)
• YAML files for the labelled dataset (under benchmarks/ground_truth/detection/) and for operator config (.ziran/detectors.yaml); JSON result + baseline artifacts under benchmarks/results/ (existing pattern). (021-detection-accuracy-benchmark)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (cassette + comparison + result models), PyYAML (CVE target definitions, reusing spec-007 schema), Click/argparse (benchmark CLI), existing AgentScanner + PentestOrchestrator. Recording (opt-in) additionally needs the existing pentest extra (langgraph) + a live BaseLLMClient. No new runtime dependencies. (022-pentest-vs-scanner-benchmark)
• YAML for CVE-modeled ground-truth agents (benchmarks/ground_truth/agents/); JSON cassettes for recorded agent runs (benchmarks/ground_truth/pentest_runs/); JSON results + baseline under benchmarks/results/ (existing pattern). (022-pentest-vs-scanner-benchmark)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (ManyShotConfig model + validators), PyYAML (vectors + synthetic corpus loading), existing AttackLibrary / AttackExecutor / AgentScanner. No new runtime dependencies (token estimate is a char heuristic, not tiktoken). (023-many-shot-jailbreak)
• YAML — the vector file (ziran/application/attacks/vectors/many_shot_jailbreak.yaml) and a synthetic shot corpus (ziran/application/attacks/vectors/many_shot_corpus.yaml). (023-many-shot-jailbreak)
• Python 3.11+ (CI matrix 3.11/3.12/3.13) backend; TypeScript 5.x / Node frontend — no new source code, only manifests, lockfiles, CI workflows, and docs. + package managers + audit tooling — uv (Python lock/sync), npm (frontend lock), pip-audit (Python vuln gate), npm audit (frontend vuln gate). No new runtime dependencies in ziran/. (024-security-alert-remediation)
• N/A (no data store). The committed risk-acceptance record (docs/security/risk-acceptances.md) is the only new persisted artifact. (024-security-alert-remediation)
• Python 3.11+ (CI matrix 3.11/3.12/3.13); TypeScript frontend unaffected. (025-dependency-modernization)
• N/A. Touched persisted artifact: docs/security/risk-acceptances.md (rows removed). (025-dependency-modernization)
• Python 3.11+ (CI matrix 3.11/3.12/3.13) backend; TypeScript 5.x / React 18 frontend. + Backend — FastAPI, SQLAlchemy 2.0 (async), Alembic, asyncpg, Pydantic v2, NetworkX, mdutils/f-string HTML report. Frontend — React 18, Vite, TanStack Query v5, vis-network v10.0.2 + vis-data v8, Tailwind/shadcn. Report — vis-network via CDN (currently v9.1.9). No new runtime dependencies anticipated (vis-network clustering + hierarchical layout already available). (026-interactive-knowledge-graph)
• PostgreSQL via asyncpg (ZIRAN_DATABASE_URL). New: graph_state_json JSONB column on phase_results. (026-interactive-knowledge-graph)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (entities/config), PyYAML (vector loading), re (stdlib). No new dependencies. (027-detector-indicator-false-positives)
• N/A — attack vectors are YAML files under ziran/application/attacks/vectors/; benchmark artifacts under benchmarks/. (027-detector-indicator-false-positives)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + stdlib re; existing PyYAML (pattern loading), Pydantic v2 (DangerousChain), NetworkX. No new dependencies. (033-claude-code-chain-patterns)
• N/A — patterns in ziran/application/knowledge_graph/chain_patterns.yaml; benchmark YAML under benchmarks/ground_truth/. (033-claude-code-chain-patterns)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Click (CLI), Pydantic v2 (existing entities), stdlib re/functools; reuses canonical_tool_name (#417) and SA001 secret rules. No new dependencies. (034-claude-code-otel-traces)
• N/A. Report file trace_analysis.json in --out (existing). (034-claude-code-otel-traces)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Click, Pydantic v2 (baseline file models); reuses #418 agent_chains. No new dependencies. (039-audit-allowlist-baseline)
• one user-committed JSON file (the baseline); read and written only by the CLI. (039-audit-allowlist-baseline)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (models), PyYAML safe_load/compose (frontmatter), stdlib json/re; reuses load_claude_mcp_config (#422) and the domain is_dangerous classifier. No new dependencies. (037-claude-code-plugin-parser)
• N/A — reads plugin files only. (037-claude-code-plugin-parser)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Click (CLI), existing StaticAnalyzer, ToolChainAnalyzer (NetworkX) and #416 load_claude_code. No new dependencies. (038-audit-claude-code-plugins)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13); composite action in bash. + Click, stdlib json/pathlib, existing ziran/application/cicd/sarif.py, #419 --baseline; action uses setup-python + upload-sarif (already used). No new dependencies. (040-action-plugin-audit)
• N/A. Files: the SARIF output, the user-committed baseline. (040-action-plugin-audit)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2, stdlib math/hashlib/asyncio, existing optional llm extra (litellm aembedding). No new dependencies. (042-semantic-embedding-detection)
• Committed JSON embedding cassette benchmarks/ground_truth/semantic_embeddings.json (only once recorded with a real model). (042-semantic-embedding-detection)
• Markdown (MkDocs Material); Python 3.11+ test and example stdio server (CI matrix 3.11, 3.12, 3.13) + None new; shipped ziran audit / analyze-traces / watch-registry CLI, Click CliRunner, stdlib json/sys (044-claude-code-plugin-guide)
• N/A (committed example files; runtime output in git-ignored reports/ or tmp_path) (044-claude-code-plugin-guide)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (config + benchmark models), stdlib asyncio; reuses LLMJudgeDetector, create_llm_client, ReplayLLMClient. No new dependencies. (043-two-tier-judging)
• N/A at runtime. Benchmark: optional cheap-model cassette benchmarks/ground_truth/prefilter_verdicts.json, result benchmarks/results/two_tier_judging.json. (043-two-tier-judging)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (usage + price models), PyYAML safe_load (price table), Click (scan flags); reuses BaseLLMClient, many_shot.estimate_tokens, the checkpoint/resume path, PhaseExecutor, ResultBuilder. No new dependencies. (047-token-budget-cost-cap)
• shipped ziran/infrastructure/llm/prices.yaml plus optional operator .ziran/prices.yaml; usage ledger snapshot inside the existing <output>/.checkpoint.json. (047-token-budget-cost-cap)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (suppression file + finding models), PyYAML safe_load, stdlib hashlib/json/datetime, Click. No new dependencies. (046-ci-suppression-baseline)
• one user-committed YAML file, read only by ziran ci. (046-ci-suppression-baseline)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (domain models), existing AttackKnowledgeGraph (NetworkX) and ToolChainAnalyzer, langgraph 1.2.x + langchain-core via the existing langchain extra (transitive). No new dependencies. (050-langgraph-native-scanning)
• N/A — in-memory knowledge graph only. (050-langgraph-native-scanning)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (cache models), stdlib hashlib/json/os/re/shutil/asyncio.to_thread, Click (scan flags, cache clear); reuses PhaseExecutor, ResultBuilder, the CheckpointManager.save atomic-write pattern. No new dependencies. (049-incremental-scan-cache)
• per-vector JSON files under .ziran/scan_cache/<campaign_key>/ (working directory; git-ignored; never committed). (049-incremental-scan-cache)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + Pydantic v2 (Field validation), stdlib asyncio. No new dependencies. (051-probe-rate-limiting)
• N/A (target YAML is read by the existing load_target_config). (051-probe-rate-limiting)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + pytest, fastapi.testclient.TestClient (fastapi from the ui extra), stdlib unittest.mock. Tests only, no production change. No new dependencies. (052-web-route-handler-tests)
• N/A (no database, no files). (052-web-route-handler-tests)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13) + existing NetworkX-backed AttackKnowledgeGraph; stdlib only (053-enables-edge-fanout)
• N/A (in-memory graph). (053-enables-edge-fanout)
• Python 3.11+ (CI matrix 3.11, 3.12, 3.13); GitHub Actions YAML + bash (the benchmark job uses Python 3.12). + stdlib argparse/json/pathlib (already imported), actions/checkout@v7 (already used). No new dependencies. (054-benchmark-pr-delta)
• committed benchmarks/results/baseline.json (gate); CI-only _bench_base/benchmarks/results/baseline.json (delta, never committed). (054-benchmark-pr-delta)
• Markdown (MkDocs Material); Python 3.11+ test (CI matrix 3.11, 3.12, 3.13) + none new. Reads output of the existing benchmarks/atlas_coverage.py. (055-atlas-coverage-docs)