mapify-cli 1.0.0__tar.gz

mapify_cli-1.0.0/.claude/agents/README.md

@@ -0,0 +1,183 @@
+# MAP Agent Architecture
+
+This directory contains agent prompts for the MAP (Modular Agentic Planner) framework.
+
+## ⚠️ CRITICAL: Template Variables
+
+**DO NOT REMOVE Handlebars template syntax!**
+
+Agent files use **Handlebars templating** (`{{variable}}`, `{{#if}}...{{/if}}`) for runtime context injection by the Orchestrator agent.
+
+### Why Template Variables Exist
+
+```
+┌─────────────────┐
+│   Orchestrator  │  Fills in context at runtime
+└────────┬────────┘
+         │ {{language}} = "python"
+         │ {{project_name}} = "my-api"
+         │ {{#if playbook_bullets}} = [patterns from Curator]
+         │ {{#if feedback}} = [corrections from Monitor]
+         ↓
+┌─────────────────┐
+│  Actor Agent    │  Receives fully-populated prompt
+└─────────────────┘
+```
+
+### Template Variables by Category
+
+#### Context Injection (Orchestrator → All Agents)
+- `{{language}}` - Project programming language (python, go, javascript, etc.)
+- `{{framework}}` - Framework in use (FastAPI, Django, React, etc.)
+- `{{project_name}}` - Current project name
+- `{{standards_url}}` - Link to coding standards
+- `{{branch}}` - Current git branch
+- `{{related_files}}` - Files relevant to the task
+
+#### Task Specification (TaskDecomposer → Actor)
+- `{{subtask_description}}` - The specific subtask to implement
+- `{{allowed_scope}}` - Files/directories Actor is allowed to modify
+
+#### ACE Learning System (Curator → Actor)
+- `{{#if playbook_bullets}}...{{/if}}` - Proven patterns from past successes
+- This is how the system learns and improves over time
+- Curator analyzes successful implementations and adds to playbook
+- Actor gets relevant patterns automatically injected
+
+#### Feedback Loops (Monitor → Actor)
+- `{{#if feedback}}...{{/if}}` - Corrections from Monitor after failed attempt
+- Enables iterative refinement: Actor → Monitor → Actor (with feedback)
+- Critical for quality assurance
+
+### What Happens If You Remove Them
+
+| Removed | Impact | Severity |
+|---------|--------|----------|
+| `{{language}}` | Actor doesn't know what language to use | 🔴 Critical |
+| `{{project_name}}` | Generic code, doesn't match project style | 🟡 Major |
+| `{{#if playbook_bullets}}` | **Breaks ACE learning system** | 🔴 Critical |
+| `{{#if feedback}}` | **Breaks Monitor → Actor retry** | 🔴 Critical |
+| `{{subtask_description}}` | Actor doesn't know what to implement | 🔴 Critical |
+
+### How to Safely Customize Agents
+
+✅ **Safe modifications:**
+```markdown
+# Add new MCP tools
+6. **mcp__my-tool__my-function** - Custom functionality
+   - Use for specific use cases
+   - Example: my_tool(param="value")
+
+# Add domain-specific instructions
+# SECURITY REQUIREMENTS
+- All inputs must be validated
+- Use parameterized queries for SQL
+- Never log sensitive data
+
+# Adjust output format
+# OUTPUT FORMAT (extended)
+5. **Security Analysis**: List potential vulnerabilities
+6. **Performance Impact**: Expected performance characteristics
+```
+
+❌ **Unsafe modifications:**
+```markdown
+# ❌ Removing template variables
+-{{language}}  # DON'T DO THIS
+-{{project_name}}  # DON'T DO THIS
+
+# ❌ Removing conditional blocks
+-{{#if playbook_bullets}}  # DON'T DO THIS
+-{{/if}}
+
+# ❌ Simplifying "verbose" sections
+-# PLAYBOOK CONTEXT (ACE)  # This is critical infrastructure!
+```
+
+## Git Pre-commit Hook
+
+A pre-commit hook at `.git/hooks/pre-commit` validates that critical template variables are present before allowing commits.
+
+**Required patterns checked:**
+- `{{language}}`
+- `{{project_name}}`
+- `{{#if playbook_bullets}}`
+- `{{#if feedback}}`
+- `{{subtask_description}}`
+
+**To bypass (not recommended):**
+```bash
+git commit --no-verify
+```
+
+## Testing Agent Modifications
+
+After modifying an agent, test the **full workflow**, not just the agent in isolation:
+
+```bash
+# ❌ Wrong: Test agent standalone
+claude --agents '{"actor": {"prompt": "$(cat .claude/agents/actor.md)"}}' --print "implement feature"
+
+# ✅ Right: Test via Orchestrator (full MAP workflow)
+/map-feature implement simple calculator with add/subtract
+```
+
+The Orchestrator workflow ensures:
+1. TaskDecomposer breaks down the task
+2. Orchestrator fills in all template variables
+3. Actor receives fully-populated prompt with context
+4. Monitor validates the output
+5. Feedback loops work correctly
+
+## Understanding Handlebars Syntax
+
+If you see these patterns in agent files, **they are NOT comments**:
+
+```handlebars
+{{variable}}              → Replaced with actual value
+{{#if condition}}...{{/if}} → Conditional block (included if condition true)
+{{#each items}}...{{/each}} → Loop over items
+```
+
+**Example:**
+
+Before (in agent file):
+```markdown
+Project: {{project_name}}
+Language: {{language}}
+
+{{#if feedback}}
+FEEDBACK FROM PREVIOUS ATTEMPT:
+{{feedback}}
+{{/if}}
+```
+
+After (when Orchestrator invokes Actor):
+```markdown
+Project: my-api
+Language: python
+
+FEEDBACK FROM PREVIOUS ATTEMPT:
+The function is missing error handling for invalid inputs.
+Please add try/except blocks.
+```
+
+## Need Help?
+
+- **Question:** "Can I simplify this verbose agent prompt?"
+  - **Answer:** Check if it contains `{{templates}}` first. If yes, **DO NOT remove**.
+
+- **Question:** "Why is the playbook section so long?"
+  - **Answer:** It's dynamically filled by Curator. It's empty initially, grows with learning.
+
+- **Question:** "Can I remove unused template variables?"
+  - **Answer:** No. They're used by Orchestrator even if they look unused in the file.
+
+- **Question:** "The agent works fine without templates in my test."
+  - **Answer:** You tested it standalone. Test via `/map-feature` (Orchestrator workflow).
+
+## References
+
+- [MAP Framework Paper](https://github.com/Shanka123/MAP)
+- [ACE Framework Paper](https://arxiv.org/abs/2510.04618v1)
+- [Handlebars Documentation](https://handlebarsjs.com/)

mapify_cli-1.0.0/.claude/hooks/README.md

@@ -0,0 +1,55 @@
+# MAP Framework - Claude Code Hooks
+
+This directory contains Claude Code hooks for the MAP Framework.
+
+## Active Hooks
+
+### PreToolUse - Template Variable Validation
+
+**Hook**: `validate-agent-templates.sh`
+**Triggers**: Before `Edit` or `Write` operations on `.claude/agents/*.md` files
+**Purpose**: Prevents accidental removal of critical template variables
+
+**Template Variables Protected**:
+- `{{language}}` - Programming language context
+- `{{project_name}}` - Project name
+- `{{framework}}` - Framework context
+- `{{#if playbook_bullets}}` - ACE learning system
+- `{{#if feedback}}` - Monitor→Actor retry loops
+- `{{subtask_description}}` - Task specification
+
+**How It Works**:
+1. Detects when agent files are being modified
+2. Checks staged content for required template variables
+3. Blocks commit if variables are missing
+4. Provides clear error message
+
+**Override** (use carefully):
+```bash
+git commit --no-verify
+```
+
+## Removed Hooks
+
+The following hooks were removed because **bash hooks cannot call MCP tools**:
+
+- ❌ `auto-store-knowledge.sh` (PostToolUse) - Tried to call cipher MCP
+- ❌ `enrich-context.sh` (UserPromptSubmit) - Tried to search cipher MCP
+- ❌ `session-init.sh` (SessionStart) - Tried to load from cipher MCP
+- ❌ `track-metrics.sh` (SubagentStop) - Tried to store metrics in cipher MCP
+
+**Why Removed**: Bash hooks execute outside Claude Code's context and cannot invoke MCP tools.
+
+**Alternative**: Call MCP tools directly within agent prompts or slash commands.
+
+## Best Practices
+
+**DO Use Hooks For**:
+- ✅ File validation (grep, regex)
+- ✅ Git operations (status, diff)
+- ✅ Static analysis (linters)
+
+**DON'T Use Hooks For**:
+- ❌ MCP tool calls
+- ❌ Interactive prompts
+- ❌ Long operations (>10s timeout)

mapify_cli-1.0.0/.gitignore

@@ -0,0 +1,57 @@
+
+.clinerules/cipher-rules.md
+.kilocode/rules/cipher-rules.md
+.roo/rules/cipher-rules.md
+.windsurf/rules/cipher-rules.md
+.cursor/rules/cipher-rules.mdc
+.kiro/steering/cipher-rules.md
+.qoder/rules/cipher-rules.md
+.augment/rules/cipher-rules.md
+.reviews
+.coverage
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+data/
+htmlcov/
+
+# ACE Playbook - user-specific data
+.claude/embeddings_cache/
+.claude/playbook.json
+.claude/mcp_config.json
+.claude/commands/
+
+# Agent template backups
+src/mapify_cli/templates/agents.backup/
+
+# Research papers (optional, can commit if needed as docs)
+*.pdf
+coverage.json
+
+# Claude Code hooks runtime files
+.claude/sessions/
+.claude/metrics/
+.map/
+
+# Temporary verification files
+mapify_cli_verification_*.json

mapify_cli-1.0.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: mapify-cli
+Version: 1.0.0
+Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
+Project-URL: Homepage, https://github.com/azalio/map-framework
+Project-URL: Repository, https://github.com/azalio/map-framework.git
+Project-URL: Issues, https://github.com/azalio/map-framework/issues
+Author: MAP Framework Contributors
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: readchar>=4.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: ssl
+Requires-Dist: truststore>=0.9.0; extra == 'ssl'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MAP Framework for Claude Code
+
+Implementation of **Modular Agentic Planner (MAP)** — a cognitive architecture for AI agents inspired by prefrontal cortex functions. Orchestrates 8 specialized agents for development with automatic quality validation.
+
+> **Based on:** [Nature Communications research (2025)](https://github.com/Shanka123/MAP) — 74% improvement in planning tasks
+> **Enhanced with:** [ACE (Agentic Context Engineering)](https://arxiv.org/abs/2510.04618v1) — continuous learning from experience
+
+## 📖 Documentation Structure
+
+- **README** (this file) - Quick start and overview
+- **[INSTALL.md](docs/INSTALL.md)** - Complete installation guide with PATH setup and troubleshooting
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical deep dive, customization, and MCP integration
+- **[USAGE.md](docs/USAGE.md)** - Practical examples, best practices, and cost optimization
+
+## 🚀 Quick Start
+
+### Inside Claude Code (Recommended)
+
+```bash
+# Feature development
+/map-feature implement user authentication with JWT tokens
+
+# Debugging
+/map-debug fix the API 500 error on login endpoint
+
+# Refactoring
+/map-refactor refactor UserService class with dependency injection
+
+# Code review
+/map-review review the recent changes in auth.py
+```
+
+### Command Line Usage
+
+MAP Framework works exclusively through slash commands in Claude Code:
+
+```bash
+# Start Claude Code in your project directory
+cd your-project
+claude
+
+# Use slash commands inside Claude Code
+/map-feature implement user authentication with JWT tokens
+```
+
+**Note:** Direct `claude --agents` syntax is not applicable to MAP Framework, as the orchestration logic is implemented in slash command prompts (`.claude/commands/map-*.md`), not as a separate agent file.
+
+## 📦 Installation
+
+### Stable Release (Recommended)
+
+```bash
+# Using pip
+pip install mapify-cli
+
+# OR using UV (recommended for isolated tools)
+uv tool install mapify-cli
+
+# Verify installation
+mapify --version
+
+# Initialize in your project
+cd your-project
+mapify init
+```
+
+**Version Pinning:**
+```bash
+# Install specific version
+pip install mapify-cli==1.0.0
+
+# Install with version constraints (semantic versioning: MAJOR.MINOR.PATCH)
+pip install "mapify-cli>=1.0.0,<2.0.0"  # Allow 1.x versions, exclude 2.0.0+
+```
+
+**Version Information:**
+- Check installed version: `mapify --version`
+- [PyPI releases](https://pypi.org/project/mapify-cli/) - Available versions and package details
+- [GitHub releases](https://github.com/azalio/map-framework/releases) - Changelog and release notes
+
+### Development Installation
+
+For contributors or testing bleeding-edge features:
+
+```bash
+# Install from git repository
+uv tool install --from git+https://github.com/azalio/map-framework.git mapify-cli
+
+# OR clone and install locally
+git clone https://github.com/azalio/map-framework.git
+cd map-framework
+pip install -e .
+```
+
+**Other installation methods** (manual copy, troubleshooting): See [INSTALL.md](docs/INSTALL.md)
+
+**For maintainers**: Release process documented in [RELEASING.md](RELEASING.md)
+
+## Requirements
+
+- **Claude Code CLI** — installed and configured
+- **Python 3.11+** — for mapify CLI (optional)
+- **Git** — for cloning repository
+
+## 🏗️ Architecture
+
+MAP Framework orchestrates 8 specialized agents through slash commands:
+
+- **TaskDecomposer** breaks goals into subtasks
+- **Actor** generates code, **Monitor** validates quality
+- **Predictor** analyzes impact, **Evaluator** scores solutions
+- **Reflector/Curator** enable continuous learning via ACE playbook
+
+The orchestration logic lives in `.claude/commands/map-*.md` prompts, coordinating agents via the Task tool.
+
+**See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for:**
+- Detailed agent specifications and responsibilities
+- MCP integration architecture and tool usage patterns
+- Agent coordination protocol and workflow stages
+- Template customization guide with examples
+- Hooks integration (automated validation, knowledge storage, context enrichment)
+- Context engineering principles and optimizations
+
+## 🔌 MCP Integration
+
+MAP uses MCP (Model Context Protocol) servers for enhanced capabilities:
+
+- **cipher** - Knowledge base for storing and retrieving successful patterns
+- **claude-reviewer** - Professional code review with security analysis
+- **context7** - Up-to-date library documentation
+- **sequential-thinking** - Chain-of-thought reasoning for complex problems
+- **codex-bridge** - AI code generation (requires extended timeout)
+- **deepwiki** - GitHub repository intelligence
+
+Configuration files: `.claude/mcp_config.json` and `mcp_config.json`
+
+**See [ARCHITECTURE.md](docs/ARCHITECTURE.md#mcp-integration) for complete setup and usage patterns**
+
+## 📚 Usage Examples
+
+```bash
+# Feature development
+/map-feature implement user profile page with avatar upload
+
+# Bug fixing
+/map-debug debug why payment processing fails for amounts over $1000
+
+# Refactoring
+/map-refactor refactor OrderService to use dependency injection
+```
+
+**See [USAGE.md](docs/USAGE.md) for:**
+- Comprehensive usage examples with detailed scenarios
+- Best practices for optimal results
+- Cost optimization strategies (40-60% savings)
+- Playbook management commands
+
+## 🎓 ACE Playbook
+
+Built-in learning system that improves with each task:
+
+- **Reflector** extracts patterns from successes and failures
+- **Curator** maintains structured knowledge base with quality tracking
+- **Semantic search** (optional) finds patterns by meaning, not keywords
+- Automatically grows high-quality pattern library
+
+### Playbook Commands
+
+```bash
+# View statistics
+mapify playbook stats
+
+# Search patterns
+mapify playbook search "JWT authentication"
+
+# View high-quality patterns
+mapify playbook sync
+```
+
+**Optional semantic search**: `pip install -r requirements-semantic.txt` for meaning-based matching. Details in [SEMANTIC_SEARCH_SETUP.md](docs/SEMANTIC_SEARCH_SETUP.md) and [ARCHITECTURE.md](docs/ARCHITECTURE.md#semantic-search).
+
+**Playbook configuration**: See [ARCHITECTURE.md](docs/ARCHITECTURE.md#playbook-configuration) for top_k settings and optimization.
+
+## 💰 Cost Optimization
+
+MAP Framework uses intelligent model selection per agent:
+
+- **Predictor & Evaluator** use **haiku** (fast analysis) → ⬇️⬇️⬇️ cost
+- **Actor, Monitor, Reflector, Curator** use **sonnet** (quality-critical) → balanced cost
+
+**Result:** 40-60% cost reduction vs all-sonnet while maintaining code quality.
+
+**See [USAGE.md](docs/USAGE.md#cost-optimization) for detailed cost breakdown and model override strategies**
+
+## 🔗 Hooks Integration
+
+MAP integrates with Claude Code hooks for automated validation, knowledge storage, and context enrichment. Active hooks protect template variables, auto-store successful patterns, enrich prompts with relevant knowledge, and track performance metrics.
+
+**See [ARCHITECTURE.md](docs/ARCHITECTURE.md#hooks-integration) and [.claude/hooks/README.md](.claude/hooks/README.md) for configuration**
+
+## 🛠️ Troubleshooting
+
+### Command Not Found
+
+```
+Error: Slash command not recognized
+```
+
+**Solution:**
+- Ensure you're in a directory with `.claude/commands/` containing `map-*.md` files
+- Use `/map-feature`, `/map-debug`, `/map-refactor`, or `/map-review`
+- Run `/help` to see available commands
+
+### Agent Not Found
+
+```
+Error: Agent file not found
+```
+
+**Solution:** Ensure `.claude/agents/` directory contains all 8 agent files (task-decomposer.md, actor.md, monitor.md, predictor.md, evaluator.md, reflector.md, curator.md, documentation-reviewer.md)
+
+### Semantic Search Warning
+
+```
+Warning: sentence-transformers not installed
+```
+
+**Solution:** `pip install -r requirements-semantic.txt`
+See [SEMANTIC_SEARCH_SETUP.md](docs/SEMANTIC_SEARCH_SETUP.md) for detailed troubleshooting
+
+### Infinite Loops
+
+```
+Actor-Monitor loop exceeding iterations
+```
+
+**Solution:** Orchestrator limits iterations to 3-5. Clarify requirements or add constraints.
+
+**More troubleshooting**: See [INSTALL.md](docs/INSTALL.md#troubleshooting) for PATH issues, MCP configuration, and installation problems
+
+## 🔧 Customization
+
+Agent prompts in `.claude/agents/*.md` use Handlebars template syntax for dynamic context injection. You can safely modify instructions, examples, and validation criteria, but **MUST NOT remove template variables** like `{{language}}`, `{{#if playbook_bullets}}`, or `{{feedback}}` — these are critical for orchestration and ACE learning.
+
+**See [ARCHITECTURE.md](docs/ARCHITECTURE.md#customization-guide) for:**
+- Safe vs unsafe modifications with examples
+- Template variable reference
+- Model selection per agent
+- Adding custom agents
+- Template validation and git hooks
+
+## 📊 Success Metrics
+
+- **Monitor approval rate:** >80% first try
+- **Evaluator scores:** average >7.0/10
+- **Iteration count:** <3 per subtask
+- **Playbook growth:** increasing high-quality patterns
+
+## 🤝 Contributing
+
+Improvements welcome:
+- Prompts for specific languages/frameworks
+- New specialized agents
+- CI/CD integrations
+- Success story examples
+- Plugin extensions for MAP Framework
+
+## 📄 License
+
+MIT License — see LICENSE file for details
+
+## 🔗 References
+
+- [MAP Paper - Nature Communications](https://github.com/Shanka123/MAP)
+- [ACE Paper - arXiv:2510.04618v1](https://arxiv.org/abs/2510.04618v1)
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+
+---
+
+**MAP is not just automation — it's systematic quality improvement through structured validation and iterative refinement.**