Skip to content

Commit 197f082

Browse files
danielmiesslerclaude
danielmiessler
and
claude
committed
fix: Address issues #259, #260, #261 - wizard clarity and pack manifests
- #259: Clarify pack installation instructions in wizard - Added explicit "ask your AI to install" guidance - Explained that packs are markdown files with embedded instructions - #260: Fix PAI_DIR/secrets consistency between wizard and packs - Wizard now creates .env file in addition to shell exports - Packs can reliably read from $PAI_DIR/.env - #261: Add What's Included section to all packs - Updated PAIPackTemplate.md with new section after Installation Prompt - Added manifest tables to all 8 packs showing files, hooks, deps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 9b822a4 commit 197f082

File tree

10 files changed

+217
-5
lines changed

10 files changed

+217
-5
lines changed

‎Bundles/Kai/install.ts‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -832,6 +832,28 @@ ${config.elevenLabsVoiceId ? `export ELEVENLABS_VOICE_ID="${config.elevenLabsVoi
832832
console.log(`ℹ PAI environment variables already exist in ${config.shellProfile}`);
833833
}
834834

835+
// Also create .env file for packs to read (fixes #260)
836+
console.log("Creating .env file for pack compatibility...");
837+
const envFileContent = `# PAI Environment Configuration
838+
# Created by Kai Bundle installer - ${new Date().toISOString().split("T")[0]}
839+
# This file is read by packs during installation
840+
841+
DA="${config.daName}"
842+
PAI_DIR="${config.paiDir}"
843+
TIME_ZONE="${config.timeZone}"
844+
${config.elevenLabsApiKey ? `ELEVENLABS_API_KEY="${config.elevenLabsApiKey}"` : "# ELEVENLABS_API_KEY="}
845+
${config.elevenLabsVoiceId ? `ELEVENLABS_VOICE_ID="${config.elevenLabsVoiceId}"` : "# ELEVENLABS_VOICE_ID="}
846+
`;
847+
await Bun.write(`${paiDir}/.env`, envFileContent);
848+
console.log(`✓ Created ${config.paiDir}/.env`);
849+
850+
// Export to current process for immediate use
851+
process.env.PAI_DIR = config.paiDir;
852+
process.env.DA = config.daName;
853+
process.env.TIME_ZONE = config.timeZone;
854+
if (config.elevenLabsApiKey) process.env.ELEVENLABS_API_KEY = config.elevenLabsApiKey;
855+
if (config.elevenLabsVoiceId) process.env.ELEVENLABS_VOICE_ID = config.elevenLabsVoiceId;
856+
835857
// Summary
836858
printHeader("INSTALLATION COMPLETE");
837859

@@ -848,11 +870,16 @@ Your Kai system is configured with:
848870
Next steps:
849871
850872
1. Reload your shell: source ${config.shellProfile}
851-
2. Install the packs in order:
852-
- kai-hook-system
853-
- kai-history-system
854-
- kai-core-install
855-
- kai-voice-system
873+
874+
2. Install the packs in order by asking your AI:
875+
- "Install kai-hook-system pack"
876+
- "Install kai-history-system pack"
877+
- "Install kai-core-install pack"
878+
- "Install kai-voice-system pack"
879+
880+
Each pack is a markdown file in Packs/. Give it to your AI
881+
and ask it to install - it contains all instructions.
882+
856883
3. Restart Claude Code to activate hooks
857884
858885
Files created:

‎Packs/kai-agents-skill.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,24 @@ Please follow the installation instructions below to integrate this pack into yo
4040

4141
---
4242

43+
## What's Included
44+
45+
| Component | File | Purpose |
46+
|-----------|------|---------|
47+
| Agents skill | `Skills/Agents/SKILL.md` | Routing and agent definitions |
48+
| Agent factory | `Skills/Agents/Tools/AgentFactory.ts` | Dynamic agent composition |
49+
| Trait definitions | `Skills/Agents/Data/Traits.yaml` | Expertise, personality, approach traits |
50+
| Voice mapping | `Skills/Agents/Data/VoiceMapping.yaml` | Personality to ElevenLabs voice mapping |
51+
| Create agent | `Skills/Agents/Workflows/CreateCustomAgent.md` | Custom agent workflow |
52+
| List traits | `Skills/Agents/Workflows/ListTraits.md` | Show available traits |
53+
54+
**Summary:**
55+
- **Files created:** 8+ (skill, tool, workflows, data)
56+
- **Hooks registered:** 0 (skill-based, not hook-based)
57+
- **Dependencies:** kai-core-install (required), kai-voice-system (optional for voice)
58+
59+
---
60+
4361
## The Concept and/or Problem
4462

4563
AI agent systems typically offer one-size-fits-all agents. You spawn "an agent" to do research, security review, or creative work - but they all have the same personality, same approach, same voice.

‎Packs/kai-art-skill.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,24 @@ Please follow the installation instructions below to integrate this pack into yo
4343

4444
---
4545

46+
## What's Included
47+
48+
| Component | File | Purpose |
49+
|-----------|------|---------|
50+
| Art skill | `Skills/Art/SKILL.md` | Routing and quick reference |
51+
| Aesthetic config | `Skills/Art/Aesthetic.md` | Style preferences and palette |
52+
| Generate tool | `Skills/Art/Tools/Generate.ts` | Multi-model image generation CLI |
53+
| Technical diagrams | `Skills/Art/Workflows/TechnicalDiagrams.md` | Architecture diagram workflow |
54+
| Essay headers | `Skills/Art/Workflows/Essay.md` | Blog header image workflow |
55+
| Comics workflow | `Skills/Art/Workflows/Comics.md` | Sequential panel generation |
56+
57+
**Summary:**
58+
- **Files created:** 8+ (skill, tool, workflows)
59+
- **Hooks registered:** 0 (skill-based, not hook-based)
60+
- **Dependencies:** kai-core-install (required), API keys for image models
61+
62+
---
63+
4664
## The Concept and/or Problem
4765

4866
AI image generation is powerful but inconsistent. Each request requires:

‎Packs/kai-core-install.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,24 @@ Please follow the installation instructions below to integrate this Pack into yo
5656

5757
---
5858

59+
## What's Included
60+
61+
| Component | File | Purpose |
62+
|-----------|------|---------|
63+
| CORE skill | `Skills/CORE/SKILL.md` | Main identity and routing hub |
64+
| Skill system docs | `Skills/CORE/SkillSystem.md` | Skill routing architecture |
65+
| Architecture tracker | `Skills/CORE/Architecture.md` | Auto-generated system status |
66+
| Architecture tool | `Tools/PaiArchitecture.ts` | Generate architecture tracking |
67+
| CreateSkill templates | `Skills/CreateSkill/` | Templates for new skills |
68+
| Identity & Principles | `Skills/CORE/Constitution.md` | 14 founding principles |
69+
70+
**Summary:**
71+
- **Files created:** 10+ (skill files, templates, tools)
72+
- **Hooks registered:** 0 (uses hook system from kai-hook-system)
73+
- **Dependencies:** kai-hook-system (required), kai-history-system (optional)
74+
75+
---
76+
5977
# PART 1: THE PROBLEM
6078

6179
## Why You Need This

‎Packs/kai-history-system.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,23 @@ Please follow the installation instructions below to integrate this pack into yo
4343

4444
---
4545

46+
## What's Included
47+
48+
| Component | File | Purpose |
49+
|-----------|------|---------|
50+
| Universal event capture | `hooks/capture-all-events.ts` | Log all events to JSONL for audit trail |
51+
| Stop hook | `hooks/stop-hook.ts` | Capture main agent completions and learnings |
52+
| Subagent stop hook | `hooks/subagent-stop-hook.ts` | Route subagent outputs by type |
53+
| Session summary | `hooks/capture-session-summary.ts` | Summarize sessions at close |
54+
| Metadata extraction lib | `hooks/lib/metadata-extraction.ts` | Extract agent instance metadata |
55+
56+
**Summary:**
57+
- **Files created:** 5 + history directory structure
58+
- **Hooks registered:** 7 (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit)
59+
- **Dependencies:** kai-hook-system (required)
60+
61+
---
62+
4663
## The Concept and/or Problem
4764
AI agents are powerful but forgetful. Each session starts fresh with no memory of:
4865

‎Packs/kai-hook-system.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,23 @@ Please follow the installation instructions below to integrate this Pack into yo
4242

4343
---
4444

45+
## What's Included
46+
47+
| Component | File | Purpose |
48+
|-----------|------|---------|
49+
| Security validator | `hooks/security-validator.ts` | Block dangerous commands before execution |
50+
| Session initializer | `hooks/initialize-session.ts` | Set up session context and markers |
51+
| Context loader | `hooks/load-core-context.ts` | Load CORE skill at session start |
52+
| Tab title updater | `hooks/update-tab-titles.ts` | Update terminal tabs with task context |
53+
| Observability lib | `hooks/lib/observability.ts` | Event logging and dashboard integration |
54+
55+
**Summary:**
56+
- **Files created:** 5
57+
- **Hooks registered:** 4 (PreToolUse, SessionStart ×2, UserPromptSubmit)
58+
- **Dependencies:** None (foundation pack)
59+
60+
---
61+
4562
## The Concept and/or Problem
4663

4764
Claude Code fires events throughout its operation, but by default nothing listens to them:

‎Packs/kai-observability-server.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,24 @@ Please follow the installation instructions below to integrate this Pack into yo
4242

4343
---
4444

45+
## What's Included
46+
47+
| Component | File | Purpose |
48+
|-----------|------|---------|
49+
| WebSocket server | `Observability/server/index.ts` | HTTP API + WebSocket streaming |
50+
| File ingestion | `Observability/server/file-ingest.ts` | Watch JSONL and stream events |
51+
| Type definitions | `Observability/server/types.ts` | TypeScript interfaces |
52+
| Vue dashboard | `Observability/dashboard/App.vue` | Real-time monitoring UI |
53+
| Event capture hook | `hooks/capture-all-events.ts` | Capture all events to JSONL |
54+
| Metadata extraction | `hooks/lib/metadata-extraction.ts` | Agent instance tracking |
55+
56+
**Summary:**
57+
- **Files created:** 8+ (server, dashboard, hooks)
58+
- **Hooks registered:** 7 (all event types via capture-all-events)
59+
- **Dependencies:** kai-hook-system (required)
60+
61+
---
62+
4563
## The Concept and/or Problem
4664

4765
When running AI agents, especially multiple agents in parallel, you're flying blind:

‎Packs/kai-prompting-skill.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,27 @@ Please follow the installation instructions below to integrate this Pack into yo
4949

5050
---
5151

52+
## What's Included
53+
54+
| Component | File | Purpose |
55+
|-----------|------|---------|
56+
| Prompting skill | `Skills/Prompting/SKILL.md` | Routing and quick reference |
57+
| Standards guide | `Skills/Prompting/Standards.md` | Claude 4.x best practices |
58+
| Roster template | `Skills/Prompting/Templates/Primitives/Roster.hbs` | Agent/skill definitions |
59+
| Voice template | `Skills/Prompting/Templates/Primitives/Voice.hbs` | Personality calibration |
60+
| Structure template | `Skills/Prompting/Templates/Primitives/Structure.hbs` | Workflow patterns |
61+
| Briefing template | `Skills/Prompting/Templates/Primitives/Briefing.hbs` | Agent context handoff |
62+
| Gate template | `Skills/Prompting/Templates/Primitives/Gate.hbs` | Validation checklists |
63+
| Render tool | `Skills/Prompting/Tools/RenderTemplate.ts` | Template rendering CLI |
64+
| Validate tool | `Skills/Prompting/Tools/ValidateTemplate.ts` | Template validation |
65+
66+
**Summary:**
67+
- **Files created:** 12+ (skill, standards, templates, tools)
68+
- **Hooks registered:** 0 (skill-based, not hook-based)
69+
- **Dependencies:** kai-core-install (required)
70+
71+
---
72+
5273
# PART 1: THE PROBLEM
5374

5475
## Why You Need This

‎Packs/kai-voice-system.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,24 @@ Please follow the installation instructions below to integrate this Pack into yo
4545

4646
---
4747

48+
## What's Included
49+
50+
| Component | File | Purpose |
51+
|-----------|------|---------|
52+
| Voice stop hook | `hooks/stop-hook-voice.ts` | Main agent voice notification |
53+
| Subagent voice hook | `hooks/subagent-stop-hook-voice.ts` | Subagent voice notification |
54+
| Prosody enhancer | `hooks/lib/prosody-enhancer.ts` | Add emotion/pauses to speech |
55+
| Voice server | `voice/server.ts` | HTTP server for TTS requests |
56+
| Server management | `voice/manage.sh` | Start/stop/restart server |
57+
| LaunchAgent | `com.pai.voice-server.plist` | Auto-start on login (macOS) |
58+
59+
**Summary:**
60+
- **Files created:** 6
61+
- **Hooks registered:** 2 (Stop, SubagentStop)
62+
- **Dependencies:** kai-hook-system (required), kai-core-install (required), ElevenLabs API key
63+
64+
---
65+
4866
## The Concept and/or Problem
4967

5068
AI agents complete work constantly, but you only know if you're watching the screen:

‎Tools/PAIPackTemplate.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,45 @@ Please follow the installation instructions below to integrate this pack into yo
196196

197197
---
198198

199+
## What's Included
200+
<!--
201+
(256 words max)
202+
203+
INSTRUCTIONS FOR AI: Provide a quick manifest of what this pack creates.
204+
This gives users an at-a-glance summary of the pack's contents BEFORE
205+
they commit to installation.
206+
207+
Include:
208+
- A table with Component | File | Purpose columns
209+
- Summary counts: Files created, Hooks registered, Dependencies
210+
- This section is REQUIRED for all packs
211+
212+
Example:
213+
| Component | File | Purpose |
214+
|-----------|------|---------|
215+
| Session initializer | `hooks/initialize-session.ts` | Sets up session context |
216+
| Security validator | `hooks/security-validator.ts` | Blocks dangerous commands |
217+
| Observability lib | `hooks/lib/observability.ts` | Event logging to dashboard |
218+
219+
**Summary:**
220+
- **Files created:** 3
221+
- **Hooks registered:** 2
222+
- **Dependencies:** kai-hook-system (required)
223+
-->
224+
225+
| Component | File | Purpose |
226+
|-----------|------|---------|
227+
| [Component 1] | `path/to/file1.ts` | [What it does] |
228+
| [Component 2] | `path/to/file2.ts` | [What it does] |
229+
| [Library 1] | `hooks/lib/library.ts` | [Shared functionality] |
230+
231+
**Summary:**
232+
- **Files created:** [N]
233+
- **Hooks registered:** [N]
234+
- **Dependencies:** [List or "None"]
235+
236+
---
237+
199238
## The Concept and/or Problem
200239
<!--
201240
(2048 words max)
@@ -1032,6 +1071,7 @@ Format: ### {version} - {YYYY-MM-DD}
10321071
| Section | Word Limit | Purpose |
10331072
|---------|------------|---------|
10341073
| `## Installation Prompt` | 512 | Context briefing for receiving AI |
1074+
| `## What's Included` | 256 | Quick manifest of pack contents |
10351075
| `## The Concept and/or Problem` | 2048 | What problem does this solve? |
10361076
| `## The Solution` | 4096 | How does this pack solve it? |
10371077
| `## Why This Is Different` | 128 | Differentiation from similar solutions |

0 commit comments

Comments
 (0)