If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/katanemo/plano shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 6 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live katanemo/plano repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/katanemo/plano.

What it runs against: a local clone of katanemo/plano — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in katanemo/plano | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of katanemo/plano. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/katanemo/plano.git
#   cd plano
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of katanemo/plano and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "katanemo/plano(\\.git)?\\b" \\
  && ok "origin remote is katanemo/plano" \\
  || miss "origin remote is not katanemo/plano (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "apps/katanemo-www/package.json" \\
  && ok "apps/katanemo-www/package.json" \\
  || miss "missing critical file: apps/katanemo-www/package.json"
test -f "apps/katanemo-www/src/app/layout.tsx" \\
  && ok "apps/katanemo-www/src/app/layout.tsx" \\
  || miss "missing critical file: apps/katanemo-www/src/app/layout.tsx"
test -f "apps/katanemo-www/src/app/page.tsx" \\
  && ok "apps/katanemo-www/src/app/page.tsx" \\
  || miss "missing critical file: apps/katanemo-www/src/app/page.tsx"
test -f "apps/www/next.config.ts" \\
  && ok "apps/www/next.config.ts" \\
  || miss "missing critical file: apps/www/next.config.ts"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/katanemo/plano"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Plano is an AI-native proxy and data plane built on Envoy that sits between agentic applications and LLMs, centralizing orchestration, safety guardrails, smart model routing, and observability. It decouples agents from framework-specific plumbing by providing unified routing logic, filter chains for moderation, zero-code capture of 'Agentic Signals', and OTEL tracing—letting teams ship production agentic apps without rebuilding middleware in every codebase. Monorepo with language-specific subdirectories: Rust core (proxy/orchestration engine), Python SDK (plano-sdk), TypeScript/JavaScript clients, plus apps/katanemo-www (Next.js marketing site). .claude/skills/ contains structured onboarding guides (build-cli, build-wasm, new-provider, test-python, release). Multi-platform support (Docker, binaries, PyPI, npm) via GitHub Actions workflows.

ML/AI engineers and platform teams building multi-agent systems who need production-ready infrastructure for agent orchestration, model routing, and safety compliance without embedding routing logic in application code. DevOps/platform engineers deploying agentic workloads also benefit from the centralized observability and guardrail management.

Actively developed with strong foundational infrastructure: CI/CD pipelines (ci.yml, docker-push-main.yml, publish-pypi.yml, publish-binaries.yml), multi-language bindings (Rust/Python/TypeScript/JavaScript), Docker support, and organized .claude/skills for onboarding. The monorepo structure and release automation suggest production-grade maturity, though as an AI infrastructure product the ecosystem around it is still maturing.

Core risk is Rust-heavy codebase (1.6M LoC) requiring systems programming expertise for contributions; moderate risk of breaking API changes as agentic standards evolve. Single maintainer risk unknown from file structure, though the breadth of CI/CD and multi-language support suggests active backing. Dependency management across Rust, Python, TypeScript, and WASM builds adds surface area for supply-chain issues.

Actively releasing and publishing: docker-push-main.yml, publish-pypi.yml, and publish-binaries.yml workflows indicate regular releases. The .claude/skills directory (build-brightstaff, new-provider) suggests new provider integrations and CLI tooling are being actively developed. update-providers.yml workflow indicates ongoing provider compatibility work.

git clone https://github.com/katanemo/plano.git
cd plano
# For the website (Next.js):
cd apps/katanemo-www
npm install
npm run dev
# For Python SDK (inferred from PyPI publishing):
pip install plano
# For Rust core, see CONTRIBUTING.md and .claude/skills/build-cli/SKILL.md

Daily commands: For the website: cd apps/katanemo-www && npm install && npm run dev → http://localhost:3000. For the Rust proxy: consult CONTRIBUTING.md and .claude/skills/build-cli/SKILL.md for build instructions. For Python SDK: pip install plano (published to PyPI via publish-pypi.yml workflow).

• apps/katanemo-www/package.json — Defines the website project dependencies and build scripts; critical for understanding the tech stack and development workflow.
• apps/katanemo-www/src/app/layout.tsx — Root Next.js layout component that wraps all pages; establishes global styles, metadata, and UI patterns used across the site.
• apps/katanemo-www/src/app/page.tsx — Main landing page component; showcases Plano's core value proposition and is the primary entry point for visitors.
• apps/www/next.config.ts — Next.js configuration for the main documentation site; controls build behavior, image optimization, and routing rules.
• CONTRIBUTING.md — Developer contribution guidelines; essential for understanding the project's coding standards and PR workflow.
• README.md — Project overview describing Plano as an AI-native proxy for agentic apps; context for all other documentation.
• .github/workflows/ci.yml — Continuous integration pipeline; defines test, lint, and build steps that all PRs must pass.

Add a new landing page section to Katanemo website

1. Create a new React component in apps/katanemo-www/src/components/ that exports a default functional component (apps/katanemo-www/src/components/YourNewSection.tsx)
2. Import and add the component to the page.tsx layout, placing it in the DOM hierarchy where needed (apps/katanemo-www/src/app/page.tsx)
3. Use Tailwind classes from the inherited tailwind-config package for styling (inherited via @katanemo/tailwind-config in package.json) (apps/katanemo-www/src/components/YourNewSection.tsx)
4. Add any new SVG assets to apps/katanemo-www/public/ and reference them with next/image for optimization (apps/katanemo-www/public/your-asset.svg)

Add a new blog post or documentation page to Plano docs site

1. Define a new schema type in apps/www/schemaTypes/ extending the existing blogType.ts pattern (apps/www/schemaTypes/yourContentType.ts)
2. Create corresponding page component in apps/www (following Next.js app router structure) (apps/www/src/app/blog/[slug]/page.tsx)
3. Register the schema type in apps/www/sanity.config.ts so it appears in the Sanity CMS (apps/www/sanity.config.ts)
4. Update apps/www/next.config.ts if any custom routes, redirects, or content sources are needed (apps/www/next.config.ts)

Update the CI/CD pipeline or add a new GitHub Actions workflow

1. Create a new .yml file in .github/workflows/ or edit an existing one (e.g., ci.yml, docker-push-main.yml) (.github/workflows/your-new-workflow.yml)
2. Define job steps, triggers (on: push, pull_request, schedule), and environment variables (.github/workflows/your-new-workflow.yml)
3. If the workflow builds Docker images or publishes artifacts, ensure it references the correct Dockerfile and output paths (Dockerfile)
4. Commit and push the workflow file; GitHub Actions will automatically activate it on the next matching trigger event (.github/workflows/your-new-workflow.yml)

Improve code quality and linting standards across the monorepo

1. Update the shared biome.json rules in the root or per-workspace config to enforce new linting/formatting rules (apps/katanemo-www/biome.json)
2. Optionally update the shared tsconfig in @katanemo/tsconfig to tighten TypeScript strictness (apps/katanemo-www/tsconfig.json)
3. Update .pre-commit-config.yaml to add new pre-commit hooks (e.g., spell check, YAML validation) (.pre-commit-config.yaml)
4. Document the changes in CONTRIBUTING.md so all developers are aware of the new standards (CONTRIBUTING.md)

• Next.js 16 + React 19 — Enables hybrid SSG/SSR rendering for fast static marketing pages and dynamic documentation; App Router provides modern file-based routing and server components.
• Tailwind CSS 4 — Rapid utility-first styling with tight design system integration; shared across monorepo via @katanemo/tailwind-config for consistency.
• Sanity CMS — Headless CMS for structured content (blog posts, docs); decouples content authoring from presentation; allows real-time content updates without redeployment.
• Biome (linter/formatter) — Fast, unified code quality tooling; replaces ESLint + Prettier; enforces monorepo-wide standards with single configuration file.
• Docker + GitHub Actions — Containerization for reproducible deployments; CI/CD automation ensures all commits pass tests, linting, and builds before merging.

• Marketing and docs split across two Next.js apps (katanemo-www, www) instead of a single monolithic site

  • Why: Separate concerns: Katanemo corporate branding vs. Plano product documentation; allows independent deployment and styling strategies.
  • Consequence: Increased maintenance overhead; must keep shared dependencies (@katanemo/ui, tailwind-config, tsconfig) in sync across both apps.

• Use of Sanity CMS for content management in apps/www

  • Why: Enables non-developers to publish blog posts and documentation without rebuilding the site; provides a structured content model.
  • Consequence: Adds external service dependency and third-party vendor lock-in; requires Sanity API calls during build time, increasing build duration.

• Monorepo structure (Yarn workspaces implied)

  • Why: undefined
  • Consequence: undefined

WASM builds: .claude/skills/build-wasm/SKILL.md suggests WASM is supported; ensure Rust WASM target is installed (rustup target add wasm32-unknown-unknown). Monorepo workspace: apps/katanemo-www uses @katanemo scoped packages (@katanemo/shared-styles, @katanemo/ui, @katanemo/tailwind-config, @katanemo/tsconfig)—these are local workspace dependencies, not npm; ensure npm install from repo root or explicitly set workspace resolution. Provider updates: update-providers.yml suggests automated provider sync; manual changes may be overwritten. Multi-language toolchain: Rust + Python + TypeScript requires rustc, python, node all present and compatible versions—see ci.yml for version matrix. Pre-commit hooks: .pre-commit-config.yaml in use; run pre-commit install after cloning.

• Agentic Signals™ — Core differentiator of Plano—signals are zero-code metrics and events (agent latency, token usage, tool calls, failures) automatically captured from every agent interaction; understanding signal schemas is critical for monitoring and optimization
• Filter Chains — Plano's safety/moderation mechanism (jailbreak protection, policy enforcement, memory injection); understanding filter composition and ordering is essential for contributing to guardrail features
• Smart LLM Routing — Plano's ability to route by model name, semantic alias, or automatic preference—this is the proxy's core value; understanding routing policies and preference propagation is critical for model-agility features
• Envoy Filter Extensions — Plano extends Envoy's filter architecture for agentic workloads; contributors must understand Envoy's filter API, xDS configuration, and custom filter implementation patterns to extend routing/orchestration
• gRPC and Protocol Buffers — Likely used for inter-service communication between Plano proxy and agent services (Envoy native protocol); understanding protobuf schema evolution is important for backward-compatible provider additions
• OpenTelemetry Instrumentation — Plano captures traces and metrics via OTEL; understanding OTEL span/metric semantics and context propagation is necessary for adding observability to new agent types or providers
• Orchestration and Agent Composition — Plano decouples agent orchestration from application code; understanding how agents are routed, composed, and ordered (sequential, parallel, conditional) is core to Plano's value proposition

• envoyproxy/envoy — Plano is built directly on Envoy's proxy foundation—understanding Envoy's filter chain architecture and xDS configuration is essential for modifying Plano's routing and filter logic
• opentelemetry/opentelemetry-python — Plano integrates OTEL tracing and metrics; the Python SDK likely wraps opentelemetry-api for agentic signal capture and distributed tracing
• vllm-project/vllm — Complementary LLM serving infrastructure—Plano routes to LLM endpoints that vLLM may be running; understanding vLLM's API contract informs Plano provider integrations
• anthropics/anthropic-sdk-python — Likely a reference provider implementation for Plano; Anthropic SDK patterns inform how other LLM SDKs should integrate with Plano
• getsentry/sentry — Plano's observability and error tracking (via OTEL) parallels Sentry's agentic monitoring use cases; relevant for understanding guardrail enforcement and signal correlation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E tests for katanemo-www Next.js app with Playwright

The katanemo-www app (apps/katanemo-www/) has no visible test infrastructure despite being a public-facing marketing/docs site. With Next.js 16.1.6 and React 19.2.0, adding Playwright E2E tests would catch regressions in critical user journeys (logo slider, navigation, responsive layouts). This is high-value because the site showcases Plano to potential users.

• [ ] Add playwright.config.ts to apps/katanemo-www/
• [ ] Create tests/e2e/ directory with tests for LogoSlider.tsx navigation and mobile responsiveness
• [ ] Add @playwright/test as devDependency in apps/katanemo-www/package.json
• [ ] Create .github/workflows/test-www.yml to run Playwright on PR to apps/www and apps/katanemo-www
• [ ] Document test setup in apps/katanemo-www/README.md

Add type safety validation to shared packages (ui, tailwind-config, tsconfig)

The monorepo has shared packages (@katanemo/ui, @katanemo/tailwind-config, @katanemo/tsconfig) imported with wildcard versions (*) in package.json dependencies across apps/www and apps/katanemo-www. There's no visible CI workflow validating that TypeScript exports from these packages are correct or that breaking changes are caught. Adding a 'type-check-monorepo' workflow would prevent runtime import failures.

• [ ] Create .github/workflows/type-check-monorepo.yml to run tsc --noEmit on all apps after building shared packages
• [ ] Add export validation tests in the shared package directories (if they exist) to ensure public API stability
• [ ] Document shared package maintenance guidelines in CONTRIBUTING.md

Implement pre-commit hooks for Biome formatting in apps/katanemo-www and apps/www

Both Next.js apps have 'biome check' and 'biome format' scripts, but .pre-commit-config.yaml exists at root with no visible biome configuration. Developers can accidentally commit unformatted code. Adding biome pre-commit hooks would enforce consistency and reduce CI failures due to formatting.

• [ ] Update .pre-commit-config.yaml to include biomejs/biome hook with args for --write
• [ ] Test that pre-commit hook runs on apps/katanemo-www and apps/www TypeScript/JSX files
• [ ] Document setup in CONTRIBUTING.md with 'pre-commit install' instructions
• [ ] Add a check in CI to ensure pre-commit hooks haven't been skipped (via git hooks validation)

• Add missing TypeScript type definitions for Python SDK bindings. The Python SDK (421K LoC) likely exposes async APIs that TypeScript clients consume—audit apps/katanemo-www and TypeScript client code for untyped imports and generate .d.ts stubs.: Improves DX for TypeScript users and catches integration bugs early
• Expand .claude/skills/test-python/SKILL.md with concrete examples. The skill exists but likely lacks runnable test suite examples—add pytest fixtures and sample test cases for the plano-sdk.: Onboarding friction for new Python SDK contributors is high; documented patterns reduce this
• Document provider integration checklist in new-provider skill. Audit publish-pypi.yml and release workflows to identify all provider-specific steps (version bumping, changelog, API validation), then create a step-by-step checklist in .claude/skills/new-provider/SKILL.md.: Enables non-core contributors to safely add new LLM providers without tribal knowledge

The Plano codebase demonstrates a reasonable security foundation with CI/CD pipelines and tooling in place. However, there are gaps in automated dependency vulnerability detection, wildcard package versioning, and security header configuration. The primary concerns are: (1) lack of explicit dependency scanning in CI/CD, (2) use of wildcard versions for internal packages, and (3) unverified Docker base images and toolchains. The codebase would benefit from stricter dependency pinning, comprehensive SAST integration, and explicit security header configuration in the Next.js applications. No hardcoded

• Medium · Missing SAST/Dependency Scanning in CI/CD — .github/workflows/ci.yml. The CI workflow (.github/workflows/ci.yml) and other GitHub Actions do not explicitly include dependency vulnerability scanning (e.g., Dependabot, Snyk, or cargo-audit). This means known vulnerabilities in dependencies may not be detected automatically. Fix: Enable GitHub's Dependabot alerts, add cargo-audit to the Rust build pipeline, and implement npm audit checks for Node.js dependencies. Add security scanning steps to CI workflows.
• Medium · Wildcard Dependencies in package.json — apps/katanemo-www/package.json. The package.json uses wildcard version specifiers (e.g., '@katanemo/shared-styles': '*') for internal monorepo packages. This can lead to unpredictable builds and potential supply chain risks if these packages are compromised. Fix: Use pinned versions (e.g., '^0.1.0') instead of wildcards. Implement package lock discipline and ensure all dependencies are reviewed before updates.
• Low · Broad Node.js Type Definitions — apps/katanemo-www/package.json. The devDependency '@types/node' uses '^20' without an upper bound, which could introduce breaking changes in type definitions. Fix: Pin to a specific minor version, e.g., '^20.10.0' to reduce unexpected type definition changes.
• Low · Next.js version constraint could be stricter — apps/katanemo-www/package.json. Next.js dependency uses '^16.1.6', allowing minor version updates that may introduce unexpected behavior or security issues. Fix: Consider pinning to a specific minor version (e.g., '16.1.6') or regularly audit Next.js updates for security advisories.
• Medium · Docker multi-stage build with Rust toolchain — Dockerfile. The Dockerfile uses Rust 1.93.0 without signature verification and pulls from untrusted registries by default. The ENVOY_VERSION is referenced but not validated, which could lead to supply chain attacks. Fix: Add image signature verification, pin exact versions with checksums, and use official/verified base images. Document ENVOY_VERSION pinning and audit process.
• Low · Missing security headers configuration in Next.js — apps/katanemo-www/next.config.ts. The next.config.ts file is not provided, so security headers (CSP, X-Frame-Options, etc.) cannot be verified. Web applications should define strict security headers. Fix: Implement security headers via Next.js middleware or headers configuration. Add Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and Strict-Transport-Security headers.
• Low · Biome linter configuration not reviewed — apps/katanemo-www/biome.json. The biome.json configuration is present but not provided for review. Security-relevant linting rules (e.g., no dangerous DOM operations, security-related patterns) cannot be verified. Fix: Ensure Biome is configured with security rules enabled (no dangerouslySetInnerHTML, no eval, etc.). Review and document linting policies.
• Low · Incomplete static analysis workflow — .github/workflows/static.yml. The .github/workflows/static.yml file is referenced but not shown. Static analysis coverage and scope cannot be verified. Fix: Ensure static analysis includes SAST, dependency scanning, and container image scanning. Document the scope and frequency of security checks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.