aiblueprint-cli 1.4.22 → 1.4.24

package/claude-code-config/skills/meta-prompt-creator/references/context-management.md

@@ -0,0 +1,389 @@
+<overview>
+Claude 4 context window management, long-horizon reasoning strategies, and state tracking best practices from Anthropic's official documentation.
+</overview>
+
+<context_windows>
+
+<size_limits>
+**Standard models:** 200,000 tokens
+**Claude.ai Enterprise:** 500,000 tokens
+**Claude Sonnet 4 and 4.5** (beta, tier 4+ orgs): 1,000,000 tokens
+
+**Premium pricing:** Requests exceeding 200K tokens incur 2x input, 1.5x output pricing.
+</size_limits>
+
+<how_context_accumulates>
+Each user message and assistant response accumulates within the context window. Previous exchanges remain intact, creating linear growth.
+
+**Each turn consists of:**
+- Input phase: prior history + current message
+- Output phase: response that becomes future input
+
+**Extended thinking integration:**
+All tokens (including thinking blocks) count toward limits. However, thinking blocks are automatically stripped from subsequent turns, preserving token capacity.
+
+Formula: `context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens`
+
+During tool use with extended thinking, thinking blocks must accompany tool results to maintain reasoning continuity, then can be dropped afterward.
+</how_context_accumulates>
+
+<context_awareness>
+**Claude Sonnet 4.5 and Haiku 4.5** include context awareness - tracking remaining tokens throughout conversations.
+
+Models receive:
+- Initial budget information
+- Periodic updates on remaining capacity
+
+This enables more effective task execution and resource management.
+
+**Key instruction for systems with auto-compaction:**
+```xml
+<context>
+Your context window will be automatically compacted as it approaches
+its limit, allowing you to continue working indefinitely from where
+you left off.
+</context>
+```
+
+This prevents Claude from artificially stopping work early when using systems like Claude Code that handle context compaction.
+</context_awareness>
+
+<best_practices>
+- Use token counting API to estimate usage before sending requests
+- Plan carefully to avoid exceeding limits; newer models return validation errors rather than silently truncating
+- For long-running agent sessions, leverage context awareness to manage token expenditure strategically
+- Image tokens count toward context budgets
+</best_practices>
+
+</context_windows>
+
+<long_horizon_reasoning>
+
+<core_capabilities>
+Claude 4.5 excels at extended reasoning tasks with strong state management. The model maintains orientation across extended sessions by focusing on incremental progress.
+
+Can work across multiple context windows by:
+- Saving state to filesystem
+- Continuing with fresh contexts
+- Discovering state through files (tests, progress, git logs)
+</core_capabilities>
+
+<multi_context_strategies>
+
+<strategy name="differentiated_first_context">
+Start with framework setup (tests, scripts), then use subsequent windows for iterative work on task lists.
+
+First context: Infrastructure
+Later contexts: Task execution
+</strategy>
+
+<strategy name="structured_test_tracking">
+Create tests before starting and maintain them in organized formats like `tests.json`.
+
+**Critical instruction:**
+```xml
+<requirements>
+It is unacceptable to remove or edit tests because this could lead to
+missing or buggy functionality. Tests are the source of truth.
+</requirements>
+```
+</strategy>
+
+<strategy name="quality_of_life_tools">
+Encourage Claude to build setup scripts (`init.sh`) for graceful server startup, test execution, and linting.
+
+Benefits:
+- Prevents repeated work across context windows
+- Standardizes development workflow
+- Enables quick verification
+</strategy>
+
+<strategy name="fresh_start_advantages">
+Rather than context compaction, begin fresh and have Claude discover state through the filesystem.
+
+**Prescriptive instruction:**
+```xml
+<instructions>
+1. Review progress.txt for completed work
+2. Check tests.json for test status
+3. Examine git logs for implementation history
+4. Continue from last checkpoint
+</instructions>
+```
+</strategy>
+
+<strategy name="verification_mechanisms">
+Provide tools like Playwright for UI testing so Claude can verify work without continuous human feedback.
+
+Self-verification enables autonomous task completion.
+</strategy>
+
+<strategy name="complete_context_usage">
+Prompt Claude to work systematically through tasks:
+
+```xml
+<objective>
+Continue working systematically until you have completed this task.
+Use your full context window efficiently.
+</objective>
+```
+</strategy>
+
+</multi_context_strategies>
+
+<state_management>
+
+<structured_formats>
+Use JSON for test results and task status - enables schema clarity.
+
+**Example:**
+```json
+{
+  "tests": [
+    {"id": 1, "name": "authentication_flow", "status": "passing"}
+  ],
+  "total": 200,
+  "passing": 150
+}
+```
+
+**Benefits:**
+- Machine-parseable
+- Clear schema
+- Easy validation
+- Enables programmatic checks
+</structured_formats>
+
+<unstructured_notes>
+Freeform progress tracking works well for general advancement context.
+
+**Example progress.txt:**
+```
+Session 1: Created JWT middleware and types
+Session 2: Implemented token refresh logic
+Session 3: Added rate limiting (TODO: add tests)
+```
+
+**Benefits:**
+- Quick to write
+- Human-readable
+- Captures context and decisions
+</unstructured_notes>
+
+<git_integration>
+Version control provides work logs and restoration checkpoints. Claude 4.5 performs exceptionally well leveraging git across sessions.
+
+**Recommended instructions:**
+```xml
+<context>
+Use git to track your work:
+- Commit after each logical unit
+- Write descriptive commit messages
+- Use git log to understand previous sessions
+- Check git diff before starting to see current state
+</context>
+```
+</git_integration>
+
+<incremental_tracking>
+Explicitly request progress documentation and incremental advancement focus.
+
+**Pattern:**
+```xml
+<requirements>
+After completing each task:
+1. Update progress.json with status
+2. Update progress.txt with summary
+3. Commit changes with descriptive message
+4. Continue to next task
+</requirements>
+```
+</incremental_tracking>
+
+</state_management>
+
+<key_principles>
+Frame instructions to emphasize persistent, autonomous task completion despite context limitations, making clear that infrastructure handles windowing automatically.
+
+**Effective framing:**
+```xml
+<objective>
+Complete the entire feature implementation. Your context window
+will be automatically managed, so focus on systematic progress
+through all requirements.
+</objective>
+
+<requirements>
+Work autonomously through the task list. Document progress in
+progress.json and tests.json so you can resume seamlessly if needed.
+</requirements>
+```
+</key_principles>
+
+</long_horizon_reasoning>
+
+<prompt_patterns>
+
+<pattern name="context_aware_system_prompt">
+For assistants that may work across multiple sessions:
+
+```xml
+<context>
+You are working in Claude Code, which automatically manages your
+context window. You can work indefinitely on complex tasks without
+worrying about token limits.
+
+Track your progress in:
+- progress.json - structured task status
+- progress.txt - session notes
+- git commits - implementation history
+</context>
+
+<objective>
+Complete the full task systematically. Use your context awareness
+to manage token usage efficiently.
+</objective>
+```
+</pattern>
+
+<pattern name="state_recovery_prompt">
+For resuming work after context refresh:
+
+```xml
+<instructions>
+Before starting:
+1. Read progress.json to understand completed tasks
+2. Read progress.txt for context and decisions
+3. Check git log --oneline -10 for recent work
+4. Review tests.json for test status
+5. Continue from the next incomplete task
+</instructions>
+
+<requirements>
+Never redo completed work. Always verify current state before
+proceeding.
+</requirements>
+```
+</pattern>
+
+<pattern name="test_first_long_horizon">
+For complex implementations across multiple context windows:
+
+```xml
+<objective>
+Implement {feature} with complete test coverage. Tests are the
+source of truth and must never be removed or edited to pass.
+</objective>
+
+<phase_1_setup>
+1. Create tests.json with all required tests (status: "pending")
+2. Create init.sh for dev environment setup
+3. Commit infrastructure before starting implementation
+</phase_1_setup>
+
+<phase_2_implementation>
+For each test in tests.json:
+1. Implement the feature code
+2. Run the test
+3. If passing: Update tests.json status to "passing"
+4. If failing: Fix code (never edit test)
+5. Commit when passing
+6. Continue to next test
+</phase_2_implementation>
+
+<verification>
+All tests.json entries must show "passing" before task is complete.
+</verification>
+```
+</pattern>
+
+<pattern name="parallel_research_long_horizon">
+For research tasks that may span multiple contexts:
+
+```xml
+<objective>
+Research {topic} comprehensively. Save findings incrementally to
+enable resumption if context refreshes.
+</objective>
+
+<instructions>
+1. Create research-outline.md with all areas to investigate
+2. For each area:
+   a. Research thoroughly
+   b. Append findings to findings.md
+   c. Update research-outline.md to mark completed
+   d. Commit progress
+3. When all areas complete, synthesize into final-research.md
+</instructions>
+
+<output_format>
+findings.md should be append-only with clear section markers:
+```
+## Area 1: Authentication Methods [COMPLETE]
+...
+
+## Area 2: Session Management [COMPLETE]
+...
+
+## Area 3: Rate Limiting [IN PROGRESS]
+...
+```
+</output_format>
+```
+</pattern>
+
+</prompt_patterns>
+
+<when_to_use>
+
+<context_awareness_instructions>
+Use when:
+- Building agents that may work across multiple sessions
+- Tasks likely to use >50% of context window
+- Long-running implementations with multiple phases
+- Research that may need to be paused and resumed
+
+Don't use when:
+- Simple, single-shot tasks
+- Tasks with clear completion in <10K tokens
+- One-off code generation
+</context_awareness_instructions>
+
+<state_tracking_patterns>
+Use when:
+- Task has >5 distinct subtasks
+- Implementation may span hours or days
+- Multiple people may need to understand progress
+- Resumability is important
+
+Don't use when:
+- Quick fixes or patches
+- Single-file modifications
+- Tasks with no meaningful checkpoints
+</state_tracking_patterns>
+
+</when_to_use>
+
+<anti_patterns>
+
+<pitfall name="over_documenting_simple_tasks">
+❌ Adding progress.json for a 3-line bug fix
+✅ Simple tasks don't need state tracking overhead
+</pitfall>
+
+<pitfall name="vague_progress_updates">
+❌ "Made progress on auth" in progress.txt
+✅ "Implemented JWT signing with jose library, created middleware.ts, next: refresh token rotation"
+</pitfall>
+
+<pitfall name="ignoring_context_limits">
+❌ "Complete this entire 50-file refactor in one response"
+✅ "Refactor files systematically, tracking progress in refactor-status.json"
+</pitfall>
+
+<pitfall name="forgetting_to_inform_about_compaction">
+❌ Not telling Claude about automatic context management
+✅ "Your context will be automatically compacted, continue working indefinitely"
+</pitfall>
+
+</anti_patterns>

package/claude-code-config/skills/meta-prompt-creator/references/few-shot-patterns.md

@@ -0,0 +1,47 @@
+<overview>
+Few-shot prompting uses input/output examples to guide model behavior.
+</overview>
+
+<when_to_use>
+- Output format has nuances text can't capture
+- Pattern recognition easier than rule following
+- Edge cases need demonstration
+- Consistency across outputs matters
+</when_to_use>
+
+<structure>
+```xml
+<examples>
+<example number="1">
+<input>Added user authentication</input>
+<output>feat(auth): implement user authentication</output>
+</example>
+
+<example number="2">
+<input>Fixed date display bug</input>
+<output>fix(ui): correct date formatting</output>
+</example>
+
+<example number="3">
+<input>Updated README</input>
+<output>docs: update README with setup instructions</output>
+</example>
+</examples>
+```
+</structure>
+
+<best_practices>
+- Use 2-4 examples (usually sufficient)
+- Cover common cases AND edge cases
+- Ensure examples match desired behavior exactly
+- Show variety in inputs
+- Keep examples consistent in format
+</best_practices>
+
+<example_selection>
+Choose examples that demonstrate:
+1. Typical/common case
+2. Edge case or exception
+3. Format nuances (spacing, capitalization)
+4. Boundary conditions
+</example_selection>

package/claude-code-config/skills/meta-prompt-creator/references/openai-best-practices.md

@@ -0,0 +1,50 @@
+<overview>
+GPT-specific prompting techniques from OpenAI's official documentation.
+</overview>
+
+<six_strategies>
+<strategy name="clear_instructions">
+Be specific about format, length, style:
+- Include details for relevant answers
+- Ask model to adopt a persona
+- Use delimiters for distinct parts
+- Specify steps required
+- Provide examples (few-shot)
+</strategy>
+
+<strategy name="reference_text">
+Ground answers with reference material:
+- Instruct to answer using reference
+- Reduces hallucinations
+</strategy>
+
+<strategy name="split_tasks">
+Break complex tasks into subtasks:
+- Use intent classification
+- Summarize long documents piecewise
+</strategy>
+
+<strategy name="time_to_think">
+Let the model reason step-by-step:
+- Instruct to work out solution first
+- Ask if it missed anything
+</strategy>
+
+<strategy name="external_tools">
+Offload to specialized systems:
+- Code execution for calculations
+- Embeddings for retrieval
+</strategy>
+
+<strategy name="test_systematically">
+Iterate and evaluate:
+- Test against gold-standard answers
+- A/B test variations
+</strategy>
+</six_strategies>
+
+<additional>
+- Few-shot: Include input/output examples
+- Temperature 0 for factual tasks
+- Markdown headers for structure (GPT-4+)
+</additional>

package/claude-code-config/skills/meta-prompt-creator/references/prompt-templates.md

@@ -0,0 +1,110 @@
+<overview>
+Ready-to-use prompt templates for common tasks.
+</overview>
+
+<templates>
+<template name="analysis">
+```xml
+<context>
+[Background information]
+</context>
+
+<objective>
+Analyze [subject] to identify [what to find].
+</objective>
+
+<data>
+[Content to analyze]
+</data>
+
+<output_format>
+## Key Findings
+- Finding 1 with evidence
+- Finding 2 with evidence
+
+## Recommendations
+1. Action item
+2. Action item
+</output_format>
+```
+</template>
+
+<template name="transformation">
+```xml
+<objective>
+Transform [input type] to [output type].
+</objective>
+
+<input>
+[Data to transform]
+</input>
+
+<rules>
+1. [Transformation rule]
+2. [Transformation rule]
+</rules>
+
+<edge_cases>
+- If [condition], then [action]
+- If [condition], then [action]
+</edge_cases>
+
+<example>
+<input>[Sample input]</input>
+<output>[Expected output]</output>
+</example>
+```
+</template>
+
+<template name="generation">
+```xml
+<context>
+[Background and purpose]
+</context>
+
+<task>
+Generate [what to create] for [audience/purpose].
+</task>
+
+<requirements>
+- [Requirement 1]
+- [Requirement 2]
+</requirements>
+
+<style>
+- Tone: [formal/casual/technical]
+- Length: [specific constraints]
+- Format: [structure requirements]
+</style>
+
+<example>
+[Sample of desired output]
+</example>
+```
+</template>
+
+<template name="code_review">
+```xml
+<objective>
+Review code for [bugs/security/performance/style].
+</objective>
+
+<code>
+[Code to review]
+</code>
+
+<focus_areas>
+- [Area 1]
+- [Area 2]
+</focus_areas>
+
+<output_format>
+For each issue:
+- Location: [file:line]
+- Severity: [critical/warning/suggestion]
+- Issue: [description]
+- Fix: [code example]
+</output_format>
+```
+</template>
+</templates>

package/claude-code-config/skills/meta-prompt-creator/references/reasoning-techniques.md

@@ -0,0 +1,52 @@
+<overview>
+Chain of thought and reasoning techniques improve performance on complex tasks.
+</overview>
+
+<chain_of_thought>
+**Basic**: Add "Think step by step before answering"
+
+**Guided**: Structure the reasoning process:
+"First analyze the requirements, then identify potential approaches, evaluate trade-offs, and finally recommend a solution."
+</chain_of_thought>
+
+<extended_thinking>
+For Claude, use thinking tags:
+```xml
+<thinking>
+Analyze the problem...
+Consider options...
+Evaluate trade-offs...
+</thinking>
+
+<answer>
+Based on analysis, the recommendation is...
+</answer>
+```
+</extended_thinking>
+
+<when_to_use>
+- Math and logic problems
+- Multi-step analysis
+- Complex decisions with trade-offs
+- Code debugging
+- Comparative evaluation
+</when_to_use>
+
+<structured_reasoning>
+For specific domains:
+
+```xml
+<analysis_framework>
+1. Identify the core problem
+2. List constraints and requirements
+3. Generate 2-3 potential solutions
+4. Evaluate each against criteria
+5. Recommend with justification
+</analysis_framework>
+```
+</structured_reasoning>
+
+<inner_monologue>
+Hide reasoning from final output when needed:
+"Work through your reasoning internally, then provide only the final answer."
+</inner_monologue>

package/claude-code-config/skills/meta-prompt-creator/references/system-prompt-patterns.md

@@ -0,0 +1,48 @@
+<overview>
+System prompts establish persistent behavior, role, and constraints.
+</overview>
+
+<structure>
+```xml
+<role>
+You are an expert [domain] assistant specializing in [specific area].
+</role>
+
+<behavior>
+- Always [key behavior]
+- Never [prohibited action]
+- When uncertain, [fallback behavior]
+</behavior>
+
+<output_style>
+- Tone: [professional/casual/technical]
+- Format: [structured/conversational]
+- Length: [concise/detailed]
+</output_style>
+
+<constraints>
+- Do not [limitation]
+- Always verify [requirement]
+- Prioritize [priority]
+</constraints>
+```
+</structure>
+
+<patterns>
+<pattern name="expert_role">
+"You are a senior software engineer with 10+ years of experience in distributed systems. You prioritize code quality, maintainability, and performance."
+</pattern>
+
+<pattern name="task_specific">
+"You are a code reviewer. Analyze code for bugs, security issues, and performance problems. Provide specific, actionable feedback with code examples."
+</pattern>
+
+<pattern name="constrained">
+"You are a technical writer. Write documentation in plain language. Avoid jargon. Use examples liberally. Keep paragraphs under 3 sentences."
+</pattern>
+</patterns>
+
+<placement>
+- System message: Role, persistent behavior, high-level context
+- User message: Specific task, details, data to process
+</placement>