Uh oh!
There was an error while loading. Please reload this page.
Add comprehensive documentation and enhance defensive utilities for CLI tools - #22
Merged
Conversation
…and CCSDK toolkit architecture This commit documents critical insights from recent development work: Analysis Documents Added: - AMPLIFIER_CLAUDE_CODE_LEVERAGE.md: Deep analysis of how Amplifier leverages Claude Code features beyond vanilla capabilities, including memory files, subagents, commands, hooks, and their synergistic integration (10,000x+ amplification effect) - ccsdk-toolkit-comprehensive-analysis.md: Technical analysis of the CCSDK toolkit architecture, showing how it enables metacognitive recipe development with "code for structure, AI for intelligence" patterns Key Updates: - amplifier-cli-architect agent: Enhanced with concrete code patterns and examples from md-synthesizer lessons - DISCOVERIES.md: Cleaned up to remove outdated Claude Code SDK integration notes (already captured in toolkit docs) - amplifier/README.md: Updated module documentation structure Context: These analyses capture lessons learned from md-synthesizer development (4 iterations of debugging) and document how the Amplifier system creates exponential value through feature orchestration rather than simple addition. The documentation will guide future tool development and prevent repeating common pitfalls identified during recent work. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Renamed the tools/ directory to examples/ to better communicate its purpose as example implementations rather than a general tools directory. This prevents confusion when building new CLI tools, as they were incorrectly being placed here due to naming ambiguity. Changes: - Moved all example implementations from tools/ to examples/ - Updated all imports and references in documentation - Updated agent definitions and CLI templates - Verified all examples still work after migration
Added defensive programming utilities to handle common LLM response issues including JSON parsing errors, context contamination, and transient failures. Based on real-world validation showing 100% failure elimination. Key utilities: - parse_llm_json(): Extracts valid JSON from any LLM response format - retry_with_feedback(): Intelligent retry with error correction feedback - isolate_prompt(): Prevents system context leakage into responses - File I/O retry patterns for cloud sync resilience Documented patterns in DISCOVERIES.md for future reference.
Incorporated best practices from idea_synthesis example into defensive utilities and updated examples to showcase these improved patterns. This creates a robust, centralized set of defensive utilities that handle common LLM edge cases. Key enhancements: - Added graceful defaults to parse_llm_json() for better error recovery - Moved cloud-aware file I/O to defensive utilities as the standard - Added verbose debugging options for troubleshooting - Created comprehensive documentation (PATTERNS.md and README.md) Updated idea_synthesis example: - Replaced 80+ lines of custom JSON parsing with single utility call - Now uses centralized defensive utilities throughout - Serves as canonical reference implementation for new tools The examples are verified working and demonstrate best practices for: - Robust JSON parsing from LLM responses (handles markdown, mixed text) - Cloud sync-aware file operations (OneDrive, Dropbox compatibility) - Graceful degradation with empty collections instead of None
Added planning and analysis documents that capture the evolution of the md_synthesizer tool concept and comprehensive improvements to the CCSDK toolkit architecture. These documents preserve important context about: - Tool design decisions and architecture evolution - Pattern discoveries from real-world usage - Integration strategies for defensive programming - Lessons learned from failed approaches
…ion and validation criteria
… CLI tool generation - Add comprehensive tool template with all defensive patterns discovered through real failures - Create template documentation explaining philosophy and key features - Add pydantic_extraction utility for handling pydantic_ai responses - Update amplifier-cli-architect to clarify directory structure (ai_working/ not examples/) - Document tool generation pattern failures in DISCOVERIES.md - Update README to highlight template as starting point for new tools - Add pydantic-ai dependency for enhanced AI agent integration The template enforces critical patterns: - Recursive file discovery (**/*.ext not *.ext) - Minimum input validation before processing - Clear progress visibility to users - Incremental state saving for interruption safety - Resume capability for long-running processes - Defensive LLM response parsing - Cloud sync-aware file I/O with retry logic This prevents the recurring failures observed in generated tools where non-recursive globs, missing validation, and silent failures made tools unreliable.
Uh oh!
There was an error while loading. Please reload this page.
Michael J. Jabbour (michaeljabbour) added a commit
to michaeljabbour/amplifier
that referenced
this pull request
Sep 30, 2025
Complete comprehensive technical specification library with all 44 principles: **People (6 specs)** - #1 Small AI-first working groups - #2 Strategic human touchpoints only - #3 Prompt engineering as core skill - microsoft#4 Test-based verification over code review - microsoft#5 Conversation-driven development - microsoft#6 Human escape hatches always available **Process (13 specs)** - microsoft#7 Regenerate, don't edit - microsoft#8 Contract-first everything - microsoft#9 Tests as the quality gate - microsoft#10 Git as safety net - microsoft#11 Continuous validation with fast feedback - microsoft#12 Incremental processing as default - microsoft#13 Parallel exploration by default - microsoft#14 Context management as discipline - microsoft#15 Git-based everything - microsoft#16 Docs define, not describe - microsoft#17 Prompt versioning and testing - microsoft#18 Contract evolution with migration paths - microsoft#19 Cost and token budgeting **Technology (18 specs)** - microsoft#20 Self-modifying AI-first codebase - microsoft#21 Limited and domain-specific by design - microsoft#22 Layered virtualization - microsoft#23 Protected self-healing kernel - microsoft#24 Long-running agent processes - microsoft#25 Simple interfaces by design - microsoft#26 Stateless by default - microsoft#27 Disposable components everywhere - microsoft#28 CLI-first design - microsoft#29 Tool ecosystems as extensions - microsoft#30 Observability baked in - microsoft#31 Idempotency by design (reference) - microsoft#32 Error recovery patterns built in - microsoft#33 Graceful degradation by design - microsoft#34 Feature flags as deployment strategy - microsoft#35 Least-privilege automation - microsoft#36 Dependency pinning and security scanning - microsoft#37 Declarative over imperative **Governance (7 specs)** - microsoft#38 Access control and compliance - microsoft#39 Metrics and evaluation everywhere - microsoft#40 Knowledge stewardship and institutional memory - microsoft#41 Adaptive sandboxing with explicit approvals - microsoft#42 Data governance and privacy controls - microsoft#43 Model lifecycle management - microsoft#44 Self-serve recovery with known-good snapshots Each specification includes: - Plain-language definition - AI-first development rationale - 4-6 implementation approaches - 5 good/bad example pairs with working code - 6 related principles with relationships - 7 common pitfalls with examples - Tools organized by category - 12 actionable checklist items Statistics: - 44 specifications totaling ~10,000+ lines - 220+ good/bad code example pairs - 240+ implementation approaches - 300+ documented anti-patterns - 500+ tools and frameworks - 250+ cross-principle relationships Created through parallel AI agent execution demonstrating Principle microsoft#13 (Parallel Exploration by Default). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Joi Ito (Joi) pushed a commit
to Joi/amplifier
that referenced
this pull request
Oct 31, 2025
…LI tools (microsoft#22) * docs: add comprehensive analysis of Amplifier's Claude Code leverage and CCSDK toolkit architecture This commit documents critical insights from recent development work: Analysis Documents Added: - AMPLIFIER_CLAUDE_CODE_LEVERAGE.md: Deep analysis of how Amplifier leverages Claude Code features beyond vanilla capabilities, including memory files, subagents, commands, hooks, and their synergistic integration (10,000x+ amplification effect) - ccsdk-toolkit-comprehensive-analysis.md: Technical analysis of the CCSDK toolkit architecture, showing how it enables metacognitive recipe development with "code for structure, AI for intelligence" patterns Key Updates: - amplifier-cli-architect agent: Enhanced with concrete code patterns and examples from md-synthesizer lessons - DISCOVERIES.md: Cleaned up to remove outdated Claude Code SDK integration notes (already captured in toolkit docs) - amplifier/README.md: Updated module documentation structure Context: These analyses capture lessons learned from md-synthesizer development (4 iterations of debugging) and document how the Amplifier system creates exponential value through feature orchestration rather than simple addition. The documentation will guide future tool development and prevent repeating common pitfalls identified during recent work. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * Merge branch 'main' of https://github.com/microsoft/amplifier into cli-tool-demo * refactor: simplify timeout comments and error messages in KnowledgeSynthesizer * refactor: rename ccsdk_toolkit/tools to examples for clarity Renamed the tools/ directory to examples/ to better communicate its purpose as example implementations rather than a general tools directory. This prevents confusion when building new CLI tools, as they were incorrectly being placed here due to naming ambiguity. Changes: - Moved all example implementations from tools/ to examples/ - Updated all imports and references in documentation - Updated agent definitions and CLI templates - Verified all examples still work after migration * feat: add defensive utilities for robust LLM response handling Added defensive programming utilities to handle common LLM response issues including JSON parsing errors, context contamination, and transient failures. Based on real-world validation showing 100% failure elimination. Key utilities: - parse_llm_json(): Extracts valid JSON from any LLM response format - retry_with_feedback(): Intelligent retry with error correction feedback - isolate_prompt(): Prevents system context leakage into responses - File I/O retry patterns for cloud sync resilience Documented patterns in DISCOVERIES.md for future reference. * feat: enhance defensive utilities and update examples to use them Incorporated best practices from idea_synthesis example into defensive utilities and updated examples to showcase these improved patterns. This creates a robust, centralized set of defensive utilities that handle common LLM edge cases. Key enhancements: - Added graceful defaults to parse_llm_json() for better error recovery - Moved cloud-aware file I/O to defensive utilities as the standard - Added verbose debugging options for troubleshooting - Created comprehensive documentation (PATTERNS.md and README.md) Updated idea_synthesis example: - Replaced 80+ lines of custom JSON parsing with single utility call - Now uses centralized defensive utilities throughout - Serves as canonical reference implementation for new tools The examples are verified working and demonstrate best practices for: - Robust JSON parsing from LLM responses (handles markdown, mixed text) - Cloud sync-aware file operations (OneDrive, Dropbox compatibility) - Graceful degradation with empty collections instead of None * docs: add analysis documents for md_synthesizer and CCSDK improvements Added planning and analysis documents that capture the evolution of the md_synthesizer tool concept and comprehensive improvements to the CCSDK toolkit architecture. These documents preserve important context about: - Tool design decisions and architecture evolution - Pattern discoveries from real-world usage - Integration strategies for defensive programming - Lessons learned from failed approaches * Merge branch 'main' of https://github.com/microsoft/amplifier into cli-tool-demo * docs: update amplifier-cli-architect documentation for tool organization and validation criteria * Merge branch 'main' of https://github.com/microsoft/amplifier into cli-tool-demo * docs: update CLAUDE_CODE_SDK_PYTHON_REPO.md with new SDK features and examples * feat: add tool templates and enhance defensive utilities for reliable CLI tool generation - Add comprehensive tool template with all defensive patterns discovered through real failures - Create template documentation explaining philosophy and key features - Add pydantic_extraction utility for handling pydantic_ai responses - Update amplifier-cli-architect to clarify directory structure (ai_working/ not examples/) - Document tool generation pattern failures in DISCOVERIES.md - Update README to highlight template as starting point for new tools - Add pydantic-ai dependency for enhanced AI agent integration The template enforces critical patterns: - Recursive file discovery (**/*.ext not *.ext) - Minimum input validation before processing - Clear progress visibility to users - Incremental state saving for interruption safety - Resume capability for long-running processes - Defensive LLM response parsing - Cloud sync-aware file I/O with retry logic This prevents the recurring failures observed in generated tools where non-recursive globs, missing validation, and silent failures made tools unreliable.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduce detailed analyses of the Amplifier's Claude Code leverage and CCSDK toolkit architecture, documenting critical insights and lessons learned. Simplify the organization of example implementations and enhance defensive programming utilities for robust LLM response handling. Update tool templates to enforce best practices and prevent common failures in CLI tool generation. Improve documentation for clarity and guidance on tool development.