Fix playbook agent confusion: SQLite migration and cipher integration by azalio · Pull Request #30 · azalio/map-framework

azalio · 2025-11-05T08:06:26Z

Summary

Fixes three recurring issues where Claude Code agents struggled with playbook usage:

❌ Looking for legacy .claude/playbook.json (migrated to SQLite in 2024)
❌ Attempting direct SQLite modifications via sqlite3 commands
❌ Using --mode hybrid flag expecting cipher integration (doesn't work in bash workflows)

Changes

1. Playbook + Cipher Integration (Commit `4e48e6e`)

Problem: mapify playbook query --mode hybrid doesn't actually search cipher because:

Bash commands spawn separate processes
Separate processes can't invoke Claude MCP tools
_query_cipher() returns empty list (graceful degradation)

Solution: Two-step pattern

# Step 1: Local playbook (via Bash)
PLAYBOOK_BULLETS=$(mapify playbook query "task" --limit 5)

# Step 2: Cipher (via MCP tool directly)
mcp__cipher__cipher_memory_search(query="task pattern", top_k=5)

Files changed:

.claude/commands/map-efficient.md - Added two-step pattern
src/mapify_cli/templates/commands/map-feature.md - Added two-step pattern
src/mapify_cli/templates/commands/map-efficient.md - Synced changes
docs/USAGE.md - Added warning about --mode hybrid limitations
New: docs/PLAYBOOK-CIPHER-INTEGRATION.md - Technical deep-dive (161 lines)

2. Playbook.db Usage Clarification (Commit `a5d0340`)

Problem: Agents looking for playbook.json and trying direct sqlite access

Solution:

Updated .claude/CLAUDE.md to reference playbook.db (SQLite)
Added "Playbook Update Rules" section with explicit warnings:
- ❌ sqlite3 .claude/playbook.db "UPDATE..."
- ❌ Edit(.claude/playbook.db, ...)
- ❌ Reading/writing playbook.json
- ✅ Curator agent → mapify playbook apply-delta

Files changed:

.claude/CLAUDE.md - Updated references, added rules section
New: docs/PLAYBOOK-USAGE-GUIDE.md - Comprehensive guide (140 lines)

Impact

✅ Agents will understand playbook.json doesn't exist
✅ Agents will use correct workflow: Curator → apply-delta
✅ Agents will search both playbook AND cipher correctly
✅ No more direct sqlite modifications

Testing

Verified mapify playbook query works correctly (local only)
Confirmed --mode hybrid returns local-only results (as expected)
Validated documentation clarity with examples

Documentation

PLAYBOOK-CIPHER-INTEGRATION.md: Why --mode hybrid doesn't work, correct two-step pattern
PLAYBOOK-USAGE-GUIDE.md: Common mistakes, correct workflows, CLI reference
.claude/CLAUDE.md: Updated playbook rules for MAP workflow enforcement

Stats

7 files changed: +391/-22 lines
2 new guides: 301 lines of documentation
5 files updated: Workflow commands and core documentation

Checklist

All workflow commands updated with two-step pattern
Documentation clarifies playbook.db (not .json)
Warnings against direct sqlite access added
Two comprehensive guides created
Template files synced
No breaking changes (CLI behavior unchanged)

## Problem Claude Code agents confused about how to access both playbook (local) and cipher (cross-project) knowledge. Previous attempt to use `--mode hybrid` flag was INCORRECT. ## Root Cause `mapify playbook query --mode hybrid` does NOT work in MAP workflows: 1. Command runs as separate bash process 2. Separate processes CANNOT invoke Claude MCP tools 3. _query_cipher() gracefully returns [] (empty list) 4. Result: only local playbook searched, cipher ignored From playbook_manager.py:1267-1271: ```python else: # In production, this would be called via MCP tool invocation # by Claude's orchestration layer. For library usage without # MCP, return empty results gracefully. return [] ``` ## Correct Solution: Two-Step Pattern Agents must call TWO separate tools: **Step 1 - Local Playbook** (via Bash): ```bash PLAYBOOK_BULLETS=$(mapify playbook query "[task]" --limit 5) ``` **Step 2 - Cipher** (via MCP tool): ``` mcp__cipher__cipher_memory_search( query="[task pattern]", top_k=5 ) ``` **Why**: Bash commands can't invoke MCP tools. Must call separately. ## Changes Made ### Workflow Commands (map-feature.md, map-efficient.md) - Split "Get Playbook Context" into Step A (local) + Step B (cipher) - Removed `--mode local` flag (it's default anyway) - Added explicit MCP tool call for cipher search - Explained why separate tools needed ### Documentation (USAGE.md) - Added warning that `--mode hybrid` is NO-OP in workflows - Explained technical reason (bash can't invoke MCP) - Documented correct two-step approach - Added link to detailed guide ### New Guide (PLAYBOOK-CIPHER-INTEGRATION.md) - Comprehensive explanation of the problem - Technical deep-dive into why --mode hybrid doesn't work - Examples of correct vs incorrect patterns - Decision matrix for when to use each source ## Expected Outcomes ✅ Agents understand they need TWO separate tool calls ✅ No more confusion about --mode hybrid ✅ Agents get BOTH local (project) and cipher (cross-project) knowledge ✅ Proper integration with ACE dual-memory design ## Testing Verified that: - `mapify playbook query` works (local only, as expected) - `--mode hybrid` gracefully returns local-only results - MCP tools must be called separately by agents - Documentation clearly explains the limitation Fixes issue identified when testing previous commit where --mode hybrid appeared to work but actually didn't search cipher.

## Problems Addressed Agents repeatedly made these mistakes: 1. ❌ Looking for `.claude/playbook.json` (doesn't exist - migrated to SQLite) 2. ❌ Trying to update playbook via direct sqlite3 commands 3. ❌ Using Edit tool on binary playbook.db file 4. ❌ Not understanding playbook.json is legacy ## Root Causes 1. **Outdated documentation**: .claude/CLAUDE.md referenced playbook.json 2. **Missing warnings**: No explicit guidance against direct sqlite access 3. **No usage guide**: Agents didn't have clear reference for correct approach ## Changes Made ### .claude/CLAUDE.md Updates **Before**: - Referenced `.claude/playbook.json` (legacy) - No warnings against direct database modifications **After**: - Updated to `.claude/playbook.db` (SQLite) - Added "Playbook Update Rules" section with: - ✅ Correct way: Curator agent → mapify playbook apply-delta - ❌ Never: sqlite3 commands, Edit tool, playbook.json ### New Guide: docs/PLAYBOOK-USAGE-GUIDE.md Comprehensive reference covering: **Common Mistakes to Avoid**: 1. Looking for playbook.json 2. Direct SQLite modifications 3. Using Edit tool on binary files **Correct Workflows**: - Reading: `mapify playbook query` + cipher MCP - Writing: Curator agent → apply-delta CLI **Quick Reference Table**: | Task | Correct Tool | Wrong Approach | |------|-------------|----------------| | Read playbook | mapify playbook query | playbook.json | | Search patterns | query + cipher_memory_search | --mode hybrid | | Update playbook | Curator → apply-delta | sqlite3 UPDATE | **CLI Commands Reference**: All mapify playbook commands with examples ## Expected Outcomes ✅ Agents understand playbook.json doesn't exist ✅ Agents know to NEVER use sqlite3 directly ✅ Agents use correct workflow: Curator → apply-delta ✅ Clear reference guide for all playbook operations ## Completes Original Task This commit, together with previous commit (4e48e6e), fully addresses: - ✅ playbook.json confusion → Clarified migration to playbook.db - ✅ Direct sqlite updates → Added explicit warnings + correct workflow - ✅ Cipher integration → Two-step pattern (previous commit) All three issues from original request now resolved.

Copilot

Pull Request Overview

This PR updates documentation to clarify the separation between local playbook queries and cipher memory searches in MAP workflows. The changes address confusion about the --mode hybrid flag, which does not work in MAP workflows because bash processes cannot invoke Claude MCP tools.

Key changes:

Separated playbook query (local) and cipher search (MCP) into two distinct steps in workflow documentation
Added comprehensive guides explaining why --mode hybrid doesn't work in workflows
Updated Russian documentation to reflect playbook migration from JSON to SQLite
Added explicit warnings against direct database manipulation

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/mapify_cli/templates/commands/map-feature.md	Split playbook query into two steps: local playbook query (bash) and cipher search (MCP), removed `--mode` parameter
src/mapify_cli/templates/commands/map-efficient.md	Split playbook query into two steps: local playbook query (bash) and cipher search (MCP), removed `--mode` parameter
docs/USAGE.md	Added warning that `--mode hybrid` doesn't work in MAP workflows, explained correct two-step approach
docs/PLAYBOOK-USAGE-GUIDE.md	New file documenting common mistakes and correct playbook usage patterns
docs/PLAYBOOK-CIPHER-INTEGRATION.md	New file explaining why `--mode hybrid` doesn't work and how to correctly use both tools
.claude/commands/map-efficient.md	Split playbook query into two steps matching template changes
.claude/CLAUDE.md	Updated to reference playbook.db instead of playbook.json, added playbook update rules warning against direct manipulation

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

Copilot · 2025-11-05T08:08:09Z

+\`\`\`bash
+PLAYBOOK_BULLETS=$(mapify playbook query "[subtask description]" --limit 5)
+\`\`\`


Escaped backticks are used for the closing code fence. These should be regular backticks. The backslash escaping is unnecessary and will be displayed literally in rendered markdown.

Suggested change

\`\`\`bash

PLAYBOOK_BULLETS=$(mapify playbook query "[subtask description]" --limit 5)

\`\`\`

```bash

PLAYBOOK_BULLETS=$(mapify playbook query "[subtask description]" --limit 5)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…-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/

azalio added 2 commits November 5, 2025 11:00

Copilot AI review requested due to automatic review settings November 5, 2025 08:06

Copilot AI reviewed Nov 5, 2025

View reviewed changes

azalio and others added 2 commits November 5, 2025 11:10

Update docs/USAGE.md

5cf7865

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/PLAYBOOK-CIPHER-INTEGRATION.md

7efb416

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

azalio merged commit 9f79d1a into main Nov 5, 2025
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix playbook agent confusion: SQLite migration and cipher integration#30

Fix playbook agent confusion: SQLite migration and cipher integration#30
azalio merged 4 commits intomainfrom
fix/playbook-agent-confusion

azalio commented Nov 5, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

azalio commented Nov 5, 2025

Summary

Changes

1. Playbook + Cipher Integration (Commit 4e48e6e)

2. Playbook.db Usage Clarification (Commit a5d0340)

Impact

Testing

Documentation

Stats

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

1. Playbook + Cipher Integration (Commit `4e48e6e`)

2. Playbook.db Usage Clarification (Commit `a5d0340`)