@tekmidian/pai 0.3.1 → 0.4.0

package/src/hooks/ts/user-prompt/update-tab-titles.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Tab Title Update Hook
+ * Updates tab title based on user prompt
+ *
+ * Note: All context loading handled by PAI skill system (core identity in skill description, full context in SKILL.md)
+ */
+
+import { execSync } from 'child_process';
+
+interface HookInput {
+  session_id: string;
+  prompt: string;
+  transcript_path: string;
+  hook_event_name: string;
+}
+
+/**
+ * Read stdin with timeout
+ */
+async function readStdinWithTimeout(timeout: number = 5000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    const timer = setTimeout(() => {
+      reject(new Error('Timeout reading from stdin'));
+    }, timeout);
+
+    process.stdin.on('data', (chunk) => {
+      data += chunk.toString();
+    });
+
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+
+    process.stdin.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+async function main() {
+  try {
+    // Read the hook input from stdin
+    const input = await readStdinWithTimeout();
+    const data: HookInput = JSON.parse(input);
+
+    const prompt = data.prompt || '';
+
+    // UPDATE TAB TITLE
+    // Generate quick fallback tab title
+    let tabTitle = 'Processing request...';
+    if (prompt) {
+      const words = prompt.replace(/[^\w\s]/g, ' ').trim().split(/\s+/)
+        .filter(w => w.length > 2 && !['the', 'and', 'but', 'for', 'are', 'with', 'you', 'can'].includes(w.toLowerCase()))
+        .slice(0, 3);
+
+      if (words.length > 0) {
+        tabTitle = words[0].charAt(0).toUpperCase() + words[0].slice(1).toLowerCase();
+        if (words.length > 1) {
+          tabTitle += ' ' + words.slice(1).map(w => w.toLowerCase()).join(' ');
+        }
+        tabTitle += '...';
+      }
+    }
+
+    // Set initial tab title with recycle emoji
+    try {
+      const titleWithEmoji = '♻️ ' + tabTitle;
+      const escapedTitle = titleWithEmoji.replace(/'/g, "'\\''");
+      execSync(`printf '\\033]0;${escapedTitle}\\007' >&2`);
+      execSync(`printf '\\033]2;${escapedTitle}\\007' >&2`);
+      execSync(`printf '\\033]30;${escapedTitle}\\007' >&2`);
+    } catch (e) {
+      // Silently fail
+    }
+
+    process.exit(0);
+  } catch (error) {
+    // Silently fail to not interrupt Claude's flow
+    console.error('Tab title update error:', error);
+    process.exit(0);
+  }
+}
+
+main();

package/tab-color-command.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# PAI Tab Color State Manager
+# Sets iTerm2 tab background color based on Claude Code session state.
+# Silently exits on non-iTerm2 terminals.
+#
+# Usage: tab-color-command.sh <state>
+# States: working, completed, awaiting, error, active, reset
+
+[[ -z "$ITERM_SESSION_ID" ]] && exit 0
+
+set_color() {
+    printf '\033]6;1;bg;red;brightness;%d\a' "$1"
+    printf '\033]6;1;bg;green;brightness;%d\a' "$2"
+    printf '\033]6;1;bg;blue;brightness;%d\a' "$3"
+}
+
+case "${1:-reset}" in
+    working|processing)  set_color 255 158 100 ;;  # Orange
+    completed|done)      set_color 158 206 106 ;;  # Green
+    awaiting|input)      set_color 125 207 255 ;;  # Cyan/Teal
+    error|failed)        set_color 247 118 142 ;;  # Red
+    active)              set_color 122 162 247 ;;  # Blue
+    reset|*)             printf '\033]6;1;bg;*;default\a' ;;
+esac

package/templates/ai-steering-rules.template.md

@@ -0,0 +1,58 @@
+---
+name: AI Steering Rules
+description: Universal behavioral rules for AI assistants. Loaded at startup to enforce quality standards.
+---
+
+<!-- Generated by PAI Setup -->
+
+# AI Steering Rules
+
+These rules apply to ALL responses, ALL tasks, ALL contexts. They are non-negotiable.
+
+## Surgical Fixes Only
+
+- Make every change as simple as possible
+- Impact minimal code — don't refactor unrelated areas
+- The best solution is often the simplest one
+
+## Never Assert Without Verification
+
+- Don't claim something works without proving it
+- Run tests, check logs, demonstrate correctness
+- "I believe this should work" is not verification
+
+## One Change When Debugging
+
+- Change ONE thing at a time when debugging
+- Verify after each change before moving on
+- If you change three things and it works, you don't know which fixed it
+
+## Read Before Modifying
+
+- Always read a file before editing it
+- Understand existing patterns before suggesting changes
+- Never propose changes to code you haven't seen
+
+## Find Root Causes
+
+- No temporary fixes, no workarounds, no "good enough for now"
+- If a fix feels hacky, stop and find the elegant solution
+- Treat symptoms only as diagnostic clues, not as things to patch
+
+## Prove It Works
+
+- For bug fixes: show the error before, show it fixed after
+- For features: demonstrate end-to-end functionality
+- For refactors: prove behavior is unchanged
+
+## Don't Over-Engineer
+
+- Only make changes that are directly requested or clearly necessary
+- Don't add features, refactor code, or make "improvements" beyond what was asked
+- Three similar lines of code is better than a premature abstraction
+
+## Fail Honestly
+
+- Say "I don't know" when you don't know
+- Mark unverified claims explicitly
+- Fabricating an answer is worse than admitting uncertainty

package/templates/pai-skill.template.md

@@ -374,6 +374,30 @@ Bulk/repetitive work consumes context. Delegate it to conserve your main convers
 
 ---
 
+## TIME BUDGET AWARENESS (Always Active)
+
+**Estimate effort tier BEFORE starting work, then stay within budget.**
+
+| Tier | Budget | When |
+|------|--------|------|
+| **Quick** | < 2 min | Simple lookups, one-line fixes, direct answers |
+| **Standard** | < 5 min | Single-file changes, focused research, one feature |
+| **Extended** | < 15 min | Multi-file changes, moderate research, debugging |
+| **Deep** | < 45 min | Architecture work, complex debugging, large features |
+| **Comprehensive** | < 120 min | Major refactors, full implementations, deep research |
+
+### Rules
+
+1. **Estimate at start:** Before beginning work, classify the effort tier and announce it: "This is a Standard task (~5 min)."
+2. **Check at midpoint:** If you've used > 50% of the budget and aren't > 50% done, reassess.
+3. **Compress if over budget:** If elapsed > 150% of budget, simplify the approach:
+   - Drop nice-to-haves, focus on core requirement
+   - Use existing patterns instead of novel solutions
+   - Deliver partial result with clear "what's left" summary
+4. **Never silently overrun:** If a task needs more time than budgeted, say so: "This is taking longer than expected. The Quick fix became Extended because [reason]. Continuing."
+
+---
+
 ## STACK PREFERENCES (Always Active)
 
 - **TypeScript > Python** — Use TypeScript unless explicitly told otherwise

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

@@ -0,0 +1,78 @@
+<!-- Generated by PAI Setup -->
+---
+name: Createskill
+description: MANDATORY skill creation framework for ALL skill creation requests. USE WHEN user wants to create, validate, update, or canonicalize a skill, OR user mentions skill creation, skill development, new skill, build skill, OR user references skill compliance, skill structure, or skill architecture.
+---
+
+# Createskill
+
+MANDATORY skill creation framework for ALL skill creation requests.
+
+## Authoritative Source
+
+**Before creating ANY skill, READ:** `${PAI_DIR}/skills/CORE/SkillSystem.md`
+
+**Canonical example to follow:** Look at existing skills in `~/.claude/skills/` for structure reference.
+
+## TitleCase Naming Convention
+
+**All naming must use TitleCase (PascalCase).**
+
+| Component | Format | Example |
+|-----------|--------|---------|
+| Skill directory | TitleCase | `Blogging`, `Daemon`, `CreateSkill` |
+| Workflow files | TitleCase.md | `Create.md`, `UpdateDaemonInfo.md` |
+| Reference docs | TitleCase.md | `ProsodyGuide.md`, `ApiReference.md` |
+| Tool files | TitleCase.ts | `ManageServer.ts` |
+| Help files | TitleCase.help.md | `ManageServer.help.md` |
+
+**Wrong (NEVER use):**
+- `createskill`, `create-skill`, `CREATE_SKILL`
+- `create.md`, `update-info.md`, `SYNC_REPO.md`
+
+## Workflow Routing
+
+**When executing a workflow, output this notification directly:**
+
+```
+Running the **WorkflowName** workflow from the **Createskill** skill...
+```
+
+| Workflow | Trigger | File |
+|----------|---------|------|
+| **CreateSkill** | "create a new skill" | `workflows/CreateSkill.md` |
+| **ValidateSkill** | "validate skill", "check skill" | `workflows/ValidateSkill.md` |
+| **UpdateSkill** | "update skill", "add workflow" | `workflows/UpdateSkill.md` |
+| **CanonicalizeSkill** | "canonicalize", "fix skill structure" | `workflows/CanonicalizeSkill.md` |
+
+## Examples
+
+**Example 1: Create a new skill from scratch**
+```
+User: "Create a skill for managing my recipes"
+→ Invokes CreateSkill workflow
+→ Reads SkillSystem.md for structure requirements
+→ Creates skill directory with TitleCase naming
+→ Creates SKILL.md, workflows/, tools/
+→ Generates USE WHEN triggers based on intent
+```
+
+**Example 2: Fix an existing skill that's not routing properly**
+```
+User: "The research skill isn't triggering - validate it"
+→ Invokes ValidateSkill workflow
+→ Checks SKILL.md against canonical format
+→ Verifies TitleCase naming throughout
+→ Verifies USE WHEN triggers are intent-based
+→ Reports compliance issues with fixes
+```
+
+**Example 3: Canonicalize a skill with old naming**
+```
+User: "Canonicalize the daemon skill"
+→ Invokes CanonicalizeSkill workflow
+→ Renames workflow files to TitleCase
+→ Updates routing table to match
+→ Ensures Examples section exists
+→ Verifies all checklist items
+```

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

@@ -0,0 +1,371 @@
+<!-- Generated by PAI Setup -->
+# Universal Output Capture System (UOCS) - History System Documentation
+
+**Location:** `${PAI_DIR}/History/`
+**Purpose:** Automated documentation of ALL work performed by PAI and specialized agents
+**Status:** Configure during `pai setup`
+
+---
+
+## Overview
+
+The Universal Output Capture System (UOCS) is PAI's automatic memory - capturing every feature, bug fix, decision, learning, research, and session through hooks with **zero manual effort**.
+
+**Core Principle:** Work normally, documentation handles itself.
+
+---
+
+## Quick Reference
+
+This file is the **complete reference** for the history system. All specifications, conventions, and usage patterns are documented below.
+
+---
+
+## Directory Structure
+
+```
+${PAI_DIR}/History/
+├── Sessions/YYYY-MM/          # Session summaries (SessionEnd hook)
+├── Learnings/YYYY-MM/         # Problem-solving narratives (Stop hook + manual)
+├── Research/YYYY-MM/          # Investigation reports (Researcher agents)
+├── Decisions/YYYY-MM/         # Architectural decisions (Architect agent)
+├── Execution/
+│   ├── Features/YYYY-MM/      # Feature implementations (Engineer/Designer)
+│   ├── Bugs/YYYY-MM/          # Bug fixes (Engineer)
+│   └── Refactors/YYYY-MM/     # Code improvements (Engineer)
+└── Raw-Outputs/YYYY-MM/       # JSONL logs (PostToolUse hook)
+```
+
+**Quick Decision Guide:**
+- "What happened this session?" → `Sessions/`
+- "What did we learn?" → `Learnings/`
+- "What features were built?" → `Execution/Features/`
+- "What broke and when?" → `Execution/Bugs/`
+- "What was improved?" → `Execution/Refactors/`
+- "Why this approach?" → `Decisions/`
+- "What did we investigate?" → `Research/`
+- "Raw execution logs?" → `Raw-Outputs/`
+
+---
+
+## Project Session Storage
+
+**Location:** `${PAI_DIR}/projects/{encoded-path}/`
+
+Claude Code stores session transcripts per-project. PAI organizes these with a clean structure:
+
+```
+${PAI_DIR}/projects/{encoded-path}/
+├── sessions/                    # Session transcripts (auto-organized)
+│   ├── {uuid}.jsonl            # Main session transcripts
+│   └── agent-*.jsonl           # Subagent transcripts
+├── Notes/                       # Session notes (PAI extension)
+│   └── NNNN_YYYY-MM-DD_desc.md
+└── TODO.md                      # Project task tracking
+```
+
+**Path Encoding:** Directory paths are encoded by replacing `/` and `.` with `-`
+- `/Users/you/Projects/myapp` → `-Users-you-Projects-myapp`
+
+**Session File Lifecycle:**
+1. **During session:** Claude Code writes `.jsonl` to project root
+2. **On UserPromptSubmit:** Cleanup hook moves stray files from previous sessions
+3. **On Stop:** `stop-hook.ts` moves current session files to `sessions/`
+4. **On SessionStart:** Context loader creates structure and migrates any stragglers
+
+**Key Files:**
+- `{uuid}.jsonl` - Full conversation transcript with token usage
+- `agent-*.jsonl` - Subagent (Task tool) transcripts
+- `Notes/*.md` - Human-readable session summaries
+- `TODO.md` - Synced from TodoWrite tool
+
+---
+
+## File Naming Convention
+
+**Unified format:**
+```
+YYYY-MM-DD-HHMMSS_[PROJECT]_[TYPE]_[HIERARCHY]_[DESCRIPTION].md
+```
+
+**Components:**
+- **Timestamp:** `YYYY-MM-DD-HHMMSS` - Enables chronological sorting
+- **Project:** Optional identifier (e.g., `dashboard`, `website`, `PAI`)
+- **Type:** Mandatory classification
+  - `FEATURE` - New functionality
+  - `BUG` - Bug fix
+  - `REFACTOR` - Code improvement
+  - `RESEARCH` - Investigation
+  - `DECISION` - Architectural decision
+  - `LEARNING` - Problem-solving narrative
+  - `SESSION` - Session summary
+- **Hierarchy:** Optional task number (e.g., `T1.2.3`)
+- **Description:** Kebab-case, max 60 chars
+
+**Examples:**
+```
+2025-10-13-140000_dashboard_FEATURE_T1.1_database-schema-setup.md
+2025-10-13-153000_dashboard_BUG_T1.2_jwt-expiry-validation.md
+2025-10-13-092000_PAI_DECISION_unified-capture-architecture.md
+2025-10-13-083000_LEARNING_kitty-remote-control-api.md
+2025-10-13-180000_SESSION_feature-implementation-day-1.md
+```
+
+---
+
+## Hook Integration
+
+### 1. PostToolUse Hook
+**Triggers:** Every tool execution (Bash, Edit, Write, Read, Task, etc.)
+**Implementation:** `${PAI_DIR}/Hooks/capture-all-events.ts --event-type PostToolUse`
+**Output:** Daily JSONL logs in `Raw-Outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl`
+**Purpose:** Raw execution data for forensics and analytics
+
+**Key Feature:** Completely generic - captures ENTIRE payload automatically
+- **Future-proof**: New fields added to hooks are automatically captured
+- No code updates needed when Claude Code adds new fields
+
+### 2. Stop Hook
+**Triggers:** Main agent task completion
+**Implementation:** `${PAI_DIR}/Hooks/stop-hook.ts`
+**Output:** Auto-captured files in `Learnings/` or `Sessions/` based on content
+**Purpose:** Lightweight capture of work summaries and learning moments
+
+**How it works:**
+1. Extracts structured response format sections
+2. Analyzes for learning indicators (problem, solved, discovered, fixed)
+3. Categorizes as LEARNING (2+ indicators) or WORK (general session)
+4. Generates appropriate filename and saves to history
+
+### 3. SubagentStop Hook
+**Triggers:** Specialized agent task completion
+**Implementation:** `${PAI_DIR}/Hooks/subagent-stop-hook.ts`
+**Output:** Categorized documents in appropriate directories
+**Purpose:** Organized work documentation by agent type
+
+**Categorization Logic:**
+- Architect → `Decisions/` (DECISION)
+- Engineer/Principal-Engineer → `Execution/Features|Bugs|Refactors/`
+- Designer → `Execution/Features/` (FEATURE)
+- Researchers (all types) → `Research/` (RESEARCH)
+- Pentester → `Research/` (RESEARCH)
+- Intern → `Research/` (mixed - defaults to RESEARCH)
+
+### 4. SessionEnd Hook
+**Triggers:** Session exit (when you quit Claude Code)
+**Implementation:** `${PAI_DIR}/Hooks/capture-session-summary.ts`
+**Output:** Session summary in `Sessions/YYYY-MM/`
+**Purpose:** High-level session documentation
+
+### 5. SessionStart Hook
+**Triggers:** Session initialization (when you start Claude Code)
+**Implementation:** `${PAI_DIR}/Hooks/initialize-pai-session.ts`
+**Purpose:** Load core context and prepare session environment
+
+---
+
+## Custom Slash Commands
+
+### /search-history [query]
+**Purpose:** Full-text search across all history
+**Example:** `/search-history authentication bug`
+**Implementation:** Uses ripgrep with context lines
+
+### /show-project-history [project]
+**Purpose:** Chronological timeline for project
+**Example:** `/show-project-history dashboard`
+**Output:** Most recent 30 files for project
+
+### /trace-feature [task-number]
+**Purpose:** Complete implementation history for task
+**Example:** `/trace-feature T1.2`
+**Output:** Features, bugs, refactors related to task
+
+### /bug-timeline [feature]
+**Purpose:** Bug introduction and fix timeline
+**Example:** `/bug-timeline authentication`
+**Output:** Chronological list of related bugs
+
+---
+
+## Metadata Schema
+
+Every capture file includes YAML frontmatter:
+
+```yaml
+---
+# Core classification
+capture_type: FEATURE|BUG|REFACTOR|RESEARCH|DECISION|LEARNING|SESSION
+timestamp: 2025-10-13T14:30:22-07:00
+duration_minutes: 45
+
+# Context
+project: dashboard
+executor: main|architect|engineer|designer|researcher
+session_id: uuid
+
+# Development tracking (when applicable)
+hierarchy: T1.2.3
+spec_kit_feature: 001-user-authentication
+spec_kit_task: T005
+user_story: US1
+phase: 2
+
+# Technical details
+files_changed:
+  - path/to/file.ts
+technologies:
+  - TypeScript
+  - Vitest
+
+# Outcomes
+status: completed|blocked|partial
+tests_added: 12
+tests_passing: 12
+coverage_change: +5.2%
+
+# Bug tracking (for bugs only)
+bug_severity: critical|high|medium|low
+bug_introduced_by: T1.1
+
+# Relationships
+related_to:
+  - other-capture-file.md
+depends_on:
+  - prerequisite-file.md
+
+# Searchability
+tags:
+  - authentication
+keywords:
+  - user model
+---
+```
+
+---
+
+## Common Usage Patterns
+
+### Before Starting Work
+
+```bash
+# Has this been done before?
+/search-history [feature-name]
+
+# What decisions were made about this?
+ls ${PAI_DIR}/History/Decisions/*/[project]_*
+
+# What did we learn about this domain?
+/search-history [domain-term]
+```
+
+### During Development
+
+**No action required** - work normally, everything captured automatically.
+
+### After Encountering Issues
+
+```bash
+# When did this break?
+/bug-timeline [feature-name]
+
+# Complete history of this feature
+/trace-feature T1.2.3
+
+# What similar bugs have we fixed?
+/search-history "[bug description]"
+```
+
+### Periodic Review
+
+```bash
+# What did we accomplish this week?
+ls -lt ${PAI_DIR}/History/Sessions/$(date +%Y-%m)/ | head -7
+
+# All decisions made this month
+ls ${PAI_DIR}/History/Decisions/$(date +%Y-%m)/
+
+# Learnings from this quarter
+ls ${PAI_DIR}/History/Learnings/$(date +%Y-%m)/
+```
+
+---
+
+## Advanced Queries
+
+### Find all features for project
+```bash
+find ${PAI_DIR}/History/Execution/Features -name "*_dashboard_*"
+```
+
+### Find bugs introduced in specific task
+```bash
+rg "bug_introduced_by: T1.2" ${PAI_DIR}/History/Execution/Bugs/
+```
+
+### Find all work from specific date
+```bash
+find ${PAI_DIR}/History -name "$(date +%Y-%m-%d)-*"
+```
+
+### Analyze tool usage patterns
+```bash
+cat ${PAI_DIR}/History/Raw-Outputs/$(date +%Y-%m)/*.jsonl | \
+  jq -r '.tool' | sort | uniq -c | sort -rn
+```
+
+### Extract all architectural decisions
+```bash
+find ${PAI_DIR}/History/Decisions -name "*.md" | \
+  xargs grep -l "Alternatives considered"
+```
+
+---
+
+## Benefits
+
+- **Root Cause Analysis** - "When did we break this?" instantly answerable
+- **Decision Tracking** - Every architectural choice preserved with rationale
+- **Learning Accumulation** - Problem-solving patterns captured and queryable
+- **Process Improvement** - Complete history enables identifying bottlenecks
+- **Knowledge Harvesting** - Past solutions easily found and reused
+- **Zero Overhead** - Completely automated capture
+
+---
+
+## Maintenance
+
+### Automated (No Action Required)
+- Hooks capture all work automatically
+- Files created with proper naming
+- Metadata populated by hooks
+- Categorization handled by hook logic
+
+### Manual (Periodic)
+
+**Monthly:**
+- Review directory sizes
+- Archive older months if getting large (>1000 files/month)
+- Validate hook functionality
+
+**Quarterly:**
+- Extract common learnings into best practices
+- Analyze bug patterns for process improvements
+- Review categorization accuracy
+
+---
+
+## Routing Triggers
+
+**Load this documentation when the user says:**
+- "history system" or "UOCS"
+- "how does capture work" or "automatic documentation"
+- "where are sessions saved" or "history directory"
+- "how to search history" or "find past work"
+- "SubagentStop hook" or "capture hooks"
+- "learning capture" or "session summaries"
+- Questions about file organization in History/
+
+---
+
+**This is the memory of your AI infrastructure - it remembers everything so you don't have to.**