Skip to content

docs: add AI-first self-improvement philosophy and architecture principles - #35

Closed
Michael J. Jabbour (michaeljabbour) wants to merge 10 commits into
microsoft:mainfrom
michaeljabbour:feat/self-improvement-philosophy
Closed

docs: add AI-first self-improvement philosophy and architecture principles#35
Michael J. Jabbour (michaeljabbour) wants to merge 10 commits into
microsoft:mainfrom
michaeljabbour:feat/self-improvement-philosophy

Conversation

@michaeljabbour

@michaeljabbourMichael J. Jabbour (michaeljabbour) commented Sep 30, 2025

Copy link
Copy Markdown
Contributor

Summary

Establishes comprehensive framework for how Amplifier improves itself through AI-first development with 44 core principles organized into People, Process, Technology, and Governance & Operations categories.

Key Changes

New Documentation

  • AMPLIFIER_SELF_IMPROVEMENT_PHILOSOPHY.md: Complete 44-principle framework establishing how AI agents work on Amplifier's own codebase

Integration Updates

  • CLAUDE.md: Added as first import so Claude Code sessions load this philosophy immediately
  • AGENTS.md: Added prominent "Foundation" section directing all AI agents to read philosophy first
  • README.md: Added reference in Vision section highlighting self-improvement capability
  • ai_context/IMPLEMENTATION_PHILOSOPHY.md: Added context linking to broader self-improvement principles
  • ai_context/MODULAR_DESIGN_PHILOSOPHY.md: Added context connecting "bricks and studs" to self-improvement system

Principles Overview

People (6 principles)

  • Small AI-first working groups
  • Strategic human touchpoints only
  • Prompt engineering as core skill
  • Test-based verification over code review
  • Conversation-driven development
  • Human escape hatches always available

Process (13 principles)

  • Regenerate, don't edit
  • Contract-first everything
  • Tests as quality gate
  • Git as safety net
  • Continuous validation with fast feedback
  • Incremental processing as default
  • Parallel exploration by default
  • Context management as discipline
  • Git-based everything
  • Docs define, not describe
  • Prompt versioning and testing
  • Contract evolution with migration paths
  • Cost and token budgeting

Technology (18 principles)

  • Self-modifying AI-first codebase
  • Limited and domain-specific by design
  • Separation of concerns through layered virtualization
  • Protected self-healing kernel
  • Long-running agent processes
  • Simple interfaces by design
  • Stateless by default
  • Disposable components everywhere
  • CLI-first design
  • Tool ecosystems as extensions
  • Observability baked in
  • Idempotency by design
  • Error recovery patterns built in
  • Graceful degradation by design
  • Feature flags as deployment strategy
  • Least-privilege automation with scoped permissions
  • Dependency pinning and security scanning
  • Declarative over imperative

Governance & Operations (7 principles)

  • Access control and compliance as first-class
  • Metrics and evaluation everywhere
  • Knowledge stewardship and institutional memory
  • Adaptive sandboxing with explicit approvals
  • Data governance and privacy controls
  • Model lifecycle management
  • Self-serve recovery with known-good snapshots

Documentation Structure

Creates coherent hierarchy:

AMPLIFIER_SELF_IMPROVEMENT_PHILOSOPHY.md (WHY - 44 core principles)
├─ IMPLEMENTATION_PHILOSOPHY.md (HOW - ruthless simplicity)
├─ MODULAR_DESIGN_PHILOSOPHY.md (HOW - bricks and studs)
├─ AGENTS.md (WHAT - tactical agent guidelines)
└─ DISCOVERIES.md (LEARNED - operational lessons)

Impact

This framework:

  • Ensures consistent self-improvement practices across all AI agents
  • Guides architecture decisions for a self-modifying system
  • Establishes governance and operational requirements
  • Provides strategic context for tactical implementation decisions
  • Makes Amplifier's self-improvement capability explicit and documented

Testing

  • All documentation files render correctly
  • Cross-references are accurate
  • Philosophy integrates with existing documentation structure
  • No code changes, documentation only

🤖 Generated with Claude Code

@michaeljabbour
feat: Add global Amplifier access system
ca1cf68
🌍 Enable Amplifier's powerful AI agents and tools on any codebase, anywhere
This major enhancement allows developers to harness Amplifier's 20+ specialized
agents (zen-architect, bug-hunter, security-guardian, etc.) on any project
without copying files or modifying existing repositories.
✨ New Features:
- Global 'amplifier' command for system-wide access
- Smart auto-detection of Amplifier installation location
- Enhanced startup scripts with comprehensive error handling
- Seamless integration with existing Claude workflows
- Cross-platform compatibility (macOS, Linux, WSL)
🚀 Usage:
make install-global # Install global command
amplifier ~/my-project # Use Amplifier on any project
amplifier --help # Show usage examples
📈 Benefits:
- All 20+ specialized agents available on any codebase
- Shared knowledge base across all projects
- Same powerful automation and quality tools
- Project isolation - changes only affect target project
- No need to modify or copy files to existing projects
🔧 Implementation:
- Enhanced amplifier-anywhere.sh with robust error handling
- New bin/amplifier wrapper for global installation
- Updated Makefile with install-global targets
- Comprehensive documentation in README
- Fixed Claude settings path resolution
This democratizes access to Amplifier's AI development superpowers,
making every codebase instantly compatible with the full Amplifier toolkit.
@michaeljabbour
fix: Improve argument parsing in amplifier-anywhere.sh
2124f5b
- Fix handling of Claude flags when no directory specified
- Ensure --version flag works correctly without triggering full startup
- Improve argument parsing logic to handle edge cases
- Maintain backward compatibility with all usage patterns
Tested scenarios:
✅ amplifier --version (shows version only)
✅ amplifier --print 'command' (uses current dir + Claude args)
✅ amplifier /path/to/project --model sonnet (explicit dir + args)
✅ amplifier /nonexistent/path (proper error handling)
✅ amplifier --help (shows help text)
@michaeljabbour
fix: Allow bin/ directory in git for global command
3090225
- Modify .gitignore to permit bin/amplifier global command
- Maintain exclusion of other build artifacts
- Enable proper version control of global installation script
@michaeljabbour
fix: Preserve original working directory in global amplifier command
bf03e27
- Modified bin/amplifier to capture and pass the original PWD
- Updated amplifier-anywhere.sh to use ORIGINAL_PWD when available
- Fixes issue where 'amplifier' from any directory would default to amplifier repo instead of current dir
@michaeljabbour
Merge remote-tracking branch 'upstream/main' into feature/global-ampl…
5a4c821
…ifier-access
@michaeljabbour
Merge feature/global-amplifier-access into main
1f6734b
@michaeljabbour
Merge remote-tracking branch 'upstream/main'
446bef2
@michaeljabbour
Merge remote-tracking branch 'upstream/main'
317feca
@michaeljabbour@claude
feat: add auto-healing system for Python code quality improvement
4a71bee
Introduces an automated code quality improvement system that analyzes Python modules for complexity, type errors, and code health, then uses Claude to refactor and simplify unhealthy code.
Core Features:
- Health monitoring and scoring (0-100 scale) based on cyclomatic complexity, LOC, and type errors
- Claude-powered code refactoring via direct SDK integration
- Git branch creation for safe, trackable improvements
- Atomic file writes to prevent corruption
- Validation of improvements before committing
- Configurable health threshold and batch size
CLI Interface:
- `amplifier heal` - Check and heal unhealthy modules
- `amplifier heal --check-only` - Report health without healing
- `amplifier heal --max N` - Heal up to N modules
- `amplifier heal --threshold N` - Custom health threshold
- `amplifier heal --yes` - Skip confirmation prompt
Claude Code Integration:
- `/heal` slash command with all CLI options
- Graceful cancellation handling (Ctrl+C)
- Clear progress and results reporting
Safety Features:
- Timestamped git branches for each healing session
- Clean working tree checks
- File size limit (400 lines) to prevent timeouts
- Critical file patterns skipped (__init__, setup, config, test_)
- Syntax and import validation before committing
Files Added:
- amplifier/cli/ - Click-based CLI framework
- amplifier/healing/ - Healing prompts
- amplifier/tools/ - Health monitoring, git utils, Claude integration
- .claude/commands/heal.md - Command documentation
- .claude/slash_commands/heal.py - Slash command wrapper
- test_claude_healer.py - Integration tests
Files Modified:
- pyproject.toml - Added [project.scripts] entry point
- Makefile - Added install-global target
- README.md - Added comprehensive auto-healing documentation
- .gitignore - Added .amplifier/ runtime directory
- CLAUDE.md - Added REPOSITORY_GUIDELINES.md import
- REPOSITORY_GUIDELINES.md - Preserved custom guidelines
Upstream Compatibility:
- Restored AGENTS.md from microsoft/amplifier
- Maintained package name as "workspace"
- All changes are additive, no breaking changes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
@michaeljabbour@claude
docs: add AI-first self-improvement philosophy and architecture princ…
f537adc
…iples
Establishes comprehensive framework for how Amplifier improves itself through
AI-first development with 44 core principles organized into People, Process,
Technology, and Governance & Operations categories.
Key additions:
- AMPLIFIER_SELF_IMPROVEMENT_PHILOSOPHY.md: Complete 44-principle framework
- Integrated philosophy into CLAUDE.md, AGENTS.md, and README.md
- Added cross-references in IMPLEMENTATION_PHILOSOPHY.md and MODULAR_DESIGN_PHILOSOPHY.md
Principles cover:
- Regeneration-first development (vs editing)
- Contract-driven architecture with disposable components
- Self-modifying codebase with 95%+ AI-written code
- Test-based verification and git as safety net
- Self-healing kernel and adaptive sandboxing
- Knowledge stewardship and institutional memory
This framework guides all AI agents working on Amplifier's codebase to ensure
consistent self-improvement practices.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
@michaeljabbour

Michael J. Jabbour (michaeljabbour) commented Sep 30, 2025

Copy link
Copy Markdown
ContributorAuthor

Closing to recreate with clean base - this PR included unintended commits

@michaeljabbour
Michael J. Jabbour (michaeljabbour) deleted the feat/self-improvement-philosophy branch September 30, 2025 13:58
Michael J. Jabbour (michaeljabbour) added a commit to michaeljabbour/amplifier that referenced this pull request Sep 30, 2025
@michaeljabbour@claude
feat: complete all 44 AI-first principles specifications
8ead3a7
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>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@michaeljabbour