Add README mapping skills to Heretek Swarm architecture

2026-07-01 19:54:03 -04:00 · 2026-06-02 12:07:02 -04:00
parent f23a235aa2
commit 3881b1c9ba
1 changed files with 114 additions and 0 deletions
@@ -0,0 +1,114 @@
+# Heretek Skills
+
+**AI coding agent skills for the [Heretek Swarm](https://github.com/Heretek-AI/heretek-swarm) project.**
+
+These skills provide structured guidance for AI assistants (Claude, GSD, Copilot, Cursor, etc.) working on the Heretek Swarm codebase. Each skill is a self-contained `SKILL.md` file that loads domain-specific conventions, architecture notes, file paths, and patterns so the agent can work accurately without guessing.
+
+---
+
+## The Swarm at a Glance
+
+[Heretek Swarm](https://github.com/Heretek-AI/heretek-swarm) is a self-governing collective of **23 specialized AI agents** built on Python 3.11+, FastAPI, React 19, and NATS JetStream. It runs 6 Docker containers (7 logical services) including PostgreSQL, Redis, Qdrant, NATS, an API server, a React dashboard, and an embedded Cognee memory engine.
+
+| Layer | Tech |
+|-------|------|
+| Backend | Python 3.11+, FastAPI, SQLAlchemy, asyncpg |
+| Frontend | React 19, TypeScript, Vite, Zustand, Tailwind CSS |
+| Messaging | NATS JetStream (mTLS) with A2A protocol |
+| Memory | Cognee (knowledge graph + vectors), PostgreSQL, Qdrant |
+| State | PostgreSQL (primary), Redis (cache), Qdrant (semantic) |
+| Observability | structlog, Prometheus, OpenTelemetry |
+| Infrastructure | Docker Compose, Alembic migrations |
+
+---
+
+## Skills
+
+| Skill | Use When |
+|-------|----------|
+| **[heretek-agent-development](skills/heretek-agent-development/SKILL.md)** | Creating agent actors, implementing behaviors, working with the actor/mixin architecture (23 agents, 10 mixins) |
+| **[heretek-api-development](skills/heretek-api-development/SKILL.md)** | Building FastAPI endpoints, adding routers, implementing auth middleware (27 routers, 175+ endpoints) |
+| **[heretek-backend-development](skills/heretek-backend-development/SKILL.md)** | General Python backend work — project structure, async patterns, codebase conventions (412 .py files, ~184K LOC) |
+| **[heretek-contributing](skills/heretek-contributing/SKILL.md)** | Preparing PRs, following commit conventions, running linters, understanding the review process |
+| **[heretek-debugging](skills/heretek-debugging/SKILL.md)** | Diagnosing failures, tracing issues through structured logs, profiling performance |
+| **[heretek-docker-operations](skills/heretek-docker-operations/SKILL.md)** | Docker Compose management, building images, volume persistence, container health checks |
+| **[heretek-frontend-development](skills/heretek-frontend-development/SKILL.md)** | React components, Zustand stores, Vite config, TypeScript patterns (93 components, 12 domains) |
+| **[heretek-memory-system](skills/heretek-memory-system/SKILL.md)** | Cognee-backed memory — knowledge graphs, vector search, access patterns, pre-fetching |
+| **[heretek-migration](skills/heretek-migration/SKILL.md)** | Alembic database migrations, code migrations, rollback procedures |
+| **[heretek-monitoring](skills/heretek-monitoring/SKILL.md)** | Structured logging (structlog), Prometheus metrics, OpenTelemetry tracing, health endpoints |
+| **[heretek-nats-messaging](skills/heretek-nats-messaging/SKILL.md)** | Inter-agent communication via NATS — pub/sub, JetStream persistence, queue groups, mTLS |
+| **[heretek-security](skills/heretek-security/SKILL.md)** | Zero-trust auth, JWT hardening, API key management, input validation, SOPS secrets |
+| **[heretek-state-management](skills/heretek-state-management/SKILL.md)** | PostgreSQL, Redis, and Qdrant operations — connections, caching, vector search patterns |
+| **[heretek-testing](skills/heretek-testing/SKILL.md)** | pytest + vitest patterns, test fixtures, mocking strategies, integration test setup |
+
+---
+
+## How Skills Work
+
+Each skill is a single `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: heretek-agent-development
+description: >-
+  Agent development for Heretek Swarm's 23-agent system.
+---
+```
+
+When an AI coding assistant loads a skill, it gains:
+- **File paths** — exact locations of relevant code, configs, and tests
+- **Conventions** — naming, patterns, and anti-patterns specific to this codebase
+- **Architecture notes** — how components connect, dependency chains, common pitfalls
+- **Code examples** — real patterns from the project, not generic templates
+
+### Installation
+
+Copy the `skills/` directory into your agent's skill path:
+
+```bash
+# For GSD / Claude
+cp -r skills/ ~/.gsd/agent/skills/
+
+# For project-local skills
+cp -r skills/ .claude/skills/
+```
+
+---
+
+## Project Structure
+
+```
+heretek-skills/
+├── README.md                           # This file
+├── LICENSE                             # MIT
+└── skills/
+    ├── heretek-agent-development/      # 23-agent actor system
+    ├── heretek-api-development/        # FastAPI routers & endpoints
+    ├── heretek-backend-development/    # Python backend patterns
+    ├── heretek-contributing/           # Contribution guidelines
+    ├── heretek-debugging/              # Troubleshooting patterns
+    ├── heretek-docker-operations/      # Docker Compose & containers
+    ├── heretek-frontend-development/   # React/TypeScript dashboard
+    ├── heretek-memory-system/          # Cognee memory engine
+    ├── heretek-migration/              # Alembic & code migrations
+    ├── heretek-monitoring/             # Observability stack
+    ├── heretek-nats-messaging/         # NATS JetStream messaging
+    ├── heretek-security/               # Zero-trust security
+    ├── heretek-state-management/       # PostgreSQL, Redis, Qdrant
+    └── heretek-testing/                # pytest & vitest patterns
+```
+
+---
+
+## Related Repos
+
+| Repo | Description |
+|------|-------------|
+| [Heretek-AI/heretek-swarm](https://github.com/Heretek-AI/heretek-swarm) | The main Swarm platform — 23 agents, API, dashboard, infrastructure |
+| [Heretek-AI/heretek-skills](https://github.com/Heretek-AI/heretek-skills) | This repo — AI coding skills for the Swarm codebase |
+
+---
+
+## License
+
+MIT &mdash; see [LICENSE](LICENSE).