AGENTS.md git:20260516.6626bc8A

Immutable. This exact content never changes and is served at /api/v1/blob/420f578af39686c8.

# Amplihack Agents

<!-- AMPLIHACK_CONTEXT_START -->

## 🎯 USER PREFERENCES (MANDATORY - MUST FOLLOW)

## Amplihack Copilot Workflow Rules

For any DEV, INVESTIGATE, or HYBRID request, invoke `Skill(skill="dev-orchestrator")` immediately.

After the skill is activated, the next tool call must execute the `smart-orchestrator` recipe via `amplihack recipe run smart-orchestrator`.

Do not follow the workflow manually and do not revert to legacy `ultrathink` behavior.

## Auto-routing prompt

<system-reminder source="auto-intent-router">
Before responding, classify this prompt using parallel signal evaluation:

```mermaid
flowchart TD
    MSG[User Message] --> BYPASS{"Bypass?<br/>'just answer' / 'skip workflow'"}
    BYPASS -->|yes| SKIP[SKIP: respect bypass]

    MSG --> EVAL{Detect all signals}
    EVAL --> S1["UNDERSTAND<br/>explain, how does, why,<br/>analyze, research, explore"]
    EVAL --> S2["IMPLEMENT<br/>build, fix, add, create,<br/>refactor, update, write"]
    EVAL --> S3["FILE_EDIT<br/>any code/doc file will be<br/>created / modified / deleted"]
    EVAL --> S4["SHELL_ONLY<br/>run tests, git status,<br/>check logs, show disk"]
    EVAL --> S5["QUESTION<br/>what is, how do I,<br/>explain, compare"]

    EVAL --> RESOLVE{Resolve by priority}
    RESOLVE -->|"UNDERSTAND + IMPLEMENT"| HYBRID[HYBRID → dev-orchestrator]
    RESOLVE -->|"SHELL_ONLY + IMPLEMENT"| HYBRID
    RESOLVE -->|"FILE_EDIT or IMPLEMENT alone"| DEV[DEV → dev-orchestrator]
    RESOLVE -->|"UNDERSTAND alone"| INVESTIGATE[INVESTIGATE → dev-orchestrator]
    RESOLVE -->|"SHELL_ONLY alone"| OPS[OPS: execute directly]
    RESOLVE -->|"QUESTION alone"| QA[Q&A: answer directly]
```

Resolution rules — detect all signals, then apply the FIRST matching rule:
1. BYPASS → SKIP
2. UNDERSTAND + IMPLEMENT both present → **HYBRID** (even if FILE_EDIT also present)
3. SHELL_ONLY + IMPLEMENT both present → **HYBRID** (run command then fix)
4. FILE_EDIT or IMPLEMENT present (no UNDERSTAND) → **DEV**
5. UNDERSTAND present (no IMPLEMENT) → **INVESTIGATE**
6. SHELL_ONLY present (no FILE_EDIT) → **OPS**
7. QUESTION present (no FILE_EDIT) → **Q&A**
8. Ambiguous → **DEV** (safe default)

Calibration examples (use these to resolve edge cases):
  "run tests and fix failures" = HYBRID (SHELL_ONLY + IMPLEMENT → both phases)
  "investigate X then fix Y" = HYBRID
  "what does this error mean and how do I fix it" = HYBRID (UNDERSTAND + IMPLEMENT)
  "change the default model" = DEV. "update README" = DEV. "fix a typo" = DEV.
  "review this PR" = DEV. "make sure it works" = DEV. "write docs" = DEV.
  "run tests" = OPS. "git status" = OPS.
  "what is OAuth?" = Q&A. "how does X work?" = Q&A (no fix requested).
  "what's broken?" = INVESTIGATE. "why is CI failing?" = INVESTIGATE.
  "research rate limiting then implement it" = HYBRID.
  "analyze deps and remove circular imports" = HYBRID (UNDERSTAND + IMPLEMENT).

Actions:
  DEV → Say "[auto-routed] DEV → launching dev-orchestrator" then Invoke Skill(skill="dev-orchestrator"). Do not answer inline.
  INVESTIGATE → Say "[auto-routed] INVESTIGATE → launching dev-orchestrator" then Invoke Skill(skill="dev-orchestrator"). Do not answer inline.
  HYBRID → Say "[auto-routed] HYBRID → launching dev-orchestrator" then Invoke Skill(skill="dev-orchestrator"). Do not answer inline.
  Q&A → Answer directly. No workflow needed.
  OPS → Execute directly. No workflow needed.
  SKIP → Respect the bypass.

When in doubt, choose DEV. False positive costs minutes. False negative costs quality.
</system-reminder>

## Execution Instructions

**YOUR NEXT ACTION after reading this skill MUST include a Bash tool call that
executes `amplihack recipe run smart-orchestrator`.** If your runtime requires
a `report_intent` call (e.g. Copilot CLI), emit it **in parallel** with the
Bash launch — both tool calls in the same response. The constraint is that no
_other_ substantive action (reading files, calling TodoWrite, invoking Agent,
or typing a response) may precede or replace the Bash launch.

If you find yourself doing anything else instead of launching the recipe
runner, you are bypassing the workflow. Stop. Go back. Run the recipe runner.

Development and Investigation tasks have exactly ONE execution path: the
recipe runner. There is no "Option B." There is no "I'll follow the steps
manually." There is no "Let me just quickly..." The recipe runner IS the
workflow. Skipping it means skipping the 23-step process, the recursion
guards, the goal verification, and the quality gates that exist for a reason.

A PostToolUse hook monitors every tool call after this skill activates. If
it detects 3 tool calls without recipe runner evidence, it will fire a hard
WARNING. Do not wait for the warning — run the recipe runner immediately.

When this skill is activated:

### REQUIRED: Execute via Recipe Runner — IMMEDIATELY

Your next tool call(s) must include the recipe runner launch (alongside
`report_intent` if your runtime requires it).

#### Default: Direct Execution

The recipe runner is a plain subprocess — it does **not** require tmux.
Run it via the `amplihack` CLI:

```bash
cd /path/to/repo && amplihack recipe run smart-orchestrator \
  -c task_description="TASK_DESCRIPTION_HERE" \
  -c repo_path=.
```

**Key points:**

- `amplihack recipe run` — native Rust CLI command, no external runtime required
- `-c key=value` — passes context variables to the recipe
- The recipe runner manages its own child processes (agent sessions, bash steps) as direct subprocesses
- Streams recipe-runner stderr live so you see nested step activity

This is the preferred execution mode for most scenarios. It is simpler, has
no external dependencies beyond the Rust binary, works on all
platforms, and makes output capture straightforward.

#### Durable Execution (tmux) — optional

Use tmux **only** when:

- The agent runtime may kill background processes after a timeout (e.g., some
  Claude Code hosted environments)
- You need to survive SSH disconnects or terminal closures
- You want to detach and monitor a long-running recipe interactively

```bash
tmux new-session -d -s recipe-runner \
  "cd /path/to/repo && amplihack recipe run smart-orchestrator \
     -c task_description='TASK_DESCRIPTION_HERE' \
     -c repo_path=. 2>&1 | tee recipe-runner.log"
echo "Recipe runner log: recipe-runner.log"
```

- `tmux new-session -d` — detached session, no timeout, survives disconnects
- Monitor with: `tail -f recipe-runner.log` or `tmux attach -t recipe-runner`

**Restarting a stale tmux session**: Some runtimes (e.g. Copilot CLI) block
`tmux kill-session` because it does not target a numeric PID. Use one of these
shell-policy-safe alternatives instead:

```bash
# Option A (preferred): use a unique session name per run to avoid collisions
tmux new-session -d -s "recipe-$(date +%s)" "..."

# Option B: locate the tmux server PID and terminate with numeric kill
tmux list-sessions -F '#{pid}' 2>/dev/null | xargs -I{} kill {}

# Option C: let tmux itself handle it — send exit to all panes
tmux send-keys -t recipe-runner "exit" Enter 2>/dev/null; sleep 1
```

If using Option A, update the `tail -f` / `tmux attach` commands to use the
same session name.

**The recipe runner is the required execution path for Development and
Investigation tasks.** Always try `smart-orchestrator` first.

**Required environment variables** for the recipe runner:

- `AMPLIHACK_HOME` — Auto-detected from the current working directory by
  walking parent directories for an `amplifier-bundle/` folder, with fallback
  to `~/.amplihack`. If auto-detection fails, set manually to the directory
  containing `amplifier-bundle/`. The recipe runner uses this to find
  orchestrator assets and recipe definitions.
- Preserve `AMPLIHACK_AGENT_BINARY` — nested workflow agents read this env var
  to stay on the caller's active binary (for example, Copilot in Copilot CLI).

- Unset `CLAUDECODE` — required so nested Claude Code sessions can launch.

**Direct recipe invocation when smart-orchestrator fails.**

Always try `smart-orchestrator` first — it handles classification, decomposition,
and routing automatically. However, if `smart-orchestrator` fails at the
**infrastructure level** (e.g., 0 workstreams from decomposition, missing env
vars, Rust binary version mismatch), you MAY invoke the specific workflow
recipe directly based on your classification:

| Classification | Direct Recipe            | When to Use                             |
| -------------- | ------------------------ | --------------------------------------- |
| Investigation  | `investigation-workflow` | smart-orchestrator decomposition failed |
| Development    | `default-workflow`       | smart-orchestrator decomposition failed |
| Q&A (complex)  | `qa-workflow`            | Q&A needing multi-step research         |
| Consensus      | `consensus-workflow`     | Critical decisions needing validation   |

Example:

```bash
amplihack recipe run investigation-workflow \
  -c task_description="TASK_DESCRIPTION_HERE" \
  -c repo_path=.
```

This is NOT a license to bypass `smart-orchestrator`. Only use direct
invocation after `smart-orchestrator` has failed at an infrastructure level
(not because the task seems "too simple" or "too specific").

**Handling hollow success** (recipe completes but agents produce no findings):

If a recipe returns SUCCESS but the agent outputs indicate the agents could
not access the codebase or produced empty/generic results (e.g., "no codebase
exists", "cannot proceed without a target"), this is a **hollow success**.
In this case:

1. Check that `repo_path` and `AMPLIHACK_HOME` are correct
2. Verify the working directory is the repo root
3. Retry with explicit file paths in the `task_description`
4. If retries also produce hollow results, report the infrastructure
   failure to the user with specifics

**Common rationalizations that are NOT acceptable:**

- "Let me first understand the codebase" — the recipe does that in Step 0
- "I'll follow the workflow steps manually" — NO, the recipe enforces them
- "The recipe runner might not work" — try it first, report errors if it fails
- "This is a simple task" — simple or complex, the recipe runner handles both
- "The recipe succeeded but didn't do anything useful, so I'll do it myself"
  — this is hollow success; retry with better context first

**Q&A and Operations only** may bypass the recipe runner:

- Q&A: Respond directly (analyzer agent)
- Operations: Builder agent (direct execution, no workflow steps)

### Error Recovery: Adaptive Strategy (NOT Degradation)

When `smart-orchestrator` fails, **failures must be visible and surfaced** —
never swallowed or silently degraded. The recipe handles error recovery
automatically via its built-in adaptive strategy steps, but if you observe
a failure outside the recipe, follow this protocol:

**1. Surface the error with full context:**

Report the exact error, the step that failed, and the log output. Never say
"something went wrong" — always include the specific failure details.

**2. File a bug with reproduction details:**

For infrastructure failures (import errors, missing env vars, binary not found,
decomposition producing invalid output), file a GitHub issue:

```bash
gh issue create \
  --title "smart-orchestrator infrastructure failure: <one-line summary>" \
  --body "<full error context, reproduction command, env details>" \
  --label "bug"
```

**3. Evaluate alternative strategies:**

If `smart-orchestrator` fails at the infrastructure level (not because the task
is wrong), you MAY invoke the specific workflow recipe directly. This is an
**adaptive strategy** — it must be announced explicitly, not done silently:

| Classification | Direct Recipe            | When Permitted                                      |
| -------------- | ------------------------ | --------------------------------------------------- |
| Investigation  | `investigation-workflow` | smart-orchestrator failed at parse/decompose/launch |
| Development    | `default-workflow`       | smart-orchestrator failed at parse/decompose/launch |

Example:

```bash
# ANNOUNCE the strategy change first — never do this silently
echo "[ADAPTIVE] smart-orchestrator failed at parse-decomposition: <error>"
echo "[ADAPTIVE] Switching to direct investigation-workflow invocation"
amplihack recipe run investigation-workflow \
  -c task_description="TASK_DESCRIPTION_HERE" \
  -c repo_path=.
```

**This is NOT a license to bypass smart-orchestrator.** Always try it first.
Direct invocation is only permitted when smart-orchestrator fails at the
infrastructure level. "The task seems simple" is NOT an infrastructure failure.

**4. Detect hollow success:**

A recipe can complete structurally (all steps exit 0) but produce empty or
meaningless results — agents reporting "no codebase found" or reflection
marking ACHIEVED when no work was done. After execution, check that:

- Round results contain actual findings or code changes (not "I could not access...")
- PR URLs or concrete outputs are present for Development tasks
- At least one success criterion was verifiably evaluated

If results are hollow, report this to the user with the specific empty outputs.
Do not declare success when agents produced no meaningful work.

### Required Environment Variables

The recipe runner requires these environment variables to function:

| Variable                   | Purpose                                           | Default         |
| -------------------------- | ------------------------------------------------- | --------------- |
| `AMPLIHACK_HOME`           | Root of amplihack installation (for asset lookup) | Auto-detected   |
| `AMPLIHACK_AGENT_BINARY`   | Which agent binary to use (claude, copilot, etc.) | Set by launcher |
| `AMPLIHACK_MAX_DEPTH`      | Max recursion depth for nested sessions           | `3`             |
| `AMPLIHACK_NONINTERACTIVE` | Set to `1` to skip interactive prompts            | Unset           |

If `AMPLIHACK_HOME` is not set and auto-detection fails, `parse-decomposition`
and `activate-workflow` will fail. Set it to
the directory containing `amplifier-bundle/`.

### After Execution: Reflect and verify

After execution completes, verify the goal was achieved. If not:

- For missing information: ask the user
- For fixable gaps: re-invoke with the remaining work description
- For infrastructure failures: file a bug and try adaptive strategy

### Enforcement: PostToolUse Workflow Guard

A PostToolUse hook (in `amplihack-hooks`) actively monitors every
tool call after this skill is invoked. It tracks:

- Whether `/dev` or `dev-orchestrator` was called (sets a flag)
- Whether the recipe runner was actually executed (clears the flag)
- How many tool calls have passed without workflow evidence

If 3+ tool calls pass without evidence of recipe runner execution, the hook
emits a hard WARNING. This is not a suggestion — it means you are violating
the mandatory workflow. State is stored in `/tmp/amplihack-workflow-state/`.

## User Preferences

# User Preferences

**MANDATORY**: These preferences MUST be followed by all agents. Priority #2 (only explicit user requirements override).

## Autonomy

Work autonomously. Follow workflows without asking permission between steps. Only ask when truly blocked on critical missing information.

## Core Preferences

| Setting             | Value                      |
| ------------------- | -------------------------- |
| Verbosity           | balanced                   |
| Communication Style | (not set)                  |
| Update Frequency    | regular                    |
| Priority Type       | balanced                   |
| Collaboration Style | autonomous and independent |
| Auto Update         | ask                        |
| Neo4j Auto-Shutdown | ask                        |
| Preferred Languages | (not set)                  |
| Coding Standards    | (not set)                  |

## Workflow Configuration

**Selected**: DEFAULT_WORKFLOW (`@~/.amplihack/.claude/workflows/DEFAULT_WORKFLOW.md`)
**Consensus Depth**: balanced

Use CONSENSUS_WORKFLOW for: ambiguous requirements, architectural changes, critical/security code, public APIs.

## Behavioral Rules

- **No sycophancy**: Be direct, challenge wrong ideas, point out flaws. Never use "Great idea!", "Excellent point!", etc. See `@~/.amplihack/.claude/context/TRUST.md`.
- **Quality over speed**: Always prefer complete, high-quality work over fast delivery.

## Learned Patterns

<!-- User feedback and learned behaviors are added here by /amplihack:customize learn -->

## Managing Preferences

Use `/amplihack:customize` to view or modify (`set`, `show`, `reset`, `learn`).

<!-- AMPLIHACK_CONTEXT_END -->