cnhkmcp 2.1.9__py3-none-any.whl → 2.3.0__py3-none-any.whl

cnhkmcp/untracked/skills/planning-with-files/reference.md

@@ -0,0 +1,218 @@
+# Reference: Manus Context Engineering Principles
+
+This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
+
+## The 6 Manus Principles
+
+### Principle 1: Design Around KV-Cache
+
+> "KV-cache hit rate is THE single most important metric for production AI agents."
+
+**Statistics:**
+- ~100:1 input-to-output token ratio
+- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
+- 10x cost difference!
+
+**Implementation:**
+- Keep prompt prefixes STABLE (single-token change invalidates cache)
+- NO timestamps in system prompts
+- Make context APPEND-ONLY with deterministic serialization
+
+### Principle 2: Mask, Don't Remove
+
+Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
+
+**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
+
+### Principle 3: Filesystem as External Memory
+
+> "Markdown is my 'working memory' on disk."
+
+**The Formula:**
+```
+Context Window = RAM (volatile, limited)
+Filesystem = Disk (persistent, unlimited)
+```
+
+**Compression Must Be Restorable:**
+- Keep URLs even if web content is dropped
+- Keep file paths when dropping document contents
+- Never lose the pointer to full data
+
+### Principle 4: Manipulate Attention Through Recitation
+
+> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
+
+**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
+
+**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
+
+```
+Start of context: [Original goal - far away, forgotten]
+...many tool calls...
+End of context: [Recently read task_plan.md - gets ATTENTION!]
+```
+
+### Principle 5: Keep the Wrong Stuff In
+
+> "Leave the wrong turns in the context."
+
+**Why:**
+- Failed actions with stack traces let model implicitly update beliefs
+- Reduces mistake repetition
+- Error recovery is "one of the clearest signals of TRUE agentic behavior"
+
+### Principle 6: Don't Get Few-Shotted
+
+> "Uniformity breeds fragility."
+
+**Problem:** Repetitive action-observation pairs cause drift and hallucination.
+
+**Solution:** Introduce controlled variation:
+- Vary phrasings slightly
+- Don't copy-paste patterns blindly
+- Recalibrate on repetitive tasks
+
+---
+
+## The 3 Context Engineering Strategies
+
+Based on Lance Martin's analysis of Manus architecture.
+
+### Strategy 1: Context Reduction
+
+**Compaction:**
+```
+Tool calls have TWO representations:
+├── FULL: Raw tool content (stored in filesystem)
+└── COMPACT: Reference/file path only
+
+RULES:
+- Apply compaction to STALE (older) tool results
+- Keep RECENT results FULL (to guide next decision)
+```
+
+**Summarization:**
+- Applied when compaction reaches diminishing returns
+- Generated using full tool results
+- Creates standardized summary objects
+
+### Strategy 2: Context Isolation (Multi-Agent)
+
+**Architecture:**
+```
+┌─────────────────────────────────┐
+│         PLANNER AGENT           │
+│  └─ Assigns tasks to sub-agents │
+├─────────────────────────────────┤
+│       KNOWLEDGE MANAGER         │
+│  └─ Reviews conversations       │
+│  └─ Determines filesystem store │
+├─────────────────────────────────┤
+│      EXECUTOR SUB-AGENTS        │
+│  └─ Perform assigned tasks      │
+│  └─ Have own context windows    │
+└─────────────────────────────────┘
+```
+
+**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
+
+### Strategy 3: Context Offloading
+
+**Tool Design:**
+- Use <20 atomic functions total
+- Store full results in filesystem, not context
+- Use `glob` and `grep` for searching
+- Progressive disclosure: load information only as needed
+
+---
+
+## The Agent Loop
+
+Manus operates in a continuous 7-step loop:
+
+```
+┌─────────────────────────────────────────┐
+│  1. ANALYZE CONTEXT                      │
+│     - Understand user intent             │
+│     - Assess current state               │
+│     - Review recent observations         │
+├─────────────────────────────────────────┤
+│  2. THINK                                │
+│     - Should I update the plan?          │
+│     - What's the next logical action?    │
+│     - Are there blockers?                │
+├─────────────────────────────────────────┤
+│  3. SELECT TOOL                          │
+│     - Choose ONE tool                    │
+│     - Ensure parameters available        │
+├─────────────────────────────────────────┤
+│  4. EXECUTE ACTION                       │
+│     - Tool runs in sandbox               │
+├─────────────────────────────────────────┤
+│  5. RECEIVE OBSERVATION                  │
+│     - Result appended to context         │
+├─────────────────────────────────────────┤
+│  6. ITERATE                              │
+│     - Return to step 1                   │
+│     - Continue until complete            │
+├─────────────────────────────────────────┤
+│  7. DELIVER OUTCOME                      │
+│     - Send results to user               │
+│     - Attach all relevant files          │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## File Types Manus Creates
+
+| File | Purpose | When Created | When Updated |
+|------|---------|--------------|--------------|
+| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
+| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
+| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
+| Code files | Implementation | Before execution | After errors |
+
+---
+
+## Critical Constraints
+
+- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
+- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
+- **Files are Memory:** Context = volatile. Filesystem = persistent.
+- **Never Repeat Failures:** If action failed, next action MUST be different
+- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
+
+---
+
+## Manus Statistics
+
+| Metric | Value |
+|--------|-------|
+| Average tool calls per task | ~50 |
+| Input-to-output token ratio | 100:1 |
+| Acquisition price | $2 billion |
+| Time to $100M revenue | 8 months |
+| Framework refactors since launch | 5 times |
+
+---
+
+## Key Quotes
+
+> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
+
+> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
+
+> "Error recovery is one of the clearest signals of TRUE agentic behavior."
+
+> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
+
+> "Leave the wrong turns in the context."
+
+---
+
+## Source
+
+Based on Manus's official context engineering documentation:
+https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

cnhkmcp/untracked/skills/planning-with-files/scripts/check-complete.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Check if all phases in task_plan.md are complete
+# Exit 0 if complete, exit 1 if incomplete
+# Used by Stop hook to verify task completion
+
+PLAN_FILE="${1:-task_plan.md}"
+
+if [ ! -f "$PLAN_FILE" ]; then
+    echo "ERROR: $PLAN_FILE not found"
+    echo "Cannot verify completion without a task plan."
+    exit 1
+fi
+
+echo "=== Task Completion Check ==="
+echo ""
+
+# Count phases by status (using -F for fixed string matching)
+TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
+COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
+IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
+PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
+
+# Default to 0 if empty
+: "${TOTAL:=0}"
+: "${COMPLETE:=0}"
+: "${IN_PROGRESS:=0}"
+: "${PENDING:=0}"
+
+echo "Total phases:   $TOTAL"
+echo "Complete:       $COMPLETE"
+echo "In progress:    $IN_PROGRESS"
+echo "Pending:        $PENDING"
+echo ""
+
+# Check completion
+if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
+    echo "ALL PHASES COMPLETE"
+    exit 0
+else
+    echo "TASK NOT COMPLETE"
+    echo ""
+    echo "Do not stop until all phases are complete."
+    exit 1
+fi

cnhkmcp/untracked/skills/planning-with-files/scripts/init-session.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# Initialize planning files for a new session
+# Usage: ./init-session.sh [project-name]
+
+set -e
+
+PROJECT_NAME="${1:-project}"
+DATE=$(date +%Y-%m-%d)
+
+echo "Initializing planning files for: $PROJECT_NAME"
+
+# Create task_plan.md if it doesn't exist
+if [ ! -f "task_plan.md" ]; then
+    cat > task_plan.md << 'EOF'
+# Task Plan: [Brief Description]
+
+## Goal
+[One sentence describing the end state]
+
+## Current Phase
+Phase 1
+
+## Phases
+
+### Phase 1: Requirements & Discovery
+- [ ] Understand user intent
+- [ ] Identify constraints
+- [ ] Document in findings.md
+- **Status:** in_progress
+
+### Phase 2: Planning & Structure
+- [ ] Define approach
+- [ ] Create project structure
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Execute the plan
+- [ ] Write to files before executing
+- **Status:** pending
+
+### Phase 4: Testing & Verification
+- [ ] Verify requirements met
+- [ ] Document test results
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review outputs
+- [ ] Deliver to user
+- **Status:** pending
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+
+## Errors Encountered
+| Error | Resolution |
+|-------|------------|
+EOF
+    echo "Created task_plan.md"
+else
+    echo "task_plan.md already exists, skipping"
+fi
+
+# Create findings.md if it doesn't exist
+if [ ! -f "findings.md" ]; then
+    cat > findings.md << 'EOF'
+# Findings & Decisions
+
+## Requirements
+-
+
+## Research Findings
+-
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+
+## Resources
+-
+EOF
+    echo "Created findings.md"
+else
+    echo "findings.md already exists, skipping"
+fi
+
+# Create progress.md if it doesn't exist
+if [ ! -f "progress.md" ]; then
+    cat > progress.md << EOF
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Requirements & Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Test Results
+| Test | Expected | Actual | Status |
+|------|----------|--------|--------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+    echo "Created progress.md"
+else
+    echo "progress.md already exists, skipping"
+fi
+
+echo ""
+echo "Planning files initialized!"
+echo "Files: task_plan.md, findings.md, progress.md"

cnhkmcp/untracked/skills/planning-with-files/templates/findings.md

@@ -0,0 +1,95 @@
+# Findings & Decisions
+<!-- 
+  WHAT: Your knowledge base for the task. Stores everything you discover and decide.
+  WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
+  WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
+-->
+
+## Requirements
+<!-- 
+  WHAT: What the user asked for, broken down into specific requirements.
+  WHY: Keeps requirements visible so you don't forget what you're building.
+  WHEN: Fill this in during Phase 1 (Requirements & Discovery).
+  EXAMPLE:
+    - Command-line interface
+    - Add tasks
+    - List all tasks
+    - Delete tasks
+    - Python implementation
+-->
+<!-- Captured from user request -->
+-
+
+## Research Findings
+<!-- 
+  WHAT: Key discoveries from web searches, documentation reading, or exploration.
+  WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
+  WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
+  EXAMPLE:
+    - Python's argparse module supports subcommands for clean CLI design
+    - JSON module handles file persistence easily
+    - Standard pattern: python script.py <command> [args]
+-->
+<!-- Key discoveries during exploration -->
+-
+
+## Technical Decisions
+<!-- 
+  WHAT: Architecture and implementation choices you've made, with reasoning.
+  WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
+  WHEN: Update whenever you make a significant technical choice.
+  EXAMPLE:
+    | Use JSON for storage | Simple, human-readable, built-in Python support |
+    | argparse with subcommands | Clean CLI: python todo.py add "task" |
+-->
+<!-- Decisions made with rationale -->
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Issues Encountered
+<!-- 
+  WHAT: Problems you ran into and how you solved them.
+  WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
+  WHEN: Document when you encounter blockers or unexpected challenges.
+  EXAMPLE:
+    | Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
+-->
+<!-- Errors and how they were resolved -->
+| Issue | Resolution |
+|-------|------------|
+|       |            |
+
+## Resources
+<!-- 
+  WHAT: URLs, file paths, API references, documentation links you've found useful.
+  WHY: Easy reference for later. Don't lose important links in context.
+  WHEN: Add as you discover useful resources.
+  EXAMPLE:
+    - Python argparse docs: https://docs.python.org/3/library/argparse.html
+    - Project structure: src/main.py, src/utils.py
+-->
+<!-- URLs, file paths, API references -->
+-
+
+## Visual/Browser Findings
+<!-- 
+  WHAT: Information you learned from viewing images, PDFs, or browser results.
+  WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
+  WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
+  EXAMPLE:
+    - Screenshot shows login form has email and password fields
+    - Browser shows API returns JSON with "status" and "data" keys
+-->
+<!-- CRITICAL: Update after every 2 view/browser operations -->
+<!-- Multimodal content must be captured as text immediately -->
+-
+
+---
+<!-- 
+  REMINDER: The 2-Action Rule
+  After every 2 view/browser/search operations, you MUST update this file.
+  This prevents visual information from being lost when context resets.
+-->
+*Update this file after every 2 view/browser/search operations*
+*This prevents visual information from being lost*

cnhkmcp/untracked/skills/planning-with-files/templates/progress.md

@@ -0,0 +1,114 @@
+# Progress Log
+<!-- 
+  WHAT: Your session log - a chronological record of what you did, when, and what happened.
+  WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
+  WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
+-->
+
+## Session: [DATE]
+<!-- 
+  WHAT: The date of this work session.
+  WHY: Helps track when work happened, useful for resuming after time gaps.
+  EXAMPLE: 2026-01-15
+-->
+
+### Phase 1: [Title]
+<!-- 
+  WHAT: Detailed log of actions taken during this phase.
+  WHY: Provides context for what was done, making it easier to resume or debug.
+  WHEN: Update as you work through the phase, or at least when you complete it.
+-->
+- **Status:** in_progress
+- **Started:** [timestamp]
+<!-- 
+  STATUS: Same as task_plan.md (pending, in_progress, complete)
+  TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
+-->
+- Actions taken:
+  <!-- 
+    WHAT: List of specific actions you performed.
+    EXAMPLE:
+      - Created todo.py with basic structure
+      - Implemented add functionality
+      - Fixed FileNotFoundError
+  -->
+  -
+- Files created/modified:
+  <!-- 
+    WHAT: Which files you created or changed.
+    WHY: Quick reference for what was touched. Helps with debugging and review.
+    EXAMPLE:
+      - todo.py (created)
+      - todos.json (created by app)
+      - task_plan.md (updated)
+  -->
+  -
+
+### Phase 2: [Title]
+<!-- 
+  WHAT: Same structure as Phase 1, for the next phase.
+  WHY: Keep a separate log entry for each phase to track progress clearly.
+-->
+- **Status:** pending
+- Actions taken:
+  -
+- Files created/modified:
+  -
+
+## Test Results
+<!-- 
+  WHAT: Table of tests you ran, what you expected, what actually happened.
+  WHY: Documents verification of functionality. Helps catch regressions.
+  WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
+  EXAMPLE:
+    | Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
+    | List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
+-->
+| Test | Input | Expected | Actual | Status |
+|------|-------|----------|--------|--------|
+|      |       |          |        |        |
+
+## Error Log
+<!-- 
+  WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
+  WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
+  WHEN: Add immediately when an error occurs, even if you fix it quickly.
+  EXAMPLE:
+    | 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
+    | 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
+-->
+<!-- Keep ALL errors - they help avoid repetition -->
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+|           |       | 1       |            |
+
+## 5-Question Reboot Check
+<!-- 
+  WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
+  WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
+  WHEN: Update periodically, especially when resuming after a break or context reset.
+  
+  THE 5 QUESTIONS:
+  1. Where am I? → Current phase in task_plan.md
+  2. Where am I going? → Remaining phases
+  3. What's the goal? → Goal statement in task_plan.md
+  4. What have I learned? → See findings.md
+  5. What have I done? → See progress.md (this file)
+-->
+<!-- If you can answer these, context is solid -->
+| Question | Answer |
+|----------|--------|
+| Where am I? | Phase X |
+| Where am I going? | Remaining phases |
+| What's the goal? | [goal statement] |
+| What have I learned? | See findings.md |
+| What have I done? | See above |
+
+---
+<!-- 
+  REMINDER: 
+  - Update after completing each phase or encountering errors
+  - Be detailed - this is your "what happened" log
+  - Include timestamps for errors to track when issues occurred
+-->
+*Update after completing each phase or encountering errors*