# Extension Migration Prompt (AEOS-Aware)

Paste the section below this marker into a separate Claude Code session to drive the ADR-031 extension-self-containment migration against the AEOS standard.

---

**Context: Axiom Portfolio — Extension Self-Containment Migration under AEOS 0.1**

You are working in the Axiom repository at `/Users/ben/Projects/UT_Computational_NE/axiom/`. Read these before starting:
- `CLAUDE.md` (repo context, naming conventions, AEOS reference)
- `docs/specs/spec-aeos-0.1.md` (the full Agent Extension Open Standard)
- `docs/adrs/adr-031-extension-self-containment.md` (the migration ADR)
- `docs/adrs/adr-032-standards-positioning-dual-track.md` (standards strategy — do NOT advertise AEOS externally)
- `docs/working/aeos-playbook.md` (operational guide)
- `docs/working/brand-product-strategy.md` (portfolio context)

## Governing Decisions (Locked In)

- **Naming:** extensions are purpose-named (no type suffix). Products in normal case; agents in ALL-CAPS-HYPHEN.
- **Layout:** compound by default per AEOS §5 — every extension has typed subdirectories (`agents/`, `tools/`, `commands/`, `services/`, `adapters/`, `skills/`, `hooks/`) populated only where it provides capabilities.
- **Manifest:** every extension has `axiom-extension.toml` per AEOS §6, with capabilities declared via `[[extension.provides]]` blocks, and matching entry points in `pyproject.toml`.
- **Public API:** every extension's `__init__.py` declares `__all__`. Import-linter enforces "public-API-only" cross-extension imports.
- **Testing:** every extension has `tests/unit_tests/test_standard.py` inheriting from `axiom_tests` base classes (the `axiom-tests` package provides these via `pytest11` entry point). Note: the `axiom-tests` package itself may not exist yet — if not, skeleton-inherit from a stub class and create the package during migration of the first extension.
- **Docs:** extension docs live inside the extension at `<ext>/docs/{prds,specs,decisions,working}/`. Axiom core `docs/` contains only core-platform content.
- **Signing:** Sigstore keyless signing required for all publishes (not blocking for this migration work if CI/CD is still being set up separately).

## Goal of This Migration

Migrate all existing extensions in `axiom/src/axiom/extensions/builtins/` to the AEOS canonical layout. Each migration happens as a single, reviewable PR. Git history is preserved via `git mv`. Docs and tests relocate into per-extension subdirectories. Legacy `_agent` suffixes are dropped in favor of purpose-names.

## Migration Order (Least Risky First)

Each PR is standalone — don't batch multiple extensions. Finish one, merge, then start the next.

1. **`dfib_agent/` → `triage/`** (smallest, most self-contained)
2. **`connect/`** (stays `connect/` — already purpose-named; just needs layout migration)
3. **`memory_cmd/` → `memory/`** (drop `_cmd` suffix)
4. **`mo_agent/` → `tidy/`**
5. **`prt_agent/` → `press/`**
6. **`eve_agent/` → `scan/`** (larger; more interconnected)
7. **`neut_agent/` → `neut/`** (in `Neutron_OS/` repo, not axiom/)
8. **`classroom/`** (stays `classroom/` pre-extraction; becomes `keplo` post-extraction. Coordinate with Keplo extraction planning.)

## Per-Extension Migration Checklist

For each extension PR:

### Phase 1: Preparation (before any git mv)

1. Read the current extension's code, tests, and any docs scattered in `axiom/docs/prds/`, `axiom/docs/specs/` referring to it
2. Identify all capability kinds provided (agent, tool, cmd, service, adapter, skill, hook) — most will be one or two
3. Identify cross-extension imports that exist today; note which need to migrate to public-API-only
4. Check if the extension has its own `pyproject.toml` already. If not, plan to create one.
5. Generate the target folder structure on paper: what subdirectories (`agents/`, `tools/`, etc.) will be populated?

### Phase 2: Layout migration (git mv operations)

6. Rename directory (e.g., `git mv src/axiom/extensions/builtins/dfib_agent src/axiom/extensions/builtins/triage`) only if the name changes
7. Inside the extension, create typed subdirectories as needed:
   ```
   mkdir -p <ext>/docs/{prds,specs,decisions,working}
   mkdir -p <ext>/tests/{unit_tests,integration_tests,fixtures}
   ```
8. `git mv` relevant docs from `axiom/docs/prds/prd-<ext>.md` → `<ext>/docs/prds/prd.md`
9. `git mv` relevant specs from `axiom/docs/specs/spec-<ext>.md` → `<ext>/docs/specs/spec.md`
10. `git mv` extension-specific tests from `axiom/tests/` → `<ext>/tests/unit_tests/` or `integration_tests/`
11. If the extension has source already in typed layout (e.g., `<ext>/agents/`), great; otherwise, reorganize source into the canonical subdirectory structure
12. Update all imports within the extension to reflect new paths (keep them internal; public API via `__init__.py`)

### Phase 3: Manifest and metadata

13. Create `<ext>/axiom-extension.toml` per AEOS §6 schema:
    - `[extension]` block with name (= directory name), version, description, license, aeos_version, owner, classification_ceiling, trust_profile
    - `[[extension.provides]]` blocks for each capability kind detected
    - `[[extension.consumes]]` blocks declaring dependencies on axiom-core and other extensions
    - `[extension.federation]`, `[extension.signing]`, `[extension.testing]` sections as appropriate
14. Create or update `<ext>/pyproject.toml` with matching entry points:
    ```toml
    [project.entry-points."axiom.agents"]
    my-agent = "my_ext.agents.my_agent:MyAgent"
    # ... one block per kind with registered capabilities
    ```
15. Create `<ext>/__init__.py` with `__all__` enumerating public symbols
16. Create `<ext>/README.md` from template (name, description, capabilities, usage, link to docs)
17. Create `<ext>/CHANGELOG.md` in Keep-a-Changelog format with 0.1.0 entry documenting the migration
18. Ensure `<ext>/LICENSE` exists (inherit from repo or set if different)

### Phase 4: Tests and verification

19. Create `<ext>/tests/unit_tests/test_standard.py` inheriting from `axiom_tests` base classes. If `axiom_tests` package doesn't exist yet, this migration is an opportunity to create it — but only during the FIRST migration (e.g., `triage/`). Subsequent migrations consume the existing package.
20. Move or create relevant integration tests in `<ext>/tests/integration_tests/`
21. Run the extension's tests: `pytest src/axiom/extensions/builtins/<ext>/tests/ -v`
22. Run `axi ext lint src/axiom/extensions/builtins/<ext>/` if the command exists; otherwise manually verify AEOS conformance against spec §6 schema

### Phase 5: Import cleanup

23. Update any code OUTSIDE the extension that imports from it — use only the public API (symbols in `__all__`)
24. If any code was reaching into private modules, promote those symbols to public API or refactor to not need them
25. Run the full Axiom test suite to catch downstream breakage: `pytest tests/ src/axiom/extensions/ -v --tb=short`

### Phase 6: Documentation and commit

26. Update any cross-references in other docs that referenced old paths
27. Add migration note to extension's `CHANGELOG.md`
28. Commit with message:
    ```
    refactor(<ext>): migrate to AEOS-conformant layout per ADR-031
    
    - Rename <old> → <new> (purpose-named, no type suffix)
    - Move docs from axiom/docs/ to <ext>/docs/
    - Move tests to <ext>/tests/
    - Add axiom-extension.toml manifest
    - Add __all__ in __init__.py for public API
    - Add README and CHANGELOG
    - Create standard test inheriting from axiom_tests
    
    Tests: full suite passing
    AEOS conformance: Bronze level achieved
    
    Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
    ```
29. Open PR with title `refactor(<ext>): AEOS migration` and body linking to ADR-031 and spec-aeos-0.1.md

## Ask Before Starting

Before beginning any extension migration PR, ask the user:

1. Which extension should you migrate first? (Default: `triage/` per order above)
2. Does `axiom-tests` package exist yet, or should this migration create it?
3. Are there any extension-specific constraints (e.g., active Prague-deployment dependencies) that affect how aggressive the rename can be?
4. Should the PR be branched from `main` or another working branch?

Do NOT:
- Skip phases
- Batch multiple extensions in one PR
- Reorganize internal code structure beyond what AEOS requires (scope creep kills migration PRs)
- Advertise AEOS publicly anywhere (per ADR-032, AEOS is internal until strategic decision)
- Introduce Sigstore signing in this migration — handled separately via CI/CD work

## Expected Outcome Per PR

- One extension migrated to AEOS-conformant layout
- All tests passing
- Docs co-located with code
- Manifest declares capabilities
- Public API surface clearly defined
- CHANGELOG entry documenting the migration
- PR merged, next extension started

Estimated time per PR: 2-6 hours depending on extension size. `scan/` and `classroom/` are largest (likely closer to 6).
