How kunalamin/mypka works
1. What this repository is
- This is not an application with a server/runtime; it is a local, file-based knowledge operating system.
- The architecture centers on plain Markdown on disk plus an external LLM tool (Claude Code, Codex CLI, Gemini CLI, Cursor, Obsidian chat plugin, etc.) that reads and writes the folder structure.
2. Control plane: root-level orchestration
- The root AGENTS.md is the global source of truth for how the system behaves.
- ADAPTER-PROMPT.md is the bootstrap prompt that an LLM tool uses to initialize the workspace and generate a tool-specific pointer file such as CLAUDE.md or GEMINI.md.
- VERSION, CHANGELOG.md, CONTRIBUTING.md, WAY-FORWARD.md, and the license/notice files define the repo’s governance and lifecycle, not runtime behavior.
3. Agent layer: the AI team
- Team/ contains the specialist contracts, one folder per agent, each with its own AGENTS.md.
- Team/agent-index.md acts as the routing table for the team.
- The shipped specialists are:
- Larry: orchestrator and librarian; all user interaction flows through him.
- Nolan: talent acquisition / hiring workflow.
- Pax: deep research and sourcing.
- Penn: journal writing and filing.
- The architectural boundary here is important: Larry routes and synthesizes; specialists do the work.
4. Knowledge core: PKM/
- PKM/ is the canonical knowledge store.
- It is organized by domain slices such as:
- My Life/ for the personal operating model
- CRM/ for people and organizations
- Documents/ for important documents
- Journal/ for daily notes and chronological capture
- Images/ for dated media references
- Notes are meant to connect via wikilinks rather than deep folder nesting, so the graph is in the links, not the directory tree.
5. Personal knowledge model inside My Life/
- PKM/My Life/ is the main personal framework and is explicitly split into five life concepts:
- Goals
- Habits
- Topics
- Projects
- Key Elements
- This is the repo’s most important semantic structure for personal organization; it is where long-lived life-management notes live.
6. Capture boundary: Team Inbox/
- Team Inbox/ is the ingestion point for raw, unstructured inputs.
- Inputs like screenshots, voice memos, business cards, links, or rough thoughts land here first.
- The intended flow is Inbox → Penn/Larry processing → proper location in PKM/.
- This is the repository’s main “untrusted input” boundary.
7. Working area: Deliverables/
- Deliverables/ is the team’s transient work surface for research briefs, workups, and multi-file artifacts.
- Pax places research here; Nolan places hiring workups here; Larry aggregates multi-specialist outputs here.
- This folder separates in-progress or client-facing outputs from the canonical knowledge base in PKM/.
8. Process layer: Team Knowledge/
- Team Knowledge/ contains the playbooks that define how the team operates.
- It is divided into:
- Guidelines/ for static conventions like naming rules
- SOPs/ for atomic procedures
- Workstreams/ for multi-step, multi-agent workflows
- Examples in the repo include daily journaling and vault-to-SQLite migration, which show that the system supports both everyday routines and future scaling paths.
9. Externalization and extension points
- docs/extension-spec.md defines how extensions are supposed to fit the scaffold.
- Extensions/ and Extensions/INDEX.md are the architectural slot for optional add-ons.
- The README makes clear that some extensions are membership-only and not part of the open scaffold, so the repo is designed to be extensible without those components present.
10. Assets and presentation layer
- assets/ contains the visual and media assets used by the documentation and team avatars.
- These files do not affect data flow, but they support the human-facing presentation of the agent system and onboarding docs.
11. Primary data flow
- The dominant flow is:
- user input enters through the LLM tool
- Larry receives the request
- Larry routes to the right specialist
- the specialist writes to Deliverables/, Team Knowledge/, or PKM/ depending on the task
- Penn/Larry file or normalize information into canonical notes
- The system is intentionally read/write on the filesystem, with the LLM acting as the process layer rather than a hidden backend.
12. Scaling boundary: plain Markdown first, SQLite later
- The repo’s default architecture is Markdown-first and tool-agnostic.
- A documented migration path exists to add SQLite as a lookup layer when the vault grows, but Markdown remains the source of truth.
- This keeps the core architecture simple: filesystem canonical, database optional.
13. What to draw in an architecture diagram
- Show a central local folder vault with four major zones:
- Control/agent contracts: root AGENTS.md, Team/
- Canonical knowledge: PKM/
- Processing/workspace: Deliverables/, Team Inbox/
- Operating procedures: Team Knowledge/
- Outside the vault, show the LLM client as the runtime that interprets prompts and edits files.
- The key boundaries are input capture, agent routing, canonical storage, and ephemeral work products.
Main entry points: PKM/INDEX.md PKM · agent-index.md Agent index · Team Knowledge/INDEX.md Team Knowledge · AGENTS.md Global AGENTS
Components 23
Control plane
Root-level governance, bootstrap prompt, and agent routing contracts.
- LLM client · Claude Code, Codex CLI, Gemini CLI, Cursor, or similar tool that reads and writes the vault.
- Adapter prompt · Initializes the workspace and generates a tool-specific pointer file.
ADAPTER-PROMPT.md - Global AGENTS · Root source of truth for repository behavior and agent instructions.
AGENTS.md
Agent layer
Specialist roles and their routing table.
- Agent index · Maps requests to the right specialist and defines team entry points.
Team/agent-index.md - Larry · Primary coordinator and librarian; all user interaction flows through him.
Team/Larry - Orchestrator/AGENTS.md - Nolan · Handles hiring and talent acquisition workflows.
Team/Nolan - HR/AGENTS.md - Pax · Handles deep research and sourcing work.
Team/Pax - Researcher/AGENTS.md - Penn · Handles journal writing, filing, and normalization of captured material.
Team/Penn - Journal Writer/AGENTS.md
Canonical knowledge
Markdown knowledge vault organized by domain slices and linked notes.
- PKM · Canonical Markdown knowledge store for the repository.
PKM/INDEX.md - My Life · Main personal operating model organized into goals, habits, topics, projects, and key elements.
PKM/My Life/README.md - CRM · People and organization notes.
PKM/CRM/INDEX.md - Documents · Important personal documents and reference materials.
PKM/Documents/INDEX.md - Journal · Daily notes and time-ordered capture.
PKM/Journal/INDEX.md - Images · Dated media references and image-linked notes.
PKM/Images/INDEX.md
Working areas
Inbound capture and transient deliverables used during processing.
- Team Inbox · Untrusted input boundary for screenshots, voice memos, links, and rough thoughts.
Team Inbox/README.md - Deliverables · Transient workspace for research briefs, workups, and multi-file artifacts.
Deliverables/README.md
Operating procedures
Team playbooks and workflow standards.
- Team Knowledge · Guidelines, SOPs, and workstreams that define how the team operates.
Team Knowledge/INDEX.md - Guidelines · Static conventions such as naming rules.
Team Knowledge/Guidelines/INDEX.md - SOPs · Atomic procedures for repeatable tasks.
Team Knowledge/SOPs/INDEX.md - Workstreams · Multi-step, multi-agent operating flows.
Team Knowledge/Workstreams/INDEX.md
Docs and extensions
Repository-level documentation, extension scaffold, and supporting assets.
- Extensions · Optional add-ons and architectural extension point.
Extensions/INDEX.md - Extension spec · Defines how extensions fit the scaffold.
docs/extension-spec.md - Assets · Visual and media assets for documentation and team avatars.
assets/team
Connections 27
- LLM client → Adapter prompt: bootstraps · The runtime starts from the adapter prompt to initialize the workspace.
- Adapter prompt → Global AGENTS: loads · Bootstrap points the tool at repository-wide operating rules.
- Global AGENTS → Agent index: delegates · Global instructions route requests through the team index.
- Agent index → Larry: routes to · Larry is the primary entry and coordination point.
- Agent index → Nolan: routes to · Talent and hiring tasks go to Nolan.
- Agent index → Pax: routes to · Research and sourcing tasks go to Pax.
- Agent index → Penn: routes to · Writing, filing, and normalization tasks go to Penn.
- Larry → Team Inbox: ingests · Larry helps move raw inputs from inbox to structured work.
- Larry → Deliverables: assembles · Larry aggregates multi-specialist outputs into deliverables.
- Penn → PKM: files into · Penn normalizes captured information into canonical notes.
- Pax → Deliverables: writes · Research outputs are staged in the working area.
- Nolan → Deliverables: produces · Hiring workups and artifacts live in deliverables first.
- Team Inbox → Penn: processed by · Inbox items are cleaned up and filed through Penn or Larry.
- Team Inbox → Larry: triaged by · Larry can directly triage incoming unstructured inputs.
- Deliverables → PKM: promoted to · Useful work products are canonicalized into the knowledge vault.
- PKM → My Life: contains · The personal operating model is the central semantic slice.
- PKM → CRM: contains · People and organizations live in the CRM slice.
- PKM → Documents: contains · Important documents are stored here.
- PKM → Journal: contains · Chronological capture is stored here.
- PKM → Images: contains · Dated image references are stored here.
- Team Knowledge → Guidelines: organizes · Static standards are grouped under guidelines.
- Team Knowledge → SOPs: organizes · Atomic procedures are grouped under SOPs.
- Team Knowledge → Workstreams: organizes · Multi-step workflows are grouped under workstreams.
- Workstreams → PKM: operates on · Workstreams act on the vault as the source of truth.
- Extension spec → Extensions: defines · The spec describes how extensions plug into the scaffold.
- Assets → Global AGENTS: supports · Assets support documentation and team presentation.
- Global AGENTS → Team Knowledge: references · Operating instructions point to team playbooks and procedures.