feat: implement P1 Skills System with map-workflows-guide skill by azalio · Pull Request #25 · azalio/map-framework

azalio · 2025-11-04T10:00:25Z

Summary

Implements P1 Skills System (docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md) to reduce workflow confusion by ~50%.

What's New:

Skills System architecture for passive documentation modules
map-workflows-guide skill with interactive decision tree
Auto-activation via user-prompt-submit hook
8 deep-dive resource files for workflow guidance

Key Features

Skills System Architecture

Skills: Passive documentation modules (NOT agents)
Progressive disclosure: Main SKILL.md <600 lines, details in resources/
Auto-activation: Skills suggested based on user prompts
Integration: Works seamlessly with P0 auto-activation system

map-workflows-guide Skill

Quick decision tree: 5 questions → recommended workflow
Comparison matrix: Token cost, learning, agents, use cases
8 deep-dive resources:
- map-fast-deep-dive.md (when NOT to use)
- map-efficient-deep-dive.md (optimization strategies)
- map-feature-deep-dive.md (full validation)
- map-debug-deep-dive.md (error analysis)
- map-refactor-deep-dive.md (dependency impact)
- agent-architecture.md (orchestration)
- playbook-system.md (knowledge storage)
- cipher-integration.md (cross-project learning)

Auto-Activation

Triggers:

Keywords: "which workflow", "difference between", "when to use"
Intent patterns: Questions about workflow selection

Example:

User: "which workflow should I use for authentication?"
MAP: 📚 SKILL AVAILABLE: map-workflows-guide

Implementation Details

.claude/skills/skill-rules.json: Trigger configuration (keywords, intent patterns)
.claude/hooks/helpers/suggest_skill.py: Python helper (380 lines) with regex timeout protection
.claude/hooks/user-prompt-submit.sh: Extended with STEP 2.5 for skill suggestions
Session tracking: Prevents duplicate suggestions within same session

Files Changed

Added (27 new files):

.claude/skills/skill-rules.json
.claude/skills/README.md (205 lines)
.claude/skills/map-workflows-guide/SKILL.md (577 lines)
.claude/skills/map-workflows-guide/resources/*.md (8 files, 203-346 lines each)
.claude/hooks/helpers/suggest_skill.py (380 lines)
src/mapify_cli/templates/skills/ (full sync for distribution)
src/mapify_cli/templates/hooks/helpers/suggest_skill.py

Modified:

.claude/hooks/user-prompt-submit.sh (added skill suggestion logic)
src/mapify_cli/templates/hooks/user-prompt-submit.sh
README.md (Skills System section)
docs/USAGE.md (Skills System guide)

Total: 28 files changed, 7038 insertions(+), 8 deletions(-)

Testing

Test coverage:

✅ Keyword triggers: "which workflow" → map-workflows-guide
✅ Intent patterns: "difference between map-fast and map-efficient" → match
✅ No-match cases: "implement authentication" → no suggestion (correct)
✅ Backward compatibility: Workflow suggestions still work
✅ Hook integration: Skills and workflows coexist correctly
✅ All 8 resource files exist and follow <500 line rule

Test commands:

# Test skill trigger
echo "which workflow should I use?" | python3 .claude/hooks/helpers/suggest_skill.py --rules .claude/skills/skill-rules.json

# Test full hook integration
echo "which workflow for auth?" | .claude/hooks/user-prompt-submit.sh

# Verify backward compatibility
echo "fix the failing tests" | .claude/hooks/user-prompt-submit.sh

Expected Impact

Target metrics (from implementation plan):

📊 Workflow confusion reduction: ~50%
📊 Correct workflow selection rate: >80%
📊 Skill load rate: >30% of sessions

Implementation Effort

Subtasks: 8 completed (ST-001 through ST-008)
Implementation time: ~10 hours
Workflow used: /map-efficient (batched learning)
Implementation plan: docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md

Dependencies

Depends on: P0 auto-activation system (commit dbd96ac)
Related: feat: implement P0 auto-activation system for MAP workflows #23 (auto-activation feature)

How to Test

Test skill suggestion:

# Should suggest map-workflows-guide
echo "which workflow should I use?" | .claude/hooks/user-prompt-submit.sh

Test backward compatibility:

# Should suggest /map-debug (workflow, not skill)
echo "fix the failing tests" | .claude/hooks/user-prompt-submit.sh

Load skill in Claude Code:

User: which workflow should I use for implementing authentication?
[MAP suggests map-workflows-guide skill]
User: /map-workflows-guide
[Skill loads with decision tree and resources]

Checklist

Implementation complete (all 8 subtasks)
Templates synchronized to src/mapify_cli/templates/
Documentation updated (README, USAGE, skills/README)
Testing completed (keyword, intent, backward compat)
Security review (stdin input, regex timeout, session tracking)
CI/CD passes
Manual testing in real Claude Code session

References

Implementation plan: docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md
P0 auto-activation: PR feat: implement P0 auto-activation system for MAP workflows #23, commit dbd96ac
MAP efficient workflow: .claude/commands/map-efficient.md

Closes ST-001 through ST-008 of P1 implementation plan.

Implements P1 Skills System (docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md) to reduce workflow confusion by ~50%. ## What's New ### Skills System Architecture - **Skills**: Passive documentation modules (NOT agents) - **Progressive disclosure**: Main SKILL.md <600 lines, details in resources/ - **Auto-activation**: Skills suggested based on user prompts - **Integration**: Works seamlessly with P0 auto-activation system ### map-workflows-guide Skill - **Quick decision tree**: 5 questions → recommended workflow - **Comparison matrix**: Token cost, learning, agents, use cases - **8 deep-dive resources**: map-fast, map-efficient, map-feature, map-debug, map-refactor, agent-architecture, playbook-system, cipher-integration - **Auto-triggers**: "which workflow", "difference between", "when to use" ### Implementation Details - `.claude/skills/skill-rules.json`: Trigger configuration (keywords, intent patterns) - `.claude/hooks/helpers/suggest_skill.py`: Python helper (380 lines) with regex timeout protection - `.claude/hooks/user-prompt-submit.sh`: Extended with STEP 2.5 for skill suggestions - Session tracking: Prevents duplicate suggestions within same session ### Files Added - .claude/skills/skill-rules.json - .claude/skills/README.md (205 lines) - .claude/skills/map-workflows-guide/SKILL.md (577 lines) - .claude/skills/map-workflows-guide/resources/*.md (8 files, 203-346 lines each) - .claude/hooks/helpers/suggest_skill.py (380 lines) ### Templates Synchronized All skill files synced to src/mapify_cli/templates/ for distribution via `mapify init` ### Documentation Updated - README.md: Skills System section - docs/USAGE.md: Skills System section with examples - .claude/skills/README.md: Skills architecture and best practices ## Testing - ✅ Keyword triggers: "which workflow" → map-workflows-guide - ✅ Intent patterns: "difference between map-fast and map-efficient" → match - ✅ No-match cases: "implement authentication" → no suggestion (correct) - ✅ Backward compatibility: Workflow suggestions still work - ✅ Hook integration: Skills and workflows coexist correctly - ✅ All 8 resource files exist and follow line count rules ## Effort - Implementation time: ~10 hours (ST-001 through ST-008) - 8 subtasks completed - Used /map-efficient workflow (batched learning) ## References - Implementation plan: docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md - P0 auto-activation: commit dbd96ac - MAP efficient workflow: .claude/commands/map-efficient.md Closes ST-001 through ST-008 of P1 implementation plan.

Copilot

Pull Request Overview

This PR implements a comprehensive Skills System (P1) that provides passive documentation modules to help users choose the right MAP workflow. The system includes auto-activation hooks that suggest relevant skills based on user prompts, with the first skill being "map-workflows-guide" containing detailed workflow selection guidance.

Key Changes:

Added a new Skills System with auto-suggestion capability via user prompt hooks
Created the map-workflows-guide skill with 8 detailed resource guides
Enhanced the user-prompt-submit hook to suggest skills alongside workflows
Added session tracking to prevent duplicate skill suggestions

Reviewed Changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`src/mapify_cli/templates/skills/skill-rules.json`	Trigger configuration for skill auto-activation
`src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md`	Main skill entry point with decision tree and workflow comparisons
`src/mapify_cli/templates/skills/map-workflows-guide/resources/*.md`	Eight deep-dive resource files covering workflows and system architecture
`src/mapify_cli/templates/hooks/user-prompt-submit.sh`	Enhanced hook to suggest skills based on user input
`src/mapify_cli/templates/hooks/helpers/suggest_skill.py`	Python helper for skill suggestion with security protections
`README.md`, `docs/USAGE.md`	Updated documentation covering the new Skills System

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-04T10:02:30Z

+      "type": "rename",
+      "from": "getUserData",
+      "to": "fetchUserProfile",
+      "affected": 12 файлов


Text contains Russian characters 'файлов' (files) instead of English. Should be '12 files'.

Suggested change

"affected": 12 файлов

"affected": 12 files

…-35) MEDIUM fixes: - #8: Remove dead RETRY_LOOP phase from orchestrator STEP_PHASES - #10: Fix plan path to branch-scoped .map/<branch>/task_plan_<branch>.md - #11: Fix findings path to branch-scoped .map/<branch>/findings_<branch>.md - #12: Remove references to non-existent ralph-loop-config.json - #13/#14: Rewrite map-resume to use step_state.json instead of progress.md - #15: Fix INIT_PLAN heading format (### ST-XXX with - **Status:** prefix) - #16: Fix regex in step_runner to match plan format (### heading, - **Status:**) - #17: Fix map-learn contradiction about automatic learning LOW fixes: - #9/#31: Document dual state file system (step_state.json vs workflow_state.json) - #19: Document intentional Evaluator/Reflector/Curator omission in map-efficient - #20: Fix line count reference (~150 → ~540 lines) - #21: Standardize all AskUserQuestion to Python function call syntax - #22: Rename Steps 2.5/2.6 to 2a/2b to avoid phase number collision - #23/#24: Fix map-debate comparison table (map-efficient uses single Actor) - #25: Replace cat commands with Read tool comments in map-check - #28/#29: Replace undefined thrashing_detected()/max_redecompositions - #30: Add - **Status:** pending field to map-plan template - #32: Note map-fast max 3 vs map-efficient max 5 intentional difference - #33: Remove Evaluator from map-fast skipped agents list - #34: Move AskUserQuestion to "Built-in Tools" section in map-release - #35: Replace parallel bash & processes with sequential && in map-release Template sync: All .claude/ changes mirrored to src/mapify_cli/templates/

Copilot AI review requested due to automatic review settings November 4, 2025 10:00

Copilot AI reviewed Nov 4, 2025

View reviewed changes

azalio merged commit ba23c51 into main Nov 4, 2025
12 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: implement P1 Skills System with map-workflows-guide skill#25

feat: implement P1 Skills System with map-workflows-guide skill#25
azalio merged 1 commit intomainfrom
feature/p1-skills-system

azalio commented Nov 4, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

azalio commented Nov 4, 2025

Summary

Key Features

Skills System Architecture

map-workflows-guide Skill

Auto-Activation

Implementation Details

Files Changed

Testing

Expected Impact

Implementation Effort

Dependencies

How to Test

Checklist

References

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants