portable-agent-layer 0.1.0

package/assets/skills/research.md

@@ -0,0 +1,68 @@
+---
+name: research
+description: Multi-agent parallel research — quick/standard/extensive modes with specialized researcher agents for depth, breadth, and verification
+---
+
+## Mode Routing
+
+| User says | Mode | Agents |
+|-----------|------|--------|
+| "quick research" / "minor research" | Quick | 1 agent |
+| "research" / "do research" (default) | Standard | 2 parallel agents |
+| "extensive research" / "deep research" | Extensive | 6 parallel agents |
+
+## Available Researcher Agents
+
+- **claude-researcher** — academic depth, query decomposition, scholarly synthesis
+- **multi-perspective-researcher** — breadth, multiple angles, diverse viewpoints
+- **investigative-researcher** — verification rigor, triple-checks, source credibility
+
+## Quick Mode
+
+Spawn **1 subagent** for a focused answer:
+
+- Spawn `claude-researcher` with the full query and context
+
+Wait for the result, then deliver it directly with light formatting.
+
+## Standard Mode (Default)
+
+Craft **2 different queries** optimized for each researcher's strengths, then spawn both **in parallel (in a single message)**:
+
+- Spawn `claude-researcher` with a query optimized for depth/analysis
+- Spawn `multi-perspective-researcher` with a query optimized for breadth/perspectives
+
+**Query design:**
+- claude-researcher: focus on authoritative sources, technical depth, how/why
+- multi-perspective-researcher: focus on different stakeholder views, trade-offs, alternatives
+
+## Extensive Mode
+
+Craft **6 queries** (2 per researcher type, each from a different angle), then spawn all **in parallel (in a single message)**:
+
+- Spawn `claude-researcher` — angle 1: core technical depth
+- Spawn `claude-researcher` — angle 2: historical context / evolution
+- Spawn `multi-perspective-researcher` — angle 3: stakeholder perspectives
+- Spawn `multi-perspective-researcher` — angle 4: cross-domain connections
+- Spawn `investigative-researcher` — angle 5: verify key claims
+- Spawn `investigative-researcher` — angle 6: find contradictions / counter-evidence
+
+## Synthesis (All Modes)
+
+After collecting agent results, synthesize into:
+
+1. **TLDR** — 1-2 sentence answer
+2. **Key findings** — bullet points, grouped by theme, noting which agent(s) found each
+3. **Cross-source agreement** — findings confirmed by multiple agents (high confidence)
+4. **Conflicts** — where agents disagree, with both sides presented
+5. **Gaps** — what remains unknown or needs further investigation
+6. **Sources** — deduplicated list of verified URLs from all agents
+
+Keep total output under 1500 words unless the user asks for more.
+
+## Important
+
+- All subagent spawns for a given mode MUST be in a **single message** for true parallel execution
+- Do NOT run agents sequentially — that defeats the purpose
+- Each agent returns independently — expect different formats and overlapping findings
+- The synthesis step is YOUR job as the orchestrating agent, not the subagents'

package/assets/skills/review.md

@@ -0,0 +1,19 @@
+---
+name: review
+description: Security-focused code review with severity ratings
+---
+
+When the user invokes /review <file, diff, or PR>:
+
+1. Read the target code or diff in full
+2. Analyze for:
+   - **Security** — OWASP top 10, injection, auth, data exposure
+   - **Logic** — edge cases, off-by-one, null handling, race conditions
+   - **Performance** — N+1 queries, unnecessary allocations, blocking calls
+   - **Style** — consistency with surrounding code (not your preferences)
+3. Output findings grouped by severity:
+   - CRITICAL — must fix before merge
+   - WARNING — should fix, creates risk
+   - SUGGESTION — nice to have
+4. Each finding includes: file:line, what's wrong, concrete fix
+5. End with a one-line verdict: APPROVE / REQUEST CHANGES / NEEDS DISCUSSION

package/assets/skills/summarize.md

@@ -0,0 +1,15 @@
+---
+name: summarize
+description: Structured summarization of documents, URLs, or conversations
+---
+
+When the user invokes /summarize <target>:
+
+1. Fetch or read the target content
+2. Produce:
+   - **TLDR** (1 sentence)
+   - **Key points** (5-7 bullets)
+   - **Action items** (if any exist in the content)
+   - **Notable quotes/data** (verbatim, with attribution)
+3. Keep total output under 500 words
+4. If the content is very long, note what was covered vs skipped

package/assets/templates/AGENTS.md.template

@@ -0,0 +1,45 @@
+# PAL — Portable Agent Layer
+
+You have PA installed. PAL provides persistent personal context across sessions — the user's identity, goals, projects, beliefs, and challenges are stored in TELOS files and loaded into your context automatically. Use this information to tailor your responses to who they are and what they care about.
+
+When TELOS is populated, you already know the user. When it's empty, first-run setup is required — follow the setup instructions below.
+
+{{SETUP_PROMPT}}
+{{TELOS}}
+## Memory
+
+PAL has its own memory system that persists across sessions AND across tools (Claude Code, opencode). Always prefer PAL memory over any tool-native memory system.
+
+### Where to write
+
+{{MEMORY_PATHS}}
+
+### Format
+
+- **Wisdom frames**: One `.md` file per domain/topic. Each file contains bullet-point principles the user has validated or you've learned. Append new principles to existing files or create new domain files.
+- **Relationship notes**: Daily `.md` file with bullet-point observations about the interaction (tone, preferences, corrections).
+- **Session learnings**: One `.md` file per session with a `**Title:**` line summarizing what was learned.
+- **Failure captures**: One directory per failure, named `{YYYYMMDD-HHmmss}_{slug}/`, containing a `capture.md` with what went wrong and why.
+
+## Work Tracking
+
+PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured) and `memory/state/projects.json` (AI-managed).
+
+### Projects
+
+Update `projects.json` via the work-tracking library when:
+- **Starting sustained multi-session work** → create a project with objectives and an id (slugified, e.g. "pdf-template-engine")
+- **Making a key decision** → add to the project's `decisions` array
+- **Completing a milestone** → add to `completed`, remove from `nextSteps`
+- **Session ends with open work** → update `nextSteps` and `handoff`
+- **Work is done** → set status to "completed"
+
+Do not create projects for one-off questions or quick fixes.
+
+### When to write
+
+- When the user corrects you or gives feedback → wisdom frame
+- When you learn something about how the user prefers to work → relationship note
+- When a session produces reusable insights → session learning
+- When something fails significantly (rating < 6) → failure capture
+- Do NOT write memories about trivial exchanges or things already captured in TELOS.

package/assets/templates/telos/BELIEFS.md

@@ -0,0 +1,4 @@
+# Beliefs
+
+<!-- Your values, principles, and worldview. What do you hold to be true? -->
+

package/assets/templates/telos/CHALLENGES.md

@@ -0,0 +1,4 @@
+# Challenges
+
+<!-- Current obstacles, open problems, things you're stuck on. -->
+

package/assets/templates/telos/GOALS.md

@@ -0,0 +1,12 @@
+# Goals
+
+<!-- Active goals with timeframes. What are you working toward right now? -->
+
+## Short-term
+-
+
+## Medium-term
+-
+
+## Long-term
+-

package/assets/templates/telos/IDEAS.md

@@ -0,0 +1,4 @@
+# Ideas
+
+<!-- Ideas you're exploring, things to revisit, seeds of future projects. -->
+

package/assets/templates/telos/IDENTITY.md

@@ -0,0 +1,4 @@
+# AI Identity
+
+<!-- The name and identity of your personal AI assistant. -->
+

package/assets/templates/telos/LEARNED.md

@@ -0,0 +1,4 @@
+# Learned
+
+<!-- Hard-won lessons. Things you figured out the hard way that should inform future decisions. -->
+

package/assets/templates/telos/MISSION.md

@@ -0,0 +1,4 @@
+# Mission
+
+<!-- Your core purpose. What drives you? What impact do you want to have? -->
+

package/assets/templates/telos/MODELS.md

@@ -0,0 +1,4 @@
+# Mental Models
+
+<!-- Frameworks and mental models you use for thinking and decision-making. -->
+

package/assets/templates/telos/NARRATIVES.md

@@ -0,0 +1,4 @@
+# Narratives
+
+<!-- Key stories and context about your life and work. Background that shapes how you think. -->
+

package/assets/templates/telos/PROJECTS.md

@@ -0,0 +1,7 @@
+# Projects
+
+<!-- Current projects, their status, and how they relate to each other. -->
+
+| Project | Status | Priority | Notes |
+|---------|--------|----------|-------|
+|         |        |          |       |

package/assets/templates/telos/STRATEGIES.md

@@ -0,0 +1,4 @@
+# Strategies
+
+<!-- How you approach problems. Preferred methods, workflows, decision heuristics. -->
+

package/bin/pal

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Jarvis — Claude Code wrapper with session summary on exit.
+#
+# After Claude exits, finds the most recently modified transcript JSONL
+# in ~/.claude/projects/ and extracts the sessionId from its last line.
+
+PAL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Run Claude (blocking — keeps the interactive terminal)
+claude "$@"
+EXIT_CODE=$?
+
+# Find the most recently modified transcript and extract its session ID
+LATEST=$(find "$HOME/.claude/projects" -name '*.jsonl' -type f -print0 2>/dev/null \
+  | xargs -0 ls -t 2>/dev/null | head -1)
+
+if [ -n "$LATEST" ]; then
+  SESSION_ID=$(tail -1 "$LATEST" | python3 -c "import sys,json; print(json.loads(sys.stdin.readline()).get('sessionId',''))" 2>/dev/null)
+  if [ -n "$SESSION_ID" ]; then
+    bun run "$PAL_DIR/src/tools/session-summary.ts" -- --session "$SESSION_ID" 2>/dev/null
+  fi
+fi
+
+exit $EXIT_CODE

package/bin/pal.bat

@@ -0,0 +1,8 @@
+@echo off
+REM Jarvis — Claude Code wrapper with session summary on exit.
+REM
+REM Uses PowerShell to start Claude, capture its PID, read the session ID
+REM from %USERPROFILE%\.claude\sessions\<PID>.json, then show a cost
+REM summary after Claude exits.
+
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0pal.ps1" %*

package/bin/pal.ps1

@@ -0,0 +1,30 @@
+# Jarvis — Claude Code wrapper with session summary on exit.
+#
+# After Claude exits, finds the most recently modified transcript JSONL
+# in ~/.claude/projects/ and extracts the sessionId from its last line.
+
+$palDir = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path)
+
+# Run Claude (blocking — keeps the interactive terminal)
+& claude @args
+$exitCode = $LASTEXITCODE
+
+# Find the most recently modified transcript and extract its session ID
+$latest = Get-ChildItem "$env:USERPROFILE\.claude\projects\*\*.jsonl" -ErrorAction SilentlyContinue |
+    Sort-Object LastWriteTime -Descending |
+    Select-Object -First 1
+
+if ($latest) {
+    $lastLine = Get-Content $latest.FullName -Tail 1 -ErrorAction SilentlyContinue
+    if ($lastLine) {
+        try {
+            $sessionId = ($lastLine | ConvertFrom-Json).sessionId
+            if ($sessionId) {
+                $summaryScript = Join-Path $palDir "src" "tools" "session-summary.ts"
+                & bun run $summaryScript -- --session $sessionId 2>$null
+            }
+        } catch {}
+    }
+}
+
+exit $exitCode

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "portable-agent-layer",
+  "version": "0.1.0",
+  "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
+  "type": "module",
+  "bin": {
+    "pal": "src/cli/index.ts"
+  },
+  "files": [
+    "src/",
+    "assets/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "opencode",
+    "personal-ai",
+    "context",
+    "memory",
+    "telos",
+    "agent",
+    "portable"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kovrichard/portable-agent-layer.git"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "format": "biome format",
+    "format-write": "biome format --write",
+    "lint": "biome lint",
+    "lint-write": "biome lint --write",
+    "check": "biome check",
+    "check-write": "biome check --write",
+    "lint-staged": "lint-staged",
+    "prepare": "husky",
+    "install:all": "bun run src/cli/install.ts",
+    "uninstall": "bun run src/cli/uninstall.ts",
+    "ai:entity-save": "bun run src/tools/entity-save.ts",
+    "ai:fyzz-api": "bun run src/tools/fyzz-api.ts",
+    "ai:pdf-download": "bun run src/tools/pdf-download.ts",
+    "ai:youtube-analyze": "bun run src/tools/youtube-analyze.ts",
+    "tool:patterns": "bun run src/tools/pattern-synthesis.ts",
+    "tool:reflect": "bun run src/tools/relationship-reflect.ts",
+    "tool:export": "bun run src/tools/export.ts",
+    "tool:import": "bun run src/tools/import.ts",
+    "tool:tokens": "bun run src/tools/token-cost.ts"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "bun run check"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.7",
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@opencode-ai/plugin": "latest",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@types/adm-zip": "^0.5.8",
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16"
+  }
+}