HowlPlane

An AI Engineering Control Plane

[ Documentation & Interactive System Console: howlcipher.github.io/howlplane ]

---

HowlPlane coordinates AI-assisted engineering work across heterogeneous repositories through shared context, deterministic task routing, independent adversarial reviews, repeatable verification, durable evidence, and human-controlled authority boundaries.

Core Directives

• AI proposes and implements work.
• Policies constrain actions.
• Independent reviewers challenge assumptions.
• Deterministic tools verify claims.
• Evidence records historical truth.
• Humans authorize consequential risk.

The persistent factory supervisor uses one lock per state directory. A second process is rejected without changing the durable record of the active process. Review, verification, and hygiene policy files remain human only, and skipped required checks never authorize a merge. PR and merge boundaries reconcile remote state before replay. Branch-push recovery accepts only the expected remote commit and parks mismatches for human reconciliation. CI evidence is bound to a stable, live PR head SHA before it can authorize a merge.

An expired Claude OAuth session is recorded as AUTHENTICATION_REQUIRED in durable provider capacity state. Routing can consider another eligible worker; authentication repair remains an operator action. AGY's explicit print-timeout diagnostic is treated as incomplete work even when its process exits zero. Partial changes must pass the existing timeout candidate verification or failover path before they can advance.

Factory: the everyday engineering command

From any ordinary Git repository, start a safe persistent engineering Factory without supplying a state directory, worktree, PID, or service name:

cd /path/to/project
howlplane factory start
howlplane factory status
howlplane factory logs --follow
howlplane factory stop

On its first interactive start, Factory asks for an explicit authority choice. The safe default uses the existing strict authority profile. In automation, pass --authority safe or an approved --authority-profile; Factory never infers expanded authority. It derives a stable campaign identity from the canonical repository root and remote identity, stores durable state below the XDG state home, and creates a separate managed worktree below the XDG data home. A dirty user checkout is left untouched.

factory start is the background normal workflow. factory run remains the foreground advanced/debug command, and explicit --state-dir and --target-repo overrides remain available. factory run-once also uses the zero-config resolver when those overrides are omitted.

Advanced persistent Linux user service

factory status reports the persisted supervisor state without treating an active dispatch as a process restart. Startup still reconciles interrupted work.

Factory worker deadlines can hand off to another eligible provider through the existing bounded retry loop. This requires the failed attempt's baseline to be restored and does not mark the timed-out provider globally exhausted.

An unsuccessful remediation worker produces durable failure and partial-patch evidence. Plane preserves the cumulative task patch, restores the original pre-task baseline (including undoing earlier remediation cycles), and returns the failure to the existing retry policy; it does not report that remediation as complete.

Factory backlog ingestion retains each item's detailed problem statement and acceptance criteria. Repeated discovery fills missing legacy context while preserving active tasks, existing descriptions, and lifecycle dispositions.

Install the existing supervisor as a user service using a stable controller checkout, a separate target worktree, and one persistent state directory:

python3 scripts/install_factory_service.py --state-dir /absolute/factory-state \
  --target-repo /absolute/target-worktree --python /absolute/venv/bin/python3
systemctl --user daemon-reload
systemctl --user enable --now howlplane-factory
systemctl --user status howlplane-factory
journalctl --user -u howlplane-factory -n 50
howlplane factory status --state-dir /absolute/factory-state --json
systemctl --user restart howlplane-factory
systemctl --user stop howlplane-factory

The selected Python environment must have HowlPlane's dependencies installed and run on the service host. From a container, validate it on the host first. Use --worker-path to supply a stable PATH containing installed worker CLIs. The installer refuses to overwrite a customized unit. It never binds or renews authority; existing campaign envelopes retain their original expiry.

SIGTERM wakes an idle supervisor immediately, or lets the current dispatch settle before saving stopped state and releasing its lock. Systemd allows five minutes for this, then terminates remaining workers; interrupted work is reconciled on restart. Starting the service explicitly resumes stopped state under the same supervisor lock. Unexpected failures restart after 30 seconds, with a startup rate limit. Output goes to the host's bounded journal with a per-service log rate limit. last_successful_tick_at records completed loop ticks, including idle ticks, and does not imply shipped engineering work. Use systemctl --user stop for a durable service stop. Starting at boot without an interactive login additionally depends on the host's user-lingering policy.

---

Everyday Workflow

HowlPlane's canonical direct command is howlplane. The future howl ecosystem command is owned by the separate howlcipher/howl repository and is not shipped by this repository. Run the direct command from inside any project repository on your machine:

# Stand inside any repository and prepare a governed task run (plan & dry-run):
cd /path/to/project
howlplane work "fix the highest-value open bug"

# Genuinely execute the complete closed-loop AI engineering lifecycle:
howlplane work "fix the highest-value open bug" --execute

# Force a specific implementation agent (e.g. claude_code, codex, gemini_cli, agy, devin_cli):
howlplane work "refactor database adapter" --agent codex --execute

# Inspect active project context, verification suites, and task runs:
howlplane status

# Deterministically route a task and select reviewer roles without mutating code:
howlplane route "patch authentication vulnerability"

# Run system and toolchain preflight diagnostics:
howlplane doctor

# Execute deterministic verification suites on the active repository:
howlplane verify

Direct vendor commands (claude, codex, agy) remain available as escape hatches when full multi-agent orchestration is not desired; howlplane work remains the governed default.

CLI Ownership and Migration

Command	Owner	Status
howl	howlcipher/howl	Future ecosystem umbrella command. Not provided by HowlPlane.
howlplane	howlcipher/howlplane	Canonical direct HowlPlane command.
ai	howlcipher/howlplane	Deprecated compatibility command. It writes a migration notice to stderr and then runs the same implementation.

Migrate direct invocations from ai ... to howlplane .... The legacy command remains available during the transition so existing scripts keep their arguments, exit codes, and stdout. Its notice is written to stderr so JSON and other machine-readable stdout remain intact.

The Go project integration command is also available directly:

howlplane project validate /path/to/project

For the reusable Go command API and the future umbrella integration contract, see CLI composition.

---

Closed-Loop Operating Model

HowlPlane mechanically enforces every stage of the engineering lifecycle. An agent claiming "Done." has no authority to move a task to complete; complete must be earned through clean git deltas, independent review falsification, remediation, deterministic verification, and human authority authorization:

Human Objective / Backlog Item
              ↓
  Stage 1: Discovery & Context Audit (discovered)
  ├── Project stack discovery (.ai-project.toml, project_manifest.yaml, stack markers)
  └── HowlFrame capability-bounded shadow context audit (read-only dogfooding)
              ↓
  Stage 2: Deterministic Planning & Routing (planned)
  ├── Agent Selection (Claude Code, Codex, Gemini CLI, Devin CLI, Antigravity)
  └── Specialized Reviewer Selection
              ↓
  Stage 3: Repository Baseline Isolation
  └── Captures commit SHA, modified files, and untracked files prior to agent launch
              ↓
  Stage 4: Implementation Agent Launch (implementing)
  └── Subprocess execution with live stdio streaming and timeout enforcement
              ↓
  Stage 5: Task-Attributable Delta Capture
  └── Isolates newly created/modified diffs from pre-existing repository dirt
              ↓
  Stage 6: Independent Adversarial Reviews (reviewing)
  ├── Specialized Reviewer Roles (Correctness, Regression, Security, Test Falsifier, etc.)
  ├── Strict structured findings parsing (YAML/JSON with fail-closed malformed handling)
  └── Review Reconciliation Engine (confirmed, likely, disputed, requires_human)
              ↓
  Stage 7: Autonomous Remediation & Re-Review Loop (remediating ↔ reviewing)
  ├── Targeted re-review dispatching only to reviewers with open findings
  └── Configurable remediation cycle limits
              ↓
  Stage 8: Deterministic Verification (verifying)
  └── Executes test suites, linters, and repository hygiene gates (slopslint)
              ↓
  Stage 9: Human Authority Boundary Gate (awaiting_human)
  └── Enforces explicit operator authorization for high-risk actions
              ↓
  Stage 10: Complete Evidence Ledger & Run Finalization (complete / awaiting_human / failed)
  └── Writes structured artifacts to .task_runs/<task_id>/ and durable ledger

---

Core Capabilities

1. Deterministic Task Routing (src/control_plane/router.py): Capability-based matching without remote LLM calls. Routes tasks by risk tier, reasoning requirements, and agent capability profiles.
2. Specialized Independent Reviewers (src/control_plane/reviewers.py): Generates targeted falsification briefs designed to uncover subtle regressions, contract mismatches, security boundaries, and test coverage gaps rather than cheerleading code.
3. Review Reconciliation Engine (src/control_plane/reconciler.py): Synthesizes multi-reviewer findings into structured categories (confirmed, likely, disputed, requires_human). Blocker and high-severity findings require explicit non-empty resolution reasons before dismissal.
4. Deterministic Verification Suites (src/control_plane/verification.py): Executes build, test, lint, and repository hygiene gates (slopslint) through deterministic subprocess execution.
5. Durable Evidence Ledger (logs/control_plane/evidence_ledger.jsonl): Append-only structured record of task lifecycles, review findings, and verification outcomes with automated credential and token redaction.
6. Human Authority Boundaries (src/control_plane/human_boundary.py): Enforces explicit human authorization on consequential actions (production deployments, infrastructure modifications, database drops, package releases, and repository hygiene policy weakenings).
7. Reasoning Strategy Dogfooding (src/control_plane/reasoning/): Records bounded and redacted execution trajectories, immutable pre-registered baseline and candidate definitions, versioned strategy identities, deterministic comparisons, and evidence-linked observations. One shared coordinator supports every experiment type with durable definition, baseline, candidate, and evaluation checkpoints; a fresh process can resume the exact incomplete phase without duplicating trajectories or accounting. Strategy experiments remain orthogonal to authority and never store hidden chain-of-thought or change model weights.
8. Configurable AI Resource Pool (ProviderPoolManager): Separates registered adapters, operator-enabled resources, non-generative readiness, role and capability eligibility, durable capacity, economic policy, deterministic cognitive recommendation, and final selection. Provider, interface, resource, and observed model identities remain distinct; unobserved model IDs stay null. Governed implementation and independent review consume the same pool, and schema-versioned trajectories preserve the full selection decision without hidden reasoning.

Milestone #60B used this machinery for a bounded evidence campaign and accepted six new trajectories, bringing the current schema live set to eight. Its context and routing comparisons remained INCONCLUSIVE, while its review topology candidate was FALSIFIED for one fixture only. Every comparison still had one sample per arm, cloud primary and successful repair evidence remained sparse, and provider composition plus decomposition were unobserved. The resulting decision was COLLECT_MORE_TRAJECTORY_EVIDENCE.

Milestone #60C completed six preregistered comparisons and accepted fourteen new live trajectories. It added two samples per #60B context arm, a held constant Claude versus Codex task, and a real bounded but unsuccessful repair. Provider composition and task decomposition were executed as raw trajectories but did not satisfy the milestone's meaningful-coverage criteria: the composition task was trivial exact fact extraction whose provider events label both invocations as role=review, and the decomposition task manufactured two subtasks for a simple two-fact extraction. Both are preserved as live executed attempts with coverage classified NOT_OBSERVED. A second empty-review-artifact topology fixture was also collected. All six experiment evaluations remain INCONCLUSIVE; cloud model and all cost fields remain NOT_OBSERVED. No learned routing or strategy promotion occurred.

Milestone #60D then exercised the same immutable evidence system against real historical engineering defects. Milestone #61 now extends the existing shared provider pool into a configurable resource registry with separate operator permission, readiness, capability, capacity, economic policy, deterministic recommendation, and authority stages. The work remains on its feature branch until the generic registry, CLI visibility, trajectory integration, local-only proof, compatibility, and complete verification are merged.

The implementation extends the production Python ProviderPoolManager and its existing registry, backend, review, marathon, and trajectory consumers. The deterministic TaskRouter remains an advisory recommendation layer over an already eligible candidate set; it does not grant provider permission, egress, spend, capability, or execution authority.

Provider failure classification uses dominant structural evidence. Launch outcomes and local harness budgets remain authoritative, while exact terminal provider errors distinguish authentication and capacity exhaustion from tool permission denials recorded earlier in a session. Ordinary transcript prose cannot override a current structured denial merely by quoting a session or quota warning.

---

Operating Modes & Egress Governance

HowlPlane provides mechanically enforced runtime egress governance configured via config/settings.yaml:

• local_only (Default): Outbound network egress is blocked at the application runtime level. Hosted LLM provider dispatches are rejected in preflight, LangSmith telemetry is hard-disabled, and remote document sync operations are blocked. Local Ollama backends and local vector search operate fully offline.
• connected: Enables configured hosted providers (Anthropic, Google AI, OpenAI) and optional telemetry when explicitly authorized by the operator.

Note: Application-level runtime egress governance complements but is distinct from OS-level kernel network namespace sandboxing. For complete egress mappings, see the Data Flows & Network Egress Reference.

---

Cross-Repository Operation

HowlPlane is designed to operate seamlessly across any codebase on your machine (Go, Python, TypeScript, Rust, C++, etc.). The control plane provides orchestration rules, reviewer roles, and verification schemas, while the target repository provides local truth: manifest configurations, local skills, and test/build commands.

---

HowlFrame Architectural Relationship & Dogfooding Position

HowlPlane serves as a primary real-world dogfooding consumer of the HowlFrame toolchain:

HowlPlane (AI Engineering Control Plane)
      |
      +-- normal deterministic tooling (Go, Python, Make, Git)
      |
      +-- AI coding agents (Claude Code, Codex, Gemini CLI, Devin CLI, Antigravity)
      |
      +-- HowlFrame bounded execution runtime (future constrained / policy execution paths)

• What HowlFrame is: An AI-native programming language and capability-bounded execution runtime.
• Why HowlPlane dogfoods HowlFrame: Smaller applications prove individual language features; HowlChangeOps proves governed consequential change execution; HowlPlane provides high-frequency real AI engineering workloads that pressure generated structured programs, capability boundaries, malformed AI output, instruction budgets, partial failures, result normalization, and structured evidence.
• Independence: HowlPlane remains completely usable without HowlFrame. HowlFrame is an optional runtime dependency for selected bounded tasks.

---

Knowledge & Skills Layer Subsystem

The repository's shared context layer operates as an integrated subsystem within HowlPlane:

• AGENTS.md: Canonical global engineering context and grounding protocol loaded natively across agents.
• Rules (.agents/rules/): Anti-manipulation, prompt sanitization, and safety constraints.
• Skills (.agents/skills/): 40 domain skills covering software engineering, quality assurance, defensive security, database management, and systems logic.
• Prompts (.agents/prompts/): Canonical multi-agent prompt library (work_next_item, route_task, review_change, reconcile_reviews, verify_change, ship_check).
• Grounding Profile (USER_PROFILE.md): Local user profile grounding personal context and career materials.

---

Global Installation & Setup

Option 0: Howl Ecosystem Installer (Recommended)

howl install downloads and verifies the howlplane CLI (a checksummed release binary, from GitHub Releases) and the Python control-plane engine (a checksummed wheel from the same release, installed into an isolated venv Howl manages) together, as one dependency-ordered ecosystem install -- no local Go toolchain, source checkout, or pip install -e required. Everything except project-family subcommands is transparently delegated from the howlplane binary to the managed engine; see internal/enginepath for the resolution order.

Option 1: Standalone Binary Installer

1. Download the latest ai_installer executable (Linux, macOS, Windows, .deb, .rpm) from the GitHub Releases page.
2. Run the executable in your terminal:

   ./ai_installer

   The interactive installer links global rules to Gemini CLI / Antigravity, Claude Code, Codex, and Devin CLI, and sets up your environment.

Option 2: Script-Based Setup

# Linux or macOS:
chmod +x scripts/install_global.sh
./scripts/install_global.sh

# Windows (PowerShell):
.\scripts\install_global.ps1

Option 3: Developer / Source Install

go build -o build/howlplane ./cmd/howlplane
pip install -e ".[dev]"

This is the source-build path (Howl's --profile developer uses it too); the built howlplane binary reports its own version with howlplane --version.

Configuration & Discovery Precedence

The howlplane launcher locates the HowlPlane control plane using the following order:

1. --control-plane-dir <path> CLI flag
2. HOWLPLANE_HOME or HOWLPLANE_DIR environment variable
3. AI_KNOWLEDGE_LIBRARY environment variable (deprecated fallback)
4. ~/.config/howlplane/config.toml (canonical) -> ~/.config/ai-control-plane/config.toml -> ~/.config/ai/config.toml
5. Self repository root detection

---

Documentation Index

• Control Plane Architecture
• ADR 0006 — Persistent Factory Supervisor
• Configurable AI Resource Pool
• User Guide & Operator Reference
• Local AI Worker (Ollama) & Bounded Dogfooding
• Data Flows & Network Egress Reference
• Coding Standards & Hygiene
• AI Framework Blueprint
• Localizations & Languages
• Change Log