docs(agent): add harness-style agent map and docs guardrails

.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

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
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-Co-Authored-By: claude-flow <ruv@ruv.net>
-```
-
-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.

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)

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.

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.

docs/exec-plans/active/.gitkeep

@@ -0,0 +1 @@
+

docs/exec-plans/completed/.gitkeep

@@ -0,0 +1 @@
+

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:
+```

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"