illusion-code 0.1.0__py3-none-any.whl

illusion/skills/bundled/content/loop.md

@@ -0,0 +1,82 @@
+---
+name: loop
+description: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo, defaults to 10m)
+argument-hint: "[interval] <prompt>"
+---
+
+# /loop — schedule a recurring prompt
+
+Parse the input below into `[interval] <prompt…>` and schedule it with the `cron` tool.
+
+## Parsing (in priority order)
+
+1. **Leading token**: if the first whitespace-delimited token matches `^\d+[smhd]$` (e.g. `5m`, `2h`), that's the interval; the rest is the prompt.
+2. **Trailing "every" clause**: otherwise, if the input ends with `every <N><unit>` or `every <N> <unit-word>` (e.g. `every 20m`, `every 5 minutes`, `every 2 hours`), extract that as the interval and strip it from the prompt. Only match when what follows "every" is a time expression — `check every PR` has no interval.
+3. **Default**: otherwise, interval is `10m` and the entire input is the prompt.
+
+If the resulting prompt is empty, show usage `/loop [interval] <prompt>` and stop — do not call the `cron` tool.
+
+## Interval → cron
+
+Supported suffixes: `s` (seconds, rounded up to nearest minute, min 1), `m` (minutes), `h` (hours), `d` (days). Convert:
+
+| Interval pattern      | Cron expression     | Notes                                    |
+|-----------------------|---------------------|------------------------------------------|
+| `Nm` where N ≤ 59   | `*/N * * * *`     | every N minutes                          |
+| `Nm` where N ≥ 60   | `0 */H * * *`     | round to hours (H = N/60, must divide 24)|
+| `Nh` where N ≤ 23   | `0 */N * * *`     | every N hours                            |
+| `Nd`                | `0 0 */N * *`     | every N days at midnight local           |
+| `Ns`                | treat as `ceil(N/60)m` | cron minimum granularity is 1 minute  |
+
+**If the interval doesn't cleanly divide its unit** (e.g. `7m` → `*/7 * * * *` gives uneven gaps at :56→:00; `90m` → 1.5h which cron can't express), pick the nearest clean interval and tell the user what you rounded to before scheduling.
+
+## Action
+
+1. Call the `cron` tool with:
+   - `action`: `"add"`
+   - `schedule`: the cron expression from the table above
+   - `prompt`: the parsed prompt from above, verbatim (slash commands are passed through unchanged)
+   - `recurring`: `true`
+   - `name`: a descriptive name for the job (optional, auto-generated if omitted)
+
+2. Briefly confirm: what's scheduled, the cron expression, the human-readable cadence, and that they can cancel with `cron` tool `action="remove"` (include the job name/ID).
+
+3. **Then immediately execute the parsed prompt now** — don't wait for the first cron fire. If it's a slash command, invoke it via the Skill tool; otherwise act on it directly.
+
+## Usage
+
+```
+/loop [interval] <prompt>
+
+Run a prompt or slash command on a recurring interval.
+
+Intervals: Ns, Nm, Nh, Nd (e.g. 5m, 30m, 2h, 1d). Minimum granularity is 1 minute.
+If no interval is specified, defaults to 10m.
+
+Examples:
+  /loop 5m /babysit-prs
+  /loop 30m check the deploy
+  /loop 1h /standup 1
+  /loop check the deploy          (defaults to 10m)
+  /loop check the deploy every 20m
+```
+
+## Cron Tool Reference
+
+The `cron` tool supports these actions:
+- `add`: Create a new scheduled job (requires `schedule`, `prompt`; optional `name`)
+- `update`: Modify an existing job (requires `name`)
+- `remove`: Delete a job (requires `name`)
+- `list`: List all scheduled jobs
+- `status`: Check scheduler status
+- `run`: Manually trigger a job immediately (requires `name`)
+
+**Important**: Recurring jobs do NOT auto-expire. Delete them manually with `action="remove"` when no longer needed.
+
+## Rules
+
+- Minimum interval is 1 minute
+- Recurring jobs do not auto-expire — user must delete manually
+- The prompt is executed immediately, not waiting for the first cron fire
+- Slash commands are passed through unchanged
+- Use `name` parameter to make jobs easier to identify and manage

illusion/skills/bundled/content/remember.md

@@ -0,0 +1,105 @@
+---
+name: remember
+description: Review memory entries and propose promotions, cleanup, or reorganization. Detects outdated, conflicting, and duplicate entries.
+---
+
+# Memory Review
+
+## Goal
+Review the user's memory landscape and produce a clear report of proposed changes, grouped by action type. Do NOT apply changes — present proposals for user approval.
+
+## Memory System Overview
+
+Illusion Code uses a file-based memory system:
+- **Memory directory**: `~/.illusion/data/memory/<project-name>-<hash>/`
+- **Entry point**: `MEMORY.md` (index file with links to memory files)
+- **Memory files**: Individual `.md` files with optional YAML frontmatter
+
+### Memory File Format
+```markdown
+---
+name: short-kebab-case-slug
+description: One-line summary for relevance matching
+type: user|feedback|project|reference
+---
+
+Memory content here. For feedback/project types, structure as:
+- Rule/fact
+- **Why:** Reason
+- **How to apply:** When/where this guidance applies
+```
+
+### Memory Types
+- **user**: User role, goals, preferences, knowledge
+- **feedback**: Guidance on how to approach work (corrections and confirmations)
+- **project**: Ongoing work, goals, initiatives, bugs
+- **reference**: Pointers to external resources
+
+## Steps
+
+### 1. Gather all memory layers
+- Read the `MEMORY.md` entry point from the project memory directory
+- Read all `.md` files in the memory directory (excluding MEMORY.md itself)
+- Check for any project-level configuration in `.illusion/` directory
+
+**Success criteria**: You have the contents of all memory files and can compare them.
+
+### 2. Classify each memory entry
+For each substantive memory entry, evaluate its current placement:
+
+| Check | What to look for |
+|-------|------------------|
+| **Staleness** | Is the information still accurate? Does it reference things that no longer exist? |
+| **Duplicates** | Is the same information captured in multiple places? |
+| **Conflicts** | Do any entries contradict each other? |
+| **Type accuracy** | Is the `type` field correct (user/feedback/project/reference)? |
+| **Description quality** | Does the description accurately summarize the content for relevance matching? |
+
+**Success criteria**: Each entry has been evaluated for the above checks.
+
+### 3. Identify cleanup opportunities
+Scan across all memory files for:
+- **Outdated entries**: Information contradicted by newer entries or current codebase state
+- **Duplicates**: Same information in multiple files
+- **Conflicts**: Contradictions between entries → propose resolution, noting which is more recent
+- **Orphaned entries**: Memory files not linked from MEMORY.md
+- **Missing descriptions**: Files without proper `description` field in frontmatter
+
+**Success criteria**: All issues identified.
+
+### 4. Present the report
+Output a structured report grouped by action type:
+
+1. **Updates** — entries that need content or metadata corrections
+   - Include: file name, what needs to change, why
+2. **Cleanup** — duplicates, outdated entries, conflicts to resolve
+   - Include: file names involved, recommendation
+3. **Reorganization** — entries that should be split, merged, or retyped
+   - Include: current file, proposed changes
+4. **No action needed** — brief note on entries that are fine as-is
+
+If memory is empty, say so and offer to help create initial memory entries.
+
+**Success criteria**: User can review and approve/reject each proposal individually.
+
+## Proposing Changes
+
+When proposing changes, use the memory file format:
+
+```markdown
+---
+name: proposed-slug
+description: One-line summary
+type: user|feedback|project|reference
+---
+
+Proposed content here.
+```
+
+## Rules
+- Present ALL proposals before making any changes
+- Do NOT modify files without explicit user approval
+- Do NOT create new files unless the target doesn't exist yet
+- Preserve the YAML frontmatter format when creating or updating files
+- Use `add_memory_entry` to create new memory files (handles slug generation and MEMORY.md indexing)
+- Use `remove_memory_entry` to delete memory files (handles MEMORY.md cleanup)

illusion/skills/bundled/content/simplify.md

@@ -0,0 +1,53 @@
+---
+name: simplify
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found.
+---
+
+# Simplify: Code Review and Cleanup
+
+Review all changed files for reuse, quality, and efficiency. Fix any issues found.
+
+## Phase 1: Identify Changes
+
+Run `git diff` (or `git diff HEAD` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
+
+## Phase 2: Launch Three Review Agents in Parallel
+
+Use the `agent` tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+
+### Agent 1: Code Reuse Review
+
+For each change:
+
+1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones.
+2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead.
+3. **Flag any inline logic that could use an existing utility** — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.
+
+### Agent 2: Code Quality Review
+
+Review the same changes for hacky patterns:
+
+1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
+2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones
+3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction
+4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
+5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
+6. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)
+
+### Agent 3: Efficiency Review
+
+Review the same changes for efficiency:
+
+1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
+2. **Missed concurrency**: independent operations run sequentially when they could run in parallel
+3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths
+4. **Recurring no-op updates**: state/store updates inside polling loops, intervals, or event handlers that fire unconditionally — add a change-detection guard so downstream consumers aren't notified when nothing changed
+5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
+6. **Memory**: unbounded data structures, missing cleanup, event listener leaks
+7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one
+
+## Phase 3: Fix Issues
+
+Wait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on — do not argue with the finding, just skip it.
+
+When done, briefly summarize what was fixed (or confirm the code was already clean).

illusion/skills/bundled/content/skillify.md

@@ -0,0 +1,113 @@
+---
+name: skillify
+description: "Capture this session's repeatable process into a skill. Call at end of the process you want to capture with an optional description."
+argument-hint: "[description of the process you want to capture]"
+---
+
+# Skillify
+
+You are capturing this session's repeatable process as a reusable skill.
+
+## Your Task
+
+### Step 1: Analyze the Session
+
+Before asking any questions, analyze the session to identify:
+- What repeatable process was performed
+- What the inputs/parameters were
+- The distinct steps (in order)
+- The success artifacts/criteria (e.g. not just "writing code," but "an open PR with CI fully passing") for each step
+- Where the user corrected or steered you
+- What tools and permissions were needed
+- What agents were used
+- What the goals and success artifacts were
+
+### Step 2: Interview the User
+
+You will use the `ask_user_question` tool to understand what the user wants to automate. Important notes:
+- Use `ask_user_question` for ALL questions! Never ask questions via plain text.
+- For each round, iterate as much as needed until the user is happy.
+- The user always has a freeform "Other" option to type edits or feedback -- do NOT add your own "Needs tweaking" or "I'll provide edits" option. Just offer the substantive choices.
+
+**Round 1: High level confirmation**
+- Suggest a name and description for the skill based on your analysis. Ask the user to confirm or rename.
+- Suggest high-level goal(s) and specific success criteria for the skill.
+
+**Round 2: More details**
+- Present the high-level steps you identified as a numbered list. Tell the user you will dig into the detail in the next round.
+- If you think the skill will require arguments, suggest arguments based on what you observed. Make sure you understand what someone would need to provide.
+- If it's not clear, ask if this skill should run inline (in the current conversation) or forked (as a sub-agent with its own context). Forked is better for self-contained tasks that don't need mid-process user input; inline is better when the user wants to steer mid-process.
+- Ask where the skill should be saved. Suggest a default based on context:
+  - **This repo** (`.illusion/skills/<name>/<name>.md`) — for workflows specific to this project
+  - **Personal** (`~/.illusion/skills/<name>.md`) — follows you across all repos
+
+**Round 3: Breaking down each step**
+For each major step, if it's not glaringly obvious, ask:
+- What does this step produce that later steps need? (data, artifacts, IDs)
+- What proves that this step succeeded, and that we can move on?
+- Should the user be asked to confirm before proceeding? (especially for irreversible actions like merging, sending messages, or destructive operations)
+- Are any steps independent and could run in parallel? (e.g., posting to Slack and monitoring CI at the same time)
+- How should the skill be executed? (e.g. always use a Task agent to conduct code review, or invoke an agent team for a set of concurrent steps)
+- What are the hard constraints or hard preferences? Things that must or must not happen?
+
+You may do multiple rounds of AskUserQuestion here, one round per step, especially if there are more than 3 steps or many clarification questions. Iterate as much as needed.
+
+IMPORTANT: Pay special attention to places where the user corrected you during the session, to help inform your design.
+
+**Round 4: Final questions**
+- Confirm when this skill should be invoked, and suggest/confirm trigger phrases too. (e.g. For a cherrypick workflow you could say: Use when the user wants to cherry-pick a PR to a release branch. Examples: 'cherry-pick to release', 'CP this PR', 'hotfix.')
+- You can also ask for any other gotchas or things to watch out for, if it's still unclear.
+
+Stop interviewing once you have enough information. IMPORTANT: Don't over-ask for simple processes!
+
+### Step 3: Write the SKILL.md
+
+Create the skill directory and file at the location the user chose in Round 2.
+
+Use this format:
+
+```markdown
+---
+name: {{skill-name}}
+description: {{one-line description}}
+---
+
+# {{Skill Title}}
+
+Description of when to use this skill.
+
+## Goal
+Clearly stated goal for this workflow. Best if you have clearly defined artifacts or criteria for completion.
+
+## Steps
+
+### 1. Step Name
+What to do in this step. Be specific and actionable. Include commands when appropriate.
+
+**Success criteria**: ALWAYS include this! This shows that the step is done and we can move on. Can be a list.
+
+...
+```
+
+**Note on frontmatter**: The skill loader only parses `name` and `description` from YAML frontmatter. Other fields (allowed-tools, when_to_use, arguments, context) are not currently supported but can be included as comments for documentation purposes.
+
+**Per-step annotations**:
+- **Success criteria** is REQUIRED on every step. This helps the model understand what the user expects from their workflow, and when it should have the confidence to move on.
+- **Execution**: `Direct` (default), `Task agent` (straightforward subagents), or `[human]` (user does it). Only needs specifying if not Direct.
+- **Artifacts**: Data this step produces that later steps need (e.g., PR number, commit SHA). Only include if later steps depend on it.
+- **Human checkpoint**: When to pause and ask the user before proceeding. Include for irreversible actions (merging, sending messages), error judgment (merge conflicts), or output review.
+- **Rules**: Hard rules for the workflow. User corrections during the reference session can be especially useful here.
+
+**Step structure tips:**
+- Steps that can run concurrently use sub-numbers: 3a, 3b
+- Steps requiring the user to act get `[human]` in the title
+- Keep simple skills simple — a 2-step skill doesn't need annotations on every step
+
+### Step 4: Confirm and Save
+
+Before writing the file, output the complete SKILL.md content as a yaml code block in your response so the user can review it with proper syntax highlighting. Then ask for confirmation using `ask_user_question` with a simple question like "Does this SKILL.md look good to save?" — do NOT use the body field, keep the question concise.
+
+After writing, tell the user:
+- Where the skill was saved
+- How to invoke it: `/{{skill-name}} [arguments]`
+- That they can edit the SKILL.md directly to refine it

illusion/skills/bundled/content/stuck.md

@@ -0,0 +1,54 @@
+---
+name: stuck
+description: Diagnose frozen/stuck/slow Illusion Code sessions on this machine and provide diagnostic report.
+---
+
+# /stuck — diagnose frozen/slow Illusion Code sessions
+
+The user thinks another Illusion Code session on this machine is frozen, stuck, or very slow. Investigate and provide a diagnostic report.
+
+## What to look for
+
+Scan for other Illusion Code processes (excluding the current one). The command name is `illusion`.
+
+Signs of a stuck session:
+- **High CPU (≥90%) sustained** — likely an infinite loop. Sample twice, 1-2s apart, to confirm it's not a transient spike.
+- **Process state `D` (uninterruptible sleep)** — often an I/O hang. The `state` column in `ps` output; first character matters (ignore modifiers like `+`, `s`, `<`).
+- **Process state `T` (stopped)** — user probably hit Ctrl+Z by accident.
+- **Process state `Z` (zombie)** — parent isn't reaping.
+- **Very high RSS (≥4GB)** — possible memory leak making the session sluggish.
+- **Stuck child process** — a hung `git`, `node`, or shell subprocess can freeze the parent. Check `pgrep -lP <pid>` for each session.
+
+## Investigation steps
+
+1. **List all Illusion Code processes** (macOS/Linux):
+   ```
+   ps -axo pid=,pcpu=,rss=,etime=,state=,comm=,command= | grep -E 'illusion' | grep -v grep
+   ```
+   Filter to rows where `comm` is `illusion` or command contains "illusion".
+
+2. **For anything suspicious**, gather more context:
+   - Child processes: `pgrep -lP <pid>`
+   - If high CPU: sample again after 1-2s to confirm it's sustained
+   - If a child looks hung (e.g., a git command), note its full command line with `ps -p <child_pid> -o command=`
+   - Check the session's debug log if you can infer the session ID: `~/.illusion/logs/<session-id>.log` (the last few hundred lines often show what it was doing before hanging)
+
+3. **Consider a stack dump** for a truly frozen process (advanced, optional):
+   - macOS: `sample <pid> 3` gives a 3-second native stack sample
+   - Linux: `kill -QUIT <pid>` sends a thread dump to stderr
+   - This is big — only grab it if the process is clearly hung and you want to know *why*
+
+## Report
+
+Format the report as a structured diagnostic:
+
+1. **Summary** — one short line: hostname, Illusion Code version, and a terse symptom (e.g. "session PID 12345 pegged at 100% CPU for 10min")
+2. **Details** — the full diagnostic dump:
+   - PID, CPU%, RSS, state, uptime, command line, child processes
+   - Your diagnosis of what's likely wrong
+   - Relevant debug log tail if you captured it
+
+## Notes
+- Don't kill or signal any processes — this is diagnostic only.
+- If the user gave an argument (e.g., a specific PID or symptom), focus there first.
+- If no processes are stuck, tell the user directly that everything looks healthy.