diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6936c0b..1867cf3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,16 +13,6 @@ env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" jobs: - agent-docs: - name: Agent Docs - runs-on: ubuntu-latest - steps: - - name: Check out repository - uses: actions/checkout@v5 - - - name: Validate agent-facing docs map - run: bash scripts/check_agent_docs.sh - python-contracts: name: Python Contracts runs-on: ubuntu-latest diff --git a/AGENTS.md b/AGENTS.md index e4f2882..a7521bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,41 +1,145 @@ # resolvekit-backend -This file is the **table of contents** for coding agents. Keep it short, stable, and current. +> Multi-agent orchestration framework for agentic coding -## Working Contract +## Project Overview -- Humans define intent and constraints. -- Agents implement code, tests, docs, and CI changes. -- Repository-local docs are the system of record. -- If docs and code diverge, fix docs in the same change. +A Claude Flow powered project -## First Read +**Tech Stack**: TypeScript, Node.js +**Architecture**: Domain-Driven Design with bounded contexts -1. `README.md` for product and self-host setup. -2. `docs/INDEX.md` for architecture, API, and operations maps. -3. `docs/agent-first/README.md` for agent operating principles. +## Quick Start -## Commands +### Installation +```bash +npm install +``` + +### Build +```bash +npm run build +``` +### Test ```bash -uv sync --extra dev -uv run python -m pytest -q -npm --prefix dashboard ci -npm --prefix dashboard test +npm test ``` -## Source of Truth Layout +### Development +```bash +npm run dev +``` + +## Agent Coordination + +### Swarm Configuration + +This project uses hierarchical swarm coordination for complex tasks: + +| Setting | Value | Purpose | +|---------|-------|---------| +| Topology | `hierarchical` | Queen-led coordination (anti-drift) | +| Max Agents | 8 | Optimal team size | +| Strategy | `specialized` | Clear role boundaries | +| Consensus | `raft` | Leader-based consistency | + +### When to Use Swarms + +**Invoke swarm for:** +- Multi-file changes (3+ files) +- New feature implementation +- Cross-module refactoring +- API changes with tests +- Security-related changes +- Performance optimization + +**Skip swarm for:** +- Single file edits +- Simple bug fixes (1-2 lines) +- Documentation updates +- Configuration changes + +### Available Skills + +Use `$skill-name` syntax to invoke: + +| Skill | Use Case | +|-------|----------| +| `$swarm-orchestration` | Multi-agent task coordination | +| `$memory-management` | Pattern storage and retrieval | +| `$sparc-methodology` | Structured development workflow | +| `$security-audit` | Security scanning and CVE detection | + +### Agent Types + +| Type | Role | Use Case | +|------|------|----------| +| `researcher` | Requirements analysis | Understanding scope | +| `architect` | System design | Planning structure | +| `coder` | Implementation | Writing code | +| `tester` | Test creation | Quality assurance | +| `reviewer` | Code review | Security and quality | -- `agent/` backend runtime and API handlers. -- `dashboard/` Next.js admin and API surfaces. -- `knowledge_bases/` KB service runtime. -- `docs/INDEX.md` documentation index. -- `docs/exec-plans/` active/completed execution plans and tech debt. -- `docs/generated/openapi/` generated API snapshots. +## Code Standards + +### File Organization +- **NEVER** save to root folder +- `/src` - Source code files +- `/tests` - Test files +- `/docs` - Documentation +- `/config` - Configuration files + +### Quality Rules +- Files under 500 lines +- No hardcoded secrets +- Input validation at boundaries +- Typed interfaces for public APIs +- TDD London School (mock-first) preferred + +### Commit Messages +``` +(): + +[optional body] + +Co-Authored-By: claude-flow +``` + +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore` + +## Security + +### Critical Rules +- NEVER commit secrets, credentials, or .env files +- NEVER hardcode API keys +- Always validate user input +- Use parameterized queries for SQL +- Sanitize output to prevent XSS + +### Path Security +- Validate all file paths +- Prevent directory traversal (../) +- Use absolute paths internally + +## Memory System + +### Storing Patterns +```bash +npx @claude-flow/cli memory store \ + --key "pattern-name" \ + --value "pattern description" \ + --namespace patterns +``` + +### Searching Memory +```bash +npx @claude-flow/cli memory search \ + --query "search terms" \ + --namespace patterns +``` -## Guardrails +## Links -- Never commit secrets or private `.env` values. -- Keep API contract and behavior docs synchronized. -- Prefer incremental PRs with passing checks over large refactors. -- Run `bash scripts/check_agent_docs.sh` before opening PRs that touch docs/architecture. +- Documentation: https://github.com/ruvnet/claude-flow +- Issues: https://github.com/ruvnet/claude-flow/issues diff --git a/docs/INDEX.md b/docs/INDEX.md index e95aee0..5d71052 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -2,11 +2,6 @@ This index is optimized for both engineers and LLM-based coding agents. -## Agent Entry Points - -- [Agent Map](../AGENTS.md) -- [Agent-First Harness Notes](agent-first/README.md) - ## Architecture and Service Boundaries - [Service Overview](backend/services-overview.md) @@ -28,12 +23,6 @@ This index is optimized for both engineers and LLM-based coding agents. - [Environment Reference](backend/config-env-reference.md) - [Local Dev + Docker Runbook](backend/runbooks/local-dev-and-docker.md) -## Planning and Change History - -- [Execution Plans](exec-plans/README.md) -- [Tech Debt Tracker](exec-plans/tech-debt-tracker.md) -- [Reports](reports/) - ## Protocol References - [SDK Integration Protocol](../SDK_INTEGRATION.md) diff --git a/docs/agent-first/README.md b/docs/agent-first/README.md deleted file mode 100644 index 12b6275..0000000 --- a/docs/agent-first/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Agent-First Harness Notes - -This repository follows an agent-first operating model: - -- `AGENTS.md` is a short map, not an encyclopedia. -- Detailed knowledge lives in versioned markdown under `docs/`. -- Execution plans are first-class artifacts in `docs/exec-plans/`. -- CI enforces documentation shape and discoverability with `scripts/check_agent_docs.sh`. - -Practical outcomes: - -- Agents can find architecture and constraints without oversized prompts. -- Humans review intent and outcomes instead of repeating repository context. -- Drift is visible early because doc checks run in CI. diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md deleted file mode 100644 index 9661627..0000000 --- a/docs/exec-plans/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Execution Plans - -Use this directory for implementation plans that agents execute. - -- `active/`: in-progress plans -- `completed/`: closed plans kept for historical context -- `tech-debt-tracker.md`: backlog of known debt and follow-ups - -For small changes, a lightweight plan in a PR description is enough. -For multi-step or cross-module changes, add a plan file here. diff --git a/docs/exec-plans/active/.gitkeep b/docs/exec-plans/active/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/docs/exec-plans/active/.gitkeep +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/exec-plans/completed/.gitkeep b/docs/exec-plans/completed/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/docs/exec-plans/completed/.gitkeep +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/exec-plans/tech-debt-tracker.md b/docs/exec-plans/tech-debt-tracker.md deleted file mode 100644 index f98362a..0000000 --- a/docs/exec-plans/tech-debt-tracker.md +++ /dev/null @@ -1,13 +0,0 @@ -# Tech Debt Tracker - -Track debt items that are intentionally deferred. - -Template: - -```md -- [ ] Title - - Impact: - - Scope: - - Owner: - - Link: -``` diff --git a/scripts/check_agent_docs.sh b/scripts/check_agent_docs.sh deleted file mode 100755 index fbf7d70..0000000 --- a/scripts/check_agent_docs.sh +++ /dev/null @@ -1,29 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -cd "$ROOT" - -required_files=( - "AGENTS.md" - "README.md" - "docs/INDEX.md" - "docs/agent-first/README.md" - "docs/exec-plans/README.md" - "docs/exec-plans/active/.gitkeep" - "docs/exec-plans/completed/.gitkeep" - "docs/exec-plans/tech-debt-tracker.md" -) - -for path in "${required_files[@]}"; do - if [[ ! -f "$path" ]]; then - echo "missing required file: $path" >&2 - exit 1 - fi -done - -grep -q "docs/INDEX.md" AGENTS.md || { echo "AGENTS.md must reference docs/INDEX.md" >&2; exit 1; } -grep -q "docs/agent-first/README.md" AGENTS.md || { echo "AGENTS.md must reference docs/agent-first/README.md" >&2; exit 1; } -grep -q "exec-plans" docs/INDEX.md || { echo "docs/INDEX.md must reference exec-plans" >&2; exit 1; } - -echo "agent docs check: OK"