@bastani/atomic 0.6.8-0 → 0.7.0-1

package/.agents/skills/filesystem-context/scripts/filesystem_context.py

@@ -1,425 +0,0 @@
-"""
-Filesystem Context Manager -- composable utilities for filesystem-based context engineering.
-
-Provides three core patterns for managing agent context through the filesystem:
-1. ScratchPadManager -- offload large tool outputs to files, return compact references
-2. AgentPlan / PlanStep -- persist plans to disk so agents survive context window refreshes
-3. ToolOutputHandler -- automatic offload-or-inline decision for tool outputs
-
-Use when:
-    - Tool outputs exceed ~2000 tokens and would bloat the context window
-    - Agents need plan persistence across long-horizon, multi-turn tasks
-    - Building agent systems that offload intermediate results to files
-
-Example (library usage)::
-
-    from filesystem_context import ScratchPadManager, ToolOutputHandler
-
-    handler = ToolOutputHandler(ScratchPadManager(base_path="scratch"))
-    result = handler.process_output("web_search", large_output_string)
-
-Example (CLI demo)::
-
-    python filesystem_context.py
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import shutil
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-__all__: list[str] = [
-    "ScratchPadManager",
-    "PlanStep",
-    "AgentPlan",
-    "ToolOutputHandler",
-]
-
-
-# =============================================================================
-# Pattern 1: Scratch Pad Manager
-# =============================================================================
-
-
-class ScratchPadManager:
-    """Manage temporary file storage for offloading large tool outputs.
-
-    Use when: tool outputs exceed a token threshold and would bloat the
-    context window. Writes content to a scratch directory and returns a
-    compact reference the agent can include in context instead.
-    """
-
-    def __init__(self, base_path: str = "scratch", token_threshold: int = 2000) -> None:
-        self.base_path: Path = Path(base_path)
-        self.base_path.mkdir(parents=True, exist_ok=True)
-        self.token_threshold: int = token_threshold
-
-    def estimate_tokens(self, content: str) -> int:
-        """Return a rough token estimate (~4 characters per token).
-
-        Use when: deciding whether content should be offloaded before
-        writing it to disk.
-        """
-        return len(content) // 4
-
-    def should_offload(self, content: str) -> bool:
-        """Return True if *content* exceeds the configured token threshold.
-
-        Use when: making an inline-vs-offload decision for a tool output.
-        """
-        return self.estimate_tokens(content) > self.token_threshold
-
-    def offload(self, content: str, source: str) -> Dict[str, Any]:
-        """Write *content* to a timestamped scratch file and return a reference dict.
-
-        Use when: a tool output has been determined to exceed the threshold
-        and should be persisted to disk.
-
-        Returns a dict with keys: path, source, tokens_saved, summary.
-        """
-        timestamp: str = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
-        filename: str = f"{source}_{timestamp}.txt"
-        file_path: Path = self.base_path / filename
-
-        file_path.write_text(content)
-
-        # Extract summary from first meaningful lines
-        lines: list[str] = content.strip().split("\n")[:5]
-        summary: str = "\n".join(lines)
-        if len(summary) > 300:
-            summary = summary[:300] + "..."
-
-        return {
-            "path": str(file_path),
-            "source": source,
-            "tokens_saved": self.estimate_tokens(content),
-            "summary": summary,
-        }
-
-    def format_reference(self, ref: Dict[str, Any]) -> str:
-        """Format a reference dict as a compact string for context inclusion.
-
-        Use when: constructing the replacement message that goes into context
-        in place of the full tool output.
-        """
-        return (
-            f"[Output from {ref['source']} saved to {ref['path']}. "
-            f"~{ref['tokens_saved']} tokens. "
-            f"Summary: {ref['summary'][:200]}]"
-        )
-
-    def cleanup(self, max_age_seconds: int = 3600) -> int:
-        """Remove scratch files older than *max_age_seconds*.
-
-        Use when: ending a session or when the scratch directory has grown
-        large enough to slow directory listings.
-
-        Returns the number of files removed.
-        """
-        removed: int = 0
-        now: float = datetime.now().timestamp()
-        for f in self.base_path.iterdir():
-            if f.is_file() and (now - f.stat().st_mtime) > max_age_seconds:
-                f.unlink()
-                removed += 1
-        return removed
-
-
-# =============================================================================
-# Pattern 2: Plan Persistence
-# =============================================================================
-
-
-@dataclass
-class PlanStep:
-    """Individual step in an agent plan.
-
-    Use when: building a plan that will be persisted to disk for later
-    re-reading across context window boundaries.
-    """
-
-    id: int
-    description: str
-    status: str = "pending"  # pending | in_progress | completed | blocked
-    notes: Optional[str] = None
-
-
-@dataclass
-class AgentPlan:
-    """Persistent plan that survives context window limitations.
-
-    Use when: an agent needs to track a multi-step objective across turns
-    or context refreshes. Write the plan to disk so the agent can re-read
-    it at any point, even after summarization or context window refresh.
-    """
-
-    objective: str
-    steps: List[PlanStep] = field(default_factory=list)
-    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Serialize the plan to a plain dict suitable for JSON output."""
-        return {
-            "objective": self.objective,
-            "created_at": self.created_at,
-            "steps": [
-                {
-                    "id": s.id,
-                    "description": s.description,
-                    "status": s.status,
-                    "notes": s.notes,
-                }
-                for s in self.steps
-            ],
-        }
-
-    def save(self, path: str = "scratch/current_plan.json") -> None:
-        """Persist plan to *path* as JSON.
-
-        Use when: a plan has been created or updated and must survive a
-        potential context refresh.
-        """
-        Path(path).parent.mkdir(parents=True, exist_ok=True)
-        with open(path, "w") as f:
-            json.dump(self.to_dict(), f, indent=2)
-        print(f"Plan saved to {path}")
-
-    @classmethod
-    def load(cls, path: str = "scratch/current_plan.json") -> AgentPlan:
-        """Load a plan from *path*.
-
-        Use when: resuming work in a new context window or after
-        summarization -- re-read the plan to restore task awareness.
-        """
-        with open(path, "r") as f:
-            data: Dict[str, Any] = json.load(f)
-
-        plan = cls(objective=data["objective"])
-        plan.created_at = data.get("created_at", "")
-
-        for step_data in data.get("steps", []):
-            plan.steps.append(
-                PlanStep(
-                    id=step_data["id"],
-                    description=step_data["description"],
-                    status=step_data["status"],
-                    notes=step_data.get("notes"),
-                )
-            )
-        return plan
-
-    def current_step(self) -> Optional[PlanStep]:
-        """Return the first non-completed step, or None if all are done.
-
-        Use when: determining what to work on next after re-reading a plan.
-        """
-        for step in self.steps:
-            if step.status not in ("completed", "cancelled"):
-                return step
-        return None
-
-    def complete_step(self, step_id: int, notes: Optional[str] = None) -> None:
-        """Mark step *step_id* as completed, optionally attaching *notes*.
-
-        Use when: an agent finishes a plan step and needs to record
-        progress before persisting the updated plan.
-        """
-        for step in self.steps:
-            if step.id == step_id:
-                step.status = "completed"
-                if notes:
-                    step.notes = notes
-                return
-        raise ValueError(f"Step {step_id} not found")
-
-    def progress_summary(self) -> str:
-        """Generate a compact progress string for context injection.
-
-        Use when: the agent needs a one-line status to include in context
-        without re-reading the full plan.
-        """
-        completed: int = sum(1 for s in self.steps if s.status == "completed")
-        total: int = len(self.steps)
-        current: Optional[PlanStep] = self.current_step()
-
-        summary: str = f"Objective: {self.objective}\n"
-        summary += f"Progress: {completed}/{total} steps completed\n"
-        if current:
-            summary += f"Current step: [{current.id}] {current.description}"
-        else:
-            summary += "All steps completed."
-
-        return summary
-
-
-# =============================================================================
-# Pattern 3: Tool Output Handler
-# =============================================================================
-
-
-class ToolOutputHandler:
-    """Automatically decide whether to inline or offload tool outputs.
-
-    Use when: building an agent loop that processes heterogeneous tool
-    outputs -- some small enough to inline, others requiring offload.
-    """
-
-    def __init__(self, scratch_pad: Optional[ScratchPadManager] = None) -> None:
-        self.scratch_pad: ScratchPadManager = scratch_pad or ScratchPadManager()
-
-    def process_output(self, tool_name: str, output: str) -> str:
-        """Return *output* directly if small, or a file reference if large.
-
-        Use when: handling a tool's return value in an agent loop. Pass
-        the result into context; offloading happens transparently.
-        """
-        if self.scratch_pad.should_offload(output):
-            ref: Dict[str, Any] = self.scratch_pad.offload(output, source=tool_name)
-            return self.scratch_pad.format_reference(ref)
-        return output
-
-
-# =============================================================================
-# Demonstration
-# =============================================================================
-
-
-def _demo_scratch_pad() -> None:
-    """Demonstrate the scratch pad offloading pattern."""
-    print("=" * 60)
-    print("DEMO: Scratch Pad for Tool Output Offloading")
-    print("=" * 60)
-
-    scratch = ScratchPadManager(base_path="demo_scratch", token_threshold=100)
-
-    # Small output stays in context
-    small_output: str = "API returned: {'status': 'ok', 'data': [1, 2, 3]}"
-    print(f"\nSmall output ({scratch.estimate_tokens(small_output)} tokens):")
-    print(f"  Should offload: {scratch.should_offload(small_output)}")
-
-    # Large output gets offloaded
-    large_output: str = """
-Search Results for "context engineering":
-
-1. Context Engineering: The Art of Curating LLM Context
-   URL: https://example.com/article1
-   Snippet: Context engineering is the discipline of managing what information
-   enters the language model's context window. Unlike prompt engineering which
-   focuses on instruction crafting, context engineering addresses the holistic
-   curation of all information...
-
-2. Building Production Agents with Effective Context Management
-   URL: https://example.com/article2
-   Snippet: Production agent systems require sophisticated context management
-   strategies. This includes compression, caching, and strategic partitioning
-   of work across sub-agents with isolated contexts...
-
-3. The Lost-in-Middle Problem and How to Avoid It
-   URL: https://example.com/article3
-   Snippet: Research shows that language models exhibit U-shaped attention
-   patterns, with information in the middle of long contexts receiving less
-   attention than content at the beginning or end...
-
-... (imagine 50 more results) ...
-"""
-
-    print(f"\nLarge output ({scratch.estimate_tokens(large_output)} tokens):")
-    print(f"  Should offload: {scratch.should_offload(large_output)}")
-
-    if scratch.should_offload(large_output):
-        ref = scratch.offload(large_output, source="web_search")
-        print(f"\nOffloaded to: {ref['path']}")
-        print(f"Tokens saved: {ref['tokens_saved']}")
-        print(f"\nReference for context:\n{scratch.format_reference(ref)}")
-
-
-def _demo_plan_persistence() -> None:
-    """Demonstrate the plan persistence pattern."""
-    print("\n" + "=" * 60)
-    print("DEMO: Plan Persistence for Long-Horizon Tasks")
-    print("=" * 60)
-
-    plan = AgentPlan(objective="Refactor authentication module")
-    plan.steps = [
-        PlanStep(id=1, description="Audit current auth endpoints"),
-        PlanStep(id=2, description="Design new token validation flow"),
-        PlanStep(id=3, description="Implement changes"),
-        PlanStep(id=4, description="Write tests"),
-        PlanStep(id=5, description="Deploy and monitor"),
-    ]
-
-    print("\nInitial plan:")
-    print(plan.progress_summary())
-
-    plan.save("demo_scratch/current_plan.json")
-
-    # Simulate completing first step
-    plan.complete_step(1, notes="Found 12 endpoints, 3 need updates")
-    plan.steps[1].status = "in_progress"
-
-    print("\nAfter completing step 1:")
-    print(plan.progress_summary())
-
-    plan.save("demo_scratch/current_plan.json")
-
-    # Simulate loading from file (as if in new context)
-    print("\n--- Simulating context refresh ---")
-    loaded_plan = AgentPlan.load("demo_scratch/current_plan.json")
-    print("\nPlan loaded from file:")
-    print(loaded_plan.progress_summary())
-
-
-def _demo_tool_handler() -> None:
-    """Demonstrate the integrated tool output handler."""
-    print("\n" + "=" * 60)
-    print("DEMO: Integrated Tool Output Handler")
-    print("=" * 60)
-
-    handler = ToolOutputHandler(
-        scratch_pad=ScratchPadManager(base_path="demo_scratch", token_threshold=50)
-    )
-
-    outputs: list[tuple[str, str]] = [
-        ("calculator", "42"),
-        ("file_read", "Error: File not found"),
-        (
-            "database_query",
-            """
-            Results (250 rows):
-            | id | name | email | created_at | status |
-            |----|------|-------|------------|--------|
-            | 1  | John | j@e.c | 2024-01-01 | active |
-            | 2  | Jane | j@e.c | 2024-01-02 | active |
-            ... (248 more rows) ...
-        """,
-        ),
-    ]
-
-    for tool_name, output in outputs:
-        processed: str = handler.process_output(tool_name, output)
-        print(f"\n{tool_name}:")
-        print(f"  Original length: {len(output)} chars")
-        print(f"  Processed: {processed[:100]}...")
-
-
-def _cleanup_demo() -> None:
-    """Remove demo files created during the demonstration."""
-    demo_path = Path("demo_scratch")
-    if demo_path.exists():
-        shutil.rmtree(demo_path)
-        print("\nDemo files cleaned up.")
-
-
-if __name__ == "__main__":
-    _demo_scratch_pad()
-    _demo_plan_persistence()
-    _demo_tool_handler()
-
-    print("\n" + "=" * 60)
-    print("Cleaning up demo files...")
-    _cleanup_demo()

package/.agents/skills/find-skills/SKILL.md

@@ -1,144 +0,0 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
-metadata:
-  provider: atomic
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Check the Leaderboard First
-
-Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
-
-For example, top skills for web development include:
-- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
-- `anthropics/skills` — Frontend design, document processing (100K+ installs)
-
-### Step 3: Search for Skills
-
-If the leaderboard doesn't cover the user's need, run the find command:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-### Step 4: Verify Quality Before Recommending
-
-**Do not recommend a skill based solely on search results.** Always verify:
-
-1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
-2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
-3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
-
-### Step 5: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install count and source
-3. The install command they can run
-4. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-(185K installs)
-
-To install it:
-npx skills add vercel-labs/agent-skills@react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
-```
-
-### Step 6: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```