ArchiPy Plugin

Rules, skills, and slash commands for application teams that build with ArchiPy. Works with both Cursor and Claude Code.

What this is

This plugin helps AI agents follow ArchiPy clean-architecture patterns when working in your service repos: layer boundaries, adapters, helpers (utils / decorators / interceptors), configuration, and DI.

It ships:

Rules — persistent guidance while editing matching files
Skills — agent workflows for scaffolding and docs lookup
Commands — slash entry points (/scaffold-app, /docs-helpers, …)

It is not for maintaining the ArchiPy library itself (no graphify, library changelog, or core BDD internals).

Requirements

Cursor with plugin support, or Claude Code with plugin support
Apps targeting Python 3.14+
uv package manager
PyPI package archipy (install the extras your service needs)

Install

Cursor — Local (development / personal)

# From a clone of this repo:
mkdir -p ~/.cursor/plugins/local
ln -sfn "$(pwd)" ~/.cursor/plugins/local/archipy

Then run Developer: Reload Window in Cursor (or restart Cursor).

Verify under Customize that the archipy plugin loaded (rules, skills, commands).

Cursor — Team marketplace (Teams / Enterprise)

Open Dashboard → Plugins → Team Marketplaces
Import from Repo and point at https://github.com/SyntaxArc/archipy-plugin
Set access and install mode (Default Off / Default On / Required)

Cursor — Cursor Marketplace

After this plugin is listed, open Customize or cursor.com/marketplace
Search for archipy and install
Optionally scope install to the current workspace

Claude Code — Local (development / personal)

# From a clone of this repo:
mkdir -p ~/.claude/plugins/local
ln -sfn "$(pwd)" ~/.claude/plugins/local/archipy

Then restart Claude Code or run /reload-plugins.

Claude Code — Marketplace

/plugin marketplace add SyntaxArc/archipy-plugin
/plugin install archipy@archipy

What’s included

Rules (11)

Rule file	Applies when
`architecture-for-apps.mdc`	Always
`using-archipy-adapters.mdc`	`/repositories//adapters/*/.py`
`using-archipy-utils.mdc`	`/helpers/utils//*.py`
`using-archipy-decorators.mdc`	`/helpers/decorators//*.py`
`using-archipy-interceptors.mdc`	`/helpers/interceptors//*.py`
`config-and-di.mdc`	`/configs//*.py`
`using-archipy-models.mdc`	`/models/{entities,errors,types,dtos}//*.py`
`using-archipy-repositories.mdc`	`/repositories//*.py`
`using-archipy-logics.mdc`	`/logics//*.py`
`using-archipy-services.mdc`	`/services//.py`, `*/manage.py`
`testing-bdd-for-apps.mdc`	`/features//*`

Skills (12)

Skill	When to use
`scaffold-archipy-app`	Bootstrap a new ArchiPy-based service layout
`scaffold-archipy-domain`	Full domain slice (models, repo, logic, service)
`scaffold-archipy-adapter`	Add domain adapter under `repositories/{domain}/adapters/`
`scaffold-archipy-logic`	Use-case under `logics/{domain}/` with `*_sqlalchemy_atomic_decorator`
`scaffold-archipy-service`	Thin FastAPI/gRPC service under `services/{domain}/v{n}/`
`scaffold-archipy-bdd`	Behave `features/` stub
`scaffold-archipy-utils`	Wire or create `helpers/utils`
`scaffold-archipy-decorator`	Wire or create `helpers/decorators`
`scaffold-archipy-interceptor`	Wire or create `helpers/interceptors`
`scaffold-archipy-health-checks`	Scaffold FastAPI/gRPC health checks and optional K8s probe YAML
`redis-search`	RediSearch full-text, vector search, and search-cache adapters
`archipy-docs`	Answer “how do I… with ArchiPy?” using bundled `reference.md` + live docs

Commands (19)

Command	Action
`/scaffold-app`	Run scaffold-archipy-app
`/scaffold-domain`	Run scaffold-archipy-domain
`/scaffold-adapter`	Run scaffold-archipy-adapter
`/scaffold-logic`	Run scaffold-archipy-logic
`/scaffold-service`	Run scaffold-archipy-service
`/scaffold-bdd`	Run scaffold-archipy-bdd
`/scaffold-utils`	Run scaffold-archipy-utils
`/scaffold-decorator`	Run scaffold-archipy-decorator
`/scaffold-interceptor`	Run scaffold-archipy-interceptor
`/scaffold-health-checks`	Scaffold FastAPI/gRPC health + K8s probe YAML
`/redis-search`	Scaffold Redis full-text / vector / search-cache
`/docs-quickstart`	Quickstart + bundled reference
`/docs-adapters`	Adapter patterns + docs links
`/docs-helpers`	Utils / decorators / interceptors
`/docs-config`	BaseConfig + DI docs
`/docs-errors`	Error handling docs
`/docs-testing`	BDD testing docs
`/docs-observability`	Observability docs
`/docs-health-checks`	HTTP/gRPC health checks (liveness/readiness/startup)

There is no /scaffold-helper — use the three helper-specific commands.

Quick start

Install the plugin locally (symlink above) and reload Cursor.
Open an application workspace (empty or existing Python service).
In Agent chat, run /scaffold-app — answer package name and extras (e.g. redis).
Run /docs-quickstart to confirm config + first adapter steps.
Expect: AppConfig, models stub, repositories/<domain>/, optional manage.py (if fastapi), helpers tree, .env.example.

Commands deep dive

`/scaffold-app`

Purpose: Create a minimal ArchiPy app package tree.
Asks: Package name, extras, optional first domain.
Outcome: configs/app_config.py, models stub, repositories/<domain>/, optional helpers, manage.py when FastAPI, .env.example.

`/scaffold-domain`

Purpose: Full domain slice composing models + adapter + logic + service.
Asks: Domain, extras, transport.
Outcome: DTOs/errors, repository adapters, one logic, one service v1, DI notes.

`/scaffold-adapter`

Purpose: Add a domain adapter under the domain repository.
Asks: Domain, purpose, sync/async, mocks yes/no, wrap ArchiPy vs new client.
Outcome: repositories/<domain>/adapters/<domain>_<purpose>_adapter.py (+ repository stub if missing).

`/scaffold-logic`

Purpose: Use-case class with unit-of-work decorator.
Asks: Domain, logic name, sync/async atomic.
Outcome: logics/<domain>/<name>_logic.py.

`/scaffold-service`

Purpose: Thin FastAPI router or gRPC servicer.
Asks: Domain, version, FastAPI vs gRPC.
Outcome: services/<domain>/v{n}/<domain>_service.py + AppUtils bootstrap notes.

`/scaffold-bdd`

Purpose: Behave feature layout with ScenarioContext isolation.
Asks: Feature name; mocks vs @needs-* infra.
Outcome: scenario_context.py, pool manager, test_helpers.py, environment.py, feature/steps; infra adds slim test_containers.py + .env.test.

`/scaffold-utils`

Purpose: Prefer ArchiPy utils; otherwise scaffold a pure util.
Asks: Purpose; built-in vs custom.
Outcome: Usage snippet or helpers/utils/<name>_utils.py.

`/scaffold-decorator`

Purpose: Prefer ArchiPy decorators (ttl_cache_decorator, postgres_sqlalchemy_atomic_decorator, capture_span / capture_transaction, …).
Asks: Purpose; sync/async; built-in vs custom.
Outcome: Usage snippet or helpers/decorators/<name>.py with example.

`/scaffold-interceptor`

Purpose: Prefer ArchiPy FastAPI/gRPC interceptors; custom stays cross-cutting.
Asks: Framework; sync/async; built-in vs custom.
Outcome: Interceptor module + wiring notes (DI / framework).

`/scaffold-health-checks`

Purpose: Create app-level liveness/readiness health for FastAPI and/or gRPC.
Asks: Package name, transport (FastAPI / gRPC / both), readiness dependencies, optional heartbeat liveness, optional K8s probe YAML.
Outcome: Shared check helpers + health_service.py and/or health_grpc_service.py (grpc.health.v1) + optional deploy/k8s-probes.yaml (httpGet / grpc).

`/redis-search`

Purpose: Add Redis full-text (RediSearch), vector, or search-cache adapters under a domain repository.
Asks: Search type, domain, data structure, sync/async, patterns.
Outcome: repositories/<domain>/adapters/<domain>_*_adapter.py (+ repository stub) wired via DI.

`/docs-quickstart` / `/docs-adapters` / `/docs-helpers` / `/docs-config` / `/docs-errors` / `/docs-testing` /

/docs-observability / /docs-health-checks

Purpose: Orient the agent on the matching topic using skills/archipy-docs/reference.md first, then live docs URLs.
Outcome: Short guidance + links; may suggest a /scaffold-* follow-up.

Rules deep dive

`architecture-for-apps`

Always-on layer map, call flow (services → logics → repositories → adapters), and one-way imports.

Do: Keep models free of I/O; UoW on logics; cross-domain via logics only.
Don’t: Import repositories/adapters from models/; invent a top-level app adapters/ package.

`using-archipy-adapters`

Prefer ArchiPy extras and thin domain wrappers under repositories/{domain}/adapters/.

Do: Map specific driver errors to domain errors with raise ... from e.
Don’t: Mix sync and async in one class; leak raw driver exceptions.

`using-archipy-utils`

Pure utilities; prefer ArchiPy utils. AppUtils for FastAPI/gRPC factories.

Do: Use create_fastapi_app / create_grpc_app / create_async_grpc_app; drive uvicorn from config.FASTAPI.
Don’t: Hand-roll bare FastAPI() / grpc.server(); open DB/Redis clients in utils.

`using-archipy-decorators`

Prefer ArchiPy decorators; UoW decorators belong on logics.

Do: Preserve wrapped signatures (functools.wraps); use postgres_sqlalchemy_atomic_decorator on logics.
Don’t: Construct adapters inside decorator modules.

`using-archipy-interceptors`

Cross-cutting hooks only; prefer AppUtils auto-registration for stock interceptors.

Do: Keep interceptors free of use-case writes.
Don’t: Register interceptors by importing them from adapters at module level.

`config-and-di`

BaseConfig, FastAPIConfig, customize(), DI wire order ports → adapters → repositories → logics → services.

Do: Call BaseConfig.set_global once; set FastAPI/uvicorn defaults via config.FASTAPI.
Don’t: Commit secrets or scatter os.environ outside config.

`using-archipy-models`

DTOs/entities/errors layout and naming (*InputDTO / *CommandDTO / …).

Do: Version domain DTOs under domain/v{n}/; subclass ArchiPy errors.
Don’t: Put I/O or business rules in models.

`using-archipy-repositories`

Domain data access; adapters under repositories/{domain}/adapters/.

Do: Orchestrate in {domain}_repository.py; map to repository DTOs; isolate domains.
Don’t: Call another domain’s repository; put atomic / UoW decorators here.

`using-archipy-logics`

Business rules + unit of work; domain isolation.

Do: Domain DTO in/out; *_sqlalchemy_atomic_decorator on public methods; call other logics for cross-domain.
Don’t: Import another domain’s repository; import FastAPI/gRPC.

`using-archipy-services`

Thin transport; AppUtils bootstrap; uvicorn from FastAPIConfig.

Do: Map errors to HTTP/gRPC status; version routers under v{n}/.
Don’t: Put atomic / UoW decorators or business rules in services; hardcode host/port.

`testing-bdd-for-apps`

Behave + ScenarioContext; inject ports/mocks; @needs-* infra tags.

Do: Isolate scenarios; swap mocks via DI/context.
Don’t: Share mutable globals across scenarios; use pytest as the primary style.

Project layout

archipy-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Claude Code plugin manifest
│   └── marketplace.json     # Claude Code marketplace catalog
├── .cursor-plugin/
│   ├── plugin.json          # Cursor plugin manifest
│   └── marketplace.json     # Cursor marketplace catalog
├── hooks/                   # Plugin hooks (hooks.json)
├── scripts/                 # Catalog checks + hook scripts
├── rules/                   # .mdc rules
├── skills/                  # SKILL.md directories (+ docs reference)
├── commands/                # Slash commands
├── assets/logo.jpg
├── AGENTS.md
├── CONTRIBUTING.md
├── README.md
├── LICENSE
└── CHANGELOG.md

Both Cursor and Claude Code discover rules/, skills/, commands/, and hooks/ automatically when the manifest does not override paths.

ArchiPy docs map

Plugin entry	Live documentation
`/docs-quickstart`, `scaffold-archipy-app`	Quickstart, Project structure
`/docs-adapters`, `scaffold-archipy-adapter`	Adapters, API adapters
`/redis-search`	Adapters + bundled Redis search skill stubs
`/docs-helpers`, helper scaffolds	Helpers, Observability
`/docs-config`	Config, DI
`/docs-errors`	Error handling
`/docs-testing`, `scaffold-archipy-bdd`	Testing strategy
`/docs-observability`	Observability
`/docs-health-checks`, health scaffold	Bundled `reference.md` Health checks + `/scaffold-health-checks`
`archipy-docs` / `reference.md`	Docs home, API reference

Developing / contributing

See CONTRIBUTING.md for the full checklist (version bump across four JSON files, catalog sync, CI).

Clone this repo and symlink it to ~/.cursor/plugins/local/archipy (Cursor) or ~/.claude/plugins/local/archipy (Claude Code).
Edit rules (.mdc frontmatter: description, alwaysApply / globs), skills (name + description matching folder name), or commands (name + description).
Reload the editor window after changes.
Keep consumer focus: apps using PyPI archipy, not ArchiPy monorepo maintainers.
Run python scripts/check_catalog.py before opening a PR.
Open a PR with a clear summary; update CHANGELOG.md for user-facing changes.
Bump version in both plugin.json and both marketplace.json files when publishing a release.

Marketplace / security

This repository is open source (MIT).
Ships no MCP servers and no plugin variables / secrets. Bundled hooks are hygiene-only (no network).
Cursor Marketplace submissions are manually reviewed; updates are re-reviewed.
Claude Code marketplace: /plugin marketplace add SyntaxArc/archipy-plugin
Do not add API tokens or credentials to the plugin tree.

Publish:

Cursor: cursor.com/marketplace/publish
Claude Code: /plugin marketplace add SyntaxArc/archipy-plugin

Changelog

See CHANGELOG.md.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.claude-plugin		.claude-plugin
.cursor-plugin		.cursor-plugin
.github		.github
assets		assets
commands		commands
hooks		hooks
rules		rules
scripts		scripts
skills		skills
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
lychee.toml		lychee.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ArchiPy Plugin

What this is

Requirements

Install

Cursor — Local (development / personal)

Cursor — Team marketplace (Teams / Enterprise)

Cursor — Cursor Marketplace

Claude Code — Local (development / personal)

Claude Code — Marketplace

What’s included

Rules (11)

Skills (12)

Commands (19)

Quick start

Commands deep dive

/scaffold-app

/scaffold-domain

/scaffold-adapter

/scaffold-logic

/scaffold-service

/scaffold-bdd

/scaffold-utils

/scaffold-decorator

/scaffold-interceptor

/scaffold-health-checks

/redis-search

/docs-quickstart / /docs-adapters / /docs-helpers / /docs-config / /docs-errors / /docs-testing /

Rules deep dive

architecture-for-apps

using-archipy-adapters

using-archipy-utils

using-archipy-decorators

using-archipy-interceptors

config-and-di

using-archipy-models

using-archipy-repositories

using-archipy-logics

using-archipy-services

testing-bdd-for-apps