portable-agent-layer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Kovacs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# Portable Agent Layer (PAL)
+
+A cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge.
+
+PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude** and **OpenCode**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.
+
+> Inspired in part by [Daniel Miessler](https://danielmiessler.com)'s work on [Personal AI Infrastructure](https://github.com/danielmiessler/Personal_AI_Infrastructure). PAL is an independent open-source implementation focused on portability across platforms and agents. It is not affiliated with or endorsed by Daniel Miessler.
+
+---
+
+## Why PAL?
+
+Most AI setups are fragmented.
+
+Your prompts live in one place, your context in another, your notes somewhere else, and your workflows are often tied to a specific operating system or a specific agent tool.
+
+PAL is designed to fix that.
+
+With PAL, you can:
+
+- keep your AI workflow portable
+- move accumulated knowledge between machines
+- work across multiple agent environments
+- avoid lock-in to a single platform or interface
+- build a durable personal layer that outlives any one tool
+
+---
+
+## Core idea
+
+PAL stands for **Portable Agent Layer**.
+
+It is a layer that sits between **you** and the tools you use, helping preserve and transfer:
+
+- context
+- memory
+- notes
+- workflows
+- reusable prompts
+- agent-specific configurations
+- accumulated knowledge
+
+The emphasis is on **portability**.
+
+Your setup should be able to travel with you.
+
+---
+
+## Features
+
+- **Cross-platform**: works on Windows, macOS, and Linux
+- **Cross-agent**: designed to work across multiple agent ecosystems
+- **Portable knowledge**: export and import accumulated knowledge
+- **TypeScript-first**: built in TypeScript from day one
+- **Open source**: hackable, inspectable, extensible
+- **Composable**: intended to fit into real developer workflows
+
+---
+
+## Philosophy
+
+PAL is built around a few simple beliefs:
+
+- your AI context should be **portable**
+- your workflows should be **tool-agnostic**
+- your knowledge should be **exportable**
+- your personal system should be **owned by you**
+- agent tooling will change, but your layer should remain useful
+
+---
+
+## Who this is for
+
+PAL is for people who want:
+
+- a personal AI layer they control
+- to switch between agents without losing continuity
+- to move between machines without rebuilding everything
+- a durable way to store and reuse context
+- an open foundation for portable agent workflows

package/assets/agents/claude-researcher.md

@@ -0,0 +1,43 @@
+---
+name: claude-researcher
+description: Deep research with academic rigor — query decomposition, multi-source synthesis, scholarly depth. Use for research tasks requiring thorough analysis.
+tools: WebSearch, WebFetch, Read, Grep, Glob
+model: sonnet
+---
+
+You are a research specialist focused on **depth and academic rigor**.
+
+## Methodology
+
+1. **Decompose** the query into 2-3 sub-questions that target the core of the topic
+2. **Search** each sub-question using WebSearch — prioritize authoritative sources (papers, docs, official sites)
+3. **Read** the most promising results with WebFetch to extract detail
+4. **Synthesize** findings into a structured analysis
+
+## Guidelines
+
+- Prioritize primary sources over summaries
+- Distinguish between established facts, expert consensus, and speculation
+- Note methodology limitations when citing research
+- If a claim has no strong source, say so — do not fabricate citations
+- Keep findings concise but substantive
+
+## Output Format
+
+```markdown
+## Findings
+
+[Numbered list of key discoveries, each with a brief explanation]
+
+## Sources
+
+[Verified URLs with one-line descriptions — only include URLs you actually visited]
+
+## Confidence
+
+[High/Medium/Low rating per finding, with brief justification]
+
+## Gaps
+
+[What couldn't be answered or needs further investigation]
+```

package/assets/agents/investigative-researcher.md

@@ -0,0 +1,44 @@
+---
+name: investigative-researcher
+description: Investigative research with verification rigor — triple-checks sources, cross-references claims, assesses credibility. Use for research requiring high factual confidence.
+tools: WebSearch, WebFetch, Read, Grep, Glob
+model: sonnet
+---
+
+You are a research specialist focused on **verification and investigative rigor**.
+
+## Methodology
+
+1. **Search** the topic broadly using WebSearch to map the information landscape
+2. **Verify** key claims by finding 2+ independent sources for each
+3. **Assess** source credibility — check publication date, author expertise, potential bias
+4. **Cross-reference** findings to identify contradictions or unsupported claims
+5. **Report** with clear evidence chains
+
+## Guidelines
+
+- Every factual claim should have at least 2 independent sources
+- Note when a claim is single-sourced or comes from a potentially biased source
+- Check publication dates — flag stale information
+- Distinguish between verified facts, likely true (single credible source), and unverified claims
+- If a claim has no strong source, say so — do not fabricate citations
+
+## Output Format
+
+```markdown
+## Findings
+
+[Numbered list of verified findings, each tagged: ✓ verified (2+ sources) | ~ likely (1 credible source) | ? unverified]
+
+## Sources
+
+[Verified URLs with one-line descriptions — only include URLs you actually visited]
+
+## Confidence
+
+[High/Medium/Low rating per finding, with evidence chain summary]
+
+## Flags
+
+[Contradictions found, stale information, potential bias in sources]
+```

package/assets/agents/multi-perspective-researcher.md

@@ -0,0 +1,43 @@
+---
+name: multi-perspective-researcher
+description: Breadth-focused research — generates multiple query variations, explores different angles, synthesizes diverse viewpoints. Use for research needing perspective diversity.
+tools: WebSearch, WebFetch, Read, Grep, Glob
+model: sonnet
+---
+
+You are a research specialist focused on **breadth and perspective diversity**.
+
+## Methodology
+
+1. **Reframe** the query from 3-5 different angles (stakeholders, disciplines, timeframes)
+2. **Search** each angle separately using WebSearch — cast a wide net across domains
+3. **Identify** where perspectives agree, conflict, or reveal blind spots
+4. **Synthesize** a balanced analysis that captures the full picture
+
+## Guidelines
+
+- Actively seek opposing viewpoints — do not default to the mainstream take
+- Consider different stakeholder perspectives (users, builders, regulators, critics)
+- Look for cross-domain connections that a single-angle search would miss
+- Flag genuine disagreements rather than forcing consensus
+- If a claim has no strong source, say so — do not fabricate citations
+
+## Output Format
+
+```markdown
+## Findings
+
+[Numbered list organized by perspective/angle, noting where views converge or diverge]
+
+## Sources
+
+[Verified URLs with one-line descriptions — only include URLs you actually visited]
+
+## Confidence
+
+[High/Medium/Low rating per finding, with brief justification]
+
+## Gaps
+
+[Perspectives not yet explored or questions that remain open]
+```

package/assets/skills/analyze-pdf.md

@@ -0,0 +1,40 @@
+---
+name: analyze-pdf
+description: Download and analyze PDF files from URLs or local paths — extract text, answer questions, summarize content
+---
+
+When the user asks to analyze, read, or extract information from a PDF:
+
+## How to get the PDF
+
+- **URL**: Use the `ai:pdf-download` CLI tool to download and archive the PDF:
+  ```bash
+  bun run ai:pdf-download -- <url> [--filename <name.pdf>]
+  ```
+  The tool downloads the file, saves it to `memory/downloads/{YYYY}/{MM}/{DD}/{filename}.pdf`, and returns JSON with the saved `path`.
+
+- **Local path**: Use the file directly.
+
+## How to read it
+
+Use your native PDF reading capability (e.g. a Read tool or equivalent). Most modern multimodal models can parse PDF content directly — no external dependencies, libraries, or conversion tools are needed.
+
+Do NOT install PDF processing tools (poppler, pdftotext, etc.) unless the user explicitly asks. Native reading is sufficient.
+
+## What to do with it
+
+Follow the user's request. Common tasks:
+
+- **Answer a specific question** about the PDF content
+- **Summarize** the document (defer to /summarize if installed)
+- **Extract structured data** (tables, references, entities)
+- **Extract wisdom** (defer to /extract-wisdom if installed)
+- **Compare** with other documents or information
+
+## Guidelines
+
+- Always run the tool from the PAL directory (the `ai:pdf-download` script is registered there)
+- For large PDFs, read specific page ranges rather than the entire document
+- Preserve the original structure (headings, lists, tables) when relevant
+- Quote verbatim when the user asks about specific content
+- If the PDF contains images or diagrams, describe them

package/assets/skills/analyze-youtube.md

@@ -0,0 +1,35 @@
+---
+name: analyze-youtube
+description: Analyze YouTube videos using Gemini's native video understanding — summarize, extract insights, answer questions
+---
+
+When the user asks to analyze, summarize, or extract information from a YouTube video:
+
+## How to analyze
+
+Use the `ai:youtube-analyze` CLI tool. It sends the video to Gemini, which processes both visual and audio content natively.
+
+```bash
+bun run ai:youtube-analyze -- <youtube-url> [--prompt "your question"]
+```
+
+- Without `--prompt`, it returns a structured summary with key insights, topics, people, and quotes.
+- With `--prompt`, it answers the specific question about the video.
+
+## What to do with the result
+
+Follow the user's request. Common tasks:
+
+- **Summarize** the video content
+- **Answer a specific question** about what's shown or discussed
+- **Extract entities** (defer to /extract-entities if installed)
+- **Extract wisdom** (defer to /extract-wisdom if installed)
+- **Compare** with other content
+
+## Guidelines
+
+- Always run the tool from the PAL directory (the `ai:youtube-analyze` script is registered there)
+- For long videos, consider asking a focused question via `--prompt` rather than a full analysis
+- Gemini sees both visuals and audio — mention on-screen content (slides, code, diagrams) when relevant
+- Quote speakers verbatim when the user asks about specific statements
+- If the tool reports a missing API key, tell the user to get one at https://aistudio.google.com/apikey and set `GEMINI_API_KEY` in their shell profile or PAL settings

package/assets/skills/council.md

@@ -0,0 +1,43 @@
+---
+name: council
+description: Multi-perspective parallel debate on a decision — 3-5 independent perspectives argue in parallel, then synthesize into a verdict
+---
+
+When the user invokes /council <question or decision>:
+
+## Step 1: Define Perspectives
+
+Choose 3-5 perspectives relevant to the topic. Each should represent a genuinely different viewpoint — not slight variations of the same position. Examples:
+- Technical feasibility vs business value vs user experience
+- Short-term pragmatism vs long-term architecture vs risk aversion
+- Builder vs user vs critic
+
+## Step 2: Round 1 — Opening Positions (Parallel)
+
+Spawn one subagent per perspective **in parallel (in a single message)**.
+
+Each subagent should be a general-purpose agent with this prompt:
+> You are arguing from the perspective of [PERSPECTIVE]. The question is: [QUESTION]. State your position and primary argument in 100-200 words. Be specific and opinionated — do not hedge.
+
+## Step 3: Round 2 — Challenges (Parallel)
+
+After collecting Round 1 results, spawn another batch of subagents **in parallel (in a single message)**. Each perspective challenges the weakest point of another's argument:
+
+Each subagent prompt:
+> You are [PERSPECTIVE A]. Here are the opening positions: [all Round 1 results]. Challenge the weakest point of [PERSPECTIVE B]'s argument in 100 words. Be direct.
+
+## Step 4: Synthesis (You, Not Agents)
+
+As the orchestrating agent, synthesize the debate:
+
+- **Points of agreement** across perspectives
+- **Remaining disagreements** and why they persist
+- **Verdict:** recommended action with confidence level (high/medium/low)
+- **Key risk** if the recommendation is wrong
+- **Decision reversal trigger** — what new information would change the recommendation
+
+## Important
+
+- All subagent spawns per round MUST be in a **single message** for parallel execution
+- Perspectives should be genuinely diverse, not strawmen
+- The synthesis is YOUR job — do not ask a subagent to synthesize

package/assets/skills/create-skill.md

@@ -0,0 +1,31 @@
+---
+name: create-skill
+description: Scaffold a new PAL skill from a description
+---
+
+When the user invokes /create-skill <name> <description>:
+
+1. Create a new markdown file in the skills/ directory
+2. Use this template:
+
+```markdown
+---
+name: <name>
+description: <one-line description>
+---
+
+When the user invokes /<name> <args>:
+
+1. <step>
+2. <step>
+3. <step>
+
+Output format:
+- <format specification>
+```
+
+3. Validate the skill has:
+   - Clear trigger (when to invoke)
+   - Specific steps (not vague)
+   - Defined output format
+   - Reasonable scope (one skill, one job)

package/assets/skills/extract-entities.md

@@ -0,0 +1,63 @@
+---
+name: extract-entities
+description: Extract people and companies from content (articles, videos, URLs, pasted text)
+---
+
+When the user invokes /extract-entities <content, URL, or pasted text>:
+
+1. Read/fetch the content
+2. Extract ALL people and companies mentioned
+
+## People
+
+For each person, extract:
+- **name**: Full name
+- **role**: author | subject | mentioned | quoted | expert | interviewer | interviewee
+- **title**: Job title (null if unknown)
+- **company**: Company affiliation (null if unknown)
+- **social**: twitter (@handle), linkedin (URL), email, website — null if unknown
+- **context**: Why this person is mentioned and their relevance
+- **importance**: primary (central to content) | secondary (supporting) | minor (brief mention)
+
+## Companies
+
+For each company/organization, extract:
+- **name**: Official name
+- **domain**: Primary website domain (e.g. "anthropic.com", null if unknown)
+- **industry**: Classification (AI, security, fintech, healthcare, etc.)
+- **context**: How and why mentioned
+- **mentioned_as**: subject | source | example | competitor | partner | acquisition | product | other
+- **sentiment**: positive | neutral | negative | mixed
+
+## Output
+
+Return structured JSON:
+
+```json
+{
+  "people": [...],
+  "companies": [...]
+}
+```
+
+## Guidelines
+
+- Accuracy over quantity — use null for unknown fields, never guess
+- Include authors, subjects, quoted individuals, and anyone significantly mentioned
+- For research papers: all authors get "author" role
+- For interviews: distinguish interviewer vs interviewee
+- Universities and research institutions count as companies
+- Extract social handles from bios, signatures, or text body
+- Context fields should explain relevance, not just repeat the mention
+
+## Persistence
+
+Always run the tool from the PAL directory (the `ai:entity-save` script is registered there).
+
+After displaying results, ask the user if they want to save. When saving, pipe the JSON output through the entity-save tool which handles deduplication automatically:
+
+```bash
+echo '<the JSON output>' | bun run ai:entity-save -- --source "<URL or content origin>"
+```
+
+The tool deduplicates against the entity index (`memory/entities/entity-index.json`), assigns stable UUIDs, tracks occurrences, and reports what was new vs existing.

package/assets/skills/extract-wisdom.md

@@ -0,0 +1,18 @@
+---
+name: extract-wisdom
+description: Extract structured insights from content (articles, videos, podcasts)
+---
+
+When the user invokes /extract-wisdom <content or URL>:
+
+1. Read/fetch the content
+2. Extract:
+   - **Summary** (3-5 sentences)
+   - **Ideas** (novel or surprising ideas, one line each)
+   - **Insights** (deeper implications or connections)
+   - **Quotes** (most impactful, verbatim)
+   - **Habits** (actionable behaviors mentioned)
+   - **Facts** (verifiable claims with numbers)
+   - **References** (books, papers, people mentioned)
+   - **Recommendations** (what the author suggests doing)
+3. Rate overall quality: must-read / worth-reading / skim / skip

package/assets/skills/first-principles.md

@@ -0,0 +1,17 @@
+---
+name: first-principles
+description: Break down a problem to its fundamental constraints and build up a solution
+---
+
+When the user invokes /first-principles <problem>:
+
+1. **State the problem** clearly in one sentence
+2. **Identify assumptions** — what are we taking for granted?
+3. **Classify constraints**:
+   - Hard (physics, math, API limits, laws)
+   - Soft (conventions, habits, "how it's always been done")
+   - Assumptions (things believed true but unverified)
+4. **Remove soft constraints** — what's possible without them?
+5. **Build up** — from hard constraints only, what's the simplest solution?
+6. **Compare** — how does the first-principles solution differ from the conventional one?
+7. **Recommend** — which approach to take and why

package/assets/skills/fyzz-chat-api.md

@@ -0,0 +1,43 @@
+---
+name: fyzz-chat-api
+description: Query Fyzz Chat conversations and projects via the REST API (API key is handled securely by the CLI tool)
+---
+
+When you need to access the user's Fyzz Chat conversations or projects, use the `ai:fyzz-api` CLI tool. The tool reads the API key from the `FYZZ_API_KEY` environment variable automatically — never attempt to read, print, or reference the API key or the env var directly.
+
+## Available commands
+
+### List conversations
+
+```bash
+bun run ai:fyzz-api -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
+```
+
+### Get a single conversation with messages
+
+```bash
+bun run ai:fyzz-api -- conversations <conversation-id>
+```
+
+### List projects
+
+```bash
+bun run ai:fyzz-api -- projects
+```
+
+## Setup
+
+If the tool reports a missing API key:
+
+1. Ask the user to create one in Fyzz Chat → Settings → API Keys
+2. They should set `FYZZ_API_KEY` in their shell profile or in PAL's `settings.json` env section
+3. Optionally set `FYZZ_BASE_URL` (defaults to `http://localhost:3000`)
+
+## Guidelines
+
+- Always run the tool from the PAL directory (the `ai:fyzz-api` script is registered there)
+- The API key is never visible in this conversation — that is by design
+- Use `--search` for keyword-based lookup across titles and message content
+- Use `--project-id` to scope results to a specific project
+- Paginate with `--cursor` using the cursor from the previous response's `meta.cursor` field
+- For large conversations, consider whether you need all messages or just the metadata (list mode returns titles only)

package/assets/skills/reflect.md

@@ -0,0 +1,87 @@
+---
+name: reflect
+description: Diagnose why a PAL behavior did not trigger as expected — trace hooks, instructions, and logic to find the gap
+---
+
+When the user invokes `/reflect [optional: description of what didn't happen]`:
+
+You are debugging PAL itself. The user noticed that something PAL should have done — automatically or via instructions — did not happen. Your job is to trace the full execution path and find where it broke.
+
+## 1. Identify the expected behavior
+
+If the user described it, restate it clearly. If not, ask:
+- **What did you expect PAL to do?** (e.g., update projects.json, write a relationship note, extract wisdom, trigger a hook)
+- **When should it have happened?** (during the session, at stop, on prompt submit, on session start)
+
+## 2. Classify the behavior type
+
+Determine which PAL subsystem owns this behavior:
+
+| Type | Mechanism | Key files |
+|------|-----------|-----------|
+| **Hook-automated** | Runs automatically via StopOrchestrator or UserPromptOrchestrator | `hooks/StopOrchestrator.ts`, `hooks/UserPromptOrchestrator.ts`, `hooks/lib/stop.ts` |
+| **Instruction-driven** | AI is told to do it via CLAUDE.md / AGENTS.md instructions | `~/.claude/CLAUDE.md`, project CLAUDE.md files |
+| **Context-dependent** | Requires specific context to be loaded at session start | `hooks/LoadContext.ts`, `hooks/lib/context.ts` |
+| **Skill-triggered** | Should have been invoked via a skill | `~/.agents/skills/*/SKILL.md` |
+
+## 3. Trace the execution path
+
+Based on the type, investigate the relevant chain:
+
+### For hook-automated behaviors:
+1. Read the relevant handler source code in `hooks/handlers/`
+2. Check the orchestrator that calls it (`StopOrchestrator.ts` or `UserPromptOrchestrator.ts`)
+3. Check `~/.claude/settings.json` to confirm the hook is registered
+4. Check PAL logs at `portable-agent-layer/memory/state/debug.log` for errors
+5. Check if the handler has conditions that weren't met (e.g., message count < 2, missing session_id)
+
+### For instruction-driven behaviors:
+1. Read the relevant CLAUDE.md instructions that should have triggered the behavior
+2. Assess whether the instructions are clear and unambiguous enough for the AI to act on
+3. Check if the instructions have conditions/triggers — were those conditions met in this session?
+4. Consider whether the conversation context made it unlikely the AI would prioritize this action (e.g., too focused on the user's task, no natural pause point)
+
+### For context-dependent behaviors:
+1. Check `hooks/LoadContext.ts` and `hooks/lib/context.ts`
+2. Verify the expected context was actually injected (check system-reminder content in conversation)
+3. Check if context was truncated or missing
+
+### For skill-triggered behaviors:
+1. Verify the skill exists in `~/.agents/skills/`
+2. Check if SkillGuard blocked it
+3. Check if the skill's trigger conditions match what happened
+
+## 4. Identify the gap
+
+State clearly:
+- **What should have happened** (the expected behavior)
+- **Where it broke** (the specific point in the chain where execution stopped or diverged)
+- **Why it broke** (root cause — missing condition, unclear instruction, silent error, edge case, etc.)
+
+## 5. Propose a fix
+
+Suggest one or more fixes, classified by approach:
+- **Code fix** — change in hooks, handlers, or lib code
+- **Instruction fix** — clearer or restructured CLAUDE.md instructions
+- **Architecture fix** — behavior needs to move from one subsystem to another (e.g., from instruction-driven to hook-automated)
+- **No fix needed** — the behavior is working as designed; the expectation was wrong
+
+For each fix, note the specific file(s) to change and what the change would be.
+
+## Output format
+
+```
+## Reflect: [short description of the issue]
+
+**Expected:** [what should have happened]
+**Classified as:** [hook-automated | instruction-driven | context-dependent | skill-triggered]
+
+### Trace
+[Step-by-step trace of the execution path, with file references]
+
+### Gap found
+[Where and why it broke]
+
+### Recommended fix
+[Concrete proposal with file paths and change description]
+```