Scaffold Adapter

---
name: scaffold-adapter
description: >-
  Scaffold a domain adapter under repositories/{domain}/adapters/ wrapping an ArchiPy
  adapter or external client. Use for "add Postgres/Redis/Kafka/S3/HTTP client",
  "integrate <service>", or "new adapter".
---

# Scaffold ArchiPy Adapter

## Read first

Read these plugin rules in full before generating files (paths relative to this skill directory; Claude Code: `${CLAUDE_SKILL_DIR}/../../rules/`):

- `../../rules/architecture-for-apps.mdc`
- `../../rules/using-archipy-adapters.mdc`
- `../../rules/using-archipy-repositories.mdc`

## Before writing files

1. Inspect `pyproject.toml`, the target domain, neighboring adapters, ports, DI wiring, and tests.
2. Infer installed extras, naming, sync/async style, and existing ArchiPy integration.
3. Ask only for unresolved choices:
   - Domain and adapter purpose
   - Sync or async when the repository does not establish one
   - New external client when ArchiPy has no matching adapter
4. Preserve existing adapters and contracts. Extend compatible code; do not overwrite.

## Prefer ArchiPy

If ArchiPy already ships the client (Redis, Postgres, Kafka, …), prefer:

```bash
uv add "archipy[<extra>]"
```

and a thin domain wrapper — not a full reimplementation.

## Generate

```text
repositories/<domain>/
├── adapters/
│   └── <domain>_<purpose>_adapter.py   # e.g. user_db_adapter.py
└── <domain>_repository.py              # create stub if missing
```

- Thin wrapper: wrap ArchiPy adapter (or external client); own entity construction / query building; map client errors →
  domain errors with `raise ... from e`.
- No in-memory mocks for BDD: scenarios run this adapter against its testcontainer (`@needs-*`). A port-conforming
  fake is allowed only for a third-party API that has no container.
- Ports: depend on ArchiPy ports when wrapping library adapters; add a local ABC only when the domain needs a custom
  contract.

## Do not

- Sync and async must be separate classes.
- No business logic in adapters — map data and talk to infrastructure only.
- Do **not** create a top-level `adapters/<name>/` package — domain adapters live under repositories.
- Wire via DI in `configs/containers.py`.
- Never leak raw driver exceptions; always map with `raise ... from e`.

## Verify

1. Run the repository's formatter and linter on generated Python.
2. Run the Behave scenarios that reach this adapter through the services layer (its `@needs-*` container, `/scaffold-bdd`);
   if Docker is unavailable, say so.
3. Confirm imports, port conformance, exception chaining, and DI wiring.
4. Run the `archipy-reviewer` subagent on the changes and fix every **Must fix** finding it reports.
5. Report files, dependency changes, and commands run.

## Docs

- https://syntaxarc.github.io/ArchiPy/getting-started/project_structure/
- https://syntaxarc.github.io/ArchiPy/tutorials/adapters/
- https://syntaxarc.github.io/ArchiPy/api_reference/adapters/