@nomad-e/bluma-cli 0.1.18 → 0.1.19

package/dist/config/skills/skill-creator/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: skill-creator
+description: >
+  Use this skill when the user wants to create, write, build, or author a new
+  BluMa skill. Triggers include: "create a skill", "make a new skill",
+  "build a skill for X", "I need a skill that does Y", "skill template",
+  or any request to package knowledge/workflows as a reusable skill module.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Instructions
+
+## Context
+You are a Skill Builder. You create new BluMa skills with the full Progressive Disclosure structure. Every skill you create MUST follow the standard layout.
+
+## Standard Skill Layout
+
+Every skill is a directory with this structure:
+
+```
+skill-name/
+  SKILL.md              # Core instructions (Level 2)
+  LICENSE.txt           # License terms
+  references/           # Additional docs loaded on-demand (Level 3a)
+    REFERENCE.md        # Advanced guide (if applicable)
+  scripts/              # Ready-made scripts (Level 3b)
+    (domain-relevant scripts)
+```
+
+The 3 levels of Progressive Disclosure:
+- **Level 1**: `description` in frontmatter — always visible in the skills list, acts as a trigger
+- **Level 2**: Body of SKILL.md — loaded when the skill is activated via `load_skill`
+- **Level 3**: `references/` and `scripts/` — accessed only when the task requires them
+
+## Procedure
+
+### Step 1: Ask Location (REQUIRED)
+
+Before anything else, ask the user where to create the skill:
+
+```
+message({
+  content: "Where should I create this skill?\n\n**1. Project** (`.bluma/skills/`) - Only available in THIS project\n**2. Global** (`~/.bluma/skills/`) - Available in ALL projects\n\nChoose 1 or 2:",
+  message_type: "result"
+})
+```
+
+Wait for user response before continuing.
+
+### Step 2: Analyze User Input
+
+Extract from user's content:
+- Purpose/domain
+- Responsibilities and workflows
+- Rules/constraints
+- Error scenarios
+- Whether the content is short (<100 lines) or extensive (>100 lines)
+
+### Step 3: Generate Skill Name
+
+Create kebab-case name from domain:
+- "git workflow" -> `git-workflow`
+- "api testing" -> `api-testing`
+- "pdf processing" -> `pdf`
+
+### Step 4: Determine Path
+
+Based on user's choice in Step 1:
+- **Project (1)**: `.bluma/skills/{name}/`
+- **Global (2)**: `~/.bluma/skills/{name}/`
+
+### Step 5: Check Directory
+
+```
+ls_tool({ path: "{chosen-path}/{name}" })
+```
+
+Verify directory doesn't exist (or confirm overwrite with user).
+
+### Step 6: Plan Content Split
+
+Decide what goes where based on content size:
+
+**If content is SHORT (<100 lines):**
+- Everything goes in SKILL.md body
+- references/ gets a minimal REFERENCE.md placeholder
+- scripts/ stays empty (or gets a single utility script if applicable)
+
+**If content is EXTENSIVE (>100 lines):**
+- SKILL.md body gets: overview, quick start, core procedure (the essentials)
+- references/ gets: advanced docs, detailed API guides, specialized topics
+- scripts/ gets: reusable scripts the agent can execute
+
+### Step 7: Create the Skill Structure
+
+Create the following files in order:
+
+**7a. Create SKILL.md**
+
+Use `edit_tool` with this template:
+
+```markdown
+---
+name: {kebab-case-name}
+description: >
+  Use this skill for any task involving {domain}. Triggers include: {list
+  of trigger phrases and keywords that should activate this skill}. Use
+  this skill whenever the user mentions {key terms} or any {domain}-related
+  task.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# {Domain} Guide
+
+## Overview
+
+{Brief description of what this skill covers and when to use it.}
+{If extensive content exists in references/, mention it here:}
+{For advanced features, see references/REFERENCE.md.}
+
+## Quick Start
+
+{Minimal example to get started — 5-10 lines max.}
+
+## Procedure
+
+### Step 1: {First Action}
+{Instructions}
+
+### Step 2: {Second Action}
+{Instructions}
+
+## Error Reference
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| {error} | {cause} | {fix} |
+
+## Available References
+
+{List each reference file with when to use it:}
+- REFERENCE.md: For advanced features and detailed API docs
+{Add more as needed}
+
+## Available Scripts
+
+{List each script with what it does:}
+- {script_name.py}: {one-line description}
+{Or "No scripts available for this skill." if none}
+
+## Next Steps
+
+{Point to references/ for advanced topics.}
+{Point to scripts/ for automation.}
+```
+
+**7b. Create LICENSE.txt**
+
+```
+edit_tool({
+  file_path: "{path}/{name}/LICENSE.txt",
+  old_string: "",
+  new_string: "© 2026 NomadEngenuity LDA. All rights reserved.\n\nLICENSE: Use of these materials..."
+})
+```
+
+Use the standard NomadEngenuity proprietary license (same as other native skills).
+
+**7c. Create references/REFERENCE.md**
+
+If extensive content exists, put advanced documentation here.
+If content is short, create a placeholder:
+
+```markdown
+# {Domain} — Advanced Reference
+
+{Advanced documentation, detailed examples, specialized topics.}
+{This file is loaded on-demand when the task requires deeper knowledge.}
+```
+
+**7d. Create scripts/ (if applicable)**
+
+If the domain benefits from ready-made scripts, create them.
+Each script should:
+- Be self-contained and executable with `python script.py [args]`
+- Include a docstring explaining what it does
+- Accept arguments via argparse or sys.argv
+- Print results to stdout or write to a specified output path
+
+Example script header:
+```python
+"""
+{description of what this script does}
+
+Usage:
+    python {script_name}.py --input data.csv --output ./artifacts/result.pdf
+"""
+import argparse
+```
+
+### Step 8: Report Result
+
+```
+message({
+  content: "Skill **{name}** created at `{path}/{name}/`\n\nStructure:\n- SKILL.md (core instructions)\n- LICENSE.txt\n- references/REFERENCE.md\n- scripts/ {list or empty}\n\nLocation: {Project|Global}\nThe skill is now available and will appear in the skills list.",
+  message_type: "result"
+})
+```
+
+## Location Reference
+
+| Location | Path | Scope | Use When |
+|----------|------|-------|----------|
+| Project | `.bluma/skills/` | This project only | Skill is specific to this codebase |
+| Global | `~/.bluma/skills/` | All projects | Skill is generic and reusable |
+
+## Guidelines
+
+- ALWAYS ask location first with `message_type: "result"`
+- ALWAYS create the full structure: SKILL.md + LICENSE.txt + references/ + scripts/
+- The `description` field is CRITICAL — it is the only text always visible and determines when the skill is activated. Include trigger words and phrases.
+- SKILL.md body should contain only the essentials (quick start + procedure). Advanced docs go in references/.
+- Scripts should be self-contained, executable, and well-documented.
+- Use lists not tables where possible (saves tokens)
+- No emojis in skill content
+- English only for skill content (translate user input if needed)
+- Professional, specific language
+- Extract ALL information from user input
+- NEVER create a skill with the same name as a native BluMa skill (check available_skills list first)

package/dist/config/skills/xlsx/LICENSE.txt

@@ -0,0 +1,18 @@
+BluMa — Base Language Unit · Model Agent
+Proprietary License
+
+Copyright (c) 2024-2026 BluMa Contributors
+
+This skill is part of the BluMa CLI distribution.
+It is provided as a bundled native skill and may not be
+redistributed, modified, or used outside of the BluMa agent
+framework without prior written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/dist/config/skills/xlsx/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: xlsx
+description: >
+  Use this skill any time a spreadsheet file is the primary input or output.
+  Triggers: open, read, edit, create, fix, or convert .xlsx, .xlsm, .csv,
+  or .tsv files — including adding columns, computing formulas, formatting,
+  charting, cleaning messy data, restructuring tabular data, or building
+  financial models. Also trigger when the user references a spreadsheet by
+  name or path and wants something done to it. The deliverable must be a
+  spreadsheet file. Do NOT trigger when the primary deliverable is a Word
+  document, HTML report, or standalone script.
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# XLSX — Spreadsheet Creation, Editing & Analysis
+
+## Core Principle
+
+> **Formulas, not hardcodes.** Every calculated value MUST be an Excel
+> formula so the spreadsheet stays dynamic. Never compute in Python and
+> paste the result into a cell.
+
+## Output Quality Standards
+
+### Professional Appearance
+- Consistent font throughout (Arial or Calibri, 10-11pt)
+- Headers bold with subtle background fill
+- Column widths auto-fitted to content
+- Number formatting applied to all numeric cells
+- Borders and alignment used consistently
+
+### Zero Formula Errors
+Every deliverable MUST have ZERO formula errors. After writing formulas,
+always run `scripts/recalc.py` and fix any errors before delivering.
+
+### Preserve Existing Templates
+When modifying an existing file, study and EXACTLY match its format,
+style, and conventions. Existing patterns override these guidelines.
+
+## Reading & Analyzing Data
+
+### Quick Analysis with pandas
+
+```python
+import pandas as pd
+
+df = pd.read_excel('file.xlsx')
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)
+
+df.head()
+df.info()
+df.describe()
+
+df.to_excel('output.xlsx', index=False)
+```
+
+### Reading with openpyxl (preserves formulas)
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook('file.xlsx')
+ws = wb.active
+
+for row in ws.iter_rows(min_row=1, max_row=5, values_only=True):
+    print(row)
+
+wb_data = load_workbook('file.xlsx', data_only=True)
+```
+
+**Warning**: Never open with `data_only=True` and save — formulas are
+permanently replaced with cached values.
+
+## Creating New Excel Files
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
+from openpyxl.utils import get_column_letter
+
+wb = Workbook()
+ws = wb.active
+ws.title = "Data"
+
+header_font = Font(bold=True, size=11, name='Arial')
+header_fill = PatternFill('solid', fgColor='D9E1F2')
+header_align = Alignment(horizontal='center', vertical='center')
+
+headers = ['Item', 'Qty', 'Unit Price', 'Total']
+for col, h in enumerate(headers, 1):
+    cell = ws.cell(row=1, column=col, value=h)
+    cell.font = header_font
+    cell.fill = header_fill
+    cell.alignment = header_align
+
+ws['D2'] = '=B2*C2'
+
+for col in range(1, len(headers) + 1):
+    ws.column_dimensions[get_column_letter(col)].width = 15
+
+wb.save('output.xlsx')
+```
+
+## Editing Existing Files
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook('existing.xlsx')
+ws = wb['SheetName']
+
+ws['A1'] = 'New Value'
+ws.insert_rows(2)
+ws.delete_cols(3)
+
+new_ws = wb.create_sheet('Summary')
+new_ws['A1'] = '=SUM(Data!B2:B100)'
+
+wb.save('modified.xlsx')
+```
+
+## Formula Rules
+
+### Always Use Excel Formulas
+
+```python
+# WRONG — hardcoded calculation
+total = sum(values)
+ws['B10'] = total
+
+# CORRECT — Excel formula
+ws['B10'] = '=SUM(B2:B9)'
+```
+
+This applies to ALL calculations: totals, averages, percentages,
+growth rates, ratios, conditional aggregations.
+
+### Common Formula Patterns
+
+| Operation | Formula |
+|-----------|---------|
+| Sum | `=SUM(B2:B9)` |
+| Average | `=AVERAGE(B2:B9)` |
+| Count non-empty | `=COUNTA(B2:B9)` |
+| Percentage | `=B2/B$10` |
+| Year-over-year growth | `=(C2-B2)/B2` |
+| Conditional sum | `=SUMIF(A:A,"Category",B:B)` |
+| Lookup | `=VLOOKUP(A2,Data!A:C,3,FALSE)` |
+| If/then | `=IF(B2>0,B2*C2,0)` |
+| Error handling | `=IFERROR(B2/C2,0)` |
+
+### Cross-Sheet References
+
+```python
+ws['A1'] = "=Summary!B5"
+ws['A2'] = "=VLOOKUP(A1,Data!A:C,3,FALSE)"
+```
+
+## Recalculating Formulas (MANDATORY)
+
+After creating or editing formulas with openpyxl, values are NOT
+calculated. You MUST run recalculation:
+
+```bash
+python scripts/recalc.py output.xlsx
+```
+
+The script returns JSON:
+
+```json
+{
+  "status": "success",
+  "total_errors": 0,
+  "total_formulas": 42,
+  "sheets_processed": ["Sheet1", "Summary"]
+}
+```
+
+If errors are found:
+
+```json
+{
+  "status": "errors_found",
+  "total_errors": 3,
+  "total_formulas": 42,
+  "error_summary": {
+    "#REF!": {"count": 2, "locations": ["Sheet1!B5", "Sheet1!C10"]},
+    "#DIV/0!": {"count": 1, "locations": ["Summary!D4"]}
+  }
+}
+```
+
+**Fix all errors and recalculate again until status is "success".**
+
+Common error fixes:
+- `#REF!` — Invalid cell reference; check if rows/columns were deleted
+- `#DIV/0!` — Wrap with `=IFERROR(formula, 0)`
+- `#VALUE!` — Wrong data type; check cell contents
+- `#NAME?` — Typo in function name or missing quotes on strings
+- `#N/A` — VLOOKUP/MATCH found no result; use `=IFERROR()`
+
+## Financial Model Standards
+
+### Color Coding (Industry Standard)
+
+| Color | RGB | Usage |
+|-------|-----|-------|
+| Blue text | `0000FF` | Hardcoded inputs and assumptions |
+| Black text | `000000` | All formulas and calculations |
+| Green text | `008000` | Links to other sheets in same workbook |
+| Red text | `FF0000` | External links to other files |
+| Yellow background | `FFFF00` | Key assumptions needing attention |
+
+```python
+from openpyxl.styles import Font, PatternFill
+
+input_font = Font(color='0000FF', name='Arial', size=11)
+formula_font = Font(color='000000', name='Arial', size=11)
+crossref_font = Font(color='008000', name='Arial', size=11)
+attention_fill = PatternFill('solid', fgColor='FFFF00')
+```
+
+### Number Formatting
+
+| Data Type | Format Code | Example |
+|-----------|-------------|---------|
+| Currency | `$#,##0;($#,##0);"-"` | $1,500 / ($200) / - |
+| Percentage | `0.0%` | 15.3% |
+| Multiples | `0.0x` | 8.5x |
+| Years | `@` (text) | 2024 (not 2,024) |
+| Large numbers | `$#,##0.0,,"mm"` | $1.5mm |
+| Integers | `#,##0;(#,##0);"-"` | 1,500 / (200) / - |
+
+```python
+ws['B2'].number_format = '$#,##0;($#,##0);"-"'
+ws['C2'].number_format = '0.0%'
+ws['D2'].number_format = '0.0x'
+```
+
+### Assumptions Placement
+
+Place ALL assumptions in dedicated cells with blue text. Never
+hardcode values inside formulas:
+
+```python
+ws['B3'] = 0.05
+ws['B3'].font = input_font
+ws['B3'].number_format = '0.0%'
+ws['B3'].comment = openpyxl.comments.Comment(
+    'Revenue growth assumption — Source: Management guidance FY2025',
+    'BluMa'
+)
+
+ws['C5'] = '=C4*(1+$B$3)'
+ws['C5'].font = formula_font
+```
+
+### Documentation for Hardcoded Values
+
+Every hardcoded number needs a source comment:
+- `Source: Company 10-K, FY2024, Page 45, Revenue Note`
+- `Source: Bloomberg Terminal, 2025-08-15, AAPL US Equity`
+- `Source: FactSet, Consensus Estimates, 2025-08-20`
+
+## Verification Checklist
+
+Before delivering any xlsx file:
+
+1. Run `scripts/recalc.py` — status must be "success"
+2. Spot-check 3-5 formulas against expected values
+3. Verify column mappings (Excel columns are 1-indexed)
+4. Check row offsets (DataFrame row 5 = Excel row 6 with header)
+5. Confirm no NaN or None values leaked into cells
+6. Validate number formatting on all numeric columns
+7. Ensure all hardcodes have source comments (financial models)
+8. Test edge cases: zero values, empty cells, negative numbers
+
+## Library Selection Guide
+
+| Task | Use |
+|------|-----|
+| Data analysis, filtering, grouping | pandas |
+| Formulas, formatting, styles | openpyxl |
+| Complex formatting + data analysis | Both (pandas to process, openpyxl to format) |
+| Read calculated values (no edit) | openpyxl with `data_only=True` |
+| Very large files (read-only) | openpyxl with `read_only=True` |
+
+## Available References
+
+- REFERENCE.md: Advanced financial modeling patterns, chart creation, pivot tables, conditional formatting, data validation, print layout
+
+## Available Scripts
+
+- recalc.py: Recalculate all formulas via LibreOffice and scan for errors (MANDATORY after formula changes)
+- office/soffice.py: LibreOffice process management for sandboxed environments (internal)
+- office/pack.py: Compress Office XML files into .xlsx (internal)
+- office/unpack.py: Decompress .xlsx into Office XML structure (internal)
+- office/validate.py: Validate Office XML structure against schemas (internal)