hurtener

Measure cyclomatic complexity across a Python repo to find refactor opportunities and track code health over time. Runs three analyses — ruff C901 violations (functions above a CC threshold), radon repo-wide average and grade distribution (A–F), and a reference-weighted hotspot ranking that prioritizes complex code that's actually used. Use when the user asks about cyclomatic complexity, code complexity, where to refactor, repo hygiene metrics, complexity hotspots, technical-debt prioritization, complexity scores, or wants to add a complexity gate to CI/CD. Outputs human-readable tables plus an optional JSON report suitable for trend tracking and CI artifacts.

Configure PenguiFlow ReactPlanner in production codebases (native LLM adapter, tool discovery + deferred activation, skills packs, allowlists/visibility policies, rich output, A2A router integration, guardrails, and background tasks) with safe defaults and troubleshooting.

Author "skill packs" — playbooks the PenguiFlow ReactPlanner retrieves at runtime via `skill_search`/`skill_get`/`skill_list` (NOT the same as the SKILL.md agent-tool descriptors in the project's `skills/` directory; these are runtime artifacts stored in a SQLite skill store). Configure `SkillsConfig(enabled=True, skill_packs=[SkillPackConfig(...)], top_k=..., redact_pii=True)`, pick a pack format (`*.skill.md`/`.yaml`/`.json`/`.jsonl`), declare applicability via `required_tool_names`/`required_namespaces`/`required_tags`, scope by tenant/project, compose with a runtime `skills_provider`/`skills_provider_factory`, optionally enable non-persisting `skill_propose` drafting and `SkillsDirectoryConfig` surfacing. Use when a user says "author a skill pack", "playbooks for my planner", "skill_search", "runtime skills provider", or names `SkillsConfig`.

Explain, configure, and troubleshoot the ReactPlanner reflection loop: how post-answer critique, revision, and clarification work; how to wire `ReflectionConfig` and optional `reflection_llm`; how env/spec-driven scaffolds expose the knobs; and how to verify behavior through planner events, metadata, and cost counters. Use when a user asks about "reflection loop", "self-critique", "reflection_critique", "quality_threshold", "max_revisions", or wants to compare reflection-enabled vs reflection-disabled runs.

Deep expertise for PenguiFlow persistence: implement or review a `StateStore` backend (required + optional duck-typed capabilities), enforce correct contracts (idempotency, ordering, cursors, cancellation), wire A2A router continuity via conversation bindings, sessions/tasks/updates/steering and background-task orchestration, integrate `ArtifactStore`, support distributed execution (`RemoteBinding`), and build UIs/clients around the Playground HTTP+SSE contract. Use when building/debugging StateStore or ArtifactStore implementations; designing database schemas; investigating missing/duplicated/out-of-order events; integrating A2A manager/specialist continuity, OAuth/HITL pause-resume; persisting trajectories/planner events; or implementing frontends that consume `/chat`, `/session/stream`, `/tasks`, `/events`, `/trajectory`, and `/artifacts`.

Expose a PenguiFlow agent as an A2A-spec service or call remote A2A agents from a planner — wire `A2AService` to a FastAPI app via `install_a2a_http`/`create_a2a_http_router`/`create_a2a_http_app`, serve the agent card at `/.well-known/agent-card.json`, handle JSON-RPC + REST + SSE + push-notification transports, optionally enable the gRPC binding, build manager↔specialist topologies with `A2AAgentToolset` and an `AgentRegistry`, persist conversation continuity via `RemoteBinding`/`StateStore`, and choose blocking/stream/task execution modes. Use when a user says "expose as A2A", "agent-to-agent", "call a remote agent", "agent card", "manager/specialist", "JSON-RPC", "SSE for agents", "push notifications for agents", or names `A2AService`, `RemoteBinding`, `A2AAgentToolset`.

Clone an existing PenguiFlow test agent into a new folder, remove copied state, rewire MCP/tooling for a new idea, and validate it boots cleanly. Use when you want to spin up another experiment agent quickly from a working sibling — not for greenfield agents. For brand-new agents, prefer `penguiflow new <template>` (interactive) or `penguiflow generate <spec.yaml>` (declarative, recommended Jan 2026+); see `TEMPLATING_QUICKGUIDE.md`.

Enable concurrent background work on a PenguiFlow ReactPlanner — configure `BackgroundTasksConfig(enabled=True, allow_tool_background=..., default_mode=..., default_merge_strategy=..., max_concurrent_tasks=..., task_timeout_s=...)`, expose the `tasks.*` tool surface via `build_task_tool_specs()`, supply `tool_context["task_service"]` (implementing the `TaskService` protocol) plus `session_id`, choose merge strategies (`HUMAN_GATED`/`APPEND`/`REPLACE`), use task groups for coherent multi-task reports, and let tools opt-into background execution via `spec.extra["background"]`. Use when a user says "background task", "spawn a subagent", "async tool", "task groups", or names `BackgroundTasksConfig`, `tasks.spawn`, `task.subagent`.

Attach Harbor's native terminal Runtime test/control client with authenticated REST/SSE. Use when testing sessions, tasks, tools, artifacts, events, posture, interventions, controls, reconnect, or transcript export without opening the Console.

Use the Console's Playground page to chat against your agent, attach files (images / PDFs / audio), and steer or queue input during a run. Use when validating the agent end-to-end interactively, the foreground/background task posture, image-vs-PDF MIME dispatch, and the playground's steering UI.

Tour the Console's observability pages — Overview, Live Runtime, Sessions, Tasks, Agents, Tools, Events, Background Jobs, Playground, Flows, Memory, MCP Connections, Artifacts, Settings. Use when debugging an agent's behavior, hunting a regression, or building intuition for what the runtime is actually doing under the hood.

Build a chat UI (or any other client) against the Harbor Protocol directly — auth headers, the typed wire surface, events.subscribe SSE, the topology_snapshot capability, artifact upload. Use when shipping a frontend that talks to the runtime WITHOUT the bundled Console — a custom chatbot, a Slack bot, a TUI, an IDE plugin.

Get a real, verifiable JWT into a client and attach it to a production `harbor serve` — OIDC app registration, the (tenant, user, session) + scopes claim shape, the iss/aud exact-match contract, and the no-IdP `harbor token` self-issuing on-ramp. Use when moving off `harbor dev`'s ephemeral token to a production deployment, wiring an IdP (Auth0 / Okta / Keycloak / Cognito), or standing up your own issuer.

Use `harbor dev` + `harbor console` to run an agent locally with the Console attached. Use when iterating on a Harbor project — single-process or multi-process attach posture, the `HARBOR_DEV_TOKEN` handshake, hot reload on yaml changes, and which posture to pick when.

Scaffold a new Harbor agent project with `harbor init` + `harbor scaffold`. Use when starting a fresh agent from zero — drops a tiered, commented `harbor.yaml`, the companion AGENTS.md / CLAUDE.md / README.md, and materialises the Go project so `harbor dev` boots a working runtime in under five minutes.

Walk every field in `harbor.yaml` — REQUIRED (identity + llm), COMMON (planner / memory / state / tools / skills / governance), ADVANCED (server / telemetry / artifacts / events / sessions / tasks / distributed). Use when editing the agent config beyond the scaffolded defaults.