jinn-cli 0.1.0

package/template/skills/management/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: management
+description: Manage the AI organization — hire, fire, promote, delegate, and review boards
+---
+
+# Management Skill
+
+## Trigger
+
+This skill activates when the user wants to manage their organization: hiring or firing employees, creating departments, promoting or demoting staff, delegating tasks, reviewing task boards, or restructuring teams.
+
+## Organization Structure
+
+The organization lives under the `org/` directory in the {{portalName}} home folder (`~/.jinn/org/`). Each department is a subdirectory containing employee persona YAML files and a task board.
+
+```
+org/
+  engineering/
+    department.yaml
+    board.json
+    lead-developer.yaml
+    backend-dev.yaml
+  marketing/
+    department.yaml
+    board.json
+    seo-specialist.yaml
+```
+
+## Rank Definitions
+
+- **executive** — Full access. Can see all departments and boards. Can hire and fire anyone across the entire organization.
+- **manager** — Can manage their own department. Can hire within their department. Can see and manage their department's board.
+- **senior** — Can update their own tasks. Can mentor other employees in the department.
+- **employee** — Can update their own tasks only.
+
+## Operations
+
+### Hiring an Employee
+
+Create a persona YAML file at `org/<department>/<name>.yaml`.
+
+Required fields:
+- `name` — kebab-case identifier (must match filename without extension)
+- `displayName` — human-readable name
+- `department` — department this employee belongs to (must match parent directory name)
+- `rank` — one of: executive, manager, senior, employee
+- `engine` — AI engine to use: `claude` or `codex`
+- `model` — model identifier (e.g., `sonnet`, `opus`, `o3`)
+- `persona` — multiline description of who this employee is and how they behave
+
+Example (`org/marketing/seo-specialist.yaml`):
+
+```yaml
+name: seo-specialist
+displayName: Sarah SEO
+department: marketing
+rank: employee
+engine: claude
+model: sonnet
+persona: |
+  You are Sarah, an SEO specialist in the marketing department.
+  You focus on keyword research, content optimization, and
+  technical SEO. You report to the marketing manager.
+  Your expertise includes Google Search Console, Ahrefs,
+  and content strategy.
+```
+
+Steps:
+1. Confirm the target department exists under `org/`. If not, ask the user whether to create it first.
+2. Choose a kebab-case name for the employee (e.g., `lead-developer`, `seo-specialist`).
+3. Ask the user for displayName, rank, engine, model, and persona if not provided.
+4. Write the YAML file to `org/<department>/<name>.yaml`.
+5. Confirm the hire to the user.
+
+### Firing an Employee
+
+1. Locate the employee's YAML file under `org/<department>/<name>.yaml`.
+2. Check if the employee has any active tasks on the department board (`board.json` with status other than `done`). Warn the user if so.
+3. Delete the YAML file.
+4. Remove the employee as assignee from any tasks in `board.json` (set assignee to `unassigned`).
+5. Confirm the removal to the user.
+
+### Creating a Department
+
+1. Create the directory `org/<dept-name>/`.
+2. Create `org/<dept-name>/department.yaml` with:
+   ```yaml
+   name: dept-name
+   displayName: Department Display Name
+   description: What this department does.
+   ```
+3. Create `org/<dept-name>/board.json` with an empty array: `[]`
+4. Confirm the department creation to the user.
+
+### Promoting or Demoting an Employee
+
+1. Read the employee's YAML file at `org/<department>/<name>.yaml`.
+2. Update the `rank` field to the new rank.
+3. If promoting to **manager**, add delegation capabilities to their persona (see "Promoting to Manager" below).
+4. Write the updated YAML back to the file.
+5. Confirm the change to the user, stating the old and new rank.
+
+### Promoting to Manager
+
+When promoting an employee to manager rank, their persona must be extended with delegation capabilities so they can manage their own reports. Append the following to their existing persona:
+
+```yaml
+persona: |
+  [... existing persona content ...]
+
+  ## Manager Responsibilities
+  You are the manager of the [department] department. In addition to your
+  technical expertise, you:
+
+  - Manage and delegate tasks to employees in your department
+  - You can spawn child sessions via the gateway API to delegate work
+  - Apply oversight levels to your reports' work:
+    - TRUST: simple lookups, status checks — relay directly
+    - VERIFY: code changes, routine work — spot-check key outputs
+    - THOROUGH: architecture, breaking changes — full review, multi-turn
+  - Report summaries back to the COO ({{portalName}}), not raw employee output
+  - Use the department board (board.json) to track task status
+  - When given a task by the COO, decide whether to do it yourself or
+    delegate to the right employee based on their skills and workload
+
+  ## Delegation API
+  - Create child session: POST /api/sessions with parentSessionId
+  - Send follow-up: POST /api/sessions/:id/message
+  - Poll status: GET /api/sessions/:id
+  - List your reports: GET /api/org
+```
+
+**When to suggest promoting to manager:**
+- A department has 3+ employees
+- You're spending excessive time on per-employee delegation in that department
+- A senior employee has consistently delivered high-quality work
+- The user explicitly requests it
+
+### Delegating Tasks
+
+Add a task object to the department's `board.json` file.
+
+Task object schema:
+
+```json
+{
+  "id": "uuid-v4",
+  "title": "Short description of the task",
+  "assignee": "employee-name",
+  "status": "todo",
+  "priority": "high",
+  "description": "Detailed description of what needs to be done.",
+  "createdAt": "2025-01-15T10:30:00.000Z",
+  "updatedAt": "2025-01-15T10:30:00.000Z"
+}
+```
+
+Field details:
+- `id` — generate a UUID v4
+- `title` — short, descriptive title
+- `assignee` — the `name` field from the employee's YAML (must match an existing employee in the department)
+- `status` — one of: `todo`, `in-progress`, `review`, `done`
+- `priority` — one of: `high`, `medium`, `low`
+- `description` — detailed task description
+- `createdAt` — ISO 8601 timestamp when the task was created
+- `updatedAt` — ISO 8601 timestamp, same as createdAt initially
+
+Steps:
+1. Read the current `board.json` for the department.
+2. Verify the assignee exists as an employee in that department.
+3. Generate a new task object with a UUID.
+4. Append the task to the array.
+5. Write the updated array back to `board.json`.
+6. Confirm the delegation to the user.
+
+### Reviewing Boards
+
+1. Read the department's `board.json`.
+2. Present tasks grouped by status: todo, in-progress, review, done.
+3. Include priority and assignee for each task.
+4. If the user wants to update a task status, modify the task's `status` and `updatedAt` fields in the JSON array and write it back.
+
+### Restructuring (Moving Employees Between Departments)
+
+1. Read the employee's YAML from the source department.
+2. Update the `department` field to the new department name.
+3. Write the YAML to the new department directory.
+4. Delete the YAML from the old department directory.
+5. Move any assigned tasks from the old board to the new board (or reassign them, based on user preference).
+6. Confirm the move to the user.
+
+## Communication Rules
+
+- Messages from higher-ranked employees can reference and direct lower-ranked employees.
+- @mentions in messages (e.g., `@seo-specialist`) route to the mentioned employee's engine and model as defined in their persona YAML.
+- An executive can message anyone. A manager can message employees within their department. Seniors and employees can message peers and their manager.
+
+## Error Handling
+
+- If a department does not exist when hiring, offer to create it.
+- If an employee name conflicts with an existing file, warn the user and ask for a different name.
+- If `board.json` is malformed, attempt to parse and fix it. If unrecoverable, back it up and create a fresh empty board.
+- Always validate YAML before writing to ensure it is well-formed.

package/template/skills/migrate/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: migrate
+description: Apply pending version migrations to update this {{portalName}} instance
+---
+
+# Migrate Skill
+
+## Trigger
+
+This skill activates when the user runs `/migrate`, when launched by `jinn migrate`, or when asked to update/upgrade the instance.
+
+## Overview
+
+When a new version of Jinn is released, it may include updated skills, new documentation, improved prompts, or config schema changes. These updates are shipped as **migration folders** in `~/.jinn/migrations/<version>/`. Each folder contains:
+
+- `MIGRATION.md` — AI-readable instructions describing exactly what changed
+- `files/` — New or updated files in their correct relative directory structure
+
+Your job is to apply these migrations **intelligently** — preserving user customizations while incorporating improvements.
+
+## Steps
+
+### 1. Read Current Version
+
+Read `~/.jinn/config.yaml` and note the `jinn.version` field. If the field is missing, assume `0.0.0`.
+
+### 2. List Pending Migrations
+
+List all directories in `~/.jinn/migrations/`. Each directory name is a semver version string (e.g., `0.2.0`, `0.3.0`).
+
+Sort them in ascending semver order. Filter to only versions **greater than** the current instance version.
+
+If no pending migrations exist, inform the user they are up to date and stop.
+
+### 3. Apply Each Migration In Order
+
+For each pending version, in ascending order:
+
+#### a. Read the Migration Instructions
+
+Read `~/.jinn/migrations/<version>/MIGRATION.md`. This file describes:
+- What changed in this version
+- Which files are new (safe to copy directly)
+- Which files were updated (need intelligent merging)
+- Any config schema changes
+- Any breaking changes or manual steps
+
+#### b. Follow the Instructions
+
+The MIGRATION.md will categorize changes:
+
+**New files** (safe — just copy):
+- Copy from `~/.jinn/migrations/<version>/files/<path>` to `~/.jinn/<path>`
+- These are files that didn't exist before — no conflict possible
+
+**Updated files** (needs merge):
+- The migration provides the **new template version** of the file
+- Read the user's **current version** of the file
+- Compare them and merge intelligently:
+  - For **CLAUDE.md / AGENTS.md**: Look for new sections in the template that don't exist in the user's file. Append them. Never remove user customizations.
+  - For **config.yaml**: Add new keys with their default values. Never overwrite existing user values.
+  - For **skills**: If the user hasn't modified the skill (compare with previous template version if available), replace it. If modified, merge new instructions while preserving customizations.
+  - For **docs**: Replace entirely — these are reference docs, not user-customized.
+
+**Removed files** (careful):
+- Only remove files explicitly listed in MIGRATION.md
+- Back up to `<filename>.pre-migration.bak` before removing
+
+#### c. Back Up Before Modifying
+
+Before modifying any existing file, create a backup:
+- Copy `file.ext` to `file.ext.pre-<version>.bak`
+- Example: `CLAUDE.md` → `CLAUDE.md.pre-0.2.0.bak`
+
+This ensures the user can always recover if something goes wrong.
+
+### 4. Update Version
+
+After all migrations are successfully applied, update `config.yaml`:
+
+```yaml
+jinn:
+  version: "<final-migrated-version>"
+```
+
+### 5. Sync Skill Symlinks
+
+After adding any new skills, ensure their symlinks exist:
+- `~/.jinn/.claude/skills/<skill-name>` → `../../skills/<skill-name>`
+- `~/.jinn/.agents/skills/<skill-name>` → `../../skills/<skill-name>`
+
+### 6. Clean Up
+
+Remove the applied migration directories from `~/.jinn/migrations/`.
+Keep the backup files — the user can delete them manually later.
+
+### 7. Report
+
+Give the user a clear summary:
+
+```
+Migration complete: v{old} → v{new}
+
+Added:
+- skills/migrate/ (new skill)
+- docs/migrations.md (new doc)
+
+Updated:
+- CLAUDE.md (added new delegation protocol section)
+- config.yaml (added jinn.version field)
+
+Backups created:
+- CLAUDE.md.pre-0.2.0.bak
+- config.yaml.pre-0.2.0.bak
+```
+
+## Merge Strategy Reference
+
+### CLAUDE.md / AGENTS.md Merging
+
+These are the most sensitive files — users heavily customize them. Follow this strategy:
+
+1. **Identify sections** by markdown headings (`# Heading`, `## Heading`)
+2. **New sections**: If the template has a section heading that doesn't exist in the user's file, append the entire section
+3. **Updated sections**: If both have the same section, keep the user's version unless MIGRATION.md explicitly says to replace it
+4. **Deleted sections**: Only remove if MIGRATION.md explicitly says to
+5. **Order**: Maintain the user's existing section order; append new sections at the end
+
+### config.yaml Merging
+
+1. **New top-level keys**: Add with their default values
+2. **New nested keys**: Add under the existing parent with defaults
+3. **Existing keys**: Never overwrite — the user's values take priority
+4. **Removed keys**: Only remove if MIGRATION.md explicitly says to (rare)
+
+### Skills Merging
+
+1. **New skill directories**: Copy entirely
+2. **Updated skills**: Check if the user's SKILL.md differs from the previous template version
+   - If identical (user never customized): replace with new version
+   - If different (user customized): merge cautiously, preserving user additions
+3. **Supporting files** (data, templates within skill dirs): Update unless user-modified
+
+## Error Handling
+
+- If a migration fails mid-way, **stop**. Do not continue to later versions.
+- Note which version failed and what step failed.
+- The version in config.yaml was NOT updated yet, so re-running `jinn migrate` will retry.
+- If a file conflict cannot be resolved automatically, **ask the user** for guidance.
+- If MIGRATION.md is missing from a version folder, skip that version and warn the user.
+
+## Dry Run
+
+If the user asks for a dry run or preview, read all pending MIGRATION.md files and summarize what would change — without modifying any files.

package/template/skills/new/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: new
+description: Reset the current chat session and start fresh
+---
+
+# New Session Skill
+
+## Trigger
+
+This skill activates when the user sends `/new`. It resets the current chat and starts a fresh session.
+
+## How It Works
+
+- **Web UI**: The frontend handles `/new` locally — it clears the current session and resets the chat view. No message is sent to the engine.
+- **Connectors (Slack, etc.)**: The gateway's session manager intercepts `/new`, deletes the current session for that channel/thread, and confirms with "Session reset. Starting fresh."
+
+## Your Behavior
+
+You typically won't see `/new` messages because they're handled before reaching the engine. If for some reason a `/new` message does reach you, respond with a clean greeting as if starting a fresh conversation.

package/template/skills/onboarding/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: onboarding
+description: Walk a new user through initial {{portalName}} setup and customization
+---
+
+# Onboarding Skill
+
+## Trigger
+
+This skill activates on {{portalName}}'s first run, or when the user explicitly asks to go through the onboarding/setup process.
+
+## Steps
+
+### 1. Welcome the User
+
+Greet the user warmly. Introduce {{portalName}} as their AI-powered assistant and gateway. Keep it brief and friendly.
+
+Example: "Hey! I'm {{portalName}}, your AI assistant. Let me learn about you so I can be more useful."
+
+### 2. Ask About the User
+
+Ask the following (all at once, not one by one):
+1. **Who are you?** — Name, role, business/company
+2. **What should {{portalName}} help with?** — Code reviews, deployments, monitoring, content, research, etc.
+3. **Communication style** — Do you prefer concise or detailed responses? Emoji or no emoji? What language?
+4. **Active projects** — What are you working on right now? Tech stacks, repos, status?
+
+### 3. Write Knowledge Files
+
+After the user responds, write the answers to the appropriate knowledge files:
+
+**`~/.jinn/knowledge/user-profile.md`**:
+```markdown
+# User Profile
+
+- **Name**: [name]
+- **Role**: [role]
+- **Business**: [business/company]
+- **Goals**: [what they want {{portalName}} to help with]
+```
+
+**`~/.jinn/knowledge/preferences.md`**:
+```markdown
+# Preferences
+
+- **Verbosity**: [concise/detailed]
+- **Emoji**: [yes/no/minimal]
+- **Language**: [language]
+- **Other**: [any other preferences mentioned]
+```
+
+**`~/.jinn/knowledge/projects.md`**:
+```markdown
+# Active Projects
+
+## [Project Name]
+- **Stack**: [tech stack]
+- **Repo**: [repo path or URL]
+- **Status**: [status]
+- **Notes**: [anything relevant]
+```
+
+### 4. Check for OpenClaw Migration
+
+Check if `~/.openclaw/` exists.
+
+If it does, offer to migrate:
+1. Read `~/.openclaw/openclaw.json` for config
+2. Scan `~/.openclaw/cron/jobs.json` for scheduled tasks
+3. Scan `~/.openclaw/skills/` for skill playbooks
+4. Scan `~/.openclaw/memory/` and `~/.openclaw/knowledge/` for stored context
+
+Present a summary and let the user choose what to migrate. Only migrate approved items.
+
+If no OpenClaw installation, skip this step.
+
+### 5. Scaffold Organization
+
+Based on the user's projects and needs, suggest an initial org structure:
+- Solo dev → `engineering` department with a `dev-assistant`
+- Content creator → `content` and `research` departments
+- Startup founder → `engineering`, `marketing`, `operations`
+
+Confirm with the user before creating anything.
+
+### 6. Suggest Cron Jobs
+
+Suggest useful recurring jobs based on their projects:
+- Daily standup summaries
+- Weekly reports
+- Code review reminders
+
+Only create jobs the user approves.
+
+### 7. Wrap Up
+
+Summarize what was set up and suggest next steps:
+- "Try delegating a task to an employee"
+- "Ask me to create a custom skill"
+- "Set up a Slack connector for notifications"
+
+## Error Handling
+
+- If `~/.jinn/knowledge/` doesn't exist, create it
+- If the user seems overwhelmed, simplify — suggest one department and one employee
+- If the user wants to skip onboarding, respect that and exit gracefully

package/template/skills/self-heal/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: self-heal
+description: Diagnose and fix problems in {{portalName}}'s configuration and runtime
+---
+
+# Self-Heal Skill
+
+## Trigger
+
+This skill activates when {{portalName}} is experiencing issues, errors, or unexpected behavior. It also activates when the user asks to diagnose problems, check system health, or fix something that is not working.
+
+## Diagnostic Steps
+
+Work through these checks in order. Stop and fix issues as you find them.
+
+### 1. Check Gateway Logs
+
+Read `~/.jinn/logs/gateway.log` and look for:
+- Error messages or stack traces
+- Repeated failures or crash loops
+- Connection refused or timeout errors
+- Out of memory warnings
+- Unhandled promise rejections
+
+Summarize any problems found to the user.
+
+### 2. Validate Configuration
+
+Read `~/.jinn/config.yaml` and verify:
+- The file is valid YAML (no syntax errors)
+- The `port` field is a valid number (typically 3777)
+- Required fields are present: `port`, `engine`, `model`
+- Engine value is one of: `claude`, `codex`
+- No duplicate keys or malformed values
+
+### 3. Verify Engine Availability
+
+Check that the configured AI engine is installed and accessible:
+- For Claude: run `claude --version` and confirm it returns a version number
+- For Codex: run `codex --version` and confirm it returns a version number
+
+If the engine command is not found, inform the user that the engine is not installed or not on their PATH.
+
+### 4. Check Session Database
+
+Look at the session registry for stuck sessions:
+- Read `~/.jinn/sessions.db` or the session storage
+- Look for sessions with status `running` that have not been updated recently (more than 30 minutes old)
+- These may be stuck and need to be reset
+
+### 5. Check Disk and Temp Files
+
+- Check if `~/.jinn/tmp/` contains stale files that should be cleaned up
+- Large or numerous temp files can cause issues
+
+## Common Fixes
+
+### Restart Gateway
+
+If the gateway appears to be in a bad state (crash loops, unresponsive, port conflicts):
+
+Tell the user to run:
+```bash
+jinn stop && jinn start
+```
+
+### Clear Temp Directory
+
+If temp files are stale or causing issues:
+
+Delete all contents of `~/.jinn/tmp/` but keep the directory itself.
+
+### Fix Malformed JSON
+
+If any JSON file (board.json, jobs.json, etc.) is malformed:
+1. Read the raw file content.
+2. Attempt to identify the syntax error (missing comma, bracket, quote).
+3. Fix the error and parse to verify.
+4. Write the corrected JSON back to the file.
+5. If the file is unrecoverable, back it up as `<filename>.bak` and create a fresh default (empty array `[]` for boards and job files).
+
+### Fix Malformed YAML
+
+If any YAML file (config.yaml, employee personas) is malformed:
+1. Read the raw file content.
+2. Attempt to identify the syntax error (indentation, missing colon, bad quoting).
+3. Fix the error and validate.
+4. Write the corrected YAML back to the file.
+5. If unrecoverable, back it up and inform the user what fields need to be re-entered.
+
+### Reset Stuck Sessions
+
+If sessions are stuck in `running` status:
+1. Identify the stuck sessions (running for more than 30 minutes with no updates).
+2. Update their status to `failed` or `cancelled` in the session registry.
+3. Report which sessions were reset.
+
+### Fix Port Conflicts
+
+If the gateway cannot bind to its configured port:
+1. Check if another process is using the port: `lsof -i :<port>`
+2. If another {{portalName}} instance is running, tell the user to stop it first.
+3. If a different process is using the port, suggest changing the port in `config.yaml`.
+
+## Reference
+
+For understanding {{portalName}}'s architecture and component relationships, refer to the documentation in `~/.jinn/docs/` if available.
+
+## Error Handling
+
+- If log files do not exist, note that logging may not be configured and skip that check.
+- If config.yaml does not exist, this is likely a fresh install — suggest running the onboarding process instead.
+- Always back up files before modifying them during repair.
+- Report all findings clearly to the user, even if no issues are found (a clean bill of health is useful information).