feat: Add OpenClaw skill for iloom CLI

docs/iloom-commands.md

@@ -34,6 +34,7 @@ Complete documentation for all iloom CLI commands, options, and flags.
   - [il update](#il-update)
   - [il feedback](#il-feedback)
   - [il contribute](#il-contribute)
+  - [il openclaw](#il-openclaw)
   - [il telemetry](#il-telemetry)
 
 ---
@@ -2056,6 +2057,65 @@ il contribute "facebook/react"
 
 ---
 
+### il openclaw
+
+Register iloom as an OpenClaw skill by creating a symlink from the OpenClaw workspace to the project's `openclaw-skill/` directory.
+
+**Usage:**
+```bash
+il openclaw [options]
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-f, --force` | Overwrite existing skill registration | `false` |
+| `-w, --workspace <name>` | OpenClaw workspace name | `workspace` |
+
+**Behavior:**
+
+1. Verifies `openclaw-skill/` directory exists in the project root
+2. Checks that OpenClaw is installed (`~/.openclaw` exists)
+3. Checks that the specified workspace exists under `~/.openclaw/`
+4. Creates `~/.openclaw/<workspace>/skills/` directory if needed
+5. Creates symlink: `~/.openclaw/<workspace>/skills/iloom` → `<project-root>/openclaw-skill/`
+
+**Examples:**
+
+```bash
+# Register iloom skill in the default workspace
+il openclaw
+
+# Register in a specific workspace
+il openclaw --workspace my-workspace
+il openclaw -w my-workspace
+
+# Force overwrite an existing registration
+il openclaw --force
+il openclaw -f
+
+# Combine options
+il openclaw -f -w my-workspace
+```
+
+**Error Handling:**
+
+| Scenario | Behavior |
+|----------|----------|
+| `openclaw-skill/` missing from project | Error with clear message |
+| `~/.openclaw` not found | Friendly error suggesting OpenClaw is not installed |
+| Workspace not found | Error suggesting `--workspace` flag |
+| Target already correctly linked | Reports "Already linked" and exits successfully |
+| Target exists (wrong symlink/file/dir) | Error suggesting `--force` (and `--workspace` if using default workspace) |
+
+**Notes:**
+- This command does not create `~/.openclaw` or workspace directories — those are managed by OpenClaw itself
+- The `skills/` subdirectory under the workspace is safe to auto-create
+- Running the command multiple times is idempotent when the symlink is already correct
+
+---
+
 ### il telemetry
 
 Manage anonymous usage telemetry settings.

openclaw-skill/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: iloom
+description: Manage isolated Git worktrees and AI-assisted development workflows with iloom CLI. Use when you need to create workspaces for issues/PRs, commit and merge code, run dev servers, plan and decompose features into issues, enhance issue descriptions with AI, list active workspaces, or configure iloom projects. Covers the full loom lifecycle (init, start, finish, cleanup) and all development commands (spin, commit, rebase, build, test, lint). Also use when the user has an idea for improvement or new feature — route through `il plan` for ideation and decomposition.
+metadata: { "openclaw": { "emoji": "🧵", "requires": { "anyBins": ["il", "iloom"] } } }
+---
+
+# iloom
+
+Manage isolated Git worktrees with AI-assisted development workflows.
+
+## Terminology
+
+`<workItem>` — the identifier for a work item on your configured issue tracker. Examples: `42` or `#42` (GitHub), `ENG-456` (Linear), `PROJ-789` (Jira).
+
+## Execution Modes
+
+| Mode | Commands | Notes |
+|------|----------|-------|
+| **Plain exec** (no PTY, no background) | `list`, `issues`, `projects`, `recap`, `--version`, `start --no-claude --no-code --no-dev-server --no-terminal`, `cleanup --force`, `build`, `test`, `lint`, `compile`, `add-issue` | Fast, clean JSON output |
+| **Background** (`background:true`) | `plan`, `spin`, `start` (with Claude), `summary`, `enhance`, `commit`, `finish`, `rebase` | Long-running or spawns Claude — monitor with `process action:poll sessionId:XXX` |
+| **Foreground PTY only** | `init`, `shell` | Interactive — not for AI agents |
+
+See `{baseDir}/references/non-interactive-patterns.md` for the complete execution mode guide, session lifecycle, decision bypass map, and recommended autonomous flag combinations.
+
+## Project Initialization (First-Time Setup)
+
+Before using any iloom commands, the project must have a `.iloom/settings.json` file.
+
+```bash
+mkdir -p .iloom
+echo '{"mainBranch": "main"}' > .iloom/settings.json
+```
+
+See `{baseDir}/references/initialization.md` for the complete settings schema, all configuration options, remote configuration for fork workflows, and example configurations.
+
+## Workflow: Choosing the Right Approach
+
+### Sizeable Changes (multiple issues, architectural work)
+
+Use the **plan → review → start → spin → finish** workflow:
+
+1. **Plan:** `il plan --yolo --print --json-stream 'Description'` (background) — decomposes work into issues
+2. **Review:** Present the created epic to the user; wait for approval before continuing
+3. **Start:** `il start <workItem> --yolo --no-code --no-dev-server --no-claude --no-terminal --json` (plain exec) — creates workspace without Claude
+4. **Spin:** `il spin --yolo --print --json-stream` (background) — launches Claude separately
+5. **Finish:** `il finish --force --cleanup --no-browser --json-stream` (background) — merges and cleans up
+
+### Small Changes (single issue, quick fix)
+
+Create issue + workspace + launch Claude in one step:
+
+```bash
+bash background:true command:"il start 'Add dark mode support to the settings page' --yolo --no-code --json"
+```
+
+See `{baseDir}/references/core-workflow.md` for full command flags/examples and `{baseDir}/references/planning-and-issues.md` for planning details.
+
+## References
+
+- **Project initialization and settings schema:** See `{baseDir}/references/initialization.md`
+- **Core lifecycle commands (init, start, finish, cleanup, list):** See `{baseDir}/references/core-workflow.md`
+- **Development commands (spin, commit, rebase, build, test, etc.):** See `{baseDir}/references/development-commands.md`
+- **Planning and issue management (plan, add-issue, enhance, issues):** See `{baseDir}/references/planning-and-issues.md`
+- **Settings, env vars, and global flags:** See `{baseDir}/references/configuration.md`
+- **Non-interactive patterns (PTY, background, autonomous operation):** See `{baseDir}/references/non-interactive-patterns.md`
+
+## Safety Rules
+
+1. **Use the right execution mode** for each command — see the Execution Modes table above and `{baseDir}/references/non-interactive-patterns.md` for details.
+2. **Use `background:true`** for commands that launch Claude or run extended operations: `start` (with Claude), `spin`, `plan`, `commit`, `finish`, `rebase`.
+3. **Never run `il finish` without `--force`** in autonomous mode — it will hang on confirmation prompts.
+4. **Always pass explicit flags** to avoid interactive prompts. See `{baseDir}/references/non-interactive-patterns.md` for the complete decision bypass map.
+5. **Use `--json`** when you need to parse command output programmatically. **`--json` and `--json-stream` are mutually exclusive** — prefer `--json-stream` for commands that support it (commit, finish, rebase) since it provides incremental visibility. Use `--json` only for commands without `--json-stream` support (list, cleanup, start, etc.).
+6. **Prefer manual initialization** over `il init` — create `.iloom/settings.json` directly. See `{baseDir}/references/initialization.md`.
+7. **Respect worktree isolation** — each loom is an independent workspace. Run commands from within the correct worktree directory.
+8. **NEVER kill a background session you did not start.** Other looms may be running from separate planning or development sessions (the user's own work, other agents, or prior conversations). When you see unfamiliar background sessions, **leave them alone**. Only kill sessions you explicitly launched in the current workflow. If unsure, ask the user.
+9. **Send progress updates mid-turn.** Long-running loom operations (plan, spin, commit, finish) can take minutes. Use the `message` tool to send incremental status updates to the user while waiting — don't go silent. Examples: "🧵 Spin started for issue #5, monitoring…", "✅ Tests passing, spin entering code review phase", "🔀 Merging to main…". Keep the user in the loop.
+10. **GitHub labels must already exist on the repo.** `gh issue create --label` will fail if the label doesn't exist. If the user has **write or triage permissions** on the `issueManagement.github.remote` repo, you can create labels first (`gh label create <name> -R <repo>`). Otherwise, list existing labels (`gh label list -R <repo>`) and only use those, or omit labels entirely if none match.

openclaw-skill/references/configuration.md

@@ -0,0 +1,144 @@
+# Configuration
+
+## Settings System
+
+iloom uses a layered settings system with three files:
+
+| File | Location | Scope | Git |
+|------|----------|-------|-----|
+| Global settings | `~/.config/iloom-ai/settings.json` | All projects | N/A |
+| Project settings | `.iloom/settings.json` | This project | Committed |
+| Local settings | `.iloom/settings.local.json` | This machine | Gitignored |
+
+Local overrides project, project overrides global.
+
+For the complete settings schema and all configuration options, see `{baseDir}/references/initialization.md`.
+
+### Runtime Setting Overrides
+
+Use `--set` to override any setting for a single command:
+
+```bash
+bash pty:true command:"il start 42 --set mergeBehavior.mode=github-pr --set capabilities.web.basePort=4000"
+```
+
+The `--set` flag accepts dot notation and can be repeated.
+
+---
+
+## Environment Variables
+
+### iloom Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ILOOM_DEBUG` | Enable debug logging | `false` |
+| `ILOOM_SHELL` | Override shell detection | Auto-detect |
+| `ILOOM_SETTINGS_PATH` | Override settings file location | `~/.config/iloom-ai/settings.json` |
+| `ILOOM_NO_COLOR` | Disable colored output | `false` |
+| `ILOOM_DEV_SERVER_TIMEOUT` | Dev server startup timeout (ms) | `180000` |
+| `ILOOM_UPDATE_CACHE_TIMEOUT_MINS` | Update check cache TTL (minutes) | `60` |
+
+### Issue Tracker Variables
+
+| Variable | Description | Required For |
+|----------|-------------|-------------|
+| `LINEAR_API_TOKEN` | Linear API authentication | Linear integration |
+| `JIRA_HOST` | Jira instance URL | Jira integration |
+| `JIRA_USERNAME` | Jira username | Jira integration |
+| `JIRA_API_TOKEN` | Jira API token | Jira integration |
+| `JIRA_PROJECT_KEY` | Jira project key | Jira integration |
+
+### Standard Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CI` | When `true`, disables interactive prompts |
+| `CLAUDE_API_KEY` | Claude API key (if not using Claude CLI auth) |
+
+---
+
+## Global CLI Flags
+
+Available on all commands:
+
+| Flag | Description |
+|------|-------------|
+| `--help`, `-h` | Display command help |
+| `--version`, `-v` | Display iloom version |
+| `--debug` | Enable debug output |
+| `--no-color` | Disable colored output |
+| `--set <key=value>` | Override any setting (repeatable) |
+
+---
+
+## il projects
+
+List all configured iloom projects.
+
+```bash
+bash pty:true command:"il projects --json"
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--json` | boolean | `false` | Output as JSON array |
+
+### JSON Output
+
+```json
+[
+  {
+    "configuredAt": "2026-01-15T10:00:00.000Z",
+    "projectPath": "/path/to/project",
+    "projectName": "my-project",
+    "activeLooms": 3,
+    "capabilities": ["web", "cli"]
+  }
+]
+```
+
+---
+
+## il update
+
+Update iloom CLI to the latest version.
+
+```bash
+bash pty:true command:"il update"
+bash pty:true command:"il update --dry-run"
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--dry-run` | boolean | `false` | Check for updates without installing |
+
+Only works for globally installed iloom (`npm install -g`).
+
+---
+
+## il feedback
+
+Submit bug reports or feature requests to the iloom repository.
+
+```bash
+bash pty:true command:"il feedback 'The rebase command fails on merge commits' --body 'Steps to reproduce...' --json"
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `<description>` | positional | — | Feedback description (>30 chars, >3 words) |
+| `--body <text>` | string | — | Detailed body text |
+| `--json` | boolean | `false` | Output as JSON |
+
+---
+
+## il contribute
+
+Fork, clone, and set up the iloom repository for contribution.
+
+```bash
+bash pty:true command:"il contribute"
+```
+
+No flags. Interactive setup process.