ai-dev-assisted-u

AI-assisted 5-step bugfix flow for Backlog.com — one autonomous orchestrator skill, direct step skills for Codex-style invocation, workflow-driven execution, and shared internal prompt modules.

Supports: Cursor · Claude Code · Codex · Antigravity · OpenCode

What It Does

/ai-dev-assisted-u PROJ-123

That's it. The AI runs:

1. ai-fetch — Fetch issue from Backlog, analyze root cause, trace caller dependencies
2. ai-fix — TDD implementation (failing test first), minimal fix, verification
3. ai-review — Spec compliance + code quality + security scan + regression prediction
4. ai-commit — Impact assessment, commit, push, create PR
5. ai-ship — Generate reports, post Backlog comment (plain language), update status to Resolved

The orchestrator continues automatically between steps. Run each step individually only when you want a manual checkpoint. /ai-auto-fix is a compatibility alias for the same autonomous flow.

For Codex-style skill invocation, install exposes:

$ai-init
$ai-fetch
$ai-fix
$ai-review
$ai-commit
$ai-ship

On Codex, these step entries are published from inside the ai-dev-assisted-u bundle, but they autocomplete with the same ai-* names as the other tools.

Quick Setup (3 steps, then done)

Step 1 — Install skill + workflows

# Interactive menu (one tool at a time, or all)
npx ai-dev-assisted-u install

# Global (available in all projects)
npx ai-dev-assisted-u install --tool all --location global

# Project-local (current project only)
npx ai-dev-assisted-u install --tool cursor --location project-local

# Multiple tools
npx ai-dev-assisted-u install --tool codex,cursor --location project-local

Step 2 — Setup project config

cd your-project
npx ai-dev-assisted-u setup --api-key "YOUR_BACKLOG_API_KEY"

Auto-detects git_host, backlog_space, project_key from git remote. Get your API key: Backlog > Profile > API Settings.

Step 3 — Setup MCP (once, then no more config checks)

# Cursor
npx ai-dev-assisted-u mcp-setup --tool cursor --location project-local

# Claude Code (global)
npx ai-dev-assisted-u mcp-setup --tool claude --location global

# Codex
npx ai-dev-assisted-u mcp-setup --tool codex --location project-local

This writes the backlog-mcp-server config to your IDE's MCP config file. Restart your IDE — the MCP server starts automatically on every session.

After first successful MCP call, set mcp_confirmed: true in .brain/backlog.json to skip all fallback detection on future runs.

Usage

After install + setup + mcp-setup:

Initialize shared .brain context once per project:

/ai-init
# or locally
npm run init-context -- /path/to/project

/ai-dev-assisted-u PROJ-123
/ai-dev-assisted-u https://myteam.backlog.com/view/PROJ-123
/ai-auto-fix PROJ-123 --context "button not clicking on mobile Safari only"

Individual steps:

/ai-fetch PROJ-123      — Fetch + analyze root cause + trace dependencies
/ai-fix PROJ-123        — Implement fix (TDD)
/ai-review PROJ-123     — Multi-layer review + security + manual approval gate
/ai-commit PROJ-123     — Commit + push + PR
/ai-ship PROJ-123       — Report + log + close

State is saved between steps. If a session is interrupted, resume from where it left off.

Install Path Mapping

Global Install

| Tool | Skills | Workflows | |------|--------|-----------| | Cursor | ~/.cursor/skills/ai-dev-assisted-u/ plus sibling step skill dirs | ~/.cursor/commands/ | | Claude Code | ~/.claude/skills/ai-dev-assisted-u/ plus sibling step skill dirs | only ai-dev-assisted-u and ai-auto-fix commands are kept to avoid duplicate step surfaces | | Codex | ~/.codex/skills/ai-dev-assisted-u/ with namespaced step skills | ~/.codex/workflows/ | | Antigravity | ~/.gemini/antigravity/skills/ai-dev-assisted-u/ plus sibling step skill dirs | ~/.gemini/antigravity/global_workflows/ | | OpenCode | ~/.config/opencode/skills/ai-dev-assisted-u/ plus sibling step skill dirs | ~/.config/opencode/workflows/ |

Project-Local Install

| Tool | Skills | Workflows | |------|--------|-----------| | Cursor | .cursor/skills/ai-dev-assisted-u/ plus sibling step skill dirs | .cursor/commands/ | | Claude Code | .claude/skills/ai-dev-assisted-u/ plus sibling step skill dirs | .claude/commands/ keeps only ai-dev-assisted-u and ai-auto-fix | | Codex | .codex/skills/ai-dev-assisted-u/ with namespaced step skills | .codex/workflows/ | | Antigravity | .agent/skills/ai-dev-assisted-u/ plus sibling step skill dirs | .agent/workflows/ | | OpenCode | .opencode/skills/ai-dev-assisted-u/ plus sibling step skill dirs | .opencode/workflows/ |

Local always wins over global — if both are installed, local is used.

This is intentional: global = defaults for all projects, local = per-project customization.

Global vs Local Conflict Resolution

When both global and local are installed, the skill's find command searches local paths first:

SKILL_DIR=$(find \
  ".claude/skills" ".cursor/skills" ".codex/skills" ".agent/skills" \  # LOCAL FIRST
  "${HOME}/.claude/skills" "${HOME}/.cursor/skills" \                   # global second
  "${HOME}/.codex/skills" "${HOME}/.gemini/antigravity/skills" \
  -name "SKILL.md" -path "*/ai-dev-assisted-u/*" \
  2>/dev/null | head -1 | xargs dirname)

head -1 takes the first match → local skill is always selected if it exists.

Recommended pattern:

• Install global once for your machine
• Override per-project by installing project-local in projects that need custom config

MCP Setup — One Time, Then Done

The mcp-setup command writes this to your IDE config:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["-y", "backlog-mcp-server"],
      "env": {
        "BACKLOG_API_KEY": "your-api-key",
        "BACKLOG_SPACE": "your-team.backlog.com",
        "OPTIMIZE_RESPONSE": "1",
        "MAX_TOKENS": "5000",
        "ENABLE_TOOLSETS": "issue"
      }
    }
  }
}

IDE config file locations:

| Tool | Project-local | Global | |------|--------------|--------| | Cursor | .cursor/mcp.json | ~/.cursor/mcp.json | | Claude Code | .claude/settings.json | ~/.claude.json | | Codex | .codex/mcp.json | ~/.codex/mcp.json | | Antigravity | .agent/mcp.json | ~/.gemini/antigravity/mcp.json |

After restart, the MCP server is always available. The skill skips all detection logic when mcp_confirmed: true is set in .brain/backlog.json.

.brain/backlog.json

Created by npx ai-dev-assisted-u setup:

{
  "backlog_space": "your-team.backlog.com",
  "backlog_api_key": "your-api-key",
  "project_key": "PROJ",
  "git_host": "github",
  "git_remote": "origin",
  "auto_branch": true,
  "auto_push": true,
  "report_lang": "vi",
  "mcp_confirmed": false
}

After running mcp-setup and first successful MCP call, set mcp_confirmed: true manually or the skill will set it automatically after the first successful MCP call.

Advanced options (add manually if needed):

{
  "execution_mode": "auto",
  "review_layers": ["code_quality", "security", "regression"],
  "report_auto": false,
  "comment_format": "auto",
  "pr_format": "auto",
  "lazy_fetch": true,
  "batch_concurrency": 2
}

Shared Prompt Modules

The installed package keeps one shared asset bundle under ai-dev-assisted-u/. Direct step wrappers reuse those shared assets. Internal phase logic lives in:

| Prompt | Phase | Purpose | |--------|-------|---------| | prompts/analyze.md | Fetch | Root cause analysis + dependency trace | | prompts/implement.md | Fix | TDD implementation + verification | | prompts/review.md | Review | Spec/quality/security/regression + manual/autonomous release gating | | prompts/ship.md | Commit/Ship | Impact, PR, reports, Backlog logging |

Requirements

• Node.js >= 18
• Git CLI
• Python 3.8+ with requests (for image download fallback)
• backlog-mcp-server (recommended): npm install -g backlog-mcp-server
• gh CLI (for GitHub PRs): brew install gh
• glab CLI (for GitLab PRs): brew install glab

Update

npx ai-dev-assisted-u@latest install --tool all --location global

Updates skill + workflows. Does NOT overwrite .brain/backlog.json.

Relationship to backlog-integration

This package (ai-dev-assisted-u) is a separate npm package from backlog-integration.

| | backlog-integration | ai-dev-assisted-u | |-|-----------------------|---------------------| | Focus | Installer + basic bugfix workflow | Enhanced 5-step flow with security + regression | | Internal prompts | — | analyze, implement, review, ship | | State file | .brain/bugfix_state.json | .brain/bugfix_state.json | | CLI | npx backlog-integration | npx ai-dev-assisted-u |

Both can be installed side by side. They use separate state files and skill directories.