---
model_tier: medium
name: fix-portability
pack: engineering-base
tier: 2
cluster: fix
sub: portability
skills: [check-refs]
description: Find and fix project-specific references in shared .augment/ package files
suggestion:
  eligible: false
  rationale: "Package-internal — only the event4u/agent-config repo runs this."
workspaces:
  - agent-config-maintainer
packs:
  - meta
---

# /fix portability
## Instructions

### 1. Run the portability checker

```bash
python3 src/scripts/check_portability.py --format json
```

### 2. Parse findings

If output is `[]` or "No portability violations found":

```
✅  No portability violations found. Package is project-agnostic.
```

Stop here.

### 3. Display findings

```
═══════════════════════════════════════════════
  📦 PORTABILITY VIOLATION REPORT
═══════════════════════════════════════════════

  Found: {count} violation(s)
```

Group by severity:

```
  🔴 ERRORS (must fix):
    {file}:{line} — pattern: `{pattern}` — match: `{matched_text}`

  🟡 WARNINGS (should fix):
    {file}:{line} — pattern: `{pattern}` — match: `{matched_text}`
```

### 4. Classify and fix

For each violation:

| Pattern Type | Fix Strategy |
|---|---|
| Project name (e.g., "MyApp", "acme-corp") | Replace with generic placeholder: `{project}`, `{app}` |
| Project-specific URL/domain | Replace with `https://example.com` or `{domain}` |
| Database name | Replace with `{database}` |
| Project-specific env var | Replace with generic `APP_*` equivalent |
| Project-specific path | Replace with relative or generic path |
| Docker container name | Replace with `{container}` |

Present a summary:

```
  Proposed fixes:
  1. {file}:{line} — `{old}` → `{new}`
  2. {file}:{line} — `{old}` → `{new}`

> 1. Apply all fixes
> 2. Apply interactively
> 3. Skip — report only
```

### 5. Apply fixes

Edit files in `.agent-src.uncondensed/`, then run `bash src/scripts/condense.sh --sync` to regenerate `dist/agent-src/` and `.augment/`.

After all fixes, re-run:

```bash
python3 src/scripts/check_portability.py
```

### 6. Mark hashes

For each modified file:

```bash
python3 src/scripts/condense.py --mark-done "{relative_path}"
```

## Rules

- **Always fix in `.agent-src.uncondensed/`** — never edit `.augment/` directly.
- **Copy to `.augment/`** after fixing.
- **Do NOT commit or push.**
- **`agents/` directory is allowed** to have project-specific references — skip it.
- **Do NOT fix references in code blocks** unless the code block is clearly a template.
- **Run the checker again after fixing** to verify 0 remaining issues.
