feat(skills): enhance agent skills with additional tags and commands
Some checks failed
CI / build-and-test (push) Failing after -29m56s
Some checks failed
CI / build-and-test (push) Failing after -29m56s
- Added language_tags, library_tags, framework_tags, and domain_tags to agent skills. - Introduced new commands: get_skill and get_guardrail for fetching specific skills and guardrails. - Updated database schema and migration scripts to accommodate new fields. - Enhanced skill listing functionality to support filtering by new tags. - Improved error handling and response structures for skill-related operations.
This commit is contained in:
101
AGENTS.md
Normal file
101
AGENTS.md
Normal file
@@ -0,0 +1,101 @@
|
||||
## What This Project Is
|
||||
|
||||
AMCS (Avalon Memory Control Service) is an MCP server written in Go that provides memory, knowledge, and task management for AI agents. It exposes 56+ tools via HTTP/SSE MCP transport and includes a Svelte 5 admin UI embedded in the binary.
|
||||
|
||||
# Agent Rules
|
||||
|
||||
Keep your answers short. Question everything, never assume or guess. Ask the user if you are unsure about anything.
|
||||
You must use the AMCS MCP system tools. Set Origin as the active project and always capture summaries of what was done as thoughts using the capture_thought tool. If amcs is not available write files to doc/llm/log/yyyymmdd_hh.md
|
||||
When working on postgresql use the postgresql skill. On go/api/backend the go-skill and for the frontend the "svelte-architect" skill.
|
||||
|
||||
## Commands
|
||||
|
||||
### Build & Run
|
||||
```bash
|
||||
make build # Build server binary (outputs to bin/amcs-server), embeds UI
|
||||
make build-cli # Build CLI binary (bin/amcs-cli)
|
||||
make clean # Remove bin/
|
||||
|
||||
# Run locally (builds UI then starts server)
|
||||
./scripts/run-local.sh configs/dev.yaml
|
||||
|
||||
# UI hot-reload dev server (proxy to backend on :8080)
|
||||
make ui-dev # http://localhost:5173
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
make test # All tests (svelte-check + go test ./...)
|
||||
go test ./internal/tools -run TestFunctionName -v # Single test
|
||||
go test ./internal/tools -v # Package tests
|
||||
```
|
||||
|
||||
### Database
|
||||
```bash
|
||||
make migrate # Apply SQL migrations
|
||||
make check-schema-drift # Verify no drift between DBML and SQL
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Key Pattern: Store → Tool → MCP Handler
|
||||
|
||||
Every tool domain follows the same three-layer pattern:
|
||||
|
||||
1. **Store** (`internal/store/`) — database access via BUN ORM + pgx. One file per domain (e.g., `thoughts.go`, `plans.go`).
|
||||
2. **Tool** (`internal/tools/`) — MCP tool handler structs with a `Handle(ctx, req, input)` method. Input/output types are plain Go structs; JSON schemas are auto-generated from struct tags.
|
||||
3. **Registration** (`internal/mcpserver/handlers.go`) — each domain has a `registerXxxTools(server, logger, ts)` function called from `NewHandlers`.
|
||||
|
||||
### Adding a New Tool Domain
|
||||
|
||||
Follow the checklist in `internal/tools/` (see `project_conventions.md` in memory, or look at any existing domain like `skills.go` as a reference):
|
||||
- Define input/output structs with `jsonschema` tags
|
||||
- Implement a struct with `Handle` method
|
||||
- Add the struct to `ToolSet` in `mcpserver/handlers.go`
|
||||
- Wire the store in `internal/store/db.go`
|
||||
- Add a `registerXxxTools` call in `NewHandlers`
|
||||
|
||||
### AI Provider Architecture
|
||||
|
||||
Configured in YAML under `ai.providers`. Each role (embeddings, metadata extraction) supports a primary provider and a fallback chain. Providers are named references (litellm, ollama, openrouter) that resolve to OpenAI-compatible endpoints. Health tracking per provider with cooldown on transient failures.
|
||||
|
||||
### Error Handling
|
||||
|
||||
All tool errors return structured `mcperrors.RPCError` with:
|
||||
- `data.type` — machine-readable category (`invalid_input`, `project_required`, `entity_not_found`, etc.)
|
||||
- `data.field` / `data.detail` / `data.hint` — structured validation data
|
||||
|
||||
Use helpers in `internal/mcperrors/` rather than raw errors.
|
||||
|
||||
### Authentication
|
||||
|
||||
- API key via `x-brain-key` header (dev/simple deployments)
|
||||
- OAuth 2.0 client credentials for production
|
||||
- Session store tracks active project per client connection
|
||||
|
||||
### Database Schema
|
||||
|
||||
DBML files in `schema/` are the source of truth for the database schema. Never edit the generated SQL or Go models directly — always edit the DBML, then regenerate:
|
||||
|
||||
```bash
|
||||
make generate-migrations # DBML → SQL migration files
|
||||
make generate-models # DBML → Go model structs
|
||||
make migrate # Apply pending migrations to the database
|
||||
```
|
||||
|
||||
All primary keys are `bigserial int64` (migrated from UUID in migration 015).
|
||||
|
||||
### Frontend
|
||||
|
||||
Svelte 5 + Tailwind + Skeleton UI in `ui/`. Built via pnpm and embedded into the Go binary as a static filesystem. The Vite dev server proxies API calls to the backend on `:8080`.
|
||||
|
||||
The UI uses **resolvespec-js** for admin CRUD views. The backend API for the UI follows the **ResolveSpec** convention — resource endpoints, filtering, and pagination are structured according to that spec.
|
||||
|
||||
## Configuration
|
||||
|
||||
YAML config with schema `version: 2`. Key env var overrides:
|
||||
- `DATABASE_URL` — PostgreSQL connection string
|
||||
- `AMCS_LITELLM_API_KEY`, `AMCS_OPENROUTER_API_KEY` — AI provider keys
|
||||
- `AMCS_SERVER_PORT` — defaults to 8080
|
||||
|
||||
See `configs/config.example.yaml` for the full schema. Config auto-migrates v1→v2 on startup.
|
||||
Reference in New Issue
Block a user