Sister Script

Document-first development. Automate only what's proven.

The document is the source of truth. Scripts are its children.

[!TIP]
LIFT stage of [play-learn-lift](../play-learn-lift/). Proven procedures become automation.

The Pattern

graph TD
    D[📄 Document] -->|manual test| C[💻 Commands]
    C -->|document| P[📋 Procedure]
    P -->|automate| S[🤖 Sister Script]
    S -->|improve| D

1. Start with natural language (PLAY)
2. Add manual commands (PLAY/LEARN)
3. Document working procedures (LEARN)
4. Generate automation (LIFT)

Bidirectional Evolution

• Document → Script: Proven procedures become automated
• Script → Document: Automation insights improve docs

Contents

The Intertwingularity

Sister-script is the LIFT stage of [play-learn-lift](../play-learn-lift/) — automate proven patterns.

graph LR
    SS[👯 sister-script] -->|LIFT stage of| PLL[🎮📚🚀 play-learn-lift]
    SS -->|automates| DOC[📄 documents]
    SS -->|produces| CODE[🤖 scripts]
    
    RN[📓 research-notebook] -->|feeds| SS
    SL[📜 session-log] -->|source for| SS

Sniffable Python: The Structure

Sister scripts should follow [sniffable-python/](../sniffable-python/) conventions:

#!/usr/bin/env python3
"""tool-name: One-line description.

Docstring becomes --help AND is visible to LLM.
"""

import argparse

def main():
    """CLI structure — sniff this to understand the tool."""
    parser = argparse.ArgumentParser(description=__doc__.split('\n')[0])
    # ... CLI tree here ...
    args = parser.parse_args()
    _dispatch(args)

# Implementation below the fold

Why sniffable Python for sister scripts?

• LLM can read main() and understand the CLI
• Human can run --help for the same info
• Single source of truth for documentation
• One sniff and you smell success

Directory-Agnostic Invocation

Critical pattern: Sister scripts must work when invoked from ANY directory, not just their parent. They find their skill context using the script's own location, not the caller's working directory.

Python

from pathlib import Path

# Find THIS script's location (not caller's cwd)
SCRIPT_DIR = Path(__file__).resolve().parent
SKILL_DIR = SCRIPT_DIR.parent  # If script is in skill/scripts/

# Find sibling files relative to skill, not caller
CONFIG_FILE = SKILL_DIR / "config.yml"
PATTERNS_DIR = SKILL_DIR / "patterns"

Why file?

• Path(file) — path to THIS script file
• .resolve() — resolve symlinks to get real location
• .parent — containing directory

See [sniffable-python/](../sniffable-python/) for the full Python pattern with templates.

Bash

#!/bin/bash
# tool-name: Works from any directory.

# Find THIS script's location (not the caller's cwd)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"  # If script is in skill/scripts/

# Now find sibling files relative to script location
CONFIG_FILE="$SKILL_DIR/config.yml"
PATTERNS_DIR="$SKILL_DIR/patterns"

load_patterns() {
    # Find patterns relative to skill, not caller
    for f in "$PATTERNS_DIR"/*.yml; do
        echo "Loading: $f"
    done
}

Why `BASH_SOURCE[0]}?

• $0 can be "bash" if script is sourced
• ${BASH_SOURCE[0]} always gives the script path
• Works whether script is executed directly or sourced

Why the subshell $(cd ... && pwd)?

• Resolves relative paths and symlinks
• Returns absolute path without changing caller's cwd

Why This Matters

The script finds its own context regardless of where it's invoked from.

Dovetails With

Sister Skills

Protocol Symbols

Navigation