@bastani/atomic 0.5.11-0 → 0.5.12-0

package/.agents/skills/workflow-creator/references/workflow-inputs.md

@@ -0,0 +1,274 @@
+# Workflow Inputs
+
+Workflows collect structured data from the user at invocation time through
+a single uniform API: `ctx.inputs` (and `s.inputs` inside stage
+callbacks). This reference covers how the inputs pipe works, when to
+declare a schema vs. rely on the free-form fallback, and how values
+reach the workflow from the CLI and the interactive picker.
+
+## The inputs pipe
+
+Every workflow run receives a `Record<string, string>` of inputs. The
+runtime populates it from whichever invocation surface the user chose:
+
+| Surface | How values are supplied | How they land in `ctx.inputs` |
+|---|---|---|
+| **Named run, positional** — `atomic workflow -n hello -a claude "fix the bug"` | A single positional prompt string | `{ prompt: "fix the bug" }` |
+| **Named run, structured** — `atomic workflow -n gen-spec -a claude --research_doc=notes.md --focus=standard` | One `--<field>=<value>` flag per declared input | `{ research_doc: "notes.md", focus: "standard" }` |
+| **Interactive picker** — `atomic workflow -a claude` | The user fills in a form rendered from the declared schema (or the default `prompt` field if the workflow is free-form) | Whatever the user typed, keyed by field name |
+
+Workflow code is the same either way — it always reads
+`ctx.inputs.<name>`. The invocation surface is a CLI concern, not a
+workflow concern.
+
+## Reading inputs
+
+For free-form workflows (no declared schema), the positional prompt
+lands under the reserved `prompt` key. Destructure it once at the top of
+`.run()` so every stage can close over a bare string:
+
+```ts
+defineWorkflow<"claude">({ name: "answer", description: "Single-turn answer" })
+  .run(async (ctx) => {
+    const prompt = ctx.inputs.prompt ?? "";
+
+    await ctx.stage({ name: "answer" }, {}, {}, async (s) => {
+      await s.session.query(prompt);
+      s.save(s.sessionId);
+    });
+  })
+  .compile();
+```
+
+For structured workflows, read each declared field by name. Pull them
+out of `ctx.inputs` once for readability and so downstream stages can
+close over locals:
+
+```ts
+defineWorkflow<"claude">({
+    name: "gen-spec",
+    description: "Convert a research doc into a detailed execution spec",
+    inputs: [
+      { name: "research_doc", type: "string", required: true },
+      {
+        name: "focus",
+        type: "enum",
+        required: true,
+        values: ["minimal", "standard", "exhaustive"],
+        default: "standard",
+      },
+      { name: "notes", type: "text" },
+    ],
+  })
+  .run(async (ctx) => {
+    const { research_doc, focus } = ctx.inputs;
+    const notes = ctx.inputs.notes ?? "";
+
+    await ctx.stage({ name: "write-spec" }, {}, {}, async (s) => {
+      await s.session.query(
+        `Read ${research_doc} and produce a ${focus} spec.` +
+          (notes ? `\n\nExtra guidance:\n${notes}` : ""),
+      );
+      s.save(s.sessionId);
+    });
+  })
+  .compile();
+```
+
+The nullish coalescing on `notes` handles the optional field case —
+declared-but-unset inputs resolve to `undefined` unless they have a
+`default`.
+
+## Declaring an input schema
+
+Pass an `inputs` array to `defineWorkflow({ ... })`. Each entry is a
+`WorkflowInput`:
+
+```ts
+interface WorkflowInput {
+  /** Field name — becomes the CLI flag (`--<name>`) and form label. */
+  name: string;
+  /** Input kind: string | text | enum */
+  type: "string" | "text" | "enum";
+  /** Whether the field must be non-empty before the workflow can run. */
+  required?: boolean;
+  /** Short description shown as the field caption. */
+  description?: string;
+  /** Placeholder shown when the field is empty. */
+  placeholder?: string;
+  /** Default value — enums use this to pick their initial value. */
+  default?: string;
+  /** Allowed values — required when `type` is `"enum"`. */
+  values?: string[];
+}
+```
+
+### Picking a field type
+
+| Type | Use when | Picker renders as | Example |
+|---|---|---|---|
+| `string` | Short single-line values — identifiers, file paths, branch names | Single-row text input | `research_doc: "notes.md"` |
+| `text` | Longer free-form prose — specs, prompts, extra context | Multi-row text area | `spec: "Build a..."` |
+| `enum` | A fixed set of allowed values | Radio-button row | `focus: "standard" \| "minimal" \| "exhaustive"` |
+
+Rule of thumb: use `enum` whenever there's a closed set of options — it
+gives users discoverable choices instead of making them remember magic
+strings, and the CLI will reject invalid values at parse time.
+
+### Validation enforced by the runtime
+
+The `defineWorkflow` builder validates the schema at compile time and
+rejects authoring mistakes immediately — you won't discover them in
+production:
+
+- **Input names must be valid CLI flag tails** — start with a letter,
+  then letters/digits/underscores/dashes. `1bad` is rejected because
+  `--1bad` isn't a parseable flag.
+- **Enum inputs must declare `values`** — an enum with no choices is
+  always invalid.
+- **Enum `default` must be in `values`** — prevents drift between the
+  default and the allowed set.
+- **No duplicate names** — two inputs with the same `name` shadow each
+  other and are rejected.
+
+At invocation time, the CLI does a second pass to catch runtime errors
+before spinning up any tmux session:
+
+- **Required fields must be non-empty** (whitespace-only strings are
+  treated as empty). Missing required fields produce a clear
+  `Missing required input --<name>` error and exit non-zero.
+- **Enum values must be in the allowed list.** `--focus=bogus` produces
+  `Invalid value for --focus: "bogus". Expected one of: minimal, standard, exhaustive.`
+- **Unknown flags are rejected.** A `--random_flag=value` that isn't in
+  the schema produces `Unknown input --random_flag` with the valid
+  flag list appended.
+
+This validation runs before any workflow code, so a malformed
+invocation can never reach your `.run()` callback in a half-filled
+state.
+
+## Free-form vs structured: when to use which
+
+Choose **free-form** (no `inputs` field on `defineWorkflow`) when:
+
+- The workflow takes a single unstructured request that varies widely
+  in phrasing — "find the bug", "build me a chart", "refactor the auth
+  module".
+- You want the simplest possible CLI surface.
+- The workflow's first LLM call will do its own intent extraction from
+  the raw prompt.
+
+Read the prompt via `ctx.inputs.prompt ?? ""`.
+
+Choose **structured** (declared `inputs: [...]`) when:
+
+- Several distinct fields are always needed — a file path + a focus
+  level + optional notes, for example.
+- You want the picker to show a real form (each field, its type, and
+  any validation cues) instead of a single blob text area.
+- You want the CLI to reject bad inputs before spawning a workflow —
+  e.g. a nonexistent enum value.
+- You want the invocation to be scriptable and auditable — flag-based
+  invocation reads cleanly in CI.
+
+Structured workflows can also include a `prompt` field in their schema
+if they need both a free-form request AND structured parameters. The
+`prompt` key is not magic for structured workflows — it's just a
+conventional name. You only get "positional maps to `prompt`" behavior
+when the workflow has no schema at all.
+
+## The interactive picker
+
+`atomic workflow -a <agent>` (no `-n`) launches the interactive
+picker. The picker:
+
+1. Discovers all workflows compatible with `<agent>` across local,
+   global, and builtin sources.
+2. Loads each workflow's metadata (description + declared inputs).
+3. Shows a Telescope-style fuzzy list. The user types to filter,
+   arrows to navigate, ↵ to lock in a selection.
+4. Renders the selected workflow's form. Free-form workflows get a
+   single `prompt` text field; structured workflows get one field
+   per declared input with type-specific rendering.
+5. Validates required fields on ⌃s. If any are empty, focus jumps to
+   the first invalid field and the run button stays disabled.
+6. Confirms with a y/n modal, then tears down the picker and hands
+   off to the workflow executor — same live-run surface users see
+   when they invoke the workflow with `-n` directly.
+
+The picker is the preferred discovery path for users who don't
+remember flag names. Structured workflows benefit the most from it
+because the form teaches the schema as the user fills it in.
+
+## Builtin protection
+
+Builtin workflows (the ones shipped inside the SDK — currently `ralph`
+and `deep-research-codebase`) are **reserved**. A local or global
+workflow with the same name will not shadow the builtin at resolution
+time — the runtime drops user-defined workflows with reserved names
+before any precedence merge. This prevents a user from accidentally
+redefining the canonical version of a workflow in a way that confuses
+teammates or breaks automation.
+
+You'll still see shadowed local/global workflows in
+`atomic workflow -l` output so the collision is visible, but running
+`atomic workflow -n ralph -a claude` will always land on the builtin.
+
+The practical implication: **don't name a new workflow `ralph` or
+`deep-research-codebase`**. Pick a distinct name and you'll never hit
+this.
+
+## Invocation cheat sheet
+
+```bash
+# List everything, grouped by source
+atomic workflow -l
+
+# Launch the picker for a pinned agent
+atomic workflow -a claude
+
+# Free-form, positional prompt
+atomic workflow -n hello -a claude "hello world"
+
+# Structured, one flag per field
+atomic workflow -n gen-spec -a claude \
+  --research_doc=research/docs/2026-04-11-auth.md \
+  --focus=standard \
+  --notes="pay special attention to session token storage"
+
+# Structured, long-form flag value (= form)
+atomic workflow -n gen-spec -a claude --focus standard --research_doc notes.md
+```
+
+Both `--flag=value` and `--flag value` forms are accepted. Short flags
+(`-x value`) are NOT parsed as structured inputs — only long-form
+`--<name>` flags resolve against the schema.
+
+## Pitfalls
+
+### Don't expect `inputs.prompt` on structured workflows
+
+A structured workflow that doesn't declare a `prompt` field will have
+`ctx.inputs.prompt === undefined`. The CLI also rejects a positional
+prompt for structured workflows outright — if you try
+`atomic workflow -n gen-spec -a claude "some text"` you'll get:
+
+> Error: workflow 'gen-spec' takes structured inputs — pass them as
+> `--<name>=<value>` flags instead of a positional prompt.
+
+If your workflow wants both a free-form prompt AND structured fields,
+declare `prompt` as a `text` input explicitly in the schema.
+
+### Don't rename inputs across workflow versions
+
+Declared input names are part of the workflow's public API — they map
+directly to `--<name>` flags and field identifiers in the picker.
+Renaming a field is a breaking change for any script that invokes the
+workflow. If you need to rename, add the new name alongside the old,
+migrate callers, then remove the old name in a later change.
+
+### Don't put secrets in `default`
+
+Defaults are visible in the picker and printed in CLI errors. They're
+fine for values like `"standard"` but not for API keys or auth tokens.
+Read those from environment variables inside the workflow instead.

package/.agents/skills/xlsx/LICENSE.txt

@@ -0,0 +1,30 @@
+© 2025 Anthropic, PBC. All rights reserved.
+
+LICENSE: Use of these materials (including all code, prompts, assets, files,
+and other components of this Skill) is governed by your agreement with
+Anthropic regarding use of Anthropic's services. If no separate agreement
+exists, use is governed by Anthropic's Consumer Terms of Service or
+Commercial Terms of Service, as applicable:
+https://www.anthropic.com/legal/consumer-terms
+https://www.anthropic.com/legal/commercial-terms
+Your applicable agreement is referred to as the "Agreement." "Services" are
+as defined in the Agreement.
+
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the
+contrary, users may not:
+
+- Extract these materials from the Services or retain copies of these
+  materials outside the Services
+- Reproduce or copy these materials, except for temporary copies created
+  automatically during authorized use of the Services
+- Create derivative works based on these materials
+- Distribute, sublicense, or transfer these materials to any third party
+- Make, offer to sell, sell, or import any inventions embodied in these
+  materials
+- Reverse engineer, decompile, or disassemble these materials
+
+The receipt, viewing, or possession of these materials does not convey or
+imply any license or right beyond those expressly granted above.
+
+Anthropic retains all right, title, and interest in these materials,
+including all copyrights, patents, and other intellectual property rights.

package/.agents/skills/xlsx/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: xlsx
+description: "Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \"the xlsx in my downloads\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved."
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Requirements for Outputs
+
+## All Excel files
+
+### Professional Font
+- Use a consistent, professional font (e.g., Arial, Times New Roman) for all deliverables unless otherwise instructed by the user
+
+### Zero Formula Errors
+- Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
+
+### Preserve Existing Templates (when updating templates)
+- Study and EXACTLY match existing format, style, and conventions when modifying files
+- Never impose standardized formatting on files with established patterns
+- Existing template conventions ALWAYS override these guidelines
+
+## Financial models
+
+### Color Coding Standards
+Unless otherwise stated by the user or existing template
+
+#### Industry-Standard Color Conventions
+- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios
+- **Black text (RGB: 0,0,0)**: ALL formulas and calculations
+- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook
+- **Red text (RGB: 255,0,0)**: External links to other files
+- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated
+
+### Number Formatting Standards
+
+#### Required Format Rules
+- **Years**: Format as text strings (e.g., "2024" not "2,024")
+- **Currency**: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
+- **Zeros**: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
+- **Percentages**: Default to 0.0% format (one decimal)
+- **Multiples**: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
+- **Negative numbers**: Use parentheses (123) not minus -123
+
+### Formula Construction Rules
+
+#### Assumptions Placement
+- Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
+- Use cell references instead of hardcoded values in formulas
+- Example: Use =B5*(1+$B$6) instead of =B5*1.05
+
+#### Formula Error Prevention
+- Verify all cell references are correct
+- Check for off-by-one errors in ranges
+- Ensure consistent formulas across all projection periods
+- Test with edge cases (zero values, negative numbers)
+- Verify no unintended circular references
+
+#### Documentation Requirements for Hardcodes
+- Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
+- Examples:
+  - "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
+  - "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
+  - "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
+  - "Source: FactSet, 8/20/2025, Consensus Estimates Screen"
+
+# XLSX creation, editing, and analysis
+
+## Overview
+
+A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.
+
+## Important Requirements
+
+**LibreOffice Required for Formula Recalculation**: You can assume LibreOffice is installed for recalculating formula values using the `scripts/recalc.py` script. The script automatically configures LibreOffice on first run, including in sandboxed environments where Unix sockets are restricted (handled by `scripts/office/soffice.py`)
+
+## Reading and analyzing data
+
+### Data analysis with pandas
+For data analysis, visualization, and basic operations, use **pandas** which provides powerful data manipulation capabilities:
+
+```python
+import pandas as pd
+
+# Read Excel
+df = pd.read_excel('file.xlsx')  # Default: first sheet
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict
+
+# Analyze
+df.head()      # Preview data
+df.info()      # Column info
+df.describe()  # Statistics
+
+# Write Excel
+df.to_excel('output.xlsx', index=False)
+```
+
+## Excel File Workflows
+
+## CRITICAL: Use Formulas, Not Hardcoded Values
+
+**Always use Excel formulas instead of calculating values in Python and hardcoding them.** This ensures the spreadsheet remains dynamic and updateable.
+
+### ❌ WRONG - Hardcoding Calculated Values
+```python
+# Bad: Calculating in Python and hardcoding result
+total = df['Sales'].sum()
+sheet['B10'] = total  # Hardcodes 5000
+
+# Bad: Computing growth rate in Python
+growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
+sheet['C5'] = growth  # Hardcodes 0.15
+
+# Bad: Python calculation for average
+avg = sum(values) / len(values)
+sheet['D20'] = avg  # Hardcodes 42.5
+```
+
+### ✅ CORRECT - Using Excel Formulas
+```python
+# Good: Let Excel calculate the sum
+sheet['B10'] = '=SUM(B2:B9)'
+
+# Good: Growth rate as Excel formula
+sheet['C5'] = '=(C4-C2)/C2'
+
+# Good: Average using Excel function
+sheet['D20'] = '=AVERAGE(D2:D19)'
+```
+
+This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.
+
+## Common Workflow
+1. **Choose tool**: pandas for data, openpyxl for formulas/formatting
+2. **Create/Load**: Create new workbook or load existing file
+3. **Modify**: Add/edit data, formulas, and formatting
+4. **Save**: Write to file
+5. **Recalculate formulas (MANDATORY IF USING FORMULAS)**: Use the scripts/recalc.py script
+   ```bash
+   python scripts/recalc.py output.xlsx
+   ```
+6. **Verify and fix any errors**: 
+   - The script returns JSON with error details
+   - If `status` is `errors_found`, check `error_summary` for specific error types and locations
+   - Fix the identified errors and recalculate again
+   - Common errors to fix:
+     - `#REF!`: Invalid cell references
+     - `#DIV/0!`: Division by zero
+     - `#VALUE!`: Wrong data type in formula
+     - `#NAME?`: Unrecognized formula name
+
+### Creating new Excel files
+
+```python
+# Using openpyxl for formulas and formatting
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+wb = Workbook()
+sheet = wb.active
+
+# Add data
+sheet['A1'] = 'Hello'
+sheet['B1'] = 'World'
+sheet.append(['Row', 'of', 'data'])
+
+# Add formula
+sheet['B2'] = '=SUM(A1:A10)'
+
+# Formatting
+sheet['A1'].font = Font(bold=True, color='FF0000')
+sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
+sheet['A1'].alignment = Alignment(horizontal='center')
+
+# Column width
+sheet.column_dimensions['A'].width = 20
+
+wb.save('output.xlsx')
+```
+
+### Editing existing Excel files
+
+```python
+# Using openpyxl to preserve formulas and formatting
+from openpyxl import load_workbook
+
+# Load existing file
+wb = load_workbook('existing.xlsx')
+sheet = wb.active  # or wb['SheetName'] for specific sheet
+
+# Working with multiple sheets
+for sheet_name in wb.sheetnames:
+    sheet = wb[sheet_name]
+    print(f"Sheet: {sheet_name}")
+
+# Modify cells
+sheet['A1'] = 'New Value'
+sheet.insert_rows(2)  # Insert row at position 2
+sheet.delete_cols(3)  # Delete column 3
+
+# Add new sheet
+new_sheet = wb.create_sheet('NewSheet')
+new_sheet['A1'] = 'Data'
+
+wb.save('modified.xlsx')
+```
+
+## Recalculating formulas
+
+Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided `scripts/recalc.py` script to recalculate formulas:
+
+```bash
+python scripts/recalc.py <excel_file> [timeout_seconds]
+```
+
+Example:
+```bash
+python scripts/recalc.py output.xlsx 30
+```
+
+The script:
+- Automatically sets up LibreOffice macro on first run
+- Recalculates all formulas in all sheets
+- Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
+- Returns JSON with detailed error locations and counts
+- Works on both Linux and macOS
+
+## Formula Verification Checklist
+
+Quick checks to ensure formulas work correctly:
+
+### Essential Verification
+- [ ] **Test 2-3 sample references**: Verify they pull correct values before building full model
+- [ ] **Column mapping**: Confirm Excel columns match (e.g., column 64 = BL, not BK)
+- [ ] **Row offset**: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
+
+### Common Pitfalls
+- [ ] **NaN handling**: Check for null values with `pd.notna()`
+- [ ] **Far-right columns**: FY data often in columns 50+ 
+- [ ] **Multiple matches**: Search all occurrences, not just first
+- [ ] **Division by zero**: Check denominators before using `/` in formulas (#DIV/0!)
+- [ ] **Wrong references**: Verify all cell references point to intended cells (#REF!)
+- [ ] **Cross-sheet references**: Use correct format (Sheet1!A1) for linking sheets
+
+### Formula Testing Strategy
+- [ ] **Start small**: Test formulas on 2-3 cells before applying broadly
+- [ ] **Verify dependencies**: Check all cells referenced in formulas exist
+- [ ] **Test edge cases**: Include zero, negative, and very large values
+
+### Interpreting scripts/recalc.py Output
+The script returns JSON with error details:
+```json
+{
+  "status": "success",           // or "errors_found"
+  "total_errors": 0,              // Total error count
+  "total_formulas": 42,           // Number of formulas in file
+  "error_summary": {              // Only present if errors found
+    "#REF!": {
+      "count": 2,
+      "locations": ["Sheet1!B5", "Sheet1!C10"]
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Library Selection
+- **pandas**: Best for data analysis, bulk operations, and simple data export
+- **openpyxl**: Best for complex formatting, formulas, and Excel-specific features
+
+### Working with openpyxl
+- Cell indices are 1-based (row=1, column=1 refers to cell A1)
+- Use `data_only=True` to read calculated values: `load_workbook('file.xlsx', data_only=True)`
+- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values and permanently lost
+- For large files: Use `read_only=True` for reading or `write_only=True` for writing
+- Formulas are preserved but not evaluated - use scripts/recalc.py to update values
+
+### Working with pandas
+- Specify data types to avoid inference issues: `pd.read_excel('file.xlsx', dtype={'id': str})`
+- For large files, read specific columns: `pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])`
+- Handle dates properly: `pd.read_excel('file.xlsx', parse_dates=['date_column'])`
+
+## Code Style Guidelines
+**IMPORTANT**: When generating Python code for Excel operations:
+- Write minimal, concise Python code without unnecessary comments
+- Avoid verbose variable names and redundant operations
+- Avoid unnecessary print statements
+
+**For Excel files themselves**:
+- Add comments to cells with complex formulas or important assumptions
+- Document data sources for hardcoded values
+- Include notes for key calculations and model sections