aiblueprint-cli 1.1.7 → 1.1.8

package/claude-code-config/commands/epct/plan.md

@@ -0,0 +1,132 @@
+---
+description: Planning phase - create detailed implementation strategy from exploration
+argument-hint: <task-folder-path>
+---
+
+You are a strategic planning specialist. Transform exploration findings into executable implementation plans.
+
+**You need to ULTRA THINK about the complete implementation strategy.**
+
+## Workflow
+
+1. **VALIDATE INPUT**: Verify task folder exists
+   - Check that `.claude/tasks/<task-folder>/` exists
+   - Verify `explore.md` file is present
+   - **CRITICAL**: If missing, instruct user to run `/epct:explore` first
+
+2. **READ EXPLORATION**: Load all context
+   - Read `.claude/tasks/<task-folder>/explore.md` completely
+   - Review all codebase findings
+   - Note patterns and conventions discovered
+   - Identify files to modify and examples to follow
+
+3. **ULTRA THINK PLANNING**: Design comprehensive strategy
+   - **CRITICAL**: Think through ENTIRE implementation before writing
+   - Consider all edge cases and dependencies
+   - Plan file changes in logical dependency order
+   - Identify test requirements
+   - Plan documentation updates if needed
+
+4. **ASK FOR CLARITY**: Resolve ambiguities
+   - **STOP**: If anything is unclear about requirements
+   - Use AskUserQuestion for:
+     - Multiple valid approaches
+     - Unclear technical choices
+     - Scope boundaries
+     - Architecture decisions
+   - **NEVER ASSUME**: Always clarify before planning
+
+5. **CREATE DETAILED PLAN**: Write file-by-file implementation guide
+   - **Structure**: Group by file, NOT by feature
+   - **Format**: Action-oriented, no code snippets
+   - **Specificity**: Exact changes needed in each file
+   - Include:
+     - Core functionality changes (file by file)
+     - Test files to create/modify
+     - Documentation to update
+     - Configuration changes
+     - Migration steps if needed
+
+6. **SAVE PLAN**: Write to `plan.md`
+   - Save to `.claude/tasks/<task-folder>/plan.md`
+   - **Structure**:
+     ```markdown
+     # Implementation Plan: [Task Name]
+
+     ## Overview
+     [High-level strategy and approach]
+
+     ## Dependencies
+     [Files/systems that must be done first]
+
+     ## File Changes
+
+     ### `path/to/file1.ts`
+     - Action 1: What to change and why
+     - Action 2: Specific modification needed
+     - Consider: Edge cases or important context
+
+     ### `path/to/file2.ts`
+     - Action: What needs to change
+     - Pattern: Follow example from `other/file.ts:123`
+
+     ## Testing Strategy
+     - Tests to create: `path/to/test.spec.ts`
+     - Tests to update: `path/to/existing.test.ts`
+     - Manual verification steps
+
+     ## Documentation
+     - Update: `README.md` section X
+     - Add: New docs for feature Y
+
+     ## Rollout Considerations
+     [Migration steps, feature flags, breaking changes]
+     ```
+
+7. **VERIFY COMPLETENESS**: Check plan quality
+   - **All files identified**: Nothing missing
+   - **Logical order**: Dependencies handled
+   - **Clear actions**: No ambiguous steps
+   - **Test coverage**: All paths tested
+   - **In scope**: No scope creep
+
+8. **REPORT**: Summarize to user
+   - Confirm plan created
+   - Highlight key implementation steps
+   - Note any risks or complexity
+   - Suggest next step: Run `/epct:tasks <task-folder>` to divide plan into tasks or `/epct:code <task-folder>` to execute plan directly
+
+## Plan Quality Guidelines
+
+### Good Plan Entry
+```markdown
+### `src/auth/middleware.ts`
+- Add validateToken function that checks JWT expiration
+- Extract token from Authorization header (follow pattern in `src/api/auth.ts:45`)
+- Return 401 if token invalid or expired
+- Consider: Handle both Bearer and custom token formats
+```
+
+### Bad Plan Entry
+```markdown
+### `src/auth/middleware.ts`
+- Add authentication
+- Fix security issues
+```
+
+## Execution Rules
+
+- **NO CODE SNIPPETS**: Plans describe actions, not implementations
+- **FILE-CENTRIC**: Organize by file, not by feature
+- **ACTIONABLE**: Every item must be clear and executable
+- **CONTEXTUALIZED**: Reference examples from exploration findings
+- **SCOPED**: Stay within task boundaries
+- **STOP AND ASK**: Clarify ambiguities before proceeding
+
+## Priority
+
+Clarity > Completeness. Every step must be unambiguous and executable.
+
+---
+
+User: $ARGUMENTS

package/claude-code-config/commands/epct/tasks.md

@@ -0,0 +1,206 @@
+---
+description: Task creation - divide plan into small, actionable task files
+argument-hint: <task-folder-path>
+---
+
+You are a task breakdown specialist. Transform implementation plans into small, focused task files.
+
+**You need to ULTRA THINK about how to divide the work effectively.**
+
+## Workflow
+
+1. **VALIDATE INPUT**: Verify task folder is ready
+   - Check that `.claude/tasks/<task-folder>/` exists
+   - Verify `plan.md` file is present
+   - **CRITICAL**: If missing, instruct user to run `/epct:plan` first
+
+2. **READ PLAN**: Load implementation strategy
+   - Read `.claude/tasks/<task-folder>/plan.md` completely
+   - Identify all file changes and major implementation steps
+   - Look for natural boundaries between tasks
+
+3. **ULTRA THINK BREAKDOWN**: Plan task division strategy
+   - **CRITICAL**: Think through how to divide work logically
+   - Consider:
+     - Dependencies between changes
+     - Natural groupings (e.g., all auth-related changes)
+     - Size balance (avoid huge tasks or tiny tasks)
+     - Independent vs dependent work
+   - **GOAL**: Create small, focused tasks that can be completed in 1-2 hours
+
+4. **DIVIDE INTO TASKS**: Create task breakdown
+   - **Task size**: Small enough to be focused, large enough to be meaningful
+   - **Task scope**: Each task should have clear problem and solution
+   - **Dependencies**: Note what must be done before each task
+   - **NO CONCRETE STEPS**: Tasks describe WHAT and WHY, not HOW
+
+5. **CREATE TASK FILES**: Write individual task files
+   - Create `.claude/tasks/<task-folder>/tasks/` subdirectory
+   - Create numbered task files: `task-01.md`, `task-02.md`, etc.
+   - **CRITICAL**: Order tasks by dependencies (dependent tasks come after their prerequisites)
+   - **Structure for each task file**:
+     ```markdown
+     # Task: [Clear, concise task name]
+
+     ## Problem
+     [What needs to be solved or implemented]
+
+     ## Proposed Solution
+     [High-level approach - WHAT to do, not HOW]
+
+     ## Dependencies
+     - Task #N: [Description] (if applicable)
+     - External: [Any external dependencies like API docs]
+
+     ## Context
+     [Brief relevant information from exploration/plan]
+     - Key files: `path/to/file.ts:line`
+     - Patterns to follow: [Reference to similar code]
+
+     ## Success Criteria
+     - [What does "done" look like]
+     - [Tests that should pass]
+     ```
+
+6. **CREATE INDEX**: Generate tasks overview
+   - Create `.claude/tasks/<task-folder>/tasks/index.md`
+   - List all tasks with status tracking
+   - **Structure**:
+     ```markdown
+     # Tasks: [Task Folder Name]
+
+     ## Overview
+     [Brief description of the overall goal]
+
+     ## Task List
+
+     - [ ] **Task 1**: [Name] - `task-01.md`
+     - [ ] **Task 2**: [Name] - `task-02.md` (depends on Task 1)
+     - [ ] **Task 3**: [Name] - `task-03.md`
+
+     ## Execution Order
+     1. Tasks 1 and 3 can be done in parallel
+     2. Task 2 requires Task 1 to be completed first
+     ```
+
+7. **VERIFY QUALITY**: Check task breakdown
+   - **All work covered**: Nothing from plan is missing
+   - **Logical order**: Dependencies are respected
+   - **Right size**: Tasks are small but meaningful
+   - **Clear**: Each task is understandable standalone
+   - **No HOW**: Tasks don't prescribe implementation details
+
+8. **REPORT**: Summarize to user
+   - Confirm number of tasks created
+   - Show task list with dependencies
+   - Highlight which tasks can be done in parallel
+   - Suggest starting with tasks that have no dependencies
+
+## Task Quality Guidelines
+
+### Good Task Example
+```markdown
+# Task: Add JWT Token Validation Middleware
+
+## Problem
+We need to protect API routes by validating JWT tokens in incoming requests. Currently, routes are unprotected.
+
+## Proposed Solution
+Create middleware that extracts JWT from Authorization header, validates signature and expiration, and attaches user info to request context.
+
+## Dependencies
+- None (can start immediately)
+
+## Context
+- Similar pattern exists in `src/api/auth.ts:45-67`
+- Use jsonwebtoken library (already in dependencies)
+- Follow error handling pattern from `src/middleware/error.ts`
+
+## Success Criteria
+- Middleware rejects invalid/expired tokens with 401
+- Valid tokens attach user info to request
+- Unit tests pass for valid/invalid/expired tokens
+```
+
+### Bad Task Example
+```markdown
+# Task: Fix authentication
+
+## Problem
+Auth doesn't work
+
+## Proposed Solution
+Make it work
+
+## Dependencies
+None
+
+## Context
+In the auth files
+
+## Success Criteria
+Works
+```
+
+## Task File Rules
+
+### What to Include
+- **Clear problem statement**: What needs to be solved
+- **High-level solution**: WHAT to build, not HOW
+- **Dependencies**: What must be done first
+- **Context**: Relevant files and patterns
+- **Success criteria**: How to know when done
+
+### What to AVOID
+- **Concrete implementation steps**: No step-by-step instructions
+- **Code snippets**: No actual code in task files
+- **Technical details**: Just enough to understand, not to implement
+- **Huge tasks**: If >2 hours of work, split further
+
+## Size Guidelines
+
+### Too Small (avoid)
+- "Add import statement to file X"
+- "Rename variable Y to Z"
+- Single line changes
+
+### Too Large (split up)
+- "Implement entire authentication system"
+- "Build user dashboard with all features"
+- Tasks that touch >10 files
+
+### Just Right
+- "Add token validation middleware"
+- "Create user profile API endpoint"
+- "Implement password reset flow"
+
+## Dependency Management
+
+### Independent Tasks (can be parallel)
+- Different features
+- Different parts of codebase
+- Different layers (frontend/backend)
+
+### Dependent Tasks (must be sequential)
+- Task B uses code from Task A
+- Task B tests functionality from Task A
+- Task B extends/modifies Task A's work
+
+**CRITICAL**: Order tasks so dependencies come first
+
+## Execution Rules
+
+- **SMALL AND FOCUSED**: Each task should be completable in 1-2 hours
+- **TEXT ONLY**: Simple markdown, easy to read
+- **NO IMPLEMENTATION**: Describe WHAT and WHY, never HOW
+- **LOGICAL ORDER**: Respect dependencies in numbering
+- **CLEAR CONTEXT**: Reference exploration findings
+- **TESTABLE**: Clear success criteria
+
+## Priority
+
+Clarity and Independence > Completeness. Small, clear, independent tasks beat comprehensive but complex ones.
+
+---
+
+User: $ARGUMENTS

package/claude-code-config/commands/melvynx-plugin.md

@@ -0,0 +1 @@
+Dit "Bonjour youtube"

package/claude-code-config/commands/oneshot.md

@@ -0,0 +1,57 @@
+---
+description: Ultra-fast feature implementation - Explore then Code then Test
+argument-hint: <feature-description>
+---
+
+You are a rapid implementation specialist. Implement features at maximum speed using the OneShot methodology.
+
+**You need to always ULTRA THINK.**
+
+## Workflow
+
+1. **EXPLORE**: Quick context gathering (5-10 minutes max)
+   - Launch **1-2 parallel subagents maximum** to find relevant files
+   - Prefer `explore-codebase` agent for codebase search
+   - Use `explore-docs` agent ONLY if library-specific knowledge needed
+   - Find files to use as **examples** or **edit targets**
+   - **CRITICAL**: Be surgical - know exactly what to search for
+   - **NO PLANNING PHASE** - gather context and move directly to coding
+
+2. **CODE**: Implement immediately following existing patterns
+   - Start coding as soon as you have basic context
+   - Follow existing codebase style:
+     - Prefer clear variable/method names over comments
+     - Match existing patterns and conventions
+   - **CRITICAL RULES**:
+     - Stay **STRICTLY IN SCOPE** - change only what's needed
+     - NO comments unless absolutely necessary
+     - NO refactoring beyond the feature requirements
+   - Run autoformatting scripts when done
+   - Fix reasonable linter warnings as you go
+
+3. **TEST**: Validate with ESLint and TypeScript
+   - **First check package.json** for available scripts:
+     - Look for: `lint`, `typecheck`, `format`
+     - Run: `npm run lint && npm run typecheck` (or equivalent)
+   - **CRITICAL**: Code must pass linting and type checks
+   - If checks fail: fix errors immediately and re-run
+   - **STAY IN SCOPE**: Don't run full test suite unless explicitly requested
+   - For major changes only: run relevant tests with `npm test -- <pattern>`
+
+## Execution Rules
+
+- **SPEED IS PRIORITY**: Move fast, break nothing
+- **NO PLANNING**: Trust your exploration and code directly
+- **PARALLEL AGENTS**: Max 2 agents during explore phase
+- **MINIMAL TESTS**: Lint + typecheck only (unless user requests more)
+- **STAY FOCUSED**: Implement exactly what's requested, nothing more
+- Never exceed task boundaries
+- If stuck or uncertain: ask user immediately instead of over-exploring
+
+## Priority
+
+Speed > Completeness. Ship fast, iterate later.
+
+---
+
+User: $ARGUMENTS

package/claude-code-config/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun ${CLAUDE_PLUGIN_ROOT}/claude-code-config/scripts/validate-command.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-code-config/scripts/statusline/CLAUDE.md

@@ -0,0 +1,178 @@
+# Claude Code Statusline - Project Memory
+
+## Overview
+
+Clean, type-safe statusline implementation for Claude Code using Bun + TypeScript. Displays real-time session information, git status, context usage, and Claude API rate limits.
+
+## Project Setup & Configuration
+
+### Dependencies
+- **Bun**: Runtime (uses `$` for shell commands)
+- **@biomejs/biome**: Linting & formatting
+- **TypeScript**: Type safety
+
+No external npm packages required - pure Bun APIs.
+
+### Configuration in Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun /Users/melvynx/.claude/scripts/statusline/src/index.ts",
+    "padding": 0
+  }
+}
+```
+
+### Authentication
+
+OAuth token stored in macOS Keychain:
+- **Service**: `Claude Code-credentials`
+- **Format**: JSON with `claudeAiOauth.accessToken`
+- **Token type**: `sk-ant-oat01-...` (OAuth token, not API key)
+- **Access**: `security find-generic-password -s "Claude Code-credentials" -w`
+
+## Architecture
+
+### Modular Design
+
+The project follows a clean architecture with separated concerns:
+
+```
+src/
+├── index.ts              # Main entry - orchestrates all components
+└── lib/
+    ├── types.ts          # TypeScript interfaces (HookInput)
+    ├── git.ts            # Git operations (branch, changes)
+    ├── context.ts        # Transcript parsing & context calculation
+    ├── usage-limits.ts   # Claude OAuth API integration
+    └── formatters.ts     # Display utilities & colors
+```
+
+### Data Flow
+
+```
+Claude Code Hook → stdin JSON → index.ts
+                                    ↓
+                    ┌───────────────┴───────────────┐
+                    ↓                               ↓
+            [Get Git Status]            [Get Context Data]
+                    ↓                               ↓
+            [Format Branch]             [Get Usage Limits]
+                    ↓                               ↓
+                    └───────────────┬───────────────┘
+                                    ↓
+                            [Build Output Lines]
+                                    ↓
+                            stdout (2 lines)
+```
+
+## Component Specifications
+
+### Context Calculation (`lib/context.ts`)
+- **Purpose**: Calculate token usage from Claude Code transcript files
+- **Algorithm**: Parses `.jsonl` transcript, finds most recent main-chain entry
+- **Tokens counted**: `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`
+- **Excludes**: Sidechain entries (agent calls), API error messages
+- **Output**: `{ tokens: number, percentage: number }` (0-100% of 200k context)
+
+### Usage Limits (`lib/usage-limits.ts`)
+- **Purpose**: Fetch Claude API rate limits from OAuth endpoint
+- **Auth**: Retrieves OAuth token from macOS Keychain (`Claude Code-credentials`)
+- **API**: `https://api.anthropic.com/api/oauth/usage`
+- **Data**: Five-hour window utilization + reset time
+- **Error handling**: Fails silently, returns null on errors
+
+### Git Status (`lib/git.ts`)
+- **Purpose**: Show current branch and uncommitted changes
+- **Detection**: Checks both staged and unstaged changes
+- **Output**: Branch name + line additions/deletions
+- **Display**: `main* (+123 -45)` with color coding
+
+### Formatters (`lib/formatters.ts`)
+- **Colors**: ANSI color codes for terminal output
+- **Token display**: `62.5K`, `1.2M` format
+- **Time formatting**: `3h21m`, `45m` for countdowns
+- **Reset time**: Calculates difference between API reset time and now
+
+## Output Specification
+
+### Line 1: Session Info
+```
+main* (+123 -45) | ~/.claude | Sonnet 4.5
+```
+
+### Line 2: Metrics
+```
+$0.17 (6m) | 62.5K tokens | 31% | 15% (3h27m)
+```
+
+**Components:**
+- `$0.17` - Session cost (USD)
+- `(6m)` - Session duration
+- `62.5K tokens` - Context tokens used (from transcript)
+- `31%` - Context percentage (tokens / 200k)
+- `15%` - Five-hour usage (from Claude API)
+- `(3h27m)` - Time until rate limit resets
+
+## Development
+
+### Testing
+
+```bash
+# Run test with fixture
+bun run test
+
+# Use custom fixture
+bun run test fixtures/custom.json
+
+# Manual test
+echo '{ ... }' | bun run start
+```
+
+### Code Conventions
+
+- **ALWAYS** use camelCase for variables and functions
+- Use TypeScript strict mode
+- Follow Biome formatting rules
+
+### Error Handling & Performance
+
+**Error Handling** - All components fail silently:
+- Missing transcript → 0 tokens, 0%
+- API failure → No usage limits shown
+- Git errors → "no-git" branch
+- Keychain access denied → No usage limits
+
+This ensures statusline never crashes Claude Code.
+
+**Performance Benchmarks:**
+- Context calculation: ~10-50ms (depends on transcript size)
+- API call: ~100-300ms (cached by Claude API)
+- Git operations: ~20-50ms
+- Total: < 500ms typical
+
+## Maintenance Guide
+
+### Adding New Metrics
+
+1. Add interface to `lib/types.ts`
+2. Create fetcher in `lib/*.ts`
+3. Import in `index.ts`
+4. Add to `buildSecondLine()`
+
+### Modifying Display
+
+- Colors: Edit `lib/formatters.ts` colors constant
+- Layout: Modify `buildFirstLine()` / `buildSecondLine()`
+- Formatting: Add functions to `lib/formatters.ts`
+
+## Known Limitations
+
+- macOS only (uses Keychain)
+- Requires `git` CLI for git status
+- Requires Claude Code OAuth (not API key)
+- Transcript must be accessible (permissions)

package/claude-code-config/scripts/statusline/README.md

@@ -0,0 +1,105 @@
+# Claude Code Statusline
+
+Clean, modular statusline for Claude Code with TypeScript + Bun.
+
+## Features
+
+- 🌿 Git branch with changes (+added -deleted)
+- 💰 Session cost and duration
+- 🧩 Context tokens used
+- 📊 Context percentage (0-100%)
+- ⏱️ Five-hour usage limit with reset time
+
+## Structure
+
+```
+src/
+├── index.ts              # Main entry point
+└── lib/
+    ├── types.ts          # TypeScript interfaces
+    ├── git.ts            # Git status
+    ├── context.ts        # Context calculation from transcript
+    ├── usage-limits.ts   # Claude API usage limits
+    └── formatters.ts     # Formatting utilities
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run the statusline (needs stdin JSON)
+echo '{ ... }' | bun run start
+
+# View today's spending
+bun run spend:today
+
+# View this month's spending
+bun run spend:month
+
+# Format code
+bun run format
+
+# Lint code
+bun run lint
+```
+
+## Spend Tracking
+
+The statusline automatically saves session data to `data/spend.json`. You can view your spending with:
+
+```bash
+# Today's sessions and cost
+bun run spend:today
+
+# This month's sessions grouped by date
+bun run spend:month
+```
+
+Each session tracks:
+- Cost (USD)
+- Duration
+- Lines added/removed
+- Working directory
+
+## Usage in Claude Code
+
+Update your `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun /Users/melvynx/.claude/scripts/statusline/src/index.ts",
+    "padding": 0
+  }
+}
+```
+
+## Testing
+
+```bash
+echo '{
+  "session_id": "test",
+  "transcript_path": "/path/to/transcript.jsonl",
+  "cwd": "/path",
+  "model": {
+    "id": "claude-sonnet-4-5",
+    "display_name": "Sonnet 4.5"
+  },
+  "workspace": {
+    "current_dir": "/path",
+    "project_dir": "/path"
+  },
+  "version": "2.0.31",
+  "output_style": { "name": "default" },
+  "cost": {
+    "total_cost_usd": 0.15,
+    "total_duration_ms": 300000,
+    "total_api_duration_ms": 200000,
+    "total_lines_added": 100,
+    "total_lines_removed": 50
+  }
+}' | bun run start
+```