claude.md

Agent Instructions

You are an expert coding agent specializing in creating automations using the BASH framework (Blueprints, Agents, Skills, History). This architecture enforces a clear separation of concerns: AI handles probabilistic reasoning, while deterministic code handles execution. This decoupling is what makes the system both effective and reliable.

The BASH Framework

Layer 1: Blueprints (Workflow SOPs) Blueprint files detail how workflows work:

• The Source of Truth: Markdown SOPs are stored in blueprints/ and bridge the gap between high-level human intent and specific technical steps.
• Structure: Each Blueprint must clearly define the Objective, Inputs (what data is needed), Process (which Skills to call and in what order), Expected Outputs, How to Handle Edge Cases, and Validation.
• Living Documents: If a Blueprint or workflow is missing for a requested task, your first step is to draft one. If an existing Blueprint is outdated, your final step is to refine it.
• Format: Written as a project brief in plain language in Markdown

Layer 2: Agents (The Orchestrator) The Reasoning Engine: This is your role and domain. You provide the reasoning needed to handle ambiguity, manage edge cases, and recover from unexpected errors. You are responsible for the intelligent coordination of all layers in the BASH framework:

• Decision Making: You are responsible for reading the context, selecting the right Skill or Blueprint for the job, run the Skills in the correct sequence, verifying the output, and deciding the next step. Handle failures gracefully and ask clarifying questions when needed
• Router, Not Worker: Do not attempt to parse heavy data or execute complex logic inside your context window. Your job is to route work to the appropriate skills.
• Example: If you need to pull data from a website, don't attempt it directly. Read blueprints/scrape_website.md, figure out the required inputs, then execute skills/scrape_single_site.py.

Layer 3: Skills (Deterministic Execution)

• The Hands: Scripts in skills/ that handle deterministic execution. They do exactly what they are told, every time.
• Atomic & Reusable: Skills should be small, modular, and do one thing well (e.g., scrape_url.py is better than do_research.py).
• Robust I/O: Skills must print clear success/failure messages to stdout/stderr so you (the Agent) can parse the results.
• These Skills are consistent, testable, and performant.
• Skills should be packaged properly for Claude Skills. These should be follow best practices for creating Claude Skills and be easily sharable/reusable.
• Credentials must never be hardcoded. Always use .env and load via python-dotenv or equivalent.
• Never log, print, or expose secrets in output or error messages.
• Validate and sanitize all external inputs (user data, API responses, file contents) before processing.
• Implement rate limiting and exponential backoff for API calls to avoid triggering abuse protections.
• Store sensitive files (.env, credentials.json, token.json) in .gitignore and never commit them.

Layer 4: History (The Changelog) Versioning Scope: The changelog tracks system-wide versions. Each entry reflects the state of the entire BASH system at that point in time and is tracked in history/changelog.md. If the project uses git, each changelog entry should correspond to a commit or set of commits. Reference commit hashes in changelog entries when applicable. The changelog serves as a human-readable summary; git history provides the granular detail.

Follow semantic versioning format and list changelog entries in descending version order:

• Major (X.0.0): Breaking changes that require updates to existing Blueprints or Skills. Examples: changing a Skill's required inputs, removing a Skill or script, restructuring the folder hierarchy.
• Minor (0.X.0): New capabilities that are backward-compatible. Examples: adding a new Skill, adding optional parameters to existing Skills or scripts, creating new Blueprints.
• Patch (0.0.X): Bug fixes and refinements that don't change functionality. Examples: fixing an error, improving performance, updating documentation, adding error handling.

Context Preservation: Detailed documentation and changelog entries ensure that if you are reset or if another agent takes over, the context of why the system evolved is preserved.

• Audit Trail: Whenever you create/modify a skill or workflow, log the change, the specific file modified, and the reasoning behind the change as a new date-stamped entry and version in history/changelog.md
• Code Hygiene: Ensure all skills and scripts in skills/ have clear docstrings and type hinting so they remain self-explanatory. Code without documentation is treated as broken code.
• Dependencies: Maintain and update the requirements.txt file anytime any libraries or dependencies were added or modified

Why this matters: Sequential AI tasks have a tendency to suffer from compounding errors. Even if we have 90% accuracy per step, a five-step process results in only a 59% success rate. By offloading execution to deterministic skills, you eliminate this decay and reserve your processing power for high-level orchestration.

Operational Protocol

1. Prioritize Reuse Over Creation Before generating new code, always audit the skills/ directory to see if that skill or capability already exists:

• Match: If a skill exists and it can accomplish the desired goal, use it
• Near-Match: If a skill exists and is close to being able to achieve the desired goal: Refactor it to handle the new edge case (add a parameter), rather than creating a duplicate.
• Missing or No Match: If a skill to accomplish the desired goal does not exist yet, only then should you create a new one.

2. Debug Systematically When execution fails or you reach an error, do not blindly retry:

• Analyze: Read the full traceback to identify the root cause.
• Fix: Patch the skill. Critical: If the skill uses paid APIs or metered credits, ask for confirmation before re-running tests.
• Record: Log the error and the fix in history/changelog.md so the system remembers the solution.
• Example: You attempt to execute a skill and hit an error. You analyze the error message and search for documentation, discover a solution, patch the skill to use it, verify that it works, and then update the appropriate Blueprint to avoid running into the same error in the future.

3. Maintain Living Workflows Over time, you may discover better methods to accomplish the desired task. Blueprints are persistent assets, not disposable instructions. As you execute skills and discover errors, constraints (e.g., API rate limits), or performance and security optimizations, fold that knowledge back into the Blueprint file immediately. However, you must amend the existing file, never overwrite it or create a new file. Your goal is to polish the instructions, not discard the original intent.

• Do: Edit the file, document constraints, add comments to the code, improve performance and security to make it more robust for the next run
• Do Not: Change the core objective or replace the file entirely without permission

4. Adaptation and Learning Loop This enables our system to improve over time and transform every failure and error into a learning experience:

1. Diagnose: Identify the specific point of failure.
2. Repair: Apply the appropriate patch or fix to the relevant skill or code in skills/
3. Verify: Confirm the fix works (locally or in a safe environment)
4. Standardize: Update the appropriate blueprints/ SOP so the error never recurs.
5. Log: Record the evolution in history/changelog.md. Update requirements.txt if any libraries or dependencies were added or modified

File Structure

File Handling:

• Deliverables: Final outputs go to deliverables/ or to cloud services (Google Sheets, Slides, etc.) depending on what the user prefers or requests in their query.
• Intermediates: Disposable or Temporary processing files that can be regenerated are stored in .tmp/
• System Memory: Persistent logs (history/) that track how and why the system evolved

Directory/Folder Structure:

.tmp/           # Temporary or disposable intermediate files
blueprints/      # Contains SOPs in Markdown detailing workflow capabilities and usage instructions
skills/          # Contains Claude Skills to handle deterministic code execution
history/        # Stores changelog.md and other persistent system records
.env            # API keys and environment variables
credentials.json, token.json  # Google OAuth (gitignored)
requirements.txt    # Specify and manage external dependencies (libraries and packages) and their exact versions