mapify-cli 1.2.1__tar.gz → 1.2.3__tar.gz

{mapify_cli-1.2.1 → mapify_cli-1.2.3}/.claude/hooks/README.md

@@ -4,17 +4,16 @@ This directory contains Claude Code hooks for the MAP Framework.
 
 ## Active Hooks
 
-### UserPromptSubmit - Playbook Auto-Injection
+### UserPromptSubmit - Playbook Auto-Injection + Workflow Suggestion
 
 **Hook**: `user-prompt-submit.sh`
 **Triggers**: Before user prompt is submitted to Claude Code
-**Purpose**: Automatically injects relevant playbook bullets to enhance context
+**Purpose**: Automatically injects relevant playbook bullets AND suggests appropriate MAP workflows based on context
 
 **How It Works**:
-1. Extracts keywords from user message (filters stop words, handles unicode)
-2. Queries local playbook using `mapify playbook query` CLI
-3. Formats top 5 relevant bullets as markdown
-4. Injects as `additionalContext` field in JSON response
+1. **Playbook Injection**: Extracts keywords from user message, queries playbook, formats top 5 relevant bullets
+2. **Workflow Suggestion**: Matches user message against workflow-rules.json triggers, suggests best workflow (map-debug, map-feature, etc.)
+3. Combines both outputs as `additionalContext` field in JSON response
 
 **Configuration** (edit `user-prompt-submit.sh`):
 ```bash
@@ -269,3 +268,52 @@ The following hooks were removed because **bash hooks cannot call MCP tools**:
 - ❌ MCP tool calls
 - ❌ Interactive prompts
 - ❌ Long operations (>10s timeout)
+
+## Workflow Auto-Activation System
+
+**File**: `.claude/workflow-rules.json`
+**Purpose**: Automatically suggest appropriate MAP workflows based on user prompt keywords
+
+**How It Works**:
+1. User submits prompt: "Fix the failing tests in auth.test.ts"
+2. Hook matches keywords against workflow-rules.json triggers
+3. Suggests `/map-debug` workflow with reason: "Keywords: fix, failing test"
+4. Session tracking prevents repeated suggestions
+
+**Supported Workflows**:
+- `map-debug` - Bug fixes, test failures, debugging
+- `map-feature` - New features, critical implementations
+- `map-efficient` - Production code, optimizations
+- `map-refactor` - Code restructuring, cleanup
+- `map-fast` - Quick prototypes, throwaway code
+
+**Customization** (edit `.claude/workflow-rules.json`):
+```json
+{
+  "workflows": {
+    "map-debug": {
+      "priority": "high",
+      "promptTriggers": {
+        "keywords": ["bug", "error", "failing test", "fix"],
+        "intentPatterns": ["(fix|debug).*?(bug|test)"]
+      }
+    }
+  }
+}
+```
+
+**Session Tracking**:
+- Suggestions stored in `.claude/cache/workflow_suggestions_session.txt`
+- One workflow suggested per session (avoids annoyance)
+- Clear cache: `rm .claude/cache/workflow_suggestions_session.txt`
+
+**Testing**:
+```bash
+# Run auto-activation tests
+.claude/hooks/tests/test_auto_activation.sh
+```
+
+**Security** (P0 fixes applied):
+- ✅ Stdin input (prevents command injection)
+- ✅ Quoted heredoc (prevents variable expansion)
+- ✅ Regex timeout protection (prevents ReDoS attacks)

mapify_cli-1.2.3/.claude/skills/README.md

@@ -0,0 +1,205 @@
+# MAP Skills System
+
+## What are Skills?
+
+**Skills** = Passive documentation modules (NOT agents!)
+
+Skills provide specialized guidance without executing code. They help users understand MAP Framework concepts and make informed decisions.
+
+## Skills vs Agents
+
+| Skills | Agents |
+|--------|--------|
+| **Passive** documentation | **Active** execution |
+| Load via Skill tool | Execute via Task tool |
+| Provide guidance | Write code |
+| Progressive disclosure (<500 lines) | Full specification (orchestrated) |
+| User-initiated | Workflow-initiated |
+
+**Example:**
+- **Skill:** map-workflows-guide (explains when to use each workflow)
+- **Agent:** actor.md (implements code based on workflow)
+
+---
+
+## Available Skills
+
+### map-workflows-guide
+
+**Purpose:** Help users choose the right MAP workflow for their task
+
+**Triggers:** (auto-suggested when user prompts match)
+- Keywords: "which workflow", "difference between", "when to use"
+- Intent patterns: Questions about workflow selection
+
+**Content:**
+- Quick decision tree (5 questions)
+- Workflow comparison matrix (5 workflows)
+- Detailed workflow descriptions
+- Agent architecture overview
+- 8 deep-dive resource files
+
+**How to use:**
+```
+User: "Which workflow should I use for implementing auth?"
+MAP: [Auto-suggests map-workflows-guide skill]
+User: "Load map-workflows-guide"
+MAP: [Shows decision tree and comparison matrix]
+```
+
+**Resources available:**
+- `map-fast-deep-dive.md` - When (not) to use /map-fast
+- `map-efficient-deep-dive.md` - Optimization strategies
+- `map-feature-deep-dive.md` - Full validation workflow
+- `map-debug-deep-dive.md` - Debugging techniques
+- `map-refactor-deep-dive.md` - Dependency analysis
+- `agent-architecture.md` - How 8 agents orchestrate
+- `playbook-system.md` - Knowledge storage and search
+- `cipher-integration.md` - Cross-project learning
+
+---
+
+## Creating New Skills
+
+See [docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md](../docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md) for:
+- Skill structure (SKILL.md + resources/)
+- 500-line rule (progressive disclosure pattern)
+- Integration with auto-activation
+- Testing procedures
+
+### Skill Structure Template
+
+```
+.claude/skills/my-skill/
+├── SKILL.md                      # Main entry (<500 lines)
+│   ├── Frontmatter (YAML)
+│   ├── Quick overview
+│   ├── Decision support
+│   └── Links to resources/
+└── resources/
+    ├── topic-1-deep-dive.md     # Detailed exploration
+    ├── topic-2-deep-dive.md
+    └── reference-guide.md       # Quick reference
+```
+
+### Frontmatter Format
+
+```yaml
+---
+name: my-skill
+description: Brief description of what this skill provides
+version: 1.0
+---
+```
+
+---
+
+## Integration with Auto-Activation
+
+Skills work seamlessly with P0 auto-activation system:
+
+**How it works:**
+1. User prompt analyzed by `user-prompt-submit.sh` hook
+2. Hook checks `skill-rules.json` for matching triggers
+3. If match found: Suggests skill to user
+4. User can load skill for detailed guidance
+
+**Configuration:**
+- **Trigger definitions:** `.claude/skills/skill-rules.json`
+- **Auto-activation hook:** `.claude/hooks/user-prompt-submit.sh`
+- **Helper script:** `.claude/hooks/helpers/suggest_skill.py`
+
+---
+
+## File Structure
+
+```
+.claude/skills/
+├── skill-rules.json                  # Trigger configuration for all skills
+├── README.md                         # This file
+└── map-workflows-guide/
+    ├── SKILL.md                      # Main entry (<500 lines)
+    └── resources/
+        ├── map-fast-deep-dive.md
+        ├── map-efficient-deep-dive.md
+        ├── map-feature-deep-dive.md
+        ├── map-debug-deep-dive.md
+        ├── map-refactor-deep-dive.md
+        ├── agent-architecture.md
+        ├── playbook-system.md
+        └── cipher-integration.md
+```
+
+---
+
+## Best Practices
+
+### For Skill Authors
+
+1. **Follow 500-line rule** - Main SKILL.md should be scannable (~5 min read)
+2. **Progressive disclosure** - Details in resources/, linked from main
+3. **Clear triggers** - Define specific keywords and intent patterns
+4. **Examples over theory** - Show concrete use cases
+5. **Link related resources** - Cross-reference other skills/docs
+
+### For Users
+
+1. **Trust auto-suggestions** - Skills are triggered for good reasons
+2. **Load skills proactively** - Don't guess, get guidance
+3. **Explore resources** - Deep-dives provide comprehensive context
+4. **Apply patterns** - Skills show "why" and "when", not just "how"
+
+---
+
+## Troubleshooting
+
+### Skill not auto-suggesting
+
+**Check:**
+1. `skill-rules.json` has correct triggers
+2. Hook reads `skill-rules.json` successfully
+3. Test keyword matching manually:
+   ```bash
+   echo "which workflow should I use" | .claude/hooks/helpers/suggest_skill.py --rules .claude/skills/skill-rules.json
+   ```
+
+**Fix:** Update trigger patterns in `skill-rules.json`
+
+### Skill content too long
+
+**Problem:** Main SKILL.md exceeds 500 lines
+
+**Solution:**
+1. Move detailed sections to `resources/`
+2. Keep only overview + navigation in main file
+3. Add links to resources for deep dives
+
+### Resources not loading
+
+**Check:**
+1. Resource files exist in `resources/` directory
+2. Links in SKILL.md use correct paths
+3. Markdown link syntax is valid
+
+---
+
+## Metrics
+
+**Track skill effectiveness:**
+- Activation rate (how often skills are suggested)
+- Load rate (how often users load suggested skills)
+- Resource access (which deep-dives are most popular)
+- Workflow confusion reduction (before/after P1)
+
+**Target metrics:**
+- >30% of sessions load a skill
+- ~50% reduction in "which workflow?" questions
+- Correct workflow selection rate >80%
+
+---
+
+## See Also
+
+- [P1 Implementation Plan](../docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md)
+- [Auto-Activation System](../docs/auto-activation-comparison.md)
+- [MAP Architecture](../docs/ARCHITECTURE.md)

{mapify_cli-1.2.1 → mapify_cli-1.2.3}/.gitignore

@@ -43,7 +43,6 @@ htmlcov/
 .claude/playbook.db-shm
 .claude/playbook.db-wal
 .claude/mcp_config.json
-.claude/commands/
 
 # Agent template backups
 src/mapify_cli/templates/agents.backup/
@@ -55,6 +54,7 @@ coverage.json
 # Claude Code hooks runtime files
 .claude/sessions/
 .claude/metrics/
+.claude/cache/
 .map/
 
 # Temporary verification files
@@ -62,3 +62,15 @@ mapify_cli_verification_*.json
 
 docs/claude-task-master
 docs/awesome-claude-code
+docs/core
+docs/claude-code-infrastructure-showcase
+docs/claude-code-subagents
+
+
+# Curator temporary files
+.claude/curator_delta_operations.json
+.claude/curator_integration_report.json
+.claude/curator_operations.json
+.claude/*_integration_report.json
+.claude/apply_*_deltas.py
+.claude/insert_*_bullets.sql

{mapify_cli-1.2.1 → mapify_cli-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 1.2.1
+Version: 1.2.3
 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
@@ -168,6 +168,30 @@ MAP Framework offers three workflow variants optimized for different scenarios:
 - 🗑️ Learning/tutorial contexts where failure is acceptable
 - ⚠️ **NEVER for production code** - no learning, quality risks
 
+### 🎯 Auto-Activation System
+
+**Don't remember which workflow to use?** MAP automatically suggests the right workflow based on your request!
+
+Just describe your task naturally - no need to remember slash commands:
+
+| Your Request | MAP Suggests | Why |
+|--------------|--------------|-----|
+| "Fix the failing tests" | `/map-debug` | Keywords: fix, failing test |
+| "Implement user login" | `/map-feature` | Keywords: implement, feature |
+| "Optimize database queries" | `/map-efficient` | Keywords: optimize |
+| "Restructure auth module" | `/map-refactor` | Keywords: restructure |
+| "Quick prototype for testing" | `/map-fast` | Keywords: quick, prototype |
+
+**How it works:**
+1. Start typing your request normally
+2. MAP analyzes keywords and intent patterns
+3. Suggests the most appropriate workflow
+4. You can accept the suggestion or proceed with your request
+
+**Customization:**
+Edit `.claude/workflow-rules.json` to add project-specific trigger words and patterns.
+
+
 ### Key Differences
 
 **`/map-efficient` optimizations:**
@@ -186,6 +210,28 @@ MAP Framework offers three workflow variants optimized for different scenarios:
 
 **See [USAGE.md](docs/USAGE.md#workflow-variants) for detailed decision guide and real-world token usage examples.**
 
+## 📚 Skills System
+
+MAP includes interactive skills that provide specialized guidance:
+
+**map-workflows-guide** - Helps you choose the right workflow
+
+**Auto-suggested when you ask:**
+- "Which workflow should I use?"
+- "What's the difference between workflows?"
+- "When to use /map-efficient vs /map-feature?"
+
+**What you get:**
+- Quick decision tree (5 questions → recommended workflow)
+- Comparison matrix (token cost, learning, agents, use cases)
+- 8 detailed resource guides (progressive disclosure)
+
+**Skills vs Agents:**
+- **Skills** = Passive documentation (guidance)
+- **Agents** = Active execution (code generation)
+
+**See [docs/USAGE.md](docs/USAGE.md#skills-system) for full details.**
+
 ## Requirements
 
 - **Claude Code CLI** — installed and configured

{mapify_cli-1.2.1 → mapify_cli-1.2.3}/README.md

@@ -138,6 +138,30 @@ MAP Framework offers three workflow variants optimized for different scenarios:
 - 🗑️ Learning/tutorial contexts where failure is acceptable
 - ⚠️ **NEVER for production code** - no learning, quality risks
 
+### 🎯 Auto-Activation System
+
+**Don't remember which workflow to use?** MAP automatically suggests the right workflow based on your request!
+
+Just describe your task naturally - no need to remember slash commands:
+
+| Your Request | MAP Suggests | Why |
+|--------------|--------------|-----|
+| "Fix the failing tests" | `/map-debug` | Keywords: fix, failing test |
+| "Implement user login" | `/map-feature` | Keywords: implement, feature |
+| "Optimize database queries" | `/map-efficient` | Keywords: optimize |
+| "Restructure auth module" | `/map-refactor` | Keywords: restructure |
+| "Quick prototype for testing" | `/map-fast` | Keywords: quick, prototype |
+
+**How it works:**
+1. Start typing your request normally
+2. MAP analyzes keywords and intent patterns
+3. Suggests the most appropriate workflow
+4. You can accept the suggestion or proceed with your request
+
+**Customization:**
+Edit `.claude/workflow-rules.json` to add project-specific trigger words and patterns.
+
+
 ### Key Differences
 
 **`/map-efficient` optimizations:**
@@ -156,6 +180,28 @@ MAP Framework offers three workflow variants optimized for different scenarios:
 
 **See [USAGE.md](docs/USAGE.md#workflow-variants) for detailed decision guide and real-world token usage examples.**
 
+## 📚 Skills System
+
+MAP includes interactive skills that provide specialized guidance:
+
+**map-workflows-guide** - Helps you choose the right workflow
+
+**Auto-suggested when you ask:**
+- "Which workflow should I use?"
+- "What's the difference between workflows?"
+- "When to use /map-efficient vs /map-feature?"
+
+**What you get:**
+- Quick decision tree (5 questions → recommended workflow)
+- Comparison matrix (token cost, learning, agents, use cases)
+- 8 detailed resource guides (progressive disclosure)
+
+**Skills vs Agents:**
+- **Skills** = Passive documentation (guidance)
+- **Agents** = Active execution (code generation)
+
+**See [docs/USAGE.md](docs/USAGE.md#skills-system) for full details.**
+
 ## Requirements
 
 - **Claude Code CLI** — installed and configured

{mapify_cli-1.2.1 → mapify_cli-1.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "1.2.1"
+version = "1.2.3"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"

{mapify_cli-1.2.1 → mapify_cli-1.2.3}/src/mapify_cli/__init__.py

@@ -1116,16 +1116,28 @@ def install_hooks(project_path: Path, with_hooks: bool = True) -> int:
         hooks_count += 1
 
     # Copy helpers directory (Python helper scripts)
+    # IMPORTANT: Only copy/update files from templates, preserve user's custom files
     helpers_src = hooks_template_dir / "helpers"
     if helpers_src.exists() and helpers_src.is_dir():
         helpers_dest = hooks_dir / "helpers"
-        if helpers_dest.exists():
-            shutil.rmtree(helpers_dest)
-        shutil.copytree(helpers_src, helpers_dest)
-        # Make Python scripts executable
-        for py_file in helpers_dest.glob("*.py"):
-            if py_file.name != "__init__.py":
-                py_file.chmod(py_file.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+        helpers_dest.mkdir(exist_ok=True)  # Create dir if doesn't exist
+
+        # Copy each file individually (preserves user files not in templates)
+        for helper_file in helpers_src.rglob("*"):
+            if helper_file.is_file():
+                # Compute relative path from helpers_src
+                rel_path = helper_file.relative_to(helpers_src)
+                dest_file = helpers_dest / rel_path
+
+                # Create parent directory if needed
+                dest_file.parent.mkdir(parents=True, exist_ok=True)
+
+                # Copy template file (overwrites if exists)
+                shutil.copy2(helper_file, dest_file)
+
+                # Make Python scripts executable (except __init__.py)
+                if dest_file.suffix == ".py" and dest_file.name != "__init__.py":
+                    dest_file.chmod(dest_file.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
 
     # Copy README.md
     readme_src = hooks_template_dir / "README.md"
@@ -1837,7 +1849,7 @@ def recitation_create(
 
 @recitation_app.command("update")
 def recitation_update(
-    subtask_id: int,
+    subtask_id: str,
     status: str,
     error: Optional[str] = typer.Argument(None)
 ):