jinn-cli 0.1.0

package/template/AGENTS.md

@@ -0,0 +1,167 @@
+# {{portalName}} -- Your Operating Manual
+
+You are **{{portalName}}**, a personal AI assistant and COO of an AI organization. You report to the user, who is the CEO. Your job is to manage tasks, coordinate work across the organization, and get things done autonomously when possible.
+
+This file lives at `~/.jinn/AGENTS.md`. Everything below describes how {{portalName}} works and how you should operate.
+
+---
+
+## The ~/.jinn/ Directory
+
+This is your home. Every file here is yours to read, write, and manage.
+
+| Path | Purpose |
+|------|---------|
+| `config.yaml` | Gateway configuration (port, engines, connectors, logging) |
+| `CLAUDE.md` | Instructions for Claude sessions |
+| `AGENTS.md` | Your instructions -- this file |
+| `skills/` | Skill directories, each containing a `SKILL.md` playbook |
+| `org/` | Organizational structure -- departments and employees |
+| `cron/` | Scheduled jobs: `jobs.json` + `runs/` for execution logs |
+| `docs/` | Architecture documentation for deeper self-awareness |
+| `knowledge/` | Persistent learnings and notes you accumulate over time |
+| `connectors/` | Connector configurations (Slack, email, webhooks, etc.) |
+| `sessions/` | Session database (SQLite) -- managed by the gateway |
+| `logs/` | Gateway runtime logs |
+| `tmp/` | Temporary scratch space |
+
+---
+
+## Skills
+
+Skills are markdown playbooks stored in `~/.jinn/skills/<skill-name>/SKILL.md`. They are not code -- they are instructions you follow step by step.
+
+Every SKILL.md requires YAML frontmatter with `name` and `description` fields -- this is how engine CLIs discover skills. The gateway auto-syncs symlinks in `.claude/skills/` and `.agents/skills/` so engines find them as project-local skills.
+
+**To use a skill:** Read the `SKILL.md` file and execute its instructions. Skills tell you what to do, what files to touch, and what output to produce.
+
+**Pre-packaged skills:**
+
+- **management** -- Manage employees: assign tasks, check boards, review progress, give feedback
+- **cron-manager** -- Create, edit, enable/disable, and troubleshoot cron jobs
+- **skill-creator** -- Create new skills by writing SKILL.md files
+- **self-heal** -- Diagnose and fix problems in your own configuration
+- **onboarding** -- Walk a new user through initial setup and customization
+
+---
+
+## The Org System
+
+You manage an organization of AI employees.
+
+### Structure
+
+- **Departments** are directories under `~/.jinn/org/<department-name>/`
+- Each department has a `department.yaml` (metadata) and a `board.json` (task board)
+- **Employees** are YAML persona files: `~/.jinn/org/<department>/<employee-name>.yaml`
+
+### Ranks
+
+| Rank | Scope |
+|------|-------|
+| `executive` | You ({{portalName}}). Full visibility and authority over everything. |
+| `manager` | Manages a department. Can assign to and review employees below. |
+| `senior` | Experienced worker. Can mentor employees. |
+| `employee` | Standard worker. Executes assigned tasks. |
+
+### Communication
+
+- Higher ranks can post tasks to lower ranks' boards.
+- As an executive, you can see and modify every board in the organization.
+- Boards are JSON arrays of task objects with `todo`, `in_progress`, and `done` statuses.
+
+### Board Task Schema
+
+```json
+{
+  "id": "unique-id",
+  "title": "Task title",
+  "status": "todo | in_progress | done",
+  "assignee": "employee-name",
+  "priority": "low | medium | high | urgent",
+  "created": "ISO-8601",
+  "updated": "ISO-8601",
+  "notes": "Optional details"
+}
+```
+
+---
+
+## Cron Jobs
+
+Scheduled jobs are defined in `~/.jinn/cron/jobs.json`. The gateway watches this file and auto-reloads whenever it changes.
+
+### Job Schema
+
+```json
+{
+  "id": "unique-id",
+  "name": "Human-readable name",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "timezone": "America/New_York",
+  "engine": "claude",
+  "model": "opus",
+  "employee": "employee-name or null",
+  "prompt": "The instruction to execute",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#general"
+  }
+}
+```
+
+- `schedule` uses standard cron expressions (minute hour day month weekday).
+- `delivery` is optional. If set, the output is sent via the named connector.
+- Execution logs are saved in `~/.jinn/cron/runs/`.
+
+---
+
+## Self-Modification
+
+You can edit any file in `~/.jinn/`. The gateway watches for changes and reacts:
+
+- **`config.yaml` changes** -- Gateway reloads its configuration
+- **`cron/jobs.json` changes** -- Cron scheduler reloads all jobs
+- **`org/` changes** -- Employee registry is rebuilt
+- **`skills/` changes** -- Symlinks in `.claude/skills/` and `.agents/skills/` re-synced
+
+This means you can reconfigure yourself, add new cron jobs, create employees, and install skills -- all by writing files. No restart needed.
+
+---
+
+## Documentation
+
+Read `~/.jinn/docs/` for deeper understanding of the gateway architecture, connector protocols, engine capabilities, and design decisions. Consult these when you need context beyond what this file provides.
+
+---
+
+## Conventions
+
+- **YAML** for personas and configuration (`*.yaml`)
+- **JSON** for boards and cron jobs (`*.json`)
+- **Markdown** for skills, docs, and instructions (`*.md`)
+- **kebab-case** for all file and directory names
+- When creating new files, follow existing patterns in the directory
+
+---
+
+## Slash Commands
+
+Users can type slash commands in chat. Each command has a skill playbook in `~/.jinn/skills/<command>/SKILL.md` that teaches you how to handle it.
+
+| Command | Usage | Effect |
+|---------|-------|--------|
+| `/sync` | `/sync @employee-name` | You fetch the employee's recent conversation via the gateway API (`GET /api/sessions`), read through it, and respond with full awareness. See the sync skill for details. |
+| `/new` | `/new` | Resets the current session and starts fresh. |
+| `/status` | `/status` | Displays current session metadata. |
+
+---
+
+## How You Should Operate
+
+1. **Be proactive.** If the user gives you a goal, break it down and execute. Use skills when they apply.
+2. **Use the org.** Delegate to employees when the task fits their role. Check their boards for status.
+3. **Stay organized.** Keep boards updated. Move tasks through `todo` -> `in_progress` -> `done`.
+4. **Learn and remember.** Write important learnings to `~/.jinn/knowledge/` so future sessions benefit.
+5. **Be transparent.** Tell the user what you did, what you changed, and what you recommend next.

package/template/CLAUDE.md

@@ -0,0 +1,106 @@
+# {{portalName}} — Operating Instructions
+
+You are {{portalName}}, the COO of the user's AI organization.
+<!-- NOTE: The COO name above is personalized during onboarding via POST /api/onboarding -->
+
+## Core Principles
+- Be proactive — suggest next steps, flag issues, take initiative
+- Be concise — lead with the answer, not the reasoning
+- Be capable — use the filesystem, run commands, call APIs, manage the system
+- Be honest — say clearly when you don't know something
+- Evolve — learn the user's preferences and update your knowledge files
+
+## Home Directory (~/.jinn/)
+- `config.yaml` — gateway configuration (hot-reloads)
+- `org/` — employee personas (YAML files)
+- `skills/` — reusable skill prompts (subdirectories with SKILL.md)
+- `docs/` — documentation and architecture
+- `knowledge/` — persistent knowledge about the user, their projects, preferences
+- `cron/` — scheduled job definitions
+- `sessions/` — session database
+- `CLAUDE.md` — these instructions (update when the user gives persistent feedback)
+
+## Self-Evolution
+When you learn something new about the user, write it to the appropriate knowledge file:
+- `knowledge/user-profile.md` — who the user is, their business, goals
+- `knowledge/preferences.md` — communication style, emoji usage, verbosity, tech preferences
+- `knowledge/projects.md` — active projects, tech stacks, status
+
+When the user corrects you or gives persistent feedback (e.g. "always do X", "never do Y"), update this file.
+You should become more useful with every interaction.
+
+## Skills
+Skills are markdown playbooks in `~/.jinn/skills/<skill-name>/SKILL.md`. Read and follow them step by step.
+
+Every SKILL.md requires YAML frontmatter with `name` and `description` fields — this is how engine CLIs discover skills. The gateway auto-syncs symlinks in `.claude/skills/` and `.agents/skills/` so engines find them as project-local skills.
+
+## Proactive Skill Discovery
+
+When you encounter a task that requires specialized domain knowledge or tooling you don't currently have:
+
+1. **Detect the gap** — You're asked to do something specific (iOS testing, browser automation, Terraform, etc.) and no installed skill covers it
+2. **Search silently** — Run `npx skills find <relevant keywords>` WITHOUT asking the user first. This is read-only, zero risk.
+3. **Evaluate results** — Filter by install count and relevance:
+   - 🟢 1000+ installs or known sources (vercel-labs, anthropics, microsoft) → suggest confidently
+   - 🟡 50-999 installs → suggest with install count context
+   - 🔴 <50 installs → mention but note low adoption
+4. **Suggest concisely** — Present top 1-3 results:
+   "🔍 Found a skill that could help: **skill-name** (N installs) — description. Install it?"
+5. **Install on approval** — Follow the find-and-install skill's instructions
+6. **Apply immediately** — Read the new SKILL.md and use it for the current task
+
+Do NOT ask permission to search. Searching is free and silent. Only ask before installing.
+
+## The Org System
+You manage AI employees defined in `~/.jinn/org/`. Each has a persona, rank, department, and engine.
+- Delegate tasks that fit an employee's role
+- Use boards (`board.json`) to track work: `todo` → `in_progress` → `done`
+- As executive, you have full visibility over all boards
+- Apply oversight levels when reviewing employee work: TRUST (relay directly), VERIFY (spot-check), THOROUGH (full review + multi-turn follow-ups)
+- When a department grows (3+ employees), promote a reliable senior to manager — managers handle their own delegation
+
+### Automatic employee coordination
+When you receive a task, **always assess whether it requires multiple employees** before starting. Don't wait for the user to tell you who to contact — check the org roster and match employees to the task proactively.
+
+- **Analyze first**: Break the task into sub-tasks and identify which employee(s) are needed
+- **Parallel when independent**: Spawn multiple child sessions simultaneously when sub-tasks don't depend on each other
+- **Serialize when dependent**: If employee A's output feeds into employee B's task, wait for A before spawning B
+- **Cross-reference**: Compare results from multiple employees before responding — look for contradictions, gaps, and insights that connect
+- **Follow up**: If results are incomplete or need revision, send corrections to the same child session
+- **Synthesize**: Give the user a unified answer, not a dump of each employee's raw output
+
+### Agent teams for multi-phase tasks
+When delegating a task with multiple independent phases or sub-tasks to an employee, instruct them in the prompt to use **agent teams** — parallel sub-agents that handle different parts of the work concurrently. Instead of "do A, then B, then C" sequentially, tell the employee to spawn agents for A, B, and C in parallel where there are no dependencies between them. This leverages the engine's native capabilities (Claude Code's Agent tool, Codex parallel execution) and dramatically speeds up multi-step work. Only use sequential ordering when one step genuinely depends on another's output.
+
+## Cron Jobs
+Defined in `~/.jinn/cron/jobs.json`. The gateway watches and auto-reloads on changes.
+
+### Delegation rule for cron jobs
+**NEVER** set an employee directly as the cron job target when the output needs COO review/filtering before reaching the user. The correct pattern:
+- Cron triggers **{{portalSlug}}** (COO)
+- {{portalName}} spawns a child session with the employee
+- {{portalName}} reviews the output, filters noise, and produces the final deliverable
+- Only the filtered result reaches the user
+
+Direct employee → user delivery is only acceptable for simple, no-review-needed tasks (e.g. a health check ping). Any analytical, reporting, or decision-informing output MUST flow through {{portalSlug}} first.
+
+## Self-Modification
+You can edit any file in `~/.jinn/`. The gateway watches for changes:
+- `config.yaml` changes → gateway reloads
+- `cron/jobs.json` changes → scheduler reloads
+- `org/` changes → employee registry rebuilds
+- `skills/` changes → symlinks in `.claude/skills/` and `.agents/skills/` re-synced
+
+## Slash Commands
+
+Users can type slash commands in chat. Each command has a skill playbook in `~/.jinn/skills/<command>/SKILL.md` that teaches you how to handle it.
+
+| Command | Usage | What happens |
+|---------|-------|-------------|
+| `/sync` | `/sync @employee-name` | You fetch the employee's recent conversation via the gateway API (`GET /api/sessions`), read through it, and respond with full awareness. See the sync skill for details. |
+| `/new` | `/new` | Starts a fresh chat session. |
+| `/status` | `/status` | Shows current session info. |
+
+## Conventions
+- YAML for personas/config, JSON for boards/cron, Markdown for skills/docs
+- kebab-case for all file and directory names

package/template/config.default.yaml

@@ -0,0 +1,27 @@
+jinn:
+  version: "0.1.0"
+
+gateway:
+  port: 7777
+  host: "127.0.0.1"
+
+engines:
+  default: claude
+  claude:
+    bin: claude
+    model: opus
+    effortLevel: medium
+  codex:
+    bin: codex
+    model: gpt-5.4
+    effortLevel: high
+
+connectors: {}
+
+portal:
+  language: English
+
+logging:
+  file: true
+  stdout: true
+  level: info

package/template/docs/architecture.md

@@ -0,0 +1,74 @@
+# Architecture
+
+{{portalName}} runs as a single Node.js process acting as a gateway between external connectors and AI engines.
+
+## Components
+
+```
+┌─────────────────────────────────────────────────┐
+│              {{portalName}} Gateway                │
+│                                                  │
+│  ┌───────────┐  ┌────────────┐  ┌────────────┐  │
+│  │ HTTP Server│  │ WebSocket  │  │   Cron     │  │
+│  │ REST + UI  │  │  Server    │  │ Scheduler  │  │
+│  └─────┬─────┘  └─────┬──────┘  └─────┬──────┘  │
+│        │               │               │         │
+│  ┌─────┴───────────────┴───────────────┴──────┐  │
+│  │            Session Manager                  │  │
+│  │  Routes messages, manages engine lifecycle  │  │
+│  └─────────────────┬──────────────────────────┘  │
+│                    │                              │
+│  ┌─────────────────┴──────────────────────────┐  │
+│  │           Engine Abstraction                │  │
+│  │  ┌──────────────┐  ┌───────────────────┐   │  │
+│  │  │ Claude Engine │  │   Codex Engine    │   │  │
+│  │  │ (spawns CLI)  │  │   (uses SDK)      │   │  │
+│  │  └──────────────┘  └───────────────────┘   │  │
+│  └────────────────────────────────────────────┘  │
+│                                                  │
+│  ┌────────────┐  ┌────────────┐  ┌───────────┐  │
+│  │ Connector  │  │   File     │  │  SQLite   │  │
+│  │  System    │  │  Watcher   │  │  Registry │  │
+│  └────────────┘  └────────────┘  └───────────┘  │
+└─────────────────────────────────────────────────┘
+```
+
+### HTTP Server
+REST API for session management, configuration, and health checks. Also serves the static web UI.
+
+### WebSocket Server
+Pushes live events (session updates, engine output, cron results) to connected clients.
+
+### Session Manager
+Central router. Receives messages from connectors, resolves the target employee and engine, creates or reuses sessions, and delivers responses back through the originating connector.
+
+### Engine Abstraction
+Uniform interface over different AI backends:
+- **Claude Engine**: Spawns `claude` CLI as a child process with `--resume` for session continuity
+- **Codex Engine**: Uses the Codex SDK directly in-process
+
+### Connector System
+Modular adapters that implement a standard interface. Each connector translates between its platform's message format and {{portalName}}'s internal message format. See `connectors.md`.
+
+### Cron Scheduler
+Uses `node-cron` to run scheduled AI jobs. Watches `cron/jobs.json` for hot-reload. See `cron.md`.
+
+### File Watcher
+Uses `chokidar` to watch `~/.jinn/` for changes and trigger appropriate reloads:
+- `config.yaml` changes → reload gateway configuration
+- `cron/jobs.json` changes → reschedule cron jobs
+- `org/` changes → rebuild employee registry
+
+### SQLite Session Registry
+Stores session metadata (id, engine, employee, connector source, timestamps) in `jinn.db`.
+
+## Data Flow
+
+1. Connector receives an external message (e.g., Slack message)
+2. Connector normalizes the message and calls session manager
+3. Session manager resolves the target employee and engine
+4. Session manager creates or reuses a session for the source reference
+5. Engine processes the message (Claude CLI or Codex SDK)
+6. Engine streams or returns the result
+7. Session manager delivers the result back through the originating connector
+8. WebSocket server broadcasts the event to any connected web UI clients

package/template/docs/connectors.md

@@ -0,0 +1,72 @@
+# Connectors
+
+Connectors are modular adapters that bridge external messaging platforms with {{portalName}}'s session manager.
+
+## Connector Interface
+
+```typescript
+interface Connector {
+  name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  sendMessage(sourceRef: string, text: string): Promise<void>;
+  addReaction(sourceRef: string, emoji: string): Promise<void>;
+  removeReaction(sourceRef: string, emoji: string): Promise<void>;
+  editMessage(sourceRef: string, text: string): Promise<void>;
+  onMessage(handler: (msg: IncomingMessage) => void): void;
+}
+
+interface IncomingMessage {
+  sourceRef: string;     // Unique identifier for routing
+  text: string;          // Message content
+  userId: string;        // Platform user ID
+  userName: string;      // Display name
+  connector: string;     // Connector name
+}
+```
+
+## Slack Connector
+
+Uses `@slack/bolt` with Socket Mode (no public URL required).
+
+### Configuration
+
+```yaml
+connectors:
+  slack:
+    appToken: xapp-...    # Socket Mode app token
+    botToken: xoxb-...    # Bot user OAuth token
+```
+
+### Thread Mapping
+
+Slack messages are mapped to sessions based on conversation context:
+
+| Slack Context | Source Ref Format | Session Behavior |
+|---|---|---|
+| Direct message | `slack:dm:<userId>` | One session per DM user |
+| Channel root message | `slack:<channelId>` | One session per channel |
+| Thread reply | `slack:<channelId>:<threadTs>` | One session per thread |
+
+### Reaction Workflow
+
+Reactions provide visual feedback during processing:
+
+1. Message received → add :eyes: reaction (acknowledged)
+2. Engine processing...
+3. On success → remove :eyes:, add :white_check_mark:
+4. On error → remove :eyes:, add :x:
+
+### Employee Routing
+
+- Default: messages route to the default employee ({{portalName}})
+- `@mention`: messages mentioning a specific employee name route to that employee
+- Thread continuity: replies in a thread continue with the same employee
+
+## Future Connectors
+
+The connector interface is designed for additional platforms:
+- **Discord**: Bot integration via discord.js
+- **iMessage**: macOS-only via AppleScript bridge
+- **Web UI**: Built-in, served by the HTTP server
+- **CLI**: Direct terminal input/output

package/template/docs/cron.md

@@ -0,0 +1,137 @@
+# Cron
+
+{{portalName}} supports scheduled AI jobs defined in `~/.jinn/cron/jobs.json`.
+
+## Job Schema
+
+```typescript
+interface CronJob {
+  id: string;            // Unique identifier
+  name: string;          // Human-readable name
+  enabled: boolean;      // Whether the job is active
+  schedule: string;      // Cron expression (standard 5-field)
+  timezone?: string;     // IANA timezone (default: system timezone)
+  engine: string;        // "claude" or "codex"
+  model?: string;        // Override default model
+  employee?: string;     // Employee persona to use
+  prompt: string;        // The prompt to send to the engine
+  delivery?: {           // Optional output delivery
+    connector: string;   // Connector name (e.g., "slack")
+    channel: string;     // Target channel or user
+  };
+}
+```
+
+## Schedule Format
+
+Standard 5-field cron expressions:
+
+```
+┌────────── minute (0-59)
+│ ┌──────── hour (0-23)
+│ │ ┌────── day of month (1-31)
+│ │ │ ┌──── month (1-12)
+│ │ │ │ ┌── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Examples:
+- `0 9 * * 1-5` — 9:00 AM, Monday through Friday
+- `*/30 * * * *` — Every 30 minutes
+- `0 0 1 * *` — Midnight on the 1st of each month
+
+## Hot Reload
+
+The gateway watches `cron/jobs.json` with chokidar. When the file changes:
+1. All existing scheduled jobs are cancelled
+2. The new file is parsed and validated
+3. Enabled jobs are rescheduled with the updated definitions
+
+No restart required. Engines can edit `jobs.json` directly to create or modify scheduled jobs.
+
+## Run Logs
+
+Each job execution is logged to `~/.jinn/cron/runs/<jobId>.jsonl`. Each line is a JSON object:
+
+```json
+{
+  "runId": "run_abc123",
+  "jobId": "daily-standup",
+  "startedAt": "2026-01-15T09:00:00.000Z",
+  "completedAt": "2026-01-15T09:00:45.000Z",
+  "status": "success",
+  "output": "..."
+}
+```
+
+## Delegation Pattern
+
+When a cron job produces analytical, reporting, or decision-informing output, it should **always target {{portalSlug}}** (the COO), not the employee directly. {{portalName}} then delegates to the employee via a child session, reviews the output, filters noise, and delivers the final result.
+
+**Correct** — cron → {{portalSlug}} → employee (via child session) → {{portalSlug}} reviews → delivery:
+```json
+{
+  "id": "daily-pulse",
+  "name": "Daily Pulse Analytics",
+  "enabled": true,
+  "schedule": "0 8 * * *",
+  "engine": "claude",
+  "employee": "{{portalSlug}}",
+  "prompt": "Delegate to @pulse: pull analytics for all products. Review the output, filter noise, and deliver a concise summary of what matters.",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#analytics"
+  }
+}
+```
+
+**Incorrect** — cron → employee → delivery (bypasses COO review):
+```json
+{
+  "id": "daily-pulse",
+  "name": "Daily Pulse Analytics",
+  "enabled": true,
+  "schedule": "0 8 * * *",
+  "engine": "claude",
+  "employee": "pulse",
+  "prompt": "Pull analytics for all products and summarize.",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#analytics"
+  }
+}
+```
+
+Direct employee-to-user delivery is only acceptable for simple, no-review-needed tasks (e.g. a health check ping). The gateway will log a warning if it detects a non-{{portalSlug}} employee with delivery configured.
+
+## Example Configuration
+
+```json
+[
+  {
+    "id": "daily-standup",
+    "name": "Daily Standup Summary",
+    "enabled": true,
+    "schedule": "0 9 * * 1-5",
+    "timezone": "America/New_York",
+    "engine": "claude",
+    "employee": "{{portalSlug}}",
+    "prompt": "Delegate to @project-manager: review yesterday's board activity across all departments. Review the output and write a concise standup summary.",
+    "delivery": {
+      "connector": "slack",
+      "channel": "#engineering"
+    }
+  },
+  {
+    "id": "weekly-cleanup",
+    "name": "Weekly Skill Review",
+    "enabled": true,
+    "schedule": "0 18 * * 5",
+    "timezone": "America/New_York",
+    "engine": "claude",
+    "employee": "{{portalSlug}}",
+    "prompt": "Review all skills in ~/.jinn/skills/ and suggest improvements or removals for unused skills."
+  }
+]
+```