diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1867cf3..6936c0b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,6 +13,16 @@ 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 a7521bd..e4f2882 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,145 +1,41 @@ # resolvekit-backend -> Multi-agent orchestration framework for agentic coding +This file is the **table of contents** for coding agents. Keep it short, stable, and current. -## Project Overview +## Working Contract -A Claude Flow powered project +- 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. -**Tech Stack**: TypeScript, Node.js -**Architecture**: Domain-Driven Design with bounded contexts +## First Read -## Quick Start +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. -### Installation -```bash -npm install -``` - -### Build -```bash -npm run build -``` +## Commands -### Test ```bash -npm test +uv sync --extra dev +uv run python -m pytest -q +npm --prefix dashboard ci +npm --prefix dashboard test ``` -### 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 | +## Source of Truth Layout -## 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 -``` +- `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. -## Links +## Guardrails -- Documentation: https://github.com/ruvnet/claude-flow -- Issues: https://github.com/ruvnet/claude-flow/issues +- 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. diff --git a/docs/INDEX.md b/docs/INDEX.md index 5d71052..e95aee0 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -2,6 +2,11 @@ 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) @@ -23,6 +28,12 @@ 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 new file mode 100644 index 0000000..12b6275 --- /dev/null +++ b/docs/agent-first/README.md @@ -0,0 +1,14 @@ +# 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 new file mode 100644 index 0000000..9661627 --- /dev/null +++ b/docs/exec-plans/README.md @@ -0,0 +1,10 @@ +# 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 new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/exec-plans/active/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/exec-plans/completed/.gitkeep b/docs/exec-plans/completed/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/exec-plans/completed/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/exec-plans/tech-debt-tracker.md b/docs/exec-plans/tech-debt-tracker.md new file mode 100644 index 0000000..f98362a --- /dev/null +++ b/docs/exec-plans/tech-debt-tracker.md @@ -0,0 +1,13 @@ +# 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 new file mode 100755 index 0000000..fbf7d70 --- /dev/null +++ b/scripts/check_agent_docs.sh @@ -0,0 +1,29 @@ +#!/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"