@tekmidian/pai 0.3.2 → 0.4.0

package/templates/skills/sessions-skill.template.md

@@ -0,0 +1,102 @@
+<!-- Generated by PAI Setup -->
+---
+name: Sessions
+description: Navigate and manage PAI sessions across all projects. USE WHEN user says "list sessions", "where was I working", "show my sessions", "find session", "continue work from", "switch to project", "open project", "name project", "group projects", "consolidate", "organize projects", "clean up sessions", "work on X", "start working on X", "show me what we did on X", "bring notes together", OR asks about past sessions, previous work, or project navigation.
+---
+
+## How Session Notes Work
+
+Session notes track what was done in each Claude session. They live in a `Notes/` directory.
+
+**The key concept: notes route to a project.** When the user says "work on PAI" or "start working on myproject", you set the routing so all session notes go to that project's Notes directory. The routing is stored in `~/.claude/session-routing.json`.
+
+**Where notes actually live:**
+- Each project has a Notes directory (usually in an Obsidian vault or local Notes folder)
+- Code repos can symlink their `Notes/` to a vault path
+- Claude also keeps internal copies in `~/.claude/projects/*/Notes/` (for search/history)
+- The `pai` CLI manages everything
+
+**Project paths** are stored in `~/.claude/session-routing.json` under `project_paths`. Add your own projects by editing that file.
+
+---
+
+## What the User Might Say → What You Do
+
+**"Work on PAI" / "Start working on myproject" / "Let's do PAI stuff"**
+→ Run `pai route <project-name>`. Tell user: "Notes now routing to [path]."
+
+**"Show me the sessions where we worked on PAI" / "What did we do on myproject?"**
+→ Run `pai search <project-name>`. Show the matching sessions with dates and summaries.
+
+**"Bring the PAI notes together" / "Consolidate PAI sessions"**
+→ Search for all sessions matching the project name across all projects. Read the session notes. Combine them into a coherent summary. Write a consolidated note if asked.
+
+**"List sessions" / "Show recent sessions" / "/sessions"**
+→ ALWAYS run `pai session active` FIRST to show currently open Claude Code tabs.
+→ Then run `pai project list` and `pai session list` for the full overview.
+→ Present active sessions PROMINENTLY at the top of your response.
+
+**"Where are my notes going?" / "What's the current routing?"**
+→ Run `pai route` (no args) to show current status.
+
+**"Stop routing" / "Clear routing" / "Back to default"**
+→ Run `pai route clear`.
+
+**"Open the myproject project"**
+→ Run `pai open <project-name> --claude` to open in a new terminal tab.
+
+**"Continue work from the myproject project"**
+→ Search for relevant sessions, read the notes and TODO.md, present context summary, continue working here.
+
+---
+
+## Commands Reference
+
+| Command | What it does |
+|---------|-------------|
+| `pai session active` | **Show currently open Claude Code sessions** (checks JSONL timestamps) |
+| `pai session active --minutes 120` | Widen the detection window (default: 60 min) |
+| `pai session active --json` | JSON output for programmatic use |
+| `pai` | Show all projects with session counts |
+| `pai session list` | Detailed session list |
+| `pai search "keyword"` | Find sessions by keyword |
+| `pai route <project>` | Route notes to a project |
+| `pai route` | Show current routing status |
+| `pai route clear` | Stop routing, use defaults |
+| `pai open <project> --claude` | Open project in new tab |
+| `pai name "Name"` | Name the current project |
+| `pai info <number>` | Deep dive into a project |
+
+---
+
+## Examples
+
+**Example 1: "Show me what we did on PAI"**
+```
+→ Run: pai search pai
+→ Show matching sessions with dates
+→ Offer to read specific session notes for details
+```
+
+**Example 2: "Let's work on myproject"**
+```
+→ Run: pai route myproject
+→ Output: "Notes now routing to .../myproject/Notes"
+→ Read myproject's TODO.md to see pending work
+→ Continue from where we left off
+```
+
+**Example 3: "Bring all the PAI sessions together"**
+```
+→ Run: pai search pai (find all PAI-related sessions)
+→ Read each session note
+→ Create a consolidated summary
+→ Optionally write it to PAI's Notes directory
+```
+
+**Example 4: "Where was I working on the appstore?"**
+```
+→ Run: pai search appstore
+→ Show matching projects with session counts
+→ Offer to open or read details
+```

package/templates/skills/skill-system.template.md

@@ -0,0 +1,214 @@
+<!-- Generated by PAI Setup -->
+# Custom Skill System
+
+**The MANDATORY configuration system for ALL PAI skills.**
+
+---
+
+## THIS IS THE AUTHORITATIVE SOURCE
+
+This document defines the **required structure** for every skill in the PAI system.
+
+**ALL skill creation MUST follow this structure.**
+
+**"Canonicalize a skill"** = Restructure it to match this exact format, including TitleCase naming.
+
+---
+
+## TitleCase Naming Convention (MANDATORY)
+
+**All naming in the skill system MUST use TitleCase (PascalCase).**
+
+| Component | Wrong | Correct |
+|-----------|-------|---------|
+| Skill directory | `createskill`, `create-skill` | `Createskill` |
+| Workflow files | `create.md`, `update-info.md` | `Create.md`, `UpdateInfo.md` |
+| Reference docs | `prosody-guide.md` | `ProsodyGuide.md` |
+| Tool files | `manage-server.ts` | `ManageServer.ts` |
+| YAML name | `name: create-skill` | `name: Createskill` |
+
+**Exception:** `SKILL.md` is always uppercase (convention for the main skill file).
+
+---
+
+## The Required Structure
+
+Every SKILL.md has two parts:
+
+### 1. YAML Frontmatter (Single-Line Description)
+
+```yaml
+---
+name: SkillName
+description: [What it does]. USE WHEN [intent triggers using OR]. [Additional capabilities].
+---
+```
+
+**Rules:**
+- `name` uses **TitleCase**
+- `description` is a **single line** (not multi-line with `|`)
+- `USE WHEN` keyword is **MANDATORY** (Claude Code parses this for skill activation)
+- Use intent-based triggers with `OR` for multiple conditions
+- Max 1024 characters (Anthropic hard limit)
+
+### 2. Markdown Body
+
+```markdown
+# SkillName
+
+[Brief description]
+
+## Workflow Routing
+
+**When executing a workflow, do BOTH of these:**
+
+1. **Call the notification script** (for observability tracking):
+   ```bash
+   ~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME SKILLNAME
+   ```
+
+2. **Output the text notification** (for user visibility):
+   ```
+   Running the **WorkflowName** workflow from the **SKILLNAME** skill...
+   ```
+
+This ensures workflows appear in the observability dashboard AND the user sees the announcement.
+
+| Workflow | Trigger | File |
+|----------|---------|------|
+| **WorkflowOne** | "trigger phrase" | `workflows/WorkflowOne.md` |
+| **WorkflowTwo** | "another trigger" | `workflows/WorkflowTwo.md` |
+
+## Examples
+
+**Example 1: [Common use case]**
+```
+User: "[Typical user request]"
+→ Invokes WorkflowOne workflow
+→ [What skill does]
+→ [What user gets back]
+```
+
+## [Additional Sections]
+```
+
+---
+
+## Examples Section (REQUIRED)
+
+**Every skill MUST have an `## Examples` section** showing 2-3 concrete usage patterns.
+
+**Why Examples Matter:**
+- Anthropic research shows examples improve tool selection accuracy from 72% to 90%
+- Descriptions tell Claude WHEN to activate; examples show HOW the skill works
+
+**Example Format:**
+```markdown
+## Examples
+
+**Example 1: [Use case name]**
+```
+User: "[Actual user request]"
+→ Invokes WorkflowName workflow
+→ [What the skill does]
+→ [What user receives back]
+```
+```
+
+---
+
+## Intent Matching, Not String Matching
+
+We use **intent matching**, not exact phrase matching.
+
+**Example description:**
+```yaml
+description: Complete blog workflow. USE WHEN user mentions doing anything with their blog, website, site, including things like update, proofread, write, edit, publish, preview, blog posts, or website pages.
+```
+
+**Key Principles:**
+- Use intent language: "user mentions", "user wants to", "including things like"
+- Don't list exact phrases in quotes
+- Cover the domain conceptually
+- Use `OR` to combine multiple trigger conditions
+
+---
+
+## Directory Structure
+
+Every skill follows this structure:
+
+```
+SkillName/                    # TitleCase directory name
+├── SKILL.md                  # Main skill file (always uppercase)
+├── ReferenceDoc.md           # Optional: Reference docs (TitleCase)
+├── tools/                    # CLI tools (ALWAYS present, even if empty)
+│   ├── ToolName.ts           # TypeScript CLI tool (TitleCase)
+│   └── ToolName.help.md      # Tool documentation (TitleCase)
+└── workflows/
+    ├── Create.md             # Work execution workflow (TitleCase)
+    └── Update.md             # Work execution workflow (TitleCase)
+```
+
+---
+
+## Workflows vs Reference Documentation
+
+**CRITICAL DISTINCTION:**
+
+### Workflows (`workflows/` directory)
+- Operational procedures (create, update, delete, deploy)
+- Step-by-step execution instructions
+- Actions that change state or produce output
+- Things you "run" or "execute"
+
+### Reference Documentation (skill root)
+- Guides and how-to documentation
+- Specifications and schemas
+- Information you "read" or "reference"
+
+---
+
+## Complete Checklist
+
+Before a skill is complete:
+
+### Naming (TitleCase)
+- [ ] Skill directory uses TitleCase
+- [ ] All workflow files use TitleCase
+- [ ] All reference docs use TitleCase
+- [ ] YAML `name:` uses TitleCase
+
+### YAML Frontmatter
+- [ ] Single-line description with embedded `USE WHEN` clause
+- [ ] No separate `triggers:` or `workflows:` arrays
+- [ ] Description under 1024 characters
+
+### Markdown Body
+- [ ] `## Workflow Routing` section with table format
+- [ ] `## Examples` section with 2-3 concrete patterns
+- [ ] All workflows have routing entries
+
+### Structure
+- [ ] `tools/` directory exists (even if empty)
+- [ ] No `backups/` directory inside skill
+- [ ] Workflows contain ONLY execution procedures
+- [ ] Reference docs live at skill root
+
+---
+
+## Summary
+
+| Component | Purpose | Naming |
+|-----------|---------|--------|
+| **Skill directory** | Contains all skill files | TitleCase (e.g., `Blogging`) |
+| **SKILL.md** | Main skill file | Always uppercase |
+| **Workflow files** | Execution procedures | TitleCase (e.g., `Create.md`) |
+| **Reference docs** | Information to read | TitleCase (e.g., `ApiReference.md`) |
+| **Tool files** | CLI automation | TitleCase (e.g., `ManageServer.ts`) |
+
+This system ensures:
+1. Skills invoke properly based on intent (USE WHEN in description)
+2. Specific functionality executes accurately (Workflow Routing in body)
+3. All skills have consistent, predictable structure
+4. **All naming follows TitleCase convention**

package/templates/skills/terminal-tabs.template.md

@@ -0,0 +1,120 @@
+<!-- Generated by PAI Setup -->
+# Terminal Tab Title System
+
+## Overview
+
+The PAI system automatically updates your terminal tab title with a 4-word summary of what was done after each task completion. This provides instant visual feedback in your terminal tabs, making it easy to see what each Claude session accomplished.
+
+## How It Works
+
+The `stop-hook.ts` hook runs after every task completion and:
+
+1. **Extracts the task summary** from the COMPLETED line in responses
+2. **Generates a 4-word title** that summarizes what was accomplished
+3. **Updates your terminal tab** using ANSI escape sequences
+
+## Features
+
+### 4-Word Summary Format
+
+The system creates meaningful 4-word summaries by:
+- Using past-tense action verbs (Created, Updated, Fixed, etc.)
+- Extracting key nouns from the task
+- Prioritizing words from the COMPLETED line when available
+- Falling back to the user's original query if needed
+
+### Examples
+
+| User Query | Tab Title |
+|------------|-----------|
+| "Update the README documentation" | Updated Readme Documentation Done |
+| "Fix the stop-hook" | Fixed Stop Hook Successfully |
+| "Research AI trends" | Researched AI Trends Complete |
+| "Implement new feature" | Implemented New Feature Done |
+
+## Terminal Compatibility
+
+The tab title system works with terminals that support OSC (Operating System Command) sequences:
+
+- **Kitty** - Full support
+- **iTerm2** - Full support
+- **Terminal.app** - Full support
+- **Alacritty** - Full support
+- **VS Code Terminal** - Full support
+
+## Implementation Details
+
+### Escape Sequences Used
+
+```bash
+# OSC 0 - Sets icon and window title
+printf '\033]0;Title Here\007'
+
+# OSC 2 - Sets window title
+printf '\033]2;Title Here\007'
+
+# OSC 30 - Kitty-specific tab title
+printf '\033]30;Title Here\007'
+```
+
+### Hook Location
+
+The terminal tab functionality is implemented in:
+```
+${PAI_DIR}/Hooks/stop-hook.ts
+```
+
+### Key Functions
+
+1. **generateTabTitle(prompt, completedLine)** - Creates the 4-word summary
+2. **setTabTitle(title)** - Sends escape sequences to update the tab
+3. **Hook execution** - Runs automatically after every task
+
+## Debugging
+
+If tab titles aren't updating:
+
+1. **Check hook is executable:**
+   ```bash
+   ls -la ${PAI_DIR}/Hooks/stop-hook.ts
+   # Should show: -rwxr-xr-x
+   ```
+
+2. **Verify Claude Code settings:**
+   - Ensure stop-hook is configured in your Claude Code settings
+   - Path should be: `${PAI_DIR}/Hooks/stop-hook.ts`
+
+3. **Test manually:**
+   ```bash
+   printf '\033]0;Test Title\007' >&2
+   ```
+
+4. **Check stderr output:**
+   The hook logs to stderr with:
+   - Tab title changes
+   - User queries processed
+   - Completed text extracted
+
+## Customization
+
+To modify the tab title behavior, edit `${PAI_DIR}/Hooks/stop-hook.ts`:
+
+- Change word count (currently 4 words)
+- Modify verb tense (currently past tense)
+- Add custom prefixes or suffixes
+- Filter different stop words
+
+## Benefits
+
+- **Visual Task Tracking** - See what each tab accomplished at a glance
+- **Multi-Session Management** - Easily identify different Claude sessions
+- **Task History** - Tab titles persist as a record of completed work
+- **No Manual Updates** - Fully automatic, runs on every task completion
+
+## Integration with Voice System
+
+The terminal tab system works alongside the voice notification system:
+- Both extract information from the COMPLETED line
+- Tab gets a 4-word visual summary
+- Voice speaks the completion message
+- Both provide immediate feedback through different channels