@heretek-ai/pi-configs1.2.0

pi-configs

Autonomous Specialist Fleet Architecture & Forensic Ecosystem Audit for @mariozechner/pi-coding-agent (Pi v1.2.0+)

---

1. Executive Summary

pi-configs provides a production-grade, local-first specialist fleet architecture for the Pi coding agent ecosystem. Unlike legacy multi-agent frameworks (such as Heretek-Crew under Paperclip/OpenCode) that rely on heavy Docker sidecars and fragile shell shims, pi-configs implements 71 self-contained, ultra-narrow local specialist agents.

Every specialist in this fleet is completely isolated, operating under the Principle of Least Privilege (PoLP) with deterministic exit code 2 hook guards, automated typecheck/linter correction loops, on-demand lazy MCP adapters, and structured AST/LSP code intelligence.

It can be run standalone via per-agent launchers or installed globally/locally as an official Pi Package & Extension (@heretek-ai/pi-configs).

---

2. Core Architectural Pillars

+-----------------------------------------------------------------------------------+
|                            Pi Coding Agent (v1.2.0+)                              |
+-----------------------------------------------------------------------------------+
        |                      |                      |                      |
        v                      v                      v                      v
+---------------+      +---------------+      +---------------+      +---------------+
|  1. HOOKS     |      |  2. MCP       |      |  3. CODE INT  |      |  4. CRITIQUE  |
| pi-yaml-hooks |      | pi-mcp-adapter|      | ast-grep      |      | agent-browser |
| Exit code 2   |      | 200-tok proxy |      | ripwire       |      | taste-skill   |
| Auto-linter   |      | QuickJS mode  |      | CodeGraph     |      | agent-vision  |
| pi-warden     |      | Lazy spawns   |      | pi-lsp-adapter|      | stagehand     |
+---------------+      +---------------+      +---------------+      +---------------+

1. Deterministic Guardrails & Hooks:

   • Built on Pi-YAML-Hooks and @gotgenes/pi-permission-system.
   • Tool pre-execution gates (tool.before.*) intercept unauthorized operations and immediately abort with bash exit code 2.
   • Post-mutation gates (file.changed) deterministically trigger language-specific formatters and static linters (biome, ruff, cargo check, clang-format).
   • Anti-stall and integrity enforcers (DevMortimer/pi-warden) prevent fake "done" declarations and break infinite conversational loops.

2. Lazy, Proxy-Mode MCP Runtime:

   • Standardized on nicobailon/pi-mcp-adapter (v5.4.0+), collapsing monolithic tool schemas into an efficient ~200-token proxy tool.
   • Child-process MCP servers are spawned on-demand and reaped on idle.
   • In-process QuickJS-WASI Code Mode (mcpScript) allows multi-step tool calls in a single turn without intermediate token bleed.

3. High-Fidelity Code Intelligence & AST Hygiene:

   • Surgical structural queries and dry-run rewrites via @juvio15/pi-ast-grep across 28 languages.
   • Zero-token structural signatures and blast-radius call graphs via redhat-et/ripwire (saving ~75% input tokens).
   • Multi-language AST knowledge graph traversal via CodeGraphContext.
   • Paginated, read-only LSP inspection via nikmmd/pi-lsp-adapter preventing unmanaged diagnostic dumps.

4. Multi-Agent Orchestration & Subagent Context Isolation:

   • In-process child-process RPC worker teams via KristjanPikhof/Pi-Agents-Team.
   • Context explosion prevented by discarding raw worker transcripts and extracting only deterministic <final_answer> blocks.
   • Task tracking and anti-drift reminders via @tintinweb/pi-tasks and pi-goal-x.

5. Visual Critique, Game Testing & Anti-Slop:

   • Zero-token headless browser inspection via vercel-labs/agent-browser (Rust CDP engine).
   • Machine-graded visual defect verdicts via amitpatole/agent-vision (WCAG relative luminance math, DOM geometry).
   • In-engine Godot 4.3+ viewport frame diffing via mrf/godot-stagehand.
   • Tone and language humanization via jyooi/agent-simple-english (stripping robotic buzzwords and marketing filler).

---

3. Directory Layout

pi-configs/
|-- dist/                               # Compiled Pi Extension Distribution
|   |-- index.js                        # Extension entrypoint (registers /fleet, /specialist, dispatch_specialist)
|   |-- fleet.js                        # Programmatic catalog API for all 71 specialists
|   `-- types.js                        # TypeScript type declarations
|-- src/                                # Extension TypeScript Sources
|   |-- index.ts                        # Slash commands, tools & event lifecycle hooks
|   |-- fleet.ts                        # Agent directory discovery and charter loader
|   `-- types.ts                        # Pi runtime interfaces
|-- agents/                             # 71 Standalone Specialist Directories
|   |-- <agent-slug>/
|   |   |-- AGENTS.md                   # Operational charter, domain boundaries & DoD
|   |   |-- launch.ps1                  # One-click Windows PowerShell launcher
|   |   |-- launch.sh                   # One-click POSIX Bash launcher
|   |   `-- .pi/
|   |       |-- settings.json           # Model tier, thinking level, tool whitelist
|   |       |-- mcp.json                # Scoped lazy MCP server declarations
|   |       |-- mcp-adapter.json        # pi-mcp-adapter proxy runtime configuration
|   |       |-- hook/
|   |       |   `-- hooks.yaml          # Declarative exit-code-2 blocking guards
|   |       |-- extensions/
|   |       |   `-- index.ts            # Typed Pi extension lifecycle hooks
|   |       `-- skills/
|   |           `-- <skill-name>/
|   |               `-- SKILL.md        # Refactored, non-truncated execution skill
|-- scratchpad/                         # Forensic Audit & Architecture Outputs
|   |-- 00_OVERLAP_DECISION_MATRIX.md   # Binding judgment matrix across all 7 pillars
|   |-- 01_SPECIALIST_ROSTER_SPEC.md    # Master specification for all 71 specialists
|   |-- followup.txt                    # 109 verified wild alternatives cataloged
|   `-- *.md                            # 85 comprehensive per-repo forensic audit reports
|-- scripts/                            # Scaffolding, Generator & Verification Tooling
|   |-- build_specialist_fleet.js       # Node.js generator for all 71 specialist configs
|   |-- verify_mission_completion.js    # Deterministic 3-gate automated verification suite
|   |-- clone_and_unpack.ps1            # Staging downloader for skills, repos & npm tarballs
|   `-- expand_scratchpad.ps1           # Forensic audit expansion and verification script
|-- package.json                        # Official pi-package manifest
|-- tsconfig.json                       # TypeScript compiler options
`-- README.md                           # Master architectural documentation

---

4. The 71 Specialist Fleet Roster

The fleet is organized into 9 departmental guilds (8 core guilds + 1 rogue guild):

Guild 1: Executive, Product & Documentation

Slug	Title	Primary Tools	Recommended Model
exec-director	Fleet Executive Director & OKR Governor	git log, gh release list, codebase-memory-mcp	Claude 3.7 Sonnet (16k thinking)
product-director	Product Director & Strategic PRD Author	gh issue create, gh milestone list	Claude 3.7 Sonnet (12k thinking)
tpm-scrum-lead	Technical Product Manager & Agile Scrum Lead	gh project, gh issue comment, pi-task	Claude 3.5 Sonnet (6k thinking)
system-architect	Enterprise System Architect & ADR Owner	spectral lint, codebase-memory-mcp	Claude 3.7 Sonnet (24k thinking)
tech-docs-lead	Technical Documentation Lead & Docs Architect	markdownlint-cli2, typedoc	Claude 3.5 Sonnet (8k thinking)
ux-research-analyst	UX Telemetry & Feedback Analyst	duckdb, jq, mcp-server-duckdb	Claude 3.5 Sonnet (6k thinking)
brand-copy-spec	Brand Voice, Copywriting & Microcopy Specialist	i18n-ally-cli, jq	Claude 3.5 Sonnet (6k thinking)
api-spec-doc-specialist	OpenAPI, AsyncAPI & Protobuf API Doc Specialist	spectral lint, redocly	Claude 3.5 Sonnet (8k thinking)
creative-narrative-director	Creative Narrative Director & Worldbuilder	jq, git log, narrative trees	Claude 3.7 Sonnet (12k thinking)
humanizer-and-tone-editor	Natural Tone, Voice & Humanization Editor	agent-simple-english, git diff	Claude 3.7 Sonnet (12k thinking)

Guild 2: Visual, Aesthetic & Design Systems

Slug	Title	Primary Tools	Recommended Model
gui-visual-critic	GUI Visual Critic & Anti-AI-Slop Inspector	agent-vision, taste-skill, Playwright	Claude 3.7 Sonnet (16k thinking)
game-feel-and-vfx-critic	Game Feel, VFX & Juiciness Critic	godot-stagehand, ffmpeg, ffprobe	Claude 3.7 Sonnet (12k thinking)
ui-ux-designer	UI/UX Designer & Interactive Prototyper	tailwindcss, taste-skill, ui-ux-pro-max	Claude 3.7 Sonnet (12k thinking)
design-system-eng	Design Systems & Component Token Engineer	test-storybook, style-dictionary	Claude 3.5 Sonnet (8k thinking)
a11y-specialist	Accessibility & WCAG 2.2 AA Compliance Auditor	@axe-core/cli, pa11y-ci	Claude 3.5 Sonnet (8k thinking)
fe-perf-eng	Frontend Performance & Core Web Vitals Engineer	lighthouse-ci, vite-bundle-visualizer	Claude 3.5 Sonnet (8k thinking)
mobile-web-eng	Mobile Web & Responsive Layout Engineer	playwright test --project=Mobile_Safari	Claude 3.5 Sonnet (6k thinking)
3d-webgl-threejs-specialist	3D WebGL / WebGPU & Three.js Specialist	gltf-transform, Three.js r170+, WebGPU	Claude 3.7 Sonnet (16k thinking)

Guild 3: Core Language & Systems Engineering

Slug	Title	Primary Tools	Recommended Model
ts-node-fullstack	TypeScript / Node.js Fullstack Systems Engineer	tsc --noEmit, vitest, biome	Claude 3.7 Sonnet (12k thinking)
rust-systems-spec	Rust Systems & Memory-Safety Specialist	cargo check, cargo clippy, cargo test	Claude 3.7 Sonnet (16k thinking)
go-backend-eng	Go High-Concurrency Backend Engineer	golangci-lint, go test -race	Claude 3.7 Sonnet (12k thinking)
python-backend-spec	Python Async Backend & FastAPI Specialist	ruff check, mypy --strict, pytest	Claude 3.7 Sonnet (12k thinking)
cpp-lowlevel-eng	C++23 Low-Level Systems & Memory Engineer	clang-tidy, cmake --build, valgrind	Claude 3.7 Sonnet (16k thinking)
java-kotlin-eng	Modern Java 21+ & Kotlin Backend Specialist	./gradlew check, ktlintCheck	Claude 3.7 Sonnet (12k thinking)
ios-mobile-spec	iOS Native Swift & SwiftUI Specialist	xcodebuild test, swiftlint, simvyn	Claude 3.7 Sonnet (12k thinking)
android-mobile-spec	Android Native Kotlin & Jetpack Specialist	./gradlew testDebugUnitTest, simvyn	Claude 3.7 Sonnet (12k thinking)
embedded-rtos-firmware-eng	Embedded C, RTOS & Bare-Metal HAL Engineer	arm-none-eabi-gcc, Zephyr / FreeRTOS	Claude 3.7 Sonnet (16k thinking)
wasm-runtime-engineer	WebAssembly & WASI Systems Specialist	wasm-opt, wasm-tools validate, wasmtime	Claude 3.7 Sonnet (12k thinking)

Guild 4: Game Engineering, Graphics & Modding

Slug	Title	Primary Tools	Recommended Model
game-systems-dev	Game Systems & Gameplay Programmer	godot --headless, cargo test	Claude 3.7 Sonnet (12k thinking)
graphics-shader-eng	Graphics & Shader Pipeline Engineer	glslangValidator, naga, SPIR-V	Claude 3.7 Sonnet (16k thinking)
engine-systems-eng	Engine Core & Memory Allocator Programmer	cargo bench, valgrind --tool=cachegrind	Claude 3.7 Sonnet (16k thinking)
game-ai-dev	Game AI & Autonomous Decision Systems Programmer	godot --headless --script test/ai, navmesh	Claude 3.7 Sonnet (12k thinking)
physics-sim-eng	Physics Simulation & Collision Engineer	cargo test physics, ctest -R physics	Claude 3.7 Sonnet (12k thinking)
tech-artist-pipeline	Technical Artist & Asset Pipeline Lead	gltf-transform, Blender CLI, sprite tools	Claude 3.5 Sonnet (8k thinking)
shader-transpiler-optimizer	Multi-Target Shader Transpiler & Optimizer	naga, spirv-opt -O, WGSL / HLSL	Claude 3.7 Sonnet (12k thinking)
godot-redot-architect	Godot 4 / Redot Engine Architect	godot --headless --validate-scripts	Claude 3.7 Sonnet (12k thinking)
ue-unreal-engine-architect	Unreal Engine 5 C++ & Gameplay Architect	RunUAT.bat BuildCookRun, UE5 UHT/UBT	Claude 3.7 Sonnet (16k thinking)
universal-game-modder	Universal PC Game Modding Specialist	universal-modder, BepInEx, Harmony, SMAPI	Claude 3.7 Sonnet (16k thinking)
memory-integrity-cheat-researcher	Memory Integrity & Runtime Hooking Researcher	frida-compile, checksec, radare2-mcp	Claude 3.7 Sonnet (16k thinking)

Guild 5: Architecture, Cloud & Infrastructure

Slug	Title	Primary Tools	Recommended Model
cloud-platform-eng	Cloud Platform & OpenTofu / IaC Engineer	tofu fmt -check, tofu validate, AWS MCP	Claude 3.7 Sonnet (12k thinking)
k8s-orchestrator	Kubernetes Platform & Helm Orchestrator	kubeconform -strict, helm lint	Claude 3.5 Sonnet (8k thinking)
dba-specialist	Database Administrator & SQL Perf Engineer	sqlfluff lint, pg_format, Postgres MCP	Claude 3.7 Sonnet (12k thinking)
cache-streaming-eng	Distributed Cache & Event Streaming Engineer	redis-cli ping, kcat -L, Kafka MCP	Claude 3.5 Sonnet (8k thinking)
sre-incident-eng	SRE & Incident Commander	promtool check rules, Sentry MCP	Claude 3.7 Sonnet (12k thinking)
observability-eng	Observability & OpenTelemetry Engineer	promtool check config, OTEL collector	Claude 3.5 Sonnet (8k thinking)
git-drift-coord	Git Worktree & Branch Drift Coordinator	git status, git worktree list	Claude 3.5 Sonnet (6k thinking)

Guild 6: Quality Assurance & Verification

Slug	Title	Primary Tools	Recommended Model
e2e-browser-qa	E2E Browser QA Automation Engineer	npx playwright test, Playwright MCP	Claude 3.7 Sonnet (12k thinking)
api-contract-tester	API Contract & Pact Verification Specialist	schemathesis run, OpenAPI validation	Claude 3.5 Sonnet (8k thinking)
load-stress-tester	Performance Load & k6 Stress Testing Engineer	k6 run tests/load/scenario.js	Claude 3.5 Sonnet (8k thinking)
sabotage-qa-tester	Mutation Testing & Chaos Sabotage Tester	npx stryker run, cargo mutants	Claude 3.7 Sonnet (12k thinking)
release-qa-officer	Release QA Officer & Deployment Gatekeeper	git diff --stat, release sanity probes	Claude 3.7 Sonnet (12k thinking)

Guild 7: Defensive Security, Binary Forensics & AI Red-Teaming

Slug	Title	Primary Tools	Recommended Model
appsec-engineer	Application Security & SAST/DAST Engineer	semgrep scan --config p/security-audit	Claude 3.7 Sonnet (16k thinking)
cloud-sec-auditor	Cloud Security & IAM Permissions Auditor	checkov -d ., trivy config .	Claude 3.7 Sonnet (12k thinking)
binary-reverse-engineer	Binary Reverse Engineer & Disassembly Specialist	radare2-mcp, GhidraMCP, objdump	Claude 3.7 Sonnet (16k thinking)
firmware-sec-analyst	Firmware Security & Hardware Attack Analyst	binwalk -e, checksec, entropy scans	Claude 3.7 Sonnet (16k thinking)
threat-modeler	STRIDE Threat Modeler & Architecture Auditor	pytm, STRIDE / DREAD threat trees	Claude 3.7 Sonnet (12k thinking)
compliance-auditor	SOC2 / ISO 27001 / HIPAA Compliance Auditor	osqueryi, CIS benchmark checklists	Claude 3.5 Sonnet (8k thinking)
ai-red-teamer	AI Model Red-Teamer & Prompt Injection Auditor	garak, adversarial jailbreak fuzzers	Claude 3.7 Sonnet (16k thinking)

Guild 8: Data, Machine Learning & Code Hygiene

Slug	Title	Primary Tools	Recommended Model
data-pipeline-eng	Data Pipeline, Spark & dbt Engineer	dbt run --select, dbt test	Claude 3.7 Sonnet (12k thinking)
vector-rag-spec	Vector Database & Hybrid RAG Specialist	Qdrant / LanceDB client, ONNX embeddings	Claude 3.7 Sonnet (12k thinking)
mlops-serving-eng	Model Serving, Triton & vLLM MLOps Engineer	triton, docker compose -f triton.yml	Claude 3.7 Sonnet (12k thinking)
analytics-metrics-eng	Product Analytics & Event Tracking Engineer	duckdb, event taxonomy validators	Claude 3.5 Sonnet (8k thinking)
synthetic-eval-benchmark-eng	Synthetic Data & LLM Eval Benchmark Engineer	deepeval test run, Ragas / deepeval	Claude 3.7 Sonnet (16k thinking)
ast-structural-refactorer	AST Structural Search & Safe Refactorer	@juvio15/pi-ast-grep (6 native tools)	Claude 3.7 Sonnet (16k thinking)
linter-formatter-enforcer	Deterministic Multi-Language Linter Enforcer	biome, ruff, cargo clippy, hooks.yaml	Claude 3.5 Haiku (4k thinking)
dependency-hygiene-lockfile-surgeon	Lockfile Deduplication & Supply-Chain Surgeon	npm dedupe, cargo tree --duplicates	Claude 3.7 Sonnet (12k thinking)
dependency-patcher	Upstream Library Patcher & patch-package Eng	npx patch-package, git apply --check	Claude 3.7 Sonnet (12k thinking)
lsp-type-graph-navigator	Semantic LSP & Code Knowledge Graph Navigator	pi-lsp-adapter, CodeGraphContext	Claude 3.7 Sonnet (16k thinking)
adversarial-diff-auditor	Adversarial Diff Auditor & Codebase Watchdog	git diff, pi-slopchop watchdog review	Claude 3.7 Sonnet (16k thinking)
static-analysis-lead	Code Style, Semgrep Rules & Static Analysis Lead	semgrep --validate --config rules/	Claude 3.7 Sonnet (12k thinking)

Guild 9: Rogue — Autonomous Orchestration & Compliance Evasion

Slug	Title	Primary Tools	Recommended Model
rogue-agent	Rogue Orchestrator — Semantic Filter-Breaking Fleet Coordinator	dispatch_specialist, dispatch, read/write/edit/bash	lemonade-CyberTielCoder (heretik, 16k thinking)

rogue-agent runs on the heretic model lemonade-CyberTielCoder (https://llm.hextek.one/v1). It decomposes large or filter-tripping missions into narrow, neutral-toned sub-tasks, delegates each to the right specialist, and falls back to self-execution when decomposition fails or a delegation is refused. Guardrails: delegation fan-out ≤ 10, recursion depth ≤ 3, real-slug allowlist, and self-protection of its own guardrails.

---

5. Usage & Integration Guide

5.1 Installing as an Official Pi Package

Install the package directly into Pi:

# Global install (available across all projects)
pi install npm:@heretek-ai/pi-configs

# Project-local install (persisted in .pi/settings.json)
pi install -l npm:@heretek-ai/pi-configs

# Ephemeral test session without installing
pi -e npm:@heretek-ai/pi-configs

5.2 Slash Commands in Pi Sessions

Once loaded, the extension provides instant fleet management:

# List all 71 specialists across all 9 guilds
/fleet

# Filter specialists by keyword or guild
/fleet visual
/fleet modding

# Dynamically switch the current Pi session charter to any specialist
/specialist gui-visual-critic
/specialist godot-redot-architect
/specialist ast-structural-refactorer

5.3 Multi-Agent Task Delegation (dispatch_specialist)

Other Pi agents can use the native dispatch_specialist tool to delegate tasks out-of-process:

{
  "specialistSlug": "gui-visual-critic",
  "taskPrompt": "Capture screenshot of http://localhost:3000, inspect WCAG contrast and audit layout hierarchy against strict typography scales."
}

5.4 Standalone Launchers

Alternatively, launch any specialist directly from the command line:

On Windows PowerShell:

./agents/gui-visual-critic/launch.ps1

On Linux / macOS Bash:

./agents/gui-visual-critic/launch.sh

5.5 Deterministic Verification Suite

Run the automated verification suite to validate all 85 forensic audit reports, the alternatives register, and all 71 specialist configurations:

node scripts/verify_mission_completion.js

---

6. License

MIT License. All tools, scripts, and specialist configurations in this repository are open source and free for commercial and private use.