Personal Network Toolkit

Toolkit-Version: 0.1 (draft) — the toolkit (spec, contracts, skill, lint, templates) is versioned as a unit; see VERSION.

The Personal Network Toolkit (PNT) is a generative application-class blueprint for building and validating personal network applications (PNAs) — local-only apps for viewing contact data and working on relationship data over a firewalled private data layer. PNAs run on the user's device, never as SaaS, and bridge SaaS-held contact data into a private workspace. Why do this?

When building a PNA, specs are foundational because users will increasingly compose software by prompting AI agents, and success is measured by adherence to them.

Three deliverables, in dependency order:

1. Foundational specs. Universal vocabulary, goals, axes, architectural commitments, and typed contracts for a PNA. — shipping in v0.1 (draft).
2. Production-ready reference applications. Working PNAs you can install, study, and adapt. — first reference design is a distributed directory archive (lives at richbodo/fellows_local_db).
3. AI tooling — skill + MCP (Model Context Protocol) servers. How AI agents work with PNT. The skill at pna-build-eval-contrib/SKILL.md is what an agent reads to consume the spec at design time. The MCP servers (typed contracts in contracts/; three v1 stdio implementations in fellows_local_db/mcp_servers/) expose an already-built PNA's capabilities at runtime so AI clients (Claude Desktop, Cursor, local Ollama agents) can drive a PNA on the user's behalf.

PNT supports three modes of use, all packaged in the skill. Install it once so your agent auto-discovers it — symlink the skill into your skills directory (run from your PNT working directory):

mkdir -p ~/.claude/skills
ln -s "$(pwd)/pna-build-eval-contrib" ~/.claude/skills/pna-build-eval-contrib

A git pull here then updates the skill everywhere it's used. See docs/users-guide.md § Install the skill for copy-instead-of-symlink, project-scoped, and no-install alternatives. With the skill installed, drive any mode in natural language:

• Evaluate. Audit any contact app for safety before you install it. An AI agent reads the candidate's source, checks it against every applicable AC (Architectural Commitment), and returns a structured report flagging anything that would put your data at risk. The lowest-friction way in — and it doubles as a self-check on your own in-progress design.
• Build. An AI agent reads the spec and helps you compose a conformant PNA against the typed contracts, adapting from a reference design that shares your axis picks.
• Contribute. When you find a spec gap or have a design that adds ecosystem value, the skill walks you through preflight validation (Architecture document + AC attestation table) and then opens the PR back to PNT.

See docs/users-guide.md for step-by-step instructions for each.

PNT augments human-AI builder teams; it doesn't auto-build applications itself. It's a blueprint for AI agents to implement and humans to customize and verify. Conformance verification works at three layers: mechanical lints in tools/ (CI-enforced), LLM (Large Language Model) architectural review via the skill above, and human PR review.

Status

v0.1 (draft). The spec is feature-complete for v0.1 — universal ACs, axes, use cases, slot map with sub-contracts, and typed contracts are all in place. The "draft" label reflects that the contribution workflow described in plans/reorganization-plan.md hasn't yet been validated against fellows_local_db as the first reference design.

Most recent landing: reorganization Phases 1–4.5 (May 2026) — repo restructure, RFC 2119 + bidirectional AC↔contract traceability, skill packaging, User's Guide. See CHANGELOG.md.

What we're working toward — success looks like:

1. A new builder can read README.md + CONTRIBUTING.md and build a conformant PNA using the skill. — Materials in place; end-to-end validation pending (Phase 5 will exercise this against fellows_local_db).
2. A new user can ask an LLM (via the skill) to audit a candidate PNA's source and get an actionable AC-keyed report. — Skill flow documented; validation against a candidate pending.
3. A new contributor can submit a reference design end-to-end without maintainer hand-holding beyond review. — Skill + CONTRIBUTING in place; awaits a first external contribution (Phase 7).
4. Every accepted design has a permanent Software Heritage identifier that survives upstream repo deletion. — Awaits Phase 5 archival tooling (tools/swh-save.sh).
5. The PNA Spec evolves at least one minor version based on a contributed reference design's findings. — Awaits a contribution.
6. Every AC in the spec carries a stable ID; every typed contract names the AC(s) it realizes; every Architecture document maps each applicable AC to a verification mechanism. — First two CI-enforced via tools/lint-spec-ids.py; fellows_local_db Architecture-doc backfill pending (Phase 5).

Step-by-step instructions for each of those goals live in docs/users-guide.md.

Substantive changes from v0.1 bump the toolkit version per CHANGELOG.md.

Entry points

Read in this first if you are new:

• docs/users-guide.md — step-by-step instructions for each of the success criteria in § Status (building a PNA, auditing one, submitting a reference design).
• spec/PNA_Spec.md — universal PNA specification. Vocabulary, goals, use cases, axes, composition, universal architectural commitments, slot map with 57 sub-contracts, scope/versioning.

To contribute to the spec with a new reference design or architectural finding:

• CONTRIBUTING.md — how reference designs (and any spec changes they motivate) get accepted into PNT.

To dig into the spec more deeply:

• pna-build-eval-contrib/SKILL.md — the skill packaging the three flows (build, evaluate, contribute) for AI agents. The agent-consumption view of the toolkit.
• spec/axes.md — the Axes a PNA varies along, attested picks per Axis, and the flavor-derived ACs each pick triggers.
• spec/use_cases.md — attested classes of PNA (Directory Archive realized; Personal Relationship Manager draft; Multi-PNA ecosystem target).
• contracts/ — typed contracts for the load-bearing interfaces: JSON Schema for the worker init handshake + RPC (Remote Procedure Call) protocol, OpenAPI for distribution auth, SQL DDL (Data Definition Language) for the two database schemas, TypeScript for the Communications transport interface, JSON Schema for the five canonical MCP server tool surfaces.
• CHANGELOG.md — toolkit version history.
• llms.txt — discovery file for the spec (humans + AI agents land here cold).

Reference designs

A reference design is a working, deployed PNA that demonstrates one valid combination of axis picks against the spec. Each lives in its own repository so it can ship under its own release cadence.

• fellows_local_db — first reference design. Directory Archive use case. Its docs/Architecture.md declares Toolkit-Version conformance and the per-slot specializations. Flavor:

  Axis	Pick
  distribution	web-bundle-with-magic-link
  storage substrate	opfs-sqlite-wasm
  ingestion shape	single-source-static-mirror
  workspace shell	vanilla-js-spa
  comms transport set	mailto-only
  MCP-exposure	shared+private+comms

When a second reference design (e.g. a Personal Relationship Manager) lands, it'll be linked from here.

Prior Art

PNT is a generative application-class blueprint: a machine-readable spec, written for AI agents, that defines what makes an instance of a whole class of apps correct and lets many implementations attest conformance. docs/PriorArt.md surveys the landscape — spec-driven-development tooling, agent-interface standards, conformance test suites, Common Criteria Protection Profiles, and local-first infrastructure — and finds no published artifact occupies the same quadrant: generative + class-scoped + multi-flavor + machine-checkable. The full annotated source list is in docs/PriorArtReferences.md.

License

LICENSE.