33GOD: Creating and Working with Projects

Core Philosophy

iMi is the Project Registry: Every 33GOD project must be registered through iMi. Every unit of work must be executed within an iMi-managed worktree. This is non-negotiable for the 33GOD pipeline.

Events Drive Everything: All 33GOD work emits events through Bloodbank. Worktrees emit worktree.created, tasks emit agent.task.*, and the heartbeat system (system.heartbeat.tick) orchestrates agent coordination every 60 seconds.

Entity-Based Workspace Isolation: All actors (humans and Yi agents) are equal entities with token-based authentication. Each entity has a completely isolated workspace directory. No more shared .iMi cluster hubs.

Universal Identity: Once registered, a project has a UUID that is referenced across all 33GOD components (Bloodbank events, Plane tickets, Yi orchestrations, Flume task management). Entities also have UUIDs for cross-component identity resolution.

Worktree = Work Unit: Each worktree represents a discrete unit of work traceable to a specific task source. All worktrees live within entity workspaces for complete isolation and accountability.

Accountability Through Code: Agents cannot release worktrees until changes are staged and committed. The git history + workspace access logs + Bloodbank events become the audit trail for all actions.

When to Use This Skill

REQUIRED: Project Creation

Trigger: User or agent needs to create a new 33GOD project

Scenarios:

1. From Scratch: Create new GitHub repo, initialize git, scaffold boilerplate
2. From Existing Repo: Clone existing GitHub repo and register as 33GOD project
3. From PRD Document: Generate project from specification file

Commands:

# New project with AI-generated scaffold
imi project create --concept "FastAPI backend for ChoreScore gamification" --name ChoreScore

# New project from PRD document
imi project create --prd ./project-specs.md

# New project with explicit stack/database payload
imi project create --payload '{"name":"MyApp","stack":"react","database":"postgres"}'

# Clone and register existing repo
git clone [email protected]:user/existing-repo.git
cd existing-repo
imi init

# Initialize local repo (already exists)
cd /path/to/existing/repo
imi init

What Happens:

1. GitHub repo created (if new) or validated (if existing)
2. Project registered in PostgreSQL with globally unique UUID
3. Entity workspace claimed for this project (e.g., /home/you/33GOD/workspaces/delorenj/myproject/)
4. Full clone created in entity workspace (not shared cluster hub)
5. trunk-main worktree created for main branch
6. Project UUID returned for reference in Bloodbank/Yi/Flume

Critical: imi init requires authentication via $IMI_IDENTITY_TOKEN. The entity associated with the token owns the workspace. There is no separate "register" step. Initialization = Registration + Workspace Claim.

REQUIRED: Starting New Work

Trigger: Agent receives a task from any source

Task Sources (must link to worktree):

• Plane Ticket: plane_ticket_id from managing-tickets-and-tasks-in-plane skill
• Bloodbank Command: correlation_id from rabbitmq message
• Yi Orchestration: orchestrator_id from agent assignment
• Sprint Board: Task ID from external project management system

Before Starting Work:

# Check for in-flight work to avoid conflicts
imi list --json | jq '.data[] | select(.has_uncommitted_changes == true)'

# Check project status
imi status

# Create typed worktree linked to task source
imi add feat user-authentication
# OR: imi add fix login-bug
# OR: imi add aiops mcp-tool-refactor
# OR: imi add devops ci-migration
# OR: imi add review 123  # For PR reviews

Link Task Source (TODO - needs implementation):

# Store task source metadata in worktree
imi metadata set --worktree feat-user-authentication \
  --key plane_ticket_id \
  --value "PROJ-123"

# OR for Bloodbank task
imi metadata set --worktree feat-user-authentication \
  --key bloodbank_correlation_id \
  --value "bb-8f3a9c2e"

# OR for Yi orchestration
imi metadata set --worktree feat-user-authentication \
  --key yi_orchestrator_id \
  --value "yi-orch-5d2b1a"

Agent Claim (TODO - needs implementation):

# Claim worktree for exclusive access
imi claim feat-user-authentication --yi-id "claude-sonnet-4.5-agent-001"

# Check who owns a worktree
imi show feat-user-authentication --json | jq '.data.agent_id'

What Happens:

1. New worktree created with type-specific branch/directory naming
2. Task source metadata stored in JSONB worktrees.metadata column
3. Agent ID recorded in worktrees.agent_id column (when claim implemented)
4. .iMi/presence/<worktree>.lock file created for signaling
5. Worktree path returned for agent to cd into

Complete Command Reference

Project Lifecycle

imi init [repo] [--force]

Initialize iMi in current directory or clone from GitHub.

Behaviors:

• No args: Register current directory as 33GOD project
• With repo: Clone owner/repo from GitHub then register
• With --force: Re-initialize even if already initialized

What It Does:

1. Registers project in PostgreSQL (assigns UUID)
2. Creates .iMi/ cluster hub at parent of trunk
3. Writes .iMi/project.json with project metadata
4. Creates trunk-<branch> worktree for main branch

Example:

# Initialize existing repo
cd /home/user/code/MyProject
imi init

# Clone and initialize
imi init delorenj/ChoreScore

imi project create [--concept|--prd|--name|--payload]

Bootstrap complete new project with GitHub integration.

Parameters:

• --concept: Natural language project description
• --prd: Path to PRD markdown file
• --name: Explicit project name (optional, inferred otherwise)
• --payload: JSON string with structured definition

Stack Detection:

• PythonFastAPI: Creates pyproject.toml, mise tasks, docker-compose
• ReactVite: Creates package.json, vite config, shadcn setup
• Generic: Creates basic README and git structure

Example:

imi project create \
  --concept "FastAPI task manager with Postgres and Redis" \
  --name TaskMaster

Worktree Creation

imi add <type> <name> [--repo] [--pr]

Unified command to create worktrees of any type.

Built-in Types:

• feat - Feature development (branch: feat/, dir: feat-)
• fix - Bug fixes (branch: fix/, dir: fix-)
• aiops - AI operations: agents, rules, MCP configs, workflows (branch: aiops/, dir: aiops-)
• devops - DevOps tasks: CI, repo organization, deploys (branch: devops/, dir: devops-)
• review - Pull request reviews (branch: pr-review/, dir: pr-review-)

Custom Types: Use imi types add <name> to create custom types with your own prefixes.

Examples:

# Create feature worktree
imi add feat user-authentication

# Create fix worktree
imi add fix login-redirect-bug

# Create AI ops worktree
imi add aiops mcp-server-integration

# Create DevOps worktree
imi add devops github-actions-ci

# Create review worktree (special - requires PR number)
imi add review 123 --pr 123

Legacy Type Commands (Deprecated)

These still work but emit deprecation warnings:

imi feat <name>       # Use: imi add feat <name>
imi fix <name>        # Use: imi add fix <name>
imi aiops <name>      # Use: imi add aiops <name>
imi devops <name>     # Use: imi add devops <name>

imi review <pr_number> [repo]

Create worktree for reviewing a pull request.

Requirements:

• GitHub CLI (gh) must be installed and authenticated
• PR must exist in the repository

What It Does:

1. Fetches PR from GitHub via gh pr view <pr>
2. Creates pr-review-<number> worktree
3. Checks out PR branch
4. Displays PR metadata (title, author, description)

Example:

# Review PR in current repo
imi review 456

# Review PR in specific repo
imi review 456 delorenj/ChoreScore

Type Management

imi types list

List all available worktree types (built-in + custom).

Output:

Built-in Types:
  feat        Feature development (feat/, feat-)
  fix         Bug fixes (fix/, fix-)
  aiops       AI operations (aiops/, aiops-)
  devops      DevOps tasks (devops/, devops-)
  review      Pull request reviews (pr-review/, pr-review-)
  trunk       Main branch (empty prefix)

Custom Types:
  experiment  Experimental features (experiment/, experiment-)

imi types add <name> [--branch-prefix] [--worktree-prefix] [--description]

Add custom worktree type.

Parameters:

• name: Type name (lowercase, alphanumeric, hyphens)
• --branch-prefix: Branch prefix (defaults to <type>/)
• --worktree-prefix: Worktree directory prefix (defaults to <type>-)
• --description: Human-readable description

Example:

imi types add experiment \
  --description "Experimental features and prototypes"

# Creates type with:
# - Branch: experiment/<name>
# - Directory: experiment-<name>

imi types remove <name>

Remove custom worktree type.

Protection: Built-in types (feat, fix, aiops, devops, review, trunk) cannot be removed.

Example:

imi types remove experiment

Navigation and Discovery

imi go [query] [-r|--repo] [-w|--worktrees-only] [-a|--include-inactive]

Navigate to worktree or repository using fuzzy search.

Behaviors:

• No args: Interactive picker of all worktrees + repos
• With query: Fuzzy search by name/branch/path
• With --repo: Limit search to specific repo
• With --worktrees-only: Exclude trunk and repo roots
• With --include-inactive: Include closed/merged worktrees

Returns in JSON mode:

{
  "success": true,
  "data": {
    "target_path": "/home/user/code/Project/feat-user-auth",
    "worktree_name": "feat-user-auth",
    "branch_name": "feat/user-auth"
  }
}

Example:

# Interactive picker
imi go

# Fuzzy search
imi go user-auth

# Navigate and change directory
cd $(imi go user-auth --json | jq -r '.data.target_path')

# Search within specific repo
imi go auth --repo ChoreScore

imi trunk [repo]

Switch to trunk worktree (main branch).

Example:

# Switch to trunk in current repo
imi trunk

# Switch to trunk in specific repo
imi trunk ChoreScore

imi list [--worktrees|--projects] [repo]

List all active worktrees or projects.

Modes:

• Default: Lists both projects and their worktrees
• --worktrees: Only worktrees
• --projects: Only projects/repositories

JSON Output (for programmatic access):

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "feat-user-auth",
      "type": "feat",
      "branch": "feat/user-auth",
      "path": "/path/to/worktree",
      "agent_id": "claude-sonnet-4.5-001",
      "has_uncommitted_changes": true,
      "uncommitted_files_count": 5,
      "ahead_of_trunk": 3,
      "behind_trunk": 0,
      "metadata": {
        "plane_ticket_id": "PROJ-123"
      }
    }
  ]
}

Example:

# List all
imi list

# List only worktrees
imi list --worktrees

# List for specific repo
imi list ChoreScore

# JSON mode for scripting
imi list --json | jq '.data[] | select(.agent_id != null)'

imi status [repo]

Show comprehensive status of all worktrees.

What It Shows:

• Worktree name and type
• Current branch
• Uncommitted changes count
• Ahead/behind trunk status
• Agent ID (if claimed)
• Last commit info

Example:

# Status for all repos
imi status

# Status for specific repo
imi status ChoreScore

Worktree Lifecycle

imi remove <name> [--keep-branch] [--keep-remote] [repo]

Remove a worktree.

Default Behavior:

• Removes worktree directory
• Deletes local branch
• Deletes remote branch (if pushed)
• Marks worktree as inactive in database

Options:

• --keep-branch: Keep local branch after removing worktree
• --keep-remote: Keep remote branch (requires --keep-branch)

Safety Checks:

• Warns if uncommitted changes exist
• Confirms before deleting branches

Example:

# Remove worktree and all branches
imi remove feat-user-auth

# Remove worktree but keep branches
imi remove feat-user-auth --keep-branch --keep-remote

imi close <name> [repo]

Close a worktree without merging (cancel the branch).

Use Case: Abandoned work, experimental branches, false starts

What It Does:

1. Removes worktree directory
2. Deletes local and remote branches
3. Marks as closed in database
4. Does NOT merge to trunk

Example:

imi close feat-experimental-feature

imi merge [name] [repo]

Merge a worktree into trunk-main and close it.

Behaviors:

• No args: Merges current branch (if in worktree)
• With name: Merges specified worktree

What It Does:

1. Switches to trunk-main
2. Merges worktree branch
3. Pushes to remote
4. Removes worktree
5. Records merge metadata in database

Example:

# Merge current worktree
imi merge

# Merge specific worktree
imi merge feat-user-auth

Maintenance and Sync

imi sync [repo]

Synchronize database with actual Git worktrees.

What It Does:

• Discovers worktrees on filesystem not in database
• Marks database entries as inactive if worktree deleted
• Updates git state (uncommitted changes, ahead/behind)
• Reconciles any inconsistencies

Use Case: After manual git operations, after system crashes, periodic health checks

Example:

# Sync all repos
imi sync

# Sync specific repo
imi sync ChoreScore

imi prune [--dry-run] [--force] [repo]

Clean up stale worktree references from Git.

What It Does:

• Removes .git/worktrees/ entries for deleted worktrees
• Cleans up orphaned directories
• Updates database to match reality

Options:

• --dry-run: Show what would be removed without doing it
• --force: Remove without confirmation prompts

Example:

# Dry run to preview
imi prune --dry-run

# Actually prune
imi prune --force

imi repair

Repair repository paths in database after directories moved.

Use Case: Moved home directory, cloned to new machine, restructured code folder

What It Does:

• Auto-detects moved repositories
• Updates all paths in database
• Validates git remotes match

Example:

imi repair

Monitoring

imi monitor [repo]

Start real-time monitoring of worktree activities.

What It Displays:

• File changes (created, modified, deleted)
• Git commits
• Worktree switching
• Agent activities

Use Case: Observing agent work, debugging workflows, activity logging

Example:

# Monitor all repos
imi monitor

# Monitor specific repo
imi monitor ChoreScore

Utilities

imi completion <shell>

Generate shell completions for iMi.

Supported Shells:

• bash
• zsh
• fish
• powershell

Example:

# Generate zsh completions
imi completion zsh > ~/.zsh/completions/_imi

# Source in .zshrc
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Commands That Need Implementation

imi claim <name> --yi-id <id>

Claim a worktree for exclusive agent access.

What It Should Do:

1. Check if worktree already claimed (error if so)
2. Update worktrees.agent_id column with Yi ID
3. Create .iMi/presence/<worktree>.lock file
4. Log activity to agent_activities table
5. Return success with worktree metadata

Usage:

imi claim feat-user-auth --yi-id "claude-sonnet-4.5-001"

Error Cases:

• Worktree doesn't exist
• Worktree already claimed by another agent
• Agent ID not provided

imi release <name> --yi-id <id>

Release a worktree (must have clean state).

What It Should Do:

1. Verify agent owns the worktree (worktrees.agent_id matches)
2. Check for uncommitted changes (git status)
3. Fail if dirty state (changes not committed)
4. Clear worktrees.agent_id column (set to NULL)
5. Remove .iMi/presence/<worktree>.lock file
6. Log release activity
7. Return success

Usage:

# Will fail if uncommitted changes
imi release feat-user-auth --yi-id "claude-sonnet-4.5-001"

Error Cases:

• Worktree doesn't exist
• Agent doesn't own the worktree
• Uncommitted changes detected
• Yi ID not provided

Required Flow:

# Must commit before release
git add .
git commit -m "feat: Implement feature

Plane-Ticket: PROJ-123
Yi-ID: claude-sonnet-4.5-001

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"

# Now release succeeds
imi release feat-user-auth --yi-id "claude-sonnet-4.5-001"

imi metadata set --worktree <name> --key <key> --value <value>

Set metadata on a worktree.

What It Should Do:

1. Load worktree from database
2. Parse existing metadata JSONB column
3. Set key-value pair (merging with existing)
4. Update database with new metadata
5. Return success

Usage:

# Link to Plane ticket
imi metadata set --worktree feat-user-auth \
  --key plane_ticket_id \
  --value "PROJ-123"

# Link to Bloodbank correlation
imi metadata set --worktree feat-user-auth \
  --key bloodbank_correlation_id \
  --value "bb-8f3a9c2e"

# Link to Yi orchestrator
imi metadata set --worktree feat-user-auth \
  --key yi_orchestrator_id \
  --value "yi-orch-5d2b1a"

# Custom metadata
imi metadata set --worktree feat-user-auth \
  --key priority \
  --value "high"

imi metadata get --worktree <name> [--key <key>]

Get metadata from a worktree.

What It Should Do:

1. Load worktree from database
2. If --key provided: return single value
3. If no key: return entire metadata object
4. Support JSON output mode

Usage:

# Get specific key
imi metadata get --worktree feat-user-auth --key plane_ticket_id
# Output: PROJ-123

# Get all metadata (JSON mode)
imi metadata get --worktree feat-user-auth --json
# Output: {"plane_ticket_id": "PROJ-123", "yi_orchestrator_id": "yi-orch-5d2b1a"}

JSON Output Mode

ALL commands support --json flag for programmatic access.

Standard Response Format:

{
  "success": true,
  "data": { ... },
  "error": null
}

Error Format:

{
  "success": false,
  "data": null,
  "error": "Worktree not found: feat-nonexistent"
}

Usage Examples:

# Parse with jq
imi list --json | jq '.data[] | select(.type == "feat")'

# Extract path for cd
cd $(imi go user-auth --json | jq -r '.data.target_path')

# Check for errors in scripts
if ! result=$(imi add feat demo --json); then
  echo "Failed to create worktree"
  exit 1
fi

Worktree Lifecycle Rules

Rule 1: One Agent Per Worktree

Enforcement: The worktrees.agent_id column tracks the currently assigned agent.

Multi-Contributor Pattern:

• Multiple agents CAN contribute to the same worktree over time
• Only ONE agent may be active at any given moment
• agent_activities table tracks full history of all contributors

Example:

# Agent A starts work
imi claim feat-user-auth --yi-id "agent-a"
# ... agent-a works, commits, pushes ...

# Agent A hands off to Agent B
imi release feat-user-auth --yi-id "agent-a"
imi claim feat-user-auth --yi-id "agent-b"
# ... agent-b continues, commits, pushes ...

Rule 2: Release Requires Clean State

Enforcement: imi release command checks for uncommitted changes before releasing.

Release Checklist:

• All changes staged: git add .
• Changes committed: git commit -m "..."
• Commit message includes Yi ID and task source
• Optional: Changes pushed to remote

Commit Format (enforced):

git commit -m "feat: Implement user authentication endpoint

Implemented JWT-based authentication with refresh tokens.
Added password hashing with bcrypt.
Created login/logout/refresh endpoints.

Plane-Ticket: PROJ-123
Yi-ID: claude-sonnet-4.5-agent-001

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"

Why This Matters: The git history becomes the authoritative audit trail. If changes aren't committed, there's no record of who did what. Uncommitted changes = unaccountable work.

Rule 3: Task Source Must Be Linkable

Enforcement: Every worktree must have at least ONE of these metadata keys:

• plane_ticket_id
• bloodbank_correlation_id
• yi_orchestrator_id
• sprint_board_task_id

Verification:

# Query worktrees missing task source links
psql -U imi -d imi -c "
SELECT id, name, agent_id
FROM worktrees
WHERE active = TRUE
  AND metadata @> '{}'::jsonb;
"

Why This Matters: Without task source linking, worktrees become orphaned. You can't trace back to "why was this work done?" or "who requested this?". Task linkage enables end-to-end traceability from request → assignment → work → completion.

Agent Workflow Patterns

Pattern 1: Bloodbank Task Execution

# 1. Agent receives message from Bloodbank queue
# Message contains: task_description, correlation_id, priority

# 2. Create worktree based on task type
imi add feat user-profile-page

# 3. Link Bloodbank correlation ID (TODO - needs implementation)
imi metadata set --worktree feat-user-profile-page \
  --key bloodbank_correlation_id \
  --value "bb-a3f7d9e1"

# 4. Claim worktree (TODO - needs implementation)
imi claim feat-user-profile-page --yi-id "$YI_AGENT_ID"

# 5. Navigate and work
cd $(imi go feat-user-profile-page --json | jq -r '.data.target_path')
# ... implement feature ...

# 6. Commit with metadata
git add .
git commit -m "feat: User profile page

Correlation-ID: bb-a3f7d9e1
Yi-ID: $YI_AGENT_ID"

# 7. Release worktree (TODO - needs implementation)
imi release feat-user-profile-page --yi-id "$YI_AGENT_ID"

# 8. Publish completion event to Bloodbank
# (handled by iMi internally)

Pattern 2: Plane Ticket Assignment

# 1. Query next available ticket from Plane
plane_ticket=$(plane api issues list --state "todo" --limit 1 | jq -r '.[0].id')

# 2. Determine worktree type from ticket labels
ticket_type=$(plane api issues get $plane_ticket | jq -r '.labels[0].name')

# 3. Create worktree
imi add $ticket_type $(plane api issues get $plane_ticket | jq -r '.name')

# 4. Link Plane ticket (TODO - needs implementation)
imi metadata set --worktree <worktree-name> \
  --key plane_ticket_id \
  --value "$plane_ticket"

# 5. Claim, work, commit, release (same as above)

# 6. Update Plane ticket status
plane api issues update $plane_ticket --state "in_progress"

Pattern 3: Yi Orchestrator Handoff

# 1. Yi assigns task to agent with orchestrator_id

# 2. Check if worktree already exists (handoff from another agent)
existing_worktree=$(imi list --json | jq -r ".data[] | select(.metadata.yi_orchestrator_id == \"$ORCHESTRATOR_ID\") | .name")

if [ -z "$existing_worktree" ]; then
  # New task - create worktree
  imi add feat $TASK_NAME
  imi metadata set --worktree feat-$TASK_NAME \
    --key yi_orchestrator_id \
    --value "$ORCHESTRATOR_ID"
else
  # Handoff - claim existing worktree
  echo "Taking over worktree: $existing_worktree"
fi

# 3. Claim worktree (TODO - needs implementation)
imi claim <worktree> --yi-id "$YI_AGENT_ID"

# 4. Work, commit, release

Integration with 33GOD Components

Bloodbank (Event Bus)

Published Events:

• imi.project.created - New project registered
• imi.worktree.created - New worktree allocated
• imi.worktree.claimed - Agent claimed worktree
• imi.worktree.released - Agent released worktree
• imi.worktree.merged - Worktree merged to trunk

Consumed Events:

• task.assigned - Trigger worktree creation
• project.scaffold.requested - Trigger project creation

Plane (Sprint Board)

Integration Points:

• Worktree metadata stores plane_ticket_id
• Plane ticket custom fields store imi_worktree_id (UUID)
• Agent activities log references Plane ticket in description
• Plane webhooks trigger iMi worktree operations

Yi (Agent Orchestration)

Integration Points:

• Yi queries iMi for available worktrees before assignment
• Yi checks worktrees.agent_id to avoid double-assignment
• Yi resolves working paths via get_project_working_path() function
• Yi monitors in-flight work via v_inflight_work view

Flume (Session/Task Manager)

Integration Points:

• Flume sessions map 1:1 to iMi worktrees
• Flume task lifecycle tied to worktree lifecycle
• Flume queries iMi for project UUIDs when creating tasks

MCP Tools Reference

iMi exposes 10 MCP tools via FastMCP server for Claude Desktop integration:

Creation Tools

• create_worktree(name, worktree_type="feat", repo=None)
• create_review_worktree(pr_number, repo=None)
• create_project(concept=None, prd=None, name=None, payload=None)

Navigation Tools

• list_worktrees(repo=None)
• navigate_worktree(query, repo=None)
• show_status(repo=None)

Cleanup Tools

• remove_worktree(name, repo=None, keep_branch=False)
• sync_worktrees(repo=None)
• prune_worktrees(repo=None, dry_run=False)

Discovery Tools

• list_types()

See /home/delorenj/.claude/skills/33god-imi-worktree-management/references/mcp-tools-reference.md for detailed schemas.

Database Schema Reference

Critical Tables

projects:

• id (UUID) - Globally unique project identifier
• remote_origin (TEXT) - 1:1 mapping to GitHub URL (unique constraint)
• trunk_path (TEXT) - Filesystem path to trunk worktree
• metadata (JSONB) - Extensible project metadata

worktrees:

• id (UUID) - Globally unique worktree identifier
• project_id (UUID FK) - References projects.id
• type_id (INTEGER FK) - References worktree_types.id
• agent_id (TEXT) - Currently assigned Yi agent (NULL if unclaimed)
• has_uncommitted_changes (BOOLEAN) - Dirty state flag
• uncommitted_files_count (INTEGER) - Number of uncommitted files
• ahead_of_trunk (INTEGER) - Commits ahead of trunk
• behind_trunk (INTEGER) - Commits behind trunk
• metadata (JSONB) - Task source links stored here
  • plane_ticket_id
  • bloodbank_correlation_id
  • yi_orchestrator_id

agent_activities:

• id (UUID) - Activity identifier
• agent_id (TEXT) - Yi agent who performed action
• worktree_id (UUID FK) - Worktree where action occurred
• activity_type (TEXT) - created, modified, committed, pushed, merged
• description (TEXT) - Human-readable description

Critical Functions

register_project(name, remote_origin, default_branch, trunk_path, metadata):

• Idempotent project registration
• Returns project UUID
• Enforces 1:1 remote_origin constraint

register_worktree(project_id, type_id, name, branch_name, path, agent_id, metadata):

• Creates worktree with proper FKs
• Validates type_id exists
• Returns worktree UUID

get_inflight_work(project_id):

• Returns all worktrees with uncommitted changes or divergence
• Useful for conflict detection before starting new work

get_project_working_path(project_id, worktree_name):

• Resolves canonical filesystem path
• Returns trunk path if worktree_name is NULL
• Returns worktree path if worktree_name provided

Error Handling and Edge Cases

Uncommitted Changes on Release

Error: imi release fails if git status shows dirty state

Resolution:

# Stage changes
git add .

# Commit with proper metadata
git commit -m "feat: Description

Plane-Ticket: PROJ-123
Yi-ID: $YI_AGENT_ID"

# Retry release
imi release <worktree> --yi-id "$YI_AGENT_ID"

Worktree Already Claimed

Error: imi claim fails if agent_id is already set

Resolution:

# Check current owner
imi show <worktree> --json | jq '.data.agent_id'

# Option 1: Current agent releases first
imi release <worktree> --yi-id "<current-agent>"

# Option 2: Force claim (emergency override)
imi claim <worktree> --yi-id "$YI_AGENT_ID" --force

Missing Task Source Link

Error: Worktree created without metadata linking to task source

Resolution:

# Retroactively add task source
imi metadata set --worktree <worktree> \
  --key plane_ticket_id \
  --value "PROJ-123"

# Verify
imi metadata get --worktree <worktree> --key plane_ticket_id

Project Already Registered

Error: imi init reports project already exists

Behavior: iMi is idempotent - returns existing project UUID without error

No Action Required: This is expected behavior for distributed registration

Deprecation Notice

Old Skill: 33god-imi-worktree-management

Status: Deprecated but still functional

Migration Path: Use 33god-creating-and-working-with-projects instead for all new workflows. The old skill focused on iMi's technical capabilities; the new skill focuses on when and why to use iMi in 33GOD workflows.

Implementation Roadmap

Commands Needing Implementation:

1. imi claim <name> --yi-id <id> - Agent worktree claiming
2. imi release <name> --yi-id <id> - Agent worktree release with clean state check
3. imi metadata set --worktree <name> --key <k> --value <v> - Set metadata
4. imi metadata get --worktree <name> [--key <k>] - Get metadata

Database Schema: Already supports all features (agent_id column, metadata JSONB column with GIN index)

Implementation Path:

• Add commands to src/cli.rs
• Implement handlers in src/main.rs
• Add database methods in src/database.rs for updating agent_id and metadata
• Add lock file management in src/local.rs for .iMi/presence/ directory

References

Architecture Documentation

• /home/delorenj/code/iMi/trunk-main/docs/architecture-imi-project-registry.md
• PostgreSQL schema: /home/delorenj/code/iMi/trunk-main/migrations/001_create_schema.sql
• Helper functions: /home/delorenj/code/iMi/trunk-main/migrations/002_functions_and_helpers.sql

Related Skills

• managing-tickets-and-tasks-in-plane - Sprint board integration
• 33god-service-development - Microservice creation patterns
• 33god-development-lifecycle - Meta-level orchestration

Database Connection

# Interactive psql session
/home/delorenj/code/iMi/trunk-main/scripts/psql-imi.sh

# Query example
/home/delorenj/code/iMi/trunk-main/scripts/psql-imi.sh -c "SELECT * FROM v_inflight_work"