pwcli-core is an open-source specification for building intent-driven,
dual-engine applications: a conversational or CLI-style surface for human
intent, backed by deterministic routes, schemas, registered panels, typed tools,
provenance, and explicit approval gates.
The project is intentionally not a chatbot framework. It is a control-plane
blueprint for software that can feel conversational without surrendering runtime
predictability. It is designed as a broad starting point that can wrap existing
agent infrastructure instead of replacing it. Use OpenAI Agents SDK, LangGraph,
MCP servers, A2A agents, Goose, Claude Code, or custom runtimes for execution;
use pwcli-core for intent contracts, primitive selection, approvals,
provenance, privacy, redaction, and data boundaries.
pwcli-core is published by Protocol Wealth and initiated by Nick Rygiel,
Managing Partner / CTO and a Certified Financial Planner professional.
- Protocol Wealth GitHub: https://github.com/Protocol-Wealth
- Nick Rygiel GitHub: https://github.com/rivendale
These Protocol Wealth and maintainer repositories are companion references and
implementation inspiration. The pwcli-core specification remains neutral and
reusable outside Protocol Wealth.
nexus-core: https://github.com/Protocol-Wealth/nexus-corepwos-core: https://github.com/Protocol-Wealth/pwos-corepwplan-core: https://github.com/Protocol-Wealth/pwplan-corepw-learnai: https://github.com/Protocol-Wealth/pw-learnaiiocalc-agent-env: https://github.com/rivendale/iocalc-agent-env (public dual-license reference; verify current terms in that repo)
Human language is lossy. Production systems are not.
pwcli-core bridges that gap with a simple architecture:
- A human asks for something in natural language.
- The system compiles that request into structured intent telemetry.
- A registered panel, route, workflow, or tool is selected.
- Read-only actions run directly when safe.
- Mutating actions stop at an approval gate.
- Every result keeps source, rights, provenance, and fallback-route context.
- Dual engine: AI routes intent; deterministic infrastructure owns state.
- Bring your own panel: AI selects registered UI primitives, never invents live UI code.
- Hard trust boundaries: AI may propose, classify, parse, and select. It may not invent routes, schemas, writes, or permissions.
- Standards Before Invention: Prefer existing open standards before custom schemas.
- Assertion separation: Source metadata and AI interpretation are stored as distinct layers.
- Context packs: Static Markdown files with YAML frontmatter provide agent-loadable operating context without turning prompts into a truth store.
- Adapter governance: External agent runtimes stay useful while
pwcli-coredeclares side effects, data access, redaction, approval, and audit boundaries.
pwcli-core classifies references by operational maturity:
- Stable / formal standards: OpenAPI, JSON Schema, OAI-PMH, Dublin Core, MARC 21, IIIF, W3C PROV-O, RDF, JSON-LD, DCAT, SPDX.
- Widely adopted vocabularies: schema.org.
- Open agent protocols: Model Context Protocol (MCP), Agent-to-Agent (A2A).
- Community standards: RO-Crate.
- Emerging conventions: llms.txt, AGENTS.md.
- Local patterns: context-pack/.
- Experimental / watch layer: WebMCP.
See docs/standards-map.md and docs/companion-projects.md.
pwcli-core/
|-- SPEC.md
|-- SECURITY.md
|-- CONTRIBUTING.md
|-- AGENTS.md
|-- llms.txt
|-- context-pack/
|-- prompts/
|-- schemas/
|-- crosswalks/
|-- examples/
`-- docs/
Read these files in order:
- SPEC.md for the full architecture specification.
- prompts/architecture-engine.md for the system prompt.
- schemas/intent.schema.json for the central intent payload.
- docs/standards-map.md for standards selection.
- docs/context-packs.md for context-pack structure.
- docs/validation.md for local and CI validation.
- examples/turn-based-game/README.md for a runnable browser demo.
- docs/human-ux-guide.md for progressive disclosure patterns.
- examples/adapter-control-demo/README.md for runtime adapter, redaction, approval, and provenance flow.
- docs/agent-runtime-adapters.md for using existing agent infrastructure.
- docs/privacy-redaction-control-plane.md for data and redaction policy.
- docs/agent-poisoning-defense.md for prompt injection and agent poisoning controls.
Run the dependency-free repository checks locally:
npm run validateThe same command runs in GitHub Actions on pull requests and pushes to main
using Node 22 and Node 24.
See examples/runtime-adapters/README.md for synthetic adapter examples covering OpenAI Agents SDK, LangGraph, MCP servers, A2A agents, Goose, and Claude Code. See examples/redaction-policies/README.md for privacy and redaction policy examples. See docs/agent-poisoning-defense.md for controls against prompt injection, poisoned issues, poisoned tool outputs, and workflow exfiltration.
Open examples/turn-based-game/index.html in a browser for a no-build demo of command input, intent telemetry, registered primitive hydration, approval, deterministic execution, and return-focus ledger output. Open examples/adapter-control-demo/index.html for a no-build demo of untrusted input, runtime adapter selection, redaction policy, approval, and provenance receipts.
Illustrative synthetic example only; not a booking, emergency, or legal instruction.
User: Help me prep for our Chicago trip next week.
Intent:
- domain: travel
- intent: prepare_trip_plan
- confidence: 0.84
- sideEffectLevel: read_only
- approvalRequired: false
- fallbackRoute: /travel
- candidatePanels: [trip-plan-panel, packing-checklist-panel]
The conversational surface can hydrate a travel planning panel, cite source records, and return focus to the command stream. If confidence is low, it falls back to a static route instead of inventing behavior.
Licensed under MIT-0 OR Apache-2.0.
You may use the frictionless MIT-0 terms or the Apache 2.0 terms with an explicit patent grant. See LICENSE-MIT-0 and LICENSE-APACHE-2.0.