---
mode: subagent
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
# t1665.3: Create prompt-injection-adapter.sh — Per-Runtime System Prompt Deployment

## Origin

- **Created:** 2026-03-26
- **Session:** claude-code:interactive
- **Created by:** marcusquinn (human + ai-interactive)
- **Parent task:** t1665
- **Conversation context:** Each runtime has a different mechanism for loading system-level instructions (AGENTS.md, instructions field, .cursorrules, skills/ dir). The framework needs to deploy build.txt/AGENTS.md via each runtime's native mechanism.

## What

A new shell library `.agents/scripts/prompt-injection-adapter.sh` that deploys the aidevops system prompt (AGENTS.md, build.txt) to each runtime using its native instruction-loading mechanism. This replaces the scattered, per-runtime deployment logic currently in `agent-deploy.sh`, `generate-opencode-agents.sh`, and `generate-claude-agents.sh`.

## Why

- 5+ different system prompt mechanisms exist across runtimes, each handled in a different script
- `agent-deploy.sh:315-399` hardcodes `~/.claude:commands` and `~/.opencode:.` as deployment targets
- `generate-opencode-agents.sh:466-475` sets the `instructions` field in `opencode.json`
- Claude Code relies on AGENTS.md auto-discovery at `~/.config/Claude/AGENTS.md` and `~/.claude/AGENTS.md`
- Codex uses `~/.codex/instructions.md` (not yet configured by aidevops)
- Cursor uses `~/.cursor/rules/` (symlinked by `verify-mirrors.sh` but not deployed by setup)
- Adding a new runtime means finding all these scattered locations and adding another case

## How (Approach)

### File: `.agents/scripts/prompt-injection-adapter.sh`

Sources `runtime-registry.sh` for runtime properties.

### System prompt injection mechanisms (comprehensive map)

| Runtime | Mechanism ID | How it works | What aidevops deploys |
|---------|-------------|--------------|----------------------|
| OpenCode | `json-instructions` | `opencode.json` `"instructions"` field: array of file paths auto-loaded every session | `["~/.aidevops/agents/AGENTS.md"]` in instructions field |
| Claude Code | `agents-md-autodiscovery` | Auto-discovers `AGENTS.md` files in `~/.config/Claude/`, `~/.claude/`, and project root | AGENTS.md files with pointer line: `Add ~/.aidevops/agents/AGENTS.md to context` |
| Codex | `codex-instructions-md` | `~/.codex/instructions.md` (global) loaded every session; per-project `.codex/instructions.md` also supported; `~/.codex/skills/` for skill files | Deploy `~/.codex/instructions.md` with framework pointer; symlink `skills/` to `.agents/` |
| Cursor | `cursorrules-plus-agents` | `~/.cursor/rules/` (global rules dir) + `.cursorrules` (per-project) + AGENTS.md auto-discovery | Symlink `~/.cursor/rules/` content; deploy AGENTS.md |
| Droid | `factory-skills` | `~/.factory/skills/` directory for skill files; AGENTS.md auto-discovery | Symlink `~/.factory/skills/` to `.agents/`; deploy AGENTS.md |
| Gemini CLI | `gemini-agents-md` | `~/.gemini/AGENTS.md` (global) + `.gemini/AGENTS.md` (per-project) | Deploy AGENTS.md with framework pointer |
| Windsurf | `windsurfrules` | `.windsurfrules` (per-project) + global config | Deploy rules file with framework pointer |
| Continue.dev | `continue-rules` | `.continuerules` (per-project) + `config.json` `systemMessage` field | Deploy rules file; set systemMessage |
| Kilo/Kiro | `kilo-rules` / `kiro-rules` | AGENTS.md auto-discovery + rules directory | Deploy AGENTS.md |
| Aider | `aider-read` | `.aider.conf.yml` `read:` field lists files to include in context | Add AGENTS.md path to `read:` list |

### Core functions

```bash
deploy_prompts_for_runtime() {
    local runtime_id="$1"
    local mechanism
    mechanism=$(get_runtime_prompt_mechanism "$runtime_id")

    case "$mechanism" in
        json-instructions)          _deploy_prompt_json_instructions "$runtime_id" ;;
        agents-md-autodiscovery)    _deploy_prompt_agents_md "$runtime_id" ;;
        codex-instructions-md)      _deploy_prompt_codex_instructions ;;
        cursorrules-plus-agents)    _deploy_prompt_cursor ;;
        factory-skills)             _deploy_prompt_factory ;;
        gemini-agents-md)           _deploy_prompt_gemini ;;
        windsurfrules)              _deploy_prompt_windsurf ;;
        continue-rules)             _deploy_prompt_continue ;;
        kilo-rules|kiro-rules)      _deploy_prompt_agents_md "$runtime_id" ;;
        aider-read)                 _deploy_prompt_aider ;;
        *) print_warning "Unknown prompt mechanism '$mechanism' for $runtime_id" ;;
    esac
}

deploy_prompts_for_all_runtimes() {
    local runtime_id
    while IFS= read -r runtime_id; do
        deploy_prompts_for_runtime "$runtime_id"
    done < <(detect_installed_runtimes)
}
```

### Per-mechanism implementations

```bash
_deploy_prompt_json_instructions() {
    # OpenCode: set "instructions" field in opencode.json to point to AGENTS.md
    local runtime_id="$1"
    local config_path
    config_path=$(get_runtime_config_path "$runtime_id")
    # Use python3/jq to set config.instructions = ["~/.aidevops/agents/AGENTS.md"]
}

_deploy_prompt_agents_md() {
    # Claude Code, Gemini, Kilo, Kiro: deploy AGENTS.md with pointer line
    local runtime_id="$1"
    local reference_line='Add ~/.aidevops/agents/AGENTS.md to context for AI DevOps capabilities.'
    # Determine target directories from registry
    # Create AGENTS.md with reference line if not present
}

_deploy_prompt_codex_instructions() {
    # Codex: create ~/.codex/instructions.md with framework pointer
    local instructions_file="$HOME/.codex/instructions.md"
    local reference_line='Read ~/.aidevops/agents/AGENTS.md for AI DevOps framework capabilities and rules.'
    mkdir -p "$HOME/.codex"
    if [[ ! -f "$instructions_file" ]]; then
        echo "$reference_line" > "$instructions_file"
    elif ! grep -q 'aidevops' "$instructions_file"; then
        # Prepend to existing file
        local tmp; tmp=$(mktemp)
        echo "$reference_line" > "$tmp"
        echo "" >> "$tmp"
        cat "$instructions_file" >> "$tmp"
        mv "$tmp" "$instructions_file"
    fi
}

_deploy_prompt_cursor() {
    # Cursor: ensure ~/.cursor/rules/ exists with AGENTS.md
    # The verify-mirrors.sh symlink (.cursor/rules → ../.agents) handles per-repo
    # This handles the global ~/.cursor/ deployment
}

_deploy_prompt_factory() {
    # Droid: ensure ~/.factory/skills/ exists with AGENTS.md
    # Similar to Cursor pattern
}

_deploy_prompt_aider() {
    # Aider: add AGENTS.md to .aider.conf.yml read: list
    local aider_config="$HOME/.aider.conf.yml"
    # Parse YAML, add to read: list if not present
}
```

### Migration from existing code

| Current location | What it does | Migrates to |
|-----------------|-------------|-------------|
| `agent-deploy.sh:315-399` `inject_agents_reference()` | Deploys AGENTS.md to `~/.claude/commands/` and `~/.opencode/` | `deploy_prompts_for_all_runtimes()` |
| `agent-deploy.sh:381-399` | Deploys OpenCode config-level AGENTS.md from template | `_deploy_prompt_json_instructions("opencode")` |
| `generate-opencode-agents.sh:466-475` | Sets `instructions` field in opencode.json | `_deploy_prompt_json_instructions("opencode")` |
| `verify-mirrors.sh:24-32` | Symlinks `.cursor/rules`, `.codex/prompts`, `.factory/skills` | Stays (per-repo); adapter handles global `~/` deployment |

### Key files to reference

- `setup-modules/agent-deploy.sh:315-399` — current `inject_agents_reference()` (replace)
- `.agents/scripts/generate-opencode-agents.sh:460-475` — current instructions field setting
- `.agents/scripts/verify-mirrors.sh:24-32` — per-repo symlink targets (coordinate, don't duplicate)
- `.agents/AGENTS.md` — the content being deployed
- `.agents/prompts/build.txt` — system prompt content (referenced by instructions, not deployed directly)

## Acceptance Criteria

- [ ] `prompt-injection-adapter.sh` exists at `.agents/scripts/prompt-injection-adapter.sh`
- [ ] `deploy_prompts_for_runtime "opencode"` sets instructions field in opencode.json
- [ ] `deploy_prompts_for_runtime "claude"` deploys AGENTS.md to `~/.claude/` and `~/.config/Claude/`
- [ ] `deploy_prompts_for_runtime "codex"` creates `~/.codex/instructions.md` with framework pointer
- [ ] `deploy_prompts_for_runtime "cursor"` deploys AGENTS.md to `~/.cursor/`
- [ ] `deploy_prompts_for_all_runtimes` iterates all installed runtimes
- [ ] Idempotent: running twice doesn't duplicate content in instruction files
- [ ] Does not overwrite user content in existing instruction files (prepends pointer if missing)
- [ ] Bash 3.2 compatible, shellcheck clean
- [ ] `inject_agents_reference()` in agent-deploy.sh delegates to this adapter
