aimi-engineering

Aimi Engineering Plugin

Autonomous task execution for Claude Code with structured JSON task management.

Transform implementation plans into executable user stories, then run them autonomously with full context isolation. Stories with independent dependencies execute in parallel via Team orchestration with git worktrees. Each story gets its own agent with automatic state tracking.

Table of Contents

• Installation
• Quick Start
• Commands
• Skills
• Agents
• Workflow
• Task Schema
• Architecture
• Security
• Troubleshooting
• Version History

Installation

Claude Code

No external dependencies. This plugin is fully standalone.

# Add marketplace and install
claude /plugin marketplace add https://github.com/aimi-so/aimi-engineering-plugin
claude /plugin install aimi-engineering

Verify installation:

claude /plugin list
/aimi:status

OpenCode

Install using the built-in installer script. No external dependencies required.

git clone https://github.com/aimi-so/aimi-engineering-plugin
cd aimi-engineering-plugin
./install.sh --to opencode

This installs the plugin into OpenCode's global config directory (~/.config/opencode/) with full compatibility translation:

• Commands are translated and installed as nested directories (e.g., commands/aimi/plan.md) so they appear as /aimi:plan, /aimi:execute, etc.
• Command bodies are fully rewritten for OpenCode compatibility — agent invocations use the Task tool, CLI path references use OPENCODE_CONFIG_DIR, and error messages point to the OpenCode installer
• Skills are copied to ~/.config/opencode/skills/ with SKILL.md and reference files preserved
• Agents are translated to ~/.config/opencode/agents/aimi-*.md with model fields preserved
• Permissions are auto-configured in opencode.json for autonomous Bash execution
• Plugin source (CLI scripts, hooks) is copied to ~/.config/opencode/plugins/aimi-engineering/
• context7 MCP server is added to opencode.json
• AIMI_PLUGIN_DIR is set in your shell profile

After installation, restart your shell or run:

export AIMI_PLUGIN_DIR="$HOME/.config/opencode/plugins/aimi-engineering"

Known Limitations

• disable-model-invocation is not supported in OpenCode. The installer prepends a side-effect warning to command bodies as a workaround, instructing the model not to invoke sub-agents autonomously.
• AskUserQuestion tool is not available in OpenCode. Commands that use it are rewritten to use natural conversation prompts instead (asking the user directly in the response).
• Custom subagent_type (e.g., subagent_type: researcher) is not yet supported in OpenCode. Agents are installed as general-purpose with the agent prompt inlined into the Task tool invocation.

Project-Level Install

To install into .opencode/ in your project directory instead of globally:

./install.sh --to opencode --project

Uninstall

./install.sh --uninstall --from opencode

Preview Changes

./install.sh --to opencode --dry-run

Environment Variable

The AIMI_PLUGIN_DIR environment variable points to the installed plugin directory so that commands can locate CLI scripts, skill references, and agent definitions. The installer sets this automatically. Do not set this variable manually unless you have a custom installation layout.

Quick Start

# 1. Brainstorm your feature
/aimi:brainstorm Add user authentication with email/password

# 2. Generate tasks directly
/aimi:plan Add user authentication

# 3. Execute all stories autonomously
/aimi:execute

# 4. Review the implementation
/aimi:review

Commands

Command	Description	Usage
/aimi:brainstorm	Explore ideas through guided brainstorming	/aimi:brainstorm [feature]
/aimi:plan	Generate tasks.json directly from feature description	/aimi:plan [feature]
/aimi:deepen	Enrich tasks.json stories with research insights	/aimi:deepen [tasks-path]
/aimi:status	Show current task execution progress	/aimi:status
/aimi:next	Execute the next pending story	/aimi:next
/aimi:execute	Run all stories autonomously (parallel for v3, sequential for v2.2)	/aimi:execute
/aimi:review	Multi-agent code review with findings synthesis	/aimi:review [PR or branch]
/aimi:swarm	Execute multiple tasks.json files in parallel Docker sandboxes	/aimi:swarm [--file path] [--max N]

Command Details

/aimi:brainstorm

Standalone brainstorm workflow with codebase research and Ralph-style batched multiple-choice questions. Explores requirements and approaches interactively before committing to implementation.