fewword

Original source / Raw SKILL.md

---
name: fewword
description: Use this skill when tool outputs exceed 2000 tokens, tasks span multiple conversation turns, sub-agents need to share state, context window is bloating, plans need to persist across summarization, terminal/log output needs selective querying, or when user mentions "offload context", "dynamic context discovery", "filesystem memory", "scratch pad", "reduce context bloat", or "just-in-time context loading".
---

# FewWord - Filesystem-Based Context Engineering

The filesystem provides a single interface for storing, retrieving, and updating effectively unlimited context. This addresses the fundamental constraint that context windows are limited while tasks often require more information.

**Core insight**: Files enable dynamic context discovery—pull relevant context on demand rather than carrying everything in the context window.

**v1 Feature**: Bash commands are automatically intercepted and their output is offloaded to files when large. You will see a pointer and preview instead of full output.

## Directory Structure

```
project/
└── .fewword/                          # All plugin data in one namespace
    ├── scratch/                     # Ephemeral (auto-cleaned hourly)
    │   ├── tool_outputs/            # Offloaded command outputs
    │   └── subagents/               # Agent workspace files
    ├── memory/                      # Persistent (survives cleanup)
    │   ├── plans/                   # Archived completed plans
    │   ├── history/                 # Archived sessions
    │   ├── patterns/                # Discovered patterns
    │   └── preferences.yaml         # User preferences
    ├── index/                       # Metadata tracking
    │   ├── current_plan.yaml        # THE canonical active plan
    │   ├── tool_log.jsonl           # Tool execution log
    │   └── mcp_metadata.jsonl       # MCP tool metadata
    └── DISABLE_OFFLOAD              # Create to disable auto-offloading
```

## Escape Hatch

If automatic offloading causes issues:
- Create file: `touch .fewword/DISABLE_OFFLOAD`
- Or set env: `export FEWWORD_DISABLE=1`

## Automatic Behaviors (v1)

### Bash Output Offloading

When you run a Bash command, the plugin automatically:
1. Captures stdout+stderr to a file
2. After completion, measures output size
3. If small (<8KB): shows full output normally, deletes temp file
4. If large: shows pointer + preview (first/last 10 lines)
5. Preserves the original exit code

**What you see for large output:**
```
=== [FewWord: Output offloaded] ===
File: .fewword/scratch/tool_outputs/pytest_20250107_143022_a1b2c3d4.txt
Size: 45678 bytes, 1234 lines
Exit: 0

=== First 10 lines ===
...preview...

=== Last 10 lines ===
...preview...

=== Retrieval commands ===
  Full: cat .fewword/scratch/tool_outputs/pytest_20250107_143022_a1b2c3d4.txt
  Grep: grep 'pattern' .fewword/scratch/tool_outputs/pytest_20250107_143022_a1b2c3d4.txt
```

**Skipped commands** (v1 conservatively skips):
- Interactive: ssh, vim, less, top, watch, python, node, psql, etc.
- Already redirecting: commands with `>`, `2>`, `| tee`, `| less`
- Heredocs: commands containing `<<`
- Pipelines: commands containing `|`
- Trivial: very short commands

### MCP Tool Handling

- All MCP tool calls are logged to `.fewword/index/mcp_metadata.jsonl`
- Write-like operations (create, update, delete, commit, push) are gated
- Pagination parameters are automatically clamped to prevent excessive results

## Manual Patterns

### Pattern 1: Plan Persistence

For long-horizon tasks, use the canonical active plan:

```yaml
# .fewword/index/current_plan.yaml
objective: "Refactor authentication module"
status: in_progress
steps:
  - id: 1
    description: "Audit current auth endpoints"
    status: completed
  - id: 2
    description: "Design new token validation"
    status: in_progress
  - id: 3
    description: "Implement and test"
    status: pending
```

- Plan survives context summarization
- Re-read at turn start or when losing track
- When completed, automatically archived to `memory/plans/`

### Pattern 2: Sub-Agent File Workspaces

Sub-agents write findings directly to filesystem instead of message passing:

```
.fewword/scratch/subagents/
├── research_agent/
│   ├── findings.md
│   └── sources.jsonl
├── code_agent/
│   ├── changes.md
│   └── test_results.txt
└── synthesis.md
```

### Pattern 3: Chat History as File Reference

When context window fills:
1. Write full history to `.fewword/memory/history/session_{id}.txt`
2. Generate summary for new context window
3. Include reference: "Full history in .fewword/memory/history/session_{id}.txt"
4. Use grep to recover details lost in summarization

## Search Techniques

| Tool | Use Case | Example |
|------|----------|---------|
| `ls` / `find` | Discover structure | `find .fewword -name "*.txt" -mmin -30` |
| `grep` | Content search | `grep -rn "error" .fewword/scratch/` |
| `head`/`tail` | Boundary reads | `tail -100 .fewword/scratch/tool_outputs/log.txt` |
| `sed -n` | Line ranges | `sed -n '50,100p' file.txt` |

## References

For detailed implementation patterns, see:
- `references/implementation-patterns.md` - Code examples for each pattern
- `references/cleanup-strategies.md` - Scratch file lifecycle management


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/implementation-patterns.md

```markdown
# Implementation Patterns

Detailed code examples for filesystem-based context engineering.

## Tool Output Offloading

### Python Implementation

```python
import os
from datetime import datetime
from pathlib import Path

SCRATCH_DIR = Path(".fewword/scratch/tool_outputs")
TOKEN_THRESHOLD = 2000  # ~500 words

def estimate_tokens(text: str) -> int:
    """Rough token estimate: ~4 chars per token"""
    return len(text) // 4

def handle_tool_output(tool_name: str, output: str) -> str:
    """Offload large outputs, return reference + summary."""
    if estimate_tokens(output) < TOKEN_THRESHOLD:
        return output

    # Ensure directory exists
    SCRATCH_DIR.mkdir(parents=True, exist_ok=True)

    # Write to file
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"{tool_name}_{timestamp}.txt"
    file_path = SCRATCH_DIR / filename
    file_path.write_text(output)

    # Extract summary (first meaningful content)
    lines = output.strip().split('\n')
    summary_lines = [l for l in lines[:10] if l.strip()][:3]
    summary = ' '.join(summary_lines)[:200]

    return f"[Output ({len(output)} chars) saved to {file_path}. Preview: {summary}...]"
```

### Bash One-Liner

```bash
# For shell command outputs
output=$(some_command 2>&1)
if [ ${#output} -gt 8000 ]; then
  file=".fewword/scratch/tool_outputs/cmd_$(date +%s).txt"
  mkdir -p "$(dirname "$file")"
  echo "$output" > "$file"
  echo "[Output saved to $file. Lines: $(echo "$output" | wc -l)]"
else
  echo "$output"
fi
```

## Plan Persistence

### YAML Structure

```yaml
# .fewword/index/current_plan.yaml
meta:
  created: "2025-01-07T10:00:00Z"
  last_updated: "2025-01-07T14:30:00Z"

objective: "Implement user authentication system"
status: in_progress
success_criteria:
  - "JWT token generation works"
  - "Refresh token rotation implemented"
  - "All endpoints protected"

current_focus: "step-2"

steps:
  - id: step-1
    description: "Set up auth dependencies"
    status: completed
    notes: "Using python-jose for JWT"

  - id: step-2
    description: "Implement token generation"
    status: in_progress
    blockers: []

  - id: step-3
    description: "Add middleware protection"
    status: pending
    depends_on: [step-2]

decisions:
  - decision: "Use RS256 for JWT signing"
    rationale: "Better security for production"
    date: "2025-01-07"
```

### Plan Operations

```python
import yaml
from pathlib import Path
from datetime import datetime

PLAN_FILE = Path(".fewword/index/current_plan.yaml")

def load_plan() -> dict:
    if PLAN_FILE.exists():
        return yaml.safe_load(PLAN_FILE.read_text())
    return None

def update_step_status(step_id: str, status: str, notes: str = None):
    plan = load_plan()
    for step in plan['steps']:
        if step['id'] == step_id:
            step['status'] = status
            if notes:
                step['notes'] = notes
    plan['meta']['last_updated'] = datetime.now().isoformat()
    PLAN_FILE.write_text(yaml.dump(plan, default_flow_style=False))

def get_current_focus() -> dict:
    plan = load_plan()
    focus_id = plan.get('current_focus')
    for step in plan['steps']:
        if step['id'] == focus_id:
            return step
    return None
```

## Sub-Agent Workspaces

### Directory Setup

```bash
mkdir -p .fewword/scratch/subagents/{research,code,test,coordinator}
```

### Agent Output Format

```markdown
<!-- .fewword/scratch/subagents/research/findings.md -->
# Research Findings

## Topic: Authentication Libraries

### Evaluated Options
1. **python-jose** - Recommended
   - Pros: Well-maintained, RS256 support
   - Cons: Slightly larger API surface

2. **PyJWT**
   - Pros: Simple API
   - Cons: Less algorithm support

### Recommendation
Use python-jose with RS256 signing.

### Sources
- https://github.com/mpdavis/python-jose
- JWT.io best practices guide

---
Updated: 2025-01-07T14:00:00Z
```

### Coordinator Pattern

```python
from pathlib import Path
import glob

def synthesize_agent_findings() -> str:
    """Read all agent findings and create synthesis."""
    findings = []

    for agent_dir in Path(".fewword/scratch/subagents").iterdir():
        if agent_dir.is_dir() and agent_dir.name != "coordinator":
            findings_file = agent_dir / "findings.md"
            if findings_file.exists():
                findings.append({
                    'agent': agent_dir.name,
                    'content': findings_file.read_text()
                })

    # Write synthesis
    synthesis = "# Synthesis\n\n"
    for f in findings:
        synthesis += f"## From {f['agent']}\n{f['content']}\n\n"

    Path(".fewword/scratch/subagents/coordinator/synthesis.md").write_text(synthesis)
    return synthesis
```

## Targeted Retrieval Commands

### Find Recent Errors

```bash
# Last 5 lines around each error
grep -B 2 -A 5 -i "error\|exception\|failed" .fewword/scratch/tool_outputs/*.txt

# Just filenames with errors
grep -l "error" .fewword/scratch/tool_outputs/*.txt
```

### Search Specific Sections

```bash
# Find function definitions
grep -n "^def \|^async def " .fewword/scratch/tool_outputs/code_*.txt

# Extract JSON from mixed output
grep -o '{.*}' .fewword/scratch/tool_outputs/api_response.txt | head -1
```

### Read Line Ranges

```bash
# Lines 100-150 of a file
sed -n '100,150p' .fewword/scratch/tool_outputs/large_file.txt

# Last 50 lines
tail -50 .fewword/scratch/tool_outputs/build_log.txt

# First 20 lines
head -20 .fewword/scratch/tool_outputs/query_results.txt
```

## History Reference Pattern

```python
from pathlib import Path
from datetime import datetime

HISTORY_DIR = Path(".fewword/memory/history")

def archive_conversation(messages: list, summary: str) -> str:
    """Archive full history, return reference for new context."""
    HISTORY_DIR.mkdir(parents=True, exist_ok=True)

    session_id = datetime.now().strftime("%Y%m%d_%H%M%S")
    history_file = HISTORY_DIR / f"session_{session_id}.txt"

    # Write full history
    content = "\n\n---\n\n".join([
        f"[{m['role']}]: {m['content']}" for m in messages
    ])
    history_file.write_text(content)

    # Return reference for new context
    return f"""## Previous Session Summary
{summary}

Full conversation history available at: {history_file}
Use grep to search for specific details if needed.
"""
```

```

### references/cleanup-strategies.md

```markdown
# Cleanup Strategies

Managing scratch file lifecycle to prevent unbounded growth.

> **Windows Note**: The `find` and `du` commands shown below are Unix/Linux commands. On Windows, use Python equivalents or Git Bash. The `/cleanup` command uses cross-platform Python internally.

## Automatic Cleanup Rules

### By Age

```bash
# Delete tool outputs older than 1 hour
find .fewword/scratch/tool_outputs -type f -mmin +60 -delete

# Delete subagent files older than 2 hours
find .fewword/scratch/subagents -type f -mmin +120 -delete

# Note: index/ is NEVER auto-cleaned (contains active plan)
```

### By Size

```bash
# Delete files larger than 10MB (likely logs that got out of hand)
find .fewword/scratch -type f -size +10M -delete

# Alert on scratch dir size
du -sh .fewword/scratch/
```

### By Pattern

```bash
# Clean all temp files
find .fewword/scratch -name "*.tmp" -delete
find .fewword/scratch -name "*_temp_*" -delete

# Clean empty directories
find .fewword/scratch -type d -empty -delete
```

## Retention Policies

| Directory | Retention | Rationale |
|-----------|-----------|-----------|
| `.fewword/scratch/tool_outputs/` | 1 hour | Ephemeral, task-specific |
| `.fewword/scratch/subagents/` | 2 hours | Task-specific coordination |
| `.fewword/index/` | **Never** | Contains active plan + metadata |
| `.fewword/memory/history/` | 7 days | May need to reference |
| `.fewword/memory/plans/` | Permanent | Archived completed plans |
| `.fewword/memory/preferences.yaml` | Permanent | Learned user preferences |

## Hook Integration

The plugin includes hooks that automatically:

1. **On session start**: Clean files older than retention policy
2. **On session end**: Archive completed plans to `memory/plans/`
3. **On each response**: Warn if `.fewword/scratch/` exceeds 100MB

## Manual Cleanup Commands

```bash
# Full scratch reset
rm -rf .fewword/scratch/*

# Preserve structure, clear contents
find .fewword/scratch -type f -delete

# Selective cleanup
rm -rf .fewword/scratch/tool_outputs/*
rm -rf .fewword/scratch/subagents/*

# Use the cleanup script
python skills/fewword/scripts/cleanup_scratch.py --stats
python skills/fewword/scripts/cleanup_scratch.py --all --dry-run
python skills/fewword/scripts/cleanup_scratch.py --all
```

## Best Practices

1. **Use timestamps in filenames** - Enables age-based cleanup
2. **Separate scratch from memory** - `.fewword/scratch/` vs `.fewword/memory/`
3. **Don't store originals in scratch** - Only derived/generated content
4. **Include cleanup in task completion** - Part of "done" checklist
5. **Never manually delete index/** - Contains active plan that survives sessions

```