port-nuker 1.0.1 → 1.0.4

package/.agent/skills/skills/planning-with-files/examples.md

@@ -1,202 +0,0 @@
-# Examples: Planning with Files in Action
-
-## Example 1: Research Task
-
-**User Request:** "Research the benefits of morning exercise and write a summary"
-
-### Loop 1: Create Plan
-```bash
-Write task_plan.md
-```
-
-```markdown
-# Task Plan: Morning Exercise Benefits Research
-
-## Goal
-Create a research summary on the benefits of morning exercise.
-
-## Phases
-- [ ] Phase 1: Create this plan ✓
-- [ ] Phase 2: Search and gather sources
-- [ ] Phase 3: Synthesize findings
-- [ ] Phase 4: Deliver summary
-
-## Key Questions
-1. What are the physical health benefits?
-2. What are the mental health benefits?
-3. What scientific studies support this?
-
-## Status
-**Currently in Phase 1** - Creating plan
-```
-
-### Loop 2: Research
-```bash
-Read task_plan.md           # Refresh goals
-WebSearch "morning exercise benefits"
-Write notes.md              # Store findings
-Edit task_plan.md           # Mark Phase 2 complete
-```
-
-### Loop 3: Synthesize
-```bash
-Read task_plan.md           # Refresh goals
-Read notes.md               # Get findings
-Write morning_exercise_summary.md
-Edit task_plan.md           # Mark Phase 3 complete
-```
-
-### Loop 4: Deliver
-```bash
-Read task_plan.md           # Verify complete
-Deliver morning_exercise_summary.md
-```
-
----
-
-## Example 2: Bug Fix Task
-
-**User Request:** "Fix the login bug in the authentication module"
-
-### task_plan.md
-```markdown
-# Task Plan: Fix Login Bug
-
-## Goal
-Identify and fix the bug preventing successful login.
-
-## Phases
-- [x] Phase 1: Understand the bug report ✓
-- [x] Phase 2: Locate relevant code ✓
-- [ ] Phase 3: Identify root cause (CURRENT)
-- [ ] Phase 4: Implement fix
-- [ ] Phase 5: Test and verify
-
-## Key Questions
-1. What error message appears?
-2. Which file handles authentication?
-3. What changed recently?
-
-## Decisions Made
-- Auth handler is in src/auth/login.ts
-- Error occurs in validateToken() function
-
-## Errors Encountered
-- [Initial] TypeError: Cannot read property 'token' of undefined
-  → Root cause: user object not awaited properly
-
-## Status
-**Currently in Phase 3** - Found root cause, preparing fix
-```
-
----
-
-## Example 3: Feature Development
-
-**User Request:** "Add a dark mode toggle to the settings page"
-
-### The 3-File Pattern in Action
-
-**task_plan.md:**
-```markdown
-# Task Plan: Dark Mode Toggle
-
-## Goal
-Add functional dark mode toggle to settings.
-
-## Phases
-- [x] Phase 1: Research existing theme system ✓
-- [x] Phase 2: Design implementation approach ✓
-- [ ] Phase 3: Implement toggle component (CURRENT)
-- [ ] Phase 4: Add theme switching logic
-- [ ] Phase 5: Test and polish
-
-## Decisions Made
-- Using CSS custom properties for theme
-- Storing preference in localStorage
-- Toggle component in SettingsPage.tsx
-
-## Status
-**Currently in Phase 3** - Building toggle component
-```
-
-**notes.md:**
-```markdown
-# Notes: Dark Mode Implementation
-
-## Existing Theme System
-- Located in: src/styles/theme.ts
-- Uses: CSS custom properties
-- Current themes: light only
-
-## Files to Modify
-1. src/styles/theme.ts - Add dark theme colors
-2. src/components/SettingsPage.tsx - Add toggle
-3. src/hooks/useTheme.ts - Create new hook
-4. src/App.tsx - Wrap with ThemeProvider
-
-## Color Decisions
-- Dark background: #1a1a2e
-- Dark surface: #16213e
-- Dark text: #eaeaea
-```
-
-**dark_mode_implementation.md:** (deliverable)
-```markdown
-# Dark Mode Implementation
-
-## Changes Made
-
-### 1. Added dark theme colors
-File: src/styles/theme.ts
-...
-
-### 2. Created useTheme hook
-File: src/hooks/useTheme.ts
-...
-```
-
----
-
-## Example 4: Error Recovery Pattern
-
-When something fails, DON'T hide it:
-
-### Before (Wrong)
-```
-Action: Read config.json
-Error: File not found
-Action: Read config.json  # Silent retry
-Action: Read config.json  # Another retry
-```
-
-### After (Correct)
-```
-Action: Read config.json
-Error: File not found
-
-# Update task_plan.md:
-## Errors Encountered
-- config.json not found → Will create default config
-
-Action: Write config.json (default config)
-Action: Read config.json
-Success!
-```
-
----
-
-## The Read-Before-Decide Pattern
-
-**Always read your plan before major decisions:**
-
-```
-[Many tool calls have happened...]
-[Context is getting long...]
-[Original goal might be forgotten...]
-
-→ Read task_plan.md          # This brings goals back into attention!
-→ Now make the decision       # Goals are fresh in context
-```
-
-This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.

package/.agent/skills/skills/planning-with-files/reference.md

@@ -1,218 +0,0 @@
-# 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

package/.agent/skills/skills/planning-with-files/scripts/check-complete.sh

@@ -1,44 +0,0 @@
-#!/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

package/.agent/skills/skills/planning-with-files/scripts/init-session.sh

@@ -1,120 +0,0 @@
-#!/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"

package/.agent/skills/skills/planning-with-files/templates/findings.md

@@ -1,95 +0,0 @@
-# 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*