Host Project

Ploinky Documentation

Ploinky is a workspace-local runtime that discovers agent repositories under .ploinky/repos/, launches enabled agents across multiple execution backends, builds a routing table, and serves token- or identity-gated browser surfaces through a supervised local router.

Documentation Contract

The current branch implementation is the only valid authority for this documentation set. The HTML pages explain how the system behaves in practice, while the DS files under the specifications matrix define the normative contract. The coding-style authority is DS001 Coding Style.

When code changes behavior, interfaces, workflows, or constraints, update the affected HTML pages, docs/ploinky-overview.md, and the affected DS files in the same change. The specs must remain thorough and in sync with the code.

How the Runtime Starts

  1. The CLI initializes .ploinky/, ensures a default repository is available when possible, and records workspace configuration in .ploinky/agents.json.
  2. start <staticAgent> <port> enables the requested static agent if necessary, resolves manifest-driven dependencies, and expands the dependency graph into wave-based startup groups.
  3. Each wave is started through the selected runtime backend, then gated by readiness checks that probe either raw TCP or an MCP handshake, depending on the manifest.
  4. The resulting routes are written to .ploinky/routing.json and the static agent’s source tree becomes the static host root served by the router.
  5. The router is launched through cli/server/Watchdog.js, which supervises RoutingServer.js, manages health-check restarts, and writes router and watchdog logs under .ploinky/logs/.

Repository Map

Path Current Role
cli/ Primary implementation for the CLI, workspace services, router, auth bridge, runtime managers, and browser-surface handlers.
Agent/ Shared runtime payload mounted into agents, including AgentServer, wire-signing helpers, and the default CLI wrapper.
bin/ Entry points such as ploinky, p-cli, ploinky-shell, and helper scripts used by operators and tests.
tests/ Stage-oriented end-to-end harness, reusable verification functions, and Node unit tests for runtime services and protocol helpers.
globalDeps/ Global Node dependency baseline merged into per-agent dependency caches.
.agents/skills/ Repository-local maintenance skills. These are part of the repository workflow, not part of the Ploinky runtime contract.
dashboard/ Legacy standalone dashboard assets. The active routed /dashboard fallback lives under cli/server/dashboard/.

Current Skill Catalog

The repository includes local maintenance skills that shape documentation, spec review, and skill-generation workflows. Ploinky is documented here as a host runtime, so these skills are summarized for orientation but do not get standalone host-product pages or standalone DS files.

  • achilles_specs Extends bootstrap guidance with AchillesAgentLib requirements and coding-style additions.
  • antropic_skill_build Defines the portability baseline for Anthropic-style skills.
  • article_build Rebuilds article folders, generated chapters, SVG assets, and bibliography material.
  • cskill_build Defines conventions for C-Skills with stable specs and generated JavaScript.
  • dgskill_build Defines conventions for dynamic code-generation skills.
  • gamp_specs Rebuilds canonical repository docs, specs, and root guidance.
  • oskill_build Defines orchestration-skill preparation and execution loops.
  • review_specs Reviews and updates DS files against the current implementation.

Runtime Defaults and Operator Touchpoints

Defaults

The workspace root is discovered by locating .ploinky/. The active profile defaults to dev. Container runtime detection prefers podman and falls back to docker.

The router-managed surfaces are /webtty, /webchat, /webmeet, /dashboard, and /status.

Primary Entry Points

Use ploinky or p-cli for workspace operations, ploinky-shell for LLM-driven command suggestions, ploinky deps ... for dependency caches, and ploinky profile ... for runtime mount-policy changes.

The LLM suggestion layer consumes docs/ploinky-overview.md, so CLI and model-selection changes must keep that file accurate.

Testing Entry Points

The main regression harness is tests/test_all.sh, which orchestrates prepare, start, stop, start-again, restart, destroy, and unit-test phases. tests/run-all.sh simply dispatches to that script. tests/runFailingFast.sh replays only the most recent failing checks after a fresh prepare-and-start cycle.

Stage actions live in tests/do*.sh, stage verifications live in tests/testsAfter*.sh, reusable shell assertions live in tests/test-functions/, and Node unit tests live in tests/unit/.