@jive-ai/cli 0.0.26 → 0.0.30

package/docs/subagents.md

@@ -1,702 +0,0 @@
-# Subagent Commands
-
-Subagents are custom AI agents defined by markdown files with YAML frontmatter. They provide specialized prompts and behaviors for specific tasks, enabling teams to share and collaborate on AI agents.
-
-## Overview
-
-Subagent management in Jive allows you to:
-- Create and share custom AI agents with your team
-- Pull team subagents to your local project
-- Push local subagents to share with your team
-- Track changes with version history
-- Delete subagents when no longer needed
-
-## Subagent File Format
-
-Subagents are markdown files stored in `.claude/agents/` with YAML frontmatter:
-
-```markdown
----
-name: code-reviewer
-description: Reviews code for best practices and potential issues
-jive-id: "sub-123"
----
-
-You are a code reviewer. Analyze the provided code and:
-
-1. Identify potential bugs or issues
-2. Suggest improvements for readability
-3. Check for security vulnerabilities
-4. Recommend best practices
-
-Be thorough but concise in your feedback.
-```
-
-**Frontmatter Fields:**
-- `name` (required) - Unique identifier for the subagent
-- `description` (required) - Brief description of the subagent's purpose
-- `jive-id` (optional) - Jive platform ID (added automatically when synced)
-
-**Content:**
-- The markdown content after frontmatter is the subagent's system prompt
-- Can include instructions, examples, formatting guidelines, etc.
-
-## Commands
-
-### `jive subagents list`
-
-List all subagents for the active team.
-
-**Usage:**
-```bash
-jive subagents list
-```
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project (has active team)
-
-**Process:**
-1. Gets active team ID from `.jive/config.json`
-2. Fetches team subagents from API (`GET /api/teams/{teamId}/subagents`)
-3. Displays formatted list
-
-**Output:**
-```
-Team subagents:
-
-code-reviewer (sub-123)
-  Reviews code for best practices and potential issues
-
-bug-fixer (sub-456)
-  Analyzes code to identify and fix bugs
-
-test-writer (sub-789)
-  Generates comprehensive test cases for code
-```
-
-**Notes:**
-- Shows name, ID, and description
-- Only shows subagents for the active team
-- Use `jive team switch` to view different team's subagents
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Network connectivity issues
-
-**Implementation:** `src/commands/subagents.ts` (subagentCommands.list)
-
----
-
-### `jive subagents pull`
-
-Download team subagents to local `.claude/agents/` directory.
-
-**Usage:**
-```bash
-jive subagents pull [--overwrite]
-```
-
-**Options:**
-- `--overwrite` - Overwrite existing local files (default: skip existing)
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Process:**
-1. Fetches remote subagents from team API
-2. For each remote subagent:
-   - Checks if local file exists
-   - If exists and no `--overwrite`: skips
-   - If doesn't exist or `--overwrite`: saves file
-   - Adds `jive-id` to frontmatter for tracking
-3. Creates `.claude/agents/` directory if needed
-
-**Output:**
-```
-Pulling subagents from team...
-
-✓ code-reviewer.md
-✓ bug-fixer.md
-⊘ test-writer.md (already exists, use --overwrite to update)
-
-Downloaded 2 subagents, skipped 1
-```
-
-**Output with --overwrite:**
-```bash
-jive subagents pull --overwrite
-```
-```
-Pulling subagents from team...
-
-✓ code-reviewer.md
-✓ bug-fixer.md
-✓ test-writer.md (overwritten)
-
-Downloaded 3 subagents
-```
-
-**File Created:**
-
-`.claude/agents/code-reviewer.md`:
-```markdown
----
-name: code-reviewer
-description: Reviews code for best practices
-jive-id: "sub-123"
----
-
-You are a code reviewer...
-```
-
-**Notes:**
-- Creates directory if `.claude/agents/` doesn't exist
-- Preserves existing local changes unless `--overwrite` is used
-- Updates `jive-id` field to track sync state
-
-**Use Cases:**
-- Getting team subagents in a new project
-- Updating to latest versions from team
-- Syncing after team members add new subagents
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Network connectivity issues
-- File system permission errors
-
-**Implementation:** `src/commands/subagents.ts` (subagentCommands.pull)
-
----
-
-### `jive subagents push`
-
-Upload local subagents to the team.
-
-**Usage:**
-```bash
-jive subagents push [-m <message>] [--force]
-```
-
-**Options:**
-- `-m, --message <text>` - Change description for version history
-- `--force` - Force push without conflict checks (not fully implemented)
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Process:**
-1. Scans `.claude/agents/*.md` files (excludes `subagent-runner.md`)
-2. Parses each file's frontmatter and content
-3. For each subagent:
-   - **If has `jive-id`:** Updates existing subagent via `PUT /api/subagents/{id}`
-     - Prompts for change message if not provided via `-m`
-   - **If no `jive-id`:** Creates new subagent via `POST /api/teams/{teamId}/subagents`
-     - Adds `jive-id` to file frontmatter
-4. Saves updated files with `jive-id` added
-
-**Output:**
-```
-Pushing subagents to team...
-
-✓ code-reviewer.md (updated)
-✓ new-agent.md (created)
-
-Pushed 2 subagents
-```
-
-**With Change Message:**
-```bash
-jive subagents push -m "Added error handling checks"
-```
-```
-Pushing subagents to team...
-
-✓ code-reviewer.md (updated: "Added error handling checks")
-
-Pushed 1 subagent
-```
-
-**Interactive Prompt (when updating without -m):**
-```
-? Describe your changes to code-reviewer: (optional)
-> Improved code review criteria
-```
-
-**File Updates:**
-
-Before push (new subagent):
-```markdown
----
-name: new-agent
-description: Does something useful
----
-
-Prompt content...
-```
-
-After push:
-```markdown
----
-name: new-agent
-description: Does something useful
-jive-id: "sub-999"
----
-
-Prompt content...
-```
-
-**Notes:**
-- Automatically tracks which subagents are synced via `jive-id`
-- Version history maintained on server (via change messages)
-- Skips `subagent-runner.md` (reserved by Jive)
-
-**Use Cases:**
-- Sharing new subagents with team
-- Publishing updates to existing subagents
-- Initial upload of local subagents
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Invalid frontmatter format
-- Network connectivity issues
-- Subagent name conflicts
-
-**Implementation:** `src/commands/subagents.ts` (subagentCommands.push)
-
----
-
-### `jive subagents create`
-
-Create a new subagent interactively.
-
-**Usage:**
-```bash
-jive subagents create
-```
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Interactive Prompts:**
-- **Name:** Unique identifier for the subagent (e.g., `code-reviewer`)
-- **Description:** Brief description of purpose
-- **Prompt:** System prompt for the subagent (multi-line, Ctrl+D to finish)
-
-**Process:**
-1. Prompts for name, description, and prompt
-2. Creates subagent on server via `POST /api/teams/{teamId}/subagents`
-3. Saves to `.claude/agents/{name}.md` with `jive-id` in frontmatter
-4. Creates directory if needed
-
-**Output:**
-```
-Create a new subagent
-
-? Name: security-checker
-? Description: Analyzes code for security vulnerabilities
-? Prompt: (Ctrl+D when done)
-You are a security expert. Review code for:
-- SQL injection risks
-- XSS vulnerabilities
-- Authentication issues
-- Data exposure risks
-
-Provide specific, actionable recommendations.
-^D
-
-✓ Subagent created: security-checker
-  Saved to .claude/agents/security-checker.md
-```
-
-**File Created:**
-
-`.claude/agents/security-checker.md`:
-```markdown
----
-name: security-checker
-description: Analyzes code for security vulnerabilities
-jive-id: "sub-999"
----
-
-You are a security expert. Review code for:
-- SQL injection risks
-- XSS vulnerabilities
-- Authentication issues
-- Data exposure risks
-
-Provide specific, actionable recommendations.
-```
-
-**Notes:**
-- Subagent is immediately available to team members
-- Automatically synced (has `jive-id` from creation)
-- Can be edited locally and pushed with `jive subagents push`
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Name already exists
-- Network connectivity issues
-
-**Implementation:** `src/commands/subagents.ts` (subagentCommands.create)
-
----
-
-### `jive subagents delete <name-or-id>`
-
-Delete a subagent from the team.
-
-**Usage:**
-```bash
-jive subagents delete <name-or-id>
-```
-
-**Arguments:**
-- `<name-or-id>` (required) - Name or ID of subagent to delete
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project
-
-**Interactive Prompts:**
-- **Confirmation:** "Are you sure you want to delete {name}?" (Y/n)
-
-**Process:**
-1. Fetches team subagents to find match by name or ID
-2. Displays subagent details
-3. Prompts for confirmation
-4. Deletes from server via `DELETE /api/subagents/{id}`
-5. Deletes local `.md` file if it exists
-
-**Output:**
-```bash
-jive subagents delete code-reviewer
-```
-```
-Found subagent: code-reviewer
-Description: Reviews code for best practices
-ID: sub-123
-
-? Are you sure you want to delete code-reviewer? (Y/n) Yes
-
-✓ Deleted from team
-✓ Deleted local file: .claude/agents/code-reviewer.md
-```
-
-**By ID:**
-```bash
-jive subagents delete sub-123
-```
-
-**Notes:**
-- Deletes from team (affects all team members)
-- Also deletes local file if present
-- Cannot be undone (creates backup if file exists)
-- Other team members will still have local copy until they run `jive sync`
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Subagent not found
-- User cancels confirmation
-- Network connectivity issues
-
-**Implementation:** `src/commands/subagents.ts` (subagentCommands.delete)
-
----
-
-## Subagent Workflows
-
-### Creating and Sharing a New Subagent
-
-1. **Create the subagent:**
-   ```bash
-   jive subagents create
-   ```
-
-2. **Or create manually:**
-   ```bash
-   # Create file
-   touch .claude/agents/my-agent.md
-   ```
-
-   ```markdown
-   ---
-   name: my-agent
-   description: Does something useful
-   ---
-
-   System prompt here...
-   ```
-
-3. **Push to team:**
-   ```bash
-   jive subagents push
-   ```
-
-4. **Team members pull:**
-   ```bash
-   jive subagents pull
-   ```
-
-### Updating an Existing Subagent
-
-1. **Edit the local file:**
-   ```bash
-   # Edit .claude/agents/code-reviewer.md
-   # Update the prompt content
-   ```
-
-2. **Push changes:**
-   ```bash
-   jive subagents push -m "Improved error detection logic"
-   ```
-
-3. **Team members update:**
-   ```bash
-   jive subagents pull --overwrite
-   ```
-
-### Collaborating on Subagents
-
-**Team Member A creates:**
-```bash
-jive subagents create
-# Creates api-designer
-```
-
-**Team Member B pulls:**
-```bash
-jive subagents pull
-# Downloads api-designer.md
-```
-
-**Team Member B improves:**
-```bash
-# Edit .claude/agents/api-designer.md
-jive subagents push -m "Added REST best practices"
-```
-
-**Team Member A updates:**
-```bash
-jive subagents pull --overwrite
-# Gets latest version
-```
-
-### Using Subagents in Claude Code
-
-Once pulled, subagents can be used in Claude Code:
-
-1. **Via Task tool:**
-   ```
-   User: "Review this code for security issues"
-   Claude: Uses Task tool with subagent_type="security-checker"
-   ```
-
-2. **Via subagent-runner:**
-   The `subagent-runner.md` enables dynamic loading of team subagents
-
-3. **Via jive-mcp server:**
-   - `search_subagents` - Find subagents by name/description
-   - `call_subagent` - Execute a subagent with input
-
-## Subagent Best Practices
-
-### Naming Conventions
-
-- Use kebab-case: `code-reviewer`, `api-designer`
-- Be descriptive: `security-checker` not `checker`
-- Avoid conflicts with built-in agents
-
-### Writing Effective Prompts
-
-**Good prompt structure:**
-```markdown
----
-name: code-reviewer
-description: Reviews code for quality and best practices
----
-
-You are an expert code reviewer.
-
-## Your Role
-Review code submissions for:
-1. Bugs and logic errors
-2. Code quality and readability
-3. Performance issues
-4. Security vulnerabilities
-5. Best practice violations
-
-## Review Process
-1. Analyze the code thoroughly
-2. Identify specific issues with line numbers
-3. Suggest concrete improvements
-4. Explain the reasoning behind each suggestion
-
-## Output Format
-- Use markdown formatting
-- Group issues by category
-- Prioritize by severity (Critical, High, Medium, Low)
-- Provide code examples for fixes
-
-Be constructive and educational in your feedback.
-```
-
-**Tips:**
-- Be specific about the subagent's role and expertise
-- Provide clear instructions and structure
-- Include examples when helpful
-- Define expected output format
-- Keep prompts focused on a single purpose
-
-### Version Control
-
-**Track changes with messages:**
-```bash
-# Good messages
-jive subagents push -m "Added TypeScript-specific checks"
-jive subagents push -m "Fixed edge case in error detection"
-jive subagents push -m "Updated to use latest coding standards"
-
-# Less helpful messages
-jive subagents push -m "updated"
-jive subagents push -m "changes"
-```
-
-**Use git for local versioning:**
-```bash
-# .gitignore should NOT ignore .claude/agents/*.md
-git add .claude/agents/code-reviewer.md
-git commit -m "Improve code reviewer prompt"
-```
-
-### Team Collaboration
-
-1. **Communicate changes:**
-   - Notify team when creating new subagents
-   - Describe major updates in change messages
-   - Document breaking changes
-
-2. **Test before pushing:**
-   - Test subagent locally with Claude Code
-   - Verify prompt produces expected behavior
-   - Check for edge cases
-
-3. **Review together:**
-   - Share prompts for feedback before pushing
-   - Collaborate on improvements
-   - Establish team conventions
-
-## Troubleshooting
-
-### Subagent Not Showing in Claude Code
-
-**Symptoms:**
-- Subagent file exists but Claude doesn't use it
-- Task tool doesn't recognize subagent
-
-**Solutions:**
-1. Restart Claude Code
-2. Check frontmatter format:
-   ```markdown
-   ---
-   name: my-agent
-   description: Something
-   ---
-   ```
-3. Verify file location: `.claude/agents/my-agent.md`
-4. Check file isn't excluded (like `subagent-runner.md`)
-
-### Push/Pull Conflicts
-
-**Symptoms:**
-- Local changes overwritten by pull
-- Push fails with conflict error
-
-**Solutions:**
-1. **Before pulling, backup local changes:**
-   ```bash
-   cp .claude/agents/my-agent.md .claude/agents/my-agent.md.backup
-   jive subagents pull --overwrite
-   # Merge changes manually
-   ```
-
-2. **Push local version:**
-   ```bash
-   jive subagents push -m "Merged local improvements"
-   ```
-
-### Missing jive-id
-
-**Symptoms:**
-- Subagent pushed multiple times creates duplicates
-- Cannot update existing subagent
-
-**Solutions:**
-1. Delete duplicate from team:
-   ```bash
-   jive subagents delete duplicate-name
-   ```
-
-2. Pull from team to get correct `jive-id`:
-   ```bash
-   jive subagents pull --overwrite
-   ```
-
-### File Permission Errors
-
-**Symptoms:**
-- Cannot create `.claude/agents/` directory
-- Cannot write subagent files
-
-**Solutions:**
-```bash
-# Check permissions
-ls -la .claude/
-
-# Fix permissions
-chmod 755 .claude/
-chmod 755 .claude/agents/
-chmod 644 .claude/agents/*.md
-```
-
-## Related Commands
-
-- [`jive init`](./init.md#jive-init) - Creates `subagent-runner.md`
-- [`jive sync`](./sync.md#jive-sync) - Pulls all team resources including subagents
-- [`jive team switch`](./team.md#jive-team-switch) - Change active team (affects which subagents you see)
-
-## API Endpoints
-
-**Subagent Management:**
-- `GET /api/teams/{teamId}/subagents` - List team subagents
-- `POST /api/teams/{teamId}/subagents` - Create subagent
-- `GET /api/subagents/{id}` - Get subagent details
-- `PUT /api/subagents/{id}` - Update subagent
-- `DELETE /api/subagents/{id}` - Delete subagent
-
-## Implementation Details
-
-**Source Files:**
-- Main implementation: `src/commands/subagents.ts`
-- File utilities: `src/lib/fs-utils.ts`
-- Config helpers: `src/lib/config.ts`
-
-**Key Functions:**
-- `subagentCommands.list()` - Lists team subagents
-- `subagentCommands.pull()` - Downloads subagents
-- `subagentCommands.push()` - Uploads subagents
-- `subagentCommands.create()` - Creates new subagent
-- `subagentCommands.delete()` - Deletes subagent
-- `parseSubagentFile()` - Parses markdown with frontmatter
-- `saveSubagentFile()` - Writes subagent file with frontmatter
-
-**Frontmatter Parsing:**
-Uses `gray-matter` library to parse YAML frontmatter from markdown files.