@stella-studio/ck 1.0.0

package/docs/journals/251106135700-wrong-about-agent-skills.md

@@ -0,0 +1,184 @@
+# I was wrong about Agent Skills and how I refactor them
+
+**Date**: 2025-11-06 13:57
+**Severity**: Medium
+**Component**: Agent Skills System
+**Status**: Resolved
+
+## What Happened
+
+Agent Skills dropped October 16th. I started building them immediately. Within two weeks, I had a `cloudflare` skill at 1,131 lines, a `shadcn-ui` skill at 850 lines, and a `nextjs` skill at 900 lines, `chrome-devtools` skill with >1,200 lines. 
+
+My repo quickly got **400+ stars**.
+
+But...
+
+Every time Claude Code activated multiple related skills, I'd see context window grows dramatically. Loading 5-7 skills meant 5,000-7,000 lines flooding the context window immediately.
+
+I thought this was just how it had to be. 
+Put everything in one giant `SKILL.md` file so the agent has all the information upfront. 
+More information = better results, right?
+
+**Wrong.**
+
+--
+
+## The Brutal Truth
+
+This is embarrassing because the solution was staring me in the face the whole time. **I was treating agent skills like documentation dumps** instead of what they actually are: **context engineering problems**.
+
+The frustrating part is that I even documented the "progressive disclosure" principle in the `skill-creator` skill itself. 
+
+> *I wrote it down.* 
+> *I just didn't understand what it actually meant in practice.*
+
+Here's what really pisses me off: I wasted two weeks debugging "context growing" issues and slow activation times when the problem was entirely self-inflicted. Every single one of those massive `SKILL.md` files was **loading irrelevant information 90% of the time**.
+
+--
+
+## Technical Details
+
+### Before: The Disaster
+
+```
+.claude/skills/
+├── cloudflare/           1,131 lines
+├── cloudflare-workers/   ~800 lines
+├── nextjs/               ~900 lines
+├── shadcn-ui/            ~850 lines
+├── chrome-devtools/      ~1,200 lines
+└── (30 more similarly bloated files)
+```
+
+**Total**: ~15,000 lines across 36 skills (Approximately 120K to 300K tokens)
+
+**Problem**: Activating the `devops` context (Cloudflare or Docker or GCloud continuously) meant loading 2,500+ lines immediately. Most of it was never used.
+
+### After: Progressive Disclosure Architecture
+
+I refactored using a 3-tier loading system:
+
+**Tier 1: Metadata (always loaded)**
+- YAML frontmatter only
+- ~100 words
+- Just enough for Claude to decide if the skill is relevant
+
+**Tier 2: `SKILL.md` entry point (loaded when skill activates)**
+- ~200 lines max
+- Overview, quick start, navigation map
+- Points to references but doesn't include their content
+
+**Tier 3: Reference files & scripts (loaded on-demand)**
+- 200-300 lines each
+- Detailed documentation Claude reads only when needed
+- Modular and focused on single topics
+
+### The Numbers
+
+**claude-code skill refactor:**
+- Before: 870 lines in one file
+- After: 181 lines + 13 reference files
+- **Reduction: 79%** (4.8x better token efficiency)
+
+**Complete Phase 1 & 2 reorganization:**
+- Before: 15,000 lines across 36 individual skills
+- After: Consolidated into 20 focused skill groups (2,200 lines initial load + 45 reference files)
+  - `devops` (Cloudflare, Docker, GCloud - 14 tools)
+  - `web-frameworks` (Next.js, Turborepo, RemixIcon)
+  - `ui-styling` (shadcn/ui, Tailwind, canvas-design)
+  - `databases` (MongoDB, PostgreSQL)
+  - `ai-multimodal` (Gemini API - 5 modalities)
+  - `media-processing` (FFmpeg, ImageMagick)
+  - `chrome-devtools`, `code-review`, `sequential-thinking`, `docs-seeker`, `mcp-builder`,...
+- **Reduction: 85%** on initial activation
+
+**Real impact:**
+- Activation time: ~500ms → <100ms
+- Context overflow: Fast → Slow
+- Relevant information ratio: ~10% → ~90%
+
+--
+
+## Root Cause Analysis
+
+The fundamental mistake: **I confused "available information" with "loaded information".**
+
+But again, there's a deeper misunderstanding: **Agent skills aren't documentation.**
+
+They're **specific abilities and knowledge for development workflows**. Each skill represents a capability:
+- `devops` isn't "Cloudflare documentation" - it's the ability to deploy serverless functions
+- `ui-styling` isn't "Tailwind docs" - it's the ability to design consistent interfaces
+- `sequential-thinking` isn't a guide - it's a problem-solving methodology
+
+I had 36 individual skills because I treated each tool as needing its own documentation dump. Wrong. Skills should be organized by **workflow capabilities**, not by tools.
+
+That's why consolidation worked:
+- 36 tool-specific skills → 20 workflow-capability groups
+- "Here's everything about Cloudflare" → "Here's how to handle DevOps deployment with Cloudflare, GCloud, Docker, Vercel."
+- Documentation mindset → Development workflow mindset
+
+The 200-line limit isn't arbitrary. It's based on how much context an LLM can efficiently scan to decide what to load next. 
+Keep the entry point under ~200 lines, and Claude can quickly:
+- Understand what the skill offers
+- Decide which reference file to read
+- Load just that file (another ~200-300 lines)
+
+Total: 400-700 lines of highly relevant context instead of 1,131 lines of mixed relevance.
+
+**This is context engineering 101 and I somehow missed it.**
+
+---
+
+## Lessons Learned
+
+1. **The 200-line rule matters** - It's not a suggestion. It's the difference between fast navigation and context sludge.
+
+2. **Progressive disclosure isn't optional** - Every skill over 200 lines should be refactored. No exceptions. If you can't fit the core instructions in 200 lines, you're putting too much in the entry point.
+
+3. **References are first-class citizens** - I treated `references/` as "optional extra documentation." Wrong. References are where the real work happens. SKILL.md is just the map.
+
+4. **Test the cold start** - Clear your context, activate the skill, and measure. If it loads more than 500 lines on first activation, you're doing it wrong.
+
+5. **Metrics don't lie** - 4.8x token efficiency isn't marginal improvement. It's the difference between "works sometimes" and "works reliably."
+
+The pattern is validated.
+
+---
+
+## In conclusion
+
+**Skills ≠ Documentation**
+
+Skills are capabilities that activate during specific workflow moments:
+- Writing tests → activate `code-review`
+- Debugging production → activate `sequential-thinking`
+- Deploying infrastructure → activate `devops`
+- Building UI → activate `ui-styling` + `web-frameworks`
+
+Each skill teaches Claude *how to perform a specific development task*, not *what a tool does*.
+
+That's why treating them like documentation failed. 
+Documentation is passive reference material. 
+**Skills are active workflow knowledge.**
+
+Progressive disclosure works because it matches how development actually happens:
+1. Scan metadata → Is this capability relevant to current task?
+2. Read entry point → What workflow patterns does this enable?
+3. Load specific reference → Get implementation details for current step
+
+Each step is small, focused, and purposeful. 
+That's how you build skills that actually help instead of overwhelming.
+
+---
+
+The painful part isn't that I got it wrong initially—Agent Skills are brand new (3 weeks old). 
+The painful part is that I documented the solution myself without understanding it.
+
+Two weeks of confusion. 
+One weekend of refactoring.
+
+Lesson learned: **context engineering isn't about loading more information. It's about loading the right information at the right time.**
+
+If you want to see the repo, check this out:
+- Before (`v1` branch): https://github.com/mrgoonie/claudekit-skills/tree/v1
+- After (`main` branch): https://github.com/mrgoonie/claudekit-skills/tree/main

package/docs/journals/251212-ck-name-pattern-refactor.md

@@ -0,0 +1,70 @@
+# CK_NAME_PATTERN Refactor: Breaking 30+ Files for DRY
+
+**Date**: 2025-12-12 18:50
+**Severity**: High
+**Component**: File naming system across agents and commands
+**Status**: Resolved
+
+## What Happened
+
+We just completed a major refactor to centralize file naming patterns through the CK_NAME_PATTERN environment variable. This changed how 29 agent and command files handle naming, replacing hardcoded patterns with a centralized system.
+
+## The Brutal Truth
+
+This was absolutely maddening to implement. The codebase had naming patterns scattered across 30+ files, each with their own slightly different interpretation of how dates and slugs should be formatted. The real kick in the teeth is that we let this technical debt accumulate for so long - every new agent or command was copy-pasting the same naming logic, creating a maintenance nightmare waiting to explode.
+
+## Technical Details
+
+### The Problem
+- 13 agent files and 16 command files had hardcoded naming patterns
+- Each used different date format references: `{date}`, `YYMMDD`, `$CK_PLAN_DATE_FORMAT`
+- Inconsistent slug handling: some used `{slug}`, others implied it
+- The journal-writer agent had: `filename format: {date}-title-of-the-journal.md`
+- Plan commands had: `plans/{date}-plan-name` with date format from `$CK_PLAN_DATE_FORMAT`
+
+### The Solution
+- Added `formatDate()` and `resolveNamingPattern()` functions to session-init.cjs hook
+- Hook now computes resolved pattern at startup, keeping `{slug}` as placeholder
+- Set `CK_NAME_PATTERN` environment variable with format like "251212-1830-GH-88-{slug}"
+- Updated all 29 files to use `$CK_NAME_PATTERN` instead of their own patterns
+
+### Key Changes
+```javascript
+// Before in multiple files:
+`plans/{date}-plan-name` // with date format from $CK_PLAN_DATE_FORMAT
+`./docs/journals/{date}-title-of-the-journal.md`
+
+// After in all files:
+`plans/$CK_NAME_PATTERN`
+`./docs/journals/$CK_NAME_PATTERN.md`
+```
+
+## What We Tried
+
+1. **Initial approach**: Tried to update files manually with find/replace - failed because patterns were too inconsistent
+2. **Scripted approach**: Had to write custom logic in session-init.cjs to handle date formatting and issue extraction
+3. **Gradual migration**: Considered updating piecemeal but realized it would break consistency during transition
+
+## Root Cause Analysis
+
+This happened because of three fundamental failures:
+1. **No centralization**: When the first agent was created, we copy-pasted the naming logic instead of centralizing it
+2. **YAGNI violation**: We said "we'll centralize later" but never did
+3. **Documentation drift**: The CLAUDE.md file even had misleading references to `.ck.json` that weren't accurate
+
+The real mistake was treating naming as an implementation detail rather than a system-wide convention that needed to be enforced.
+
+## Lessons Learned
+
+1. **Centralize early**: Any convention used by more than 3 components MUST be centralized immediately
+2. **Environment variables are your friend**: For system-wide patterns, env vars prevent drift and make updates atomic
+3. **Hook-based initialization is powerful**: The session-init hook proved invaluable for computing complex patterns at startup
+4. **Documentation must match reality**: We had outdated docs that confused more than they helped
+
+## Next Steps
+
+1. Monitor for any remaining hardcoded patterns that might have been missed
+2. Add validation to ensure new agents/commands use CK_NAME_PATTERN
+3. Consider adding similar centralization for other common patterns (report paths, etc.)
+
+The refactor was painful but necessary. We now have a single source of truth for naming patterns that can be updated system-wide without touching 30+ files. That's a win for maintainability, even if it took us way too long to get here.

package/docs/journals/INDEX.md

@@ -0,0 +1,81 @@
+# Journal Entries Index
+
+## Overview
+Technical journal documenting development challenges, failures, and lessons learned. Each entry provides raw, honest assessment of what went wrong and why.
+
+## November 2025 - Plan Archival Analysis
+
+### Completed Plans
+- **2025-11-11-windows-statusline-complete.md**
+  - Windows statusline support implementation (all 5 phases completed)
+  - Why it succeeded: clear scope, explicit success criteria, user-facing value
+  - Impact: shipped feature for Windows users
+
+### Never-Started Plans
+- **2025-11-11-planning-skill-never-started.md**
+  - Plan to split 115-line SKILL.md into 7 focused references
+  - Why it failed: no execution target date, internal optimization without external pressure
+  - Lesson: planning without execution scheduling = work that won't happen
+
+### Planning-Complete-But-Not-Implemented Plans
+- **2025-11-14-aesthetic-skill-ambitious-planning.md**
+  - Combat "AI slop" designs through 4-phase enhancement (12-16 hours)
+  - Why it failed: comprehensive research created false completion feeling, scope expanded during planning
+  - Lesson: research completion is not work completion
+
+### Under-Review-But-Not-Started Plans
+- **2025-11-14-docs-commands-optimization-stuck.md**
+  - Reduce /docs:* token consumption 40-60% (identified concrete waste: 38,868 tokens/run)
+  - Why it failed: "Under Review" became indefinite limbo, optimization is abstract vs. features
+  - Lesson: optimization plans sit forever without explicit execution decision
+
+## October 2025 - Technical Debt & Process Issues
+
+- **2510181655-massive-skills-integration-technical-debt.md**
+  - Adding 62,095 lines of Anthropic skills reference implementation
+  - Straddling boilerplate vs. reference implementation goals
+  - Lesson: clear boundaries between "ClaudeKit code" and "reference materials" needed
+
+- **2510181700-obsession-with-conciseness.md**
+  - (Obsession with extreme conciseness creating maintenance debt)
+
+- **2510181710-git-workflow-evolution.md**
+  - (Git workflow patterns and evolution)
+
+- **2510181720-release-automation-reality-check.md**
+  - (Release automation challenges and reality)
+
+## Reading Guide
+
+### By Topic
+- **Process failures**: planning-skill-never-started, aesthetic-skill-ambitious-planning, docs-commands-optimization-stuck
+- **Completed work analysis**: windows-statusline-complete
+- **System architecture decisions**: massive-skills-integration-technical-debt
+- **Team practices**: obsession-with-conciseness, git-workflow-evolution, release-automation-reality-check
+
+### By Lesson Type
+- **Why plans fail**: planning-skill, aesthetic-skill, docs-optimization
+- **Why plans succeed**: windows-statusline
+- **Technical debt**: skills-integration
+- **Process evolution**: git-workflow, release-automation
+
+## Key Patterns Identified
+
+1. **Success Factor**: Clear scope + explicit metrics + phase gates + user demand
+2. **Failure Pattern**: Planning without execution scheduling → indefinite limbo
+3. **Research Trap**: Comprehensive research creates false completion feeling
+4. **Priority Creep**: Internal optimization loses to feature work every time
+5. **Time Threshold**: Plans over 8 hours without scheduling never execute
+
+## Recommendations for Future Planning
+
+- Plans under 3 hours: include execution date, treat as sprint work
+- Plans 3-8 hours: allocate specific day/time before plan completion
+- Plans over 8 hours: start with Phase 1 proof of concept only
+- Optimization work: must show real before/after measurement
+- All plans: must transition from "Planning" to "Executing" or "Deprioritized" within 72 hours
+
+---
+
+Last updated: 2025-12-17
+Total entries: 8