Skip to content

Commit bfdeb89

Browse files
nedasvinedasvi
authored
docs(agent): add harness-style agent map and docs guardrails (#27)
1 parent 169d9ed commit bfdeb89

9 files changed

Lines changed: 116 additions & 131 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,16 @@ env:
1313
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
1414

1515
jobs:
16+
agent-docs:
17+
name: Agent Docs
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Check out repository
21+
uses: actions/checkout@v5
22+
23+
- name: Validate agent-facing docs map
24+
run: bash scripts/check_agent_docs.sh
25+
1626
python-contracts:
1727
name: Python Contracts
1828
runs-on: ubuntu-latest

‎AGENTS.md‎

Lines changed: 27 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,41 @@
11
# resolvekit-backend
22

3-
> Multi-agent orchestration framework for agentic coding
3+
This file is the **table of contents** for coding agents. Keep it short, stable, and current.
44

5-
## Project Overview
5+
## Working Contract
66

7-
A Claude Flow powered project
7+
- Humans define intent and constraints.
8+
- Agents implement code, tests, docs, and CI changes.
9+
- Repository-local docs are the system of record.
10+
- If docs and code diverge, fix docs in the same change.
811

9-
**Tech Stack**: TypeScript, Node.js
10-
**Architecture**: Domain-Driven Design with bounded contexts
12+
## First Read
1113

12-
## Quick Start
14+
1. `README.md` for product and self-host setup.
15+
2. `docs/INDEX.md` for architecture, API, and operations maps.
16+
3. `docs/agent-first/README.md` for agent operating principles.
1317

14-
### Installation
15-
```bash
16-
npm install
17-
```
18-
19-
### Build
20-
```bash
21-
npm run build
22-
```
18+
## Commands
2319

24-
### Test
2520
```bash
26-
npm test
21+
uv sync --extra dev
22+
uv run python -m pytest -q
23+
npm --prefix dashboard ci
24+
npm --prefix dashboard test
2725
```
2826

29-
### Development
30-
```bash
31-
npm run dev
32-
```
33-
34-
## Agent Coordination
35-
36-
### Swarm Configuration
37-
38-
This project uses hierarchical swarm coordination for complex tasks:
39-
40-
| Setting | Value | Purpose |
41-
|---------|-------|---------|
42-
| Topology | `hierarchical` | Queen-led coordination (anti-drift) |
43-
| Max Agents | 8 | Optimal team size |
44-
| Strategy | `specialized` | Clear role boundaries |
45-
| Consensus | `raft` | Leader-based consistency |
46-
47-
### When to Use Swarms
48-
49-
**Invoke swarm for:**
50-
- Multi-file changes (3+ files)
51-
- New feature implementation
52-
- Cross-module refactoring
53-
- API changes with tests
54-
- Security-related changes
55-
- Performance optimization
56-
57-
**Skip swarm for:**
58-
- Single file edits
59-
- Simple bug fixes (1-2 lines)
60-
- Documentation updates
61-
- Configuration changes
62-
63-
### Available Skills
64-
65-
Use `$skill-name` syntax to invoke:
66-
67-
| Skill | Use Case |
68-
|-------|----------|
69-
| `$swarm-orchestration` | Multi-agent task coordination |
70-
| `$memory-management` | Pattern storage and retrieval |
71-
| `$sparc-methodology` | Structured development workflow |
72-
| `$security-audit` | Security scanning and CVE detection |
73-
74-
### Agent Types
75-
76-
| Type | Role | Use Case |
77-
|------|------|----------|
78-
| `researcher` | Requirements analysis | Understanding scope |
79-
| `architect` | System design | Planning structure |
80-
| `coder` | Implementation | Writing code |
81-
| `tester` | Test creation | Quality assurance |
82-
| `reviewer` | Code review | Security and quality |
27+
## Source of Truth Layout
8328

84-
## Code Standards
85-
86-
### File Organization
87-
- **NEVER** save to root folder
88-
- `/src` - Source code files
89-
- `/tests` - Test files
90-
- `/docs` - Documentation
91-
- `/config` - Configuration files
92-
93-
### Quality Rules
94-
- Files under 500 lines
95-
- No hardcoded secrets
96-
- Input validation at boundaries
97-
- Typed interfaces for public APIs
98-
- TDD London School (mock-first) preferred
99-
100-
### Commit Messages
101-
```
102-
<type>(<scope>): <description>
103-
104-
[optional body]
105-
106-
Co-Authored-By: claude-flow <ruv@ruv.net>
107-
```
108-
109-
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
110-
111-
## Security
112-
113-
### Critical Rules
114-
- NEVER commit secrets, credentials, or .env files
115-
- NEVER hardcode API keys
116-
- Always validate user input
117-
- Use parameterized queries for SQL
118-
- Sanitize output to prevent XSS
119-
120-
### Path Security
121-
- Validate all file paths
122-
- Prevent directory traversal (../)
123-
- Use absolute paths internally
124-
125-
## Memory System
126-
127-
### Storing Patterns
128-
```bash
129-
npx @claude-flow/cli memory store \
130-
--key "pattern-name" \
131-
--value "pattern description" \
132-
--namespace patterns
133-
```
134-
135-
### Searching Memory
136-
```bash
137-
npx @claude-flow/cli memory search \
138-
--query "search terms" \
139-
--namespace patterns
140-
```
29+
- `agent/` backend runtime and API handlers.
30+
- `dashboard/` Next.js admin and API surfaces.
31+
- `knowledge_bases/` KB service runtime.
32+
- `docs/INDEX.md` documentation index.
33+
- `docs/exec-plans/` active/completed execution plans and tech debt.
34+
- `docs/generated/openapi/` generated API snapshots.
14135

142-
## Links
36+
## Guardrails
14337

144-
- Documentation: https://github.com/ruvnet/claude-flow
145-
- Issues: https://github.com/ruvnet/claude-flow/issues
38+
- Never commit secrets or private `.env` values.
39+
- Keep API contract and behavior docs synchronized.
40+
- Prefer incremental PRs with passing checks over large refactors.
41+
- Run `bash scripts/check_agent_docs.sh` before opening PRs that touch docs/architecture.

‎docs/INDEX.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
This index is optimized for both engineers and LLM-based coding agents.
44

5+
## Agent Entry Points
6+
7+
- [Agent Map](../AGENTS.md)
8+
- [Agent-First Harness Notes](agent-first/README.md)
9+
510
## Architecture and Service Boundaries
611

712
- [Service Overview](backend/services-overview.md)
@@ -23,6 +28,12 @@ This index is optimized for both engineers and LLM-based coding agents.
2328
- [Environment Reference](backend/config-env-reference.md)
2429
- [Local Dev + Docker Runbook](backend/runbooks/local-dev-and-docker.md)
2530

31+
## Planning and Change History
32+
33+
- [Execution Plans](exec-plans/README.md)
34+
- [Tech Debt Tracker](exec-plans/tech-debt-tracker.md)
35+
- [Reports](reports/)
36+
2637
## Protocol References
2738

2839
- [SDK Integration Protocol](../SDK_INTEGRATION.md)

‎docs/agent-first/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Agent-First Harness Notes
2+
3+
This repository follows an agent-first operating model:
4+
5+
- `AGENTS.md` is a short map, not an encyclopedia.
6+
- Detailed knowledge lives in versioned markdown under `docs/`.
7+
- Execution plans are first-class artifacts in `docs/exec-plans/`.
8+
- CI enforces documentation shape and discoverability with `scripts/check_agent_docs.sh`.
9+
10+
Practical outcomes:
11+
12+
- Agents can find architecture and constraints without oversized prompts.
13+
- Humans review intent and outcomes instead of repeating repository context.
14+
- Drift is visible early because doc checks run in CI.

‎docs/exec-plans/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Execution Plans
2+
3+
Use this directory for implementation plans that agents execute.
4+
5+
- `active/`: in-progress plans
6+
- `completed/`: closed plans kept for historical context
7+
- `tech-debt-tracker.md`: backlog of known debt and follow-ups
8+
9+
For small changes, a lightweight plan in a PR description is enough.
10+
For multi-step or cross-module changes, add a plan file here.

‎docs/exec-plans/active/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/exec-plans/completed/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/exec-plans/tech-debt-tracker.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Tech Debt Tracker
2+
3+
Track debt items that are intentionally deferred.
4+
5+
Template:
6+
7+
```md
8+
- [ ] Title
9+
- Impact:
10+
- Scope:
11+
- Owner:
12+
- Link:
13+
```

‎scripts/check_agent_docs.sh‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
5+
cd "$ROOT"
6+
7+
required_files=(
8+
"AGENTS.md"
9+
"README.md"
10+
"docs/INDEX.md"
11+
"docs/agent-first/README.md"
12+
"docs/exec-plans/README.md"
13+
"docs/exec-plans/active/.gitkeep"
14+
"docs/exec-plans/completed/.gitkeep"
15+
"docs/exec-plans/tech-debt-tracker.md"
16+
)
17+
18+
for path in "${required_files[@]}"; do
19+
if [[ ! -f "$path" ]]; then
20+
echo "missing required file: $path" >&2
21+
exit 1
22+
fi
23+
done
24+
25+
grep -q "docs/INDEX.md" AGENTS.md || { echo "AGENTS.md must reference docs/INDEX.md" >&2; exit 1; }
26+
grep -q "docs/agent-first/README.md" AGENTS.md || { echo "AGENTS.md must reference docs/agent-first/README.md" >&2; exit 1; }
27+
grep -q "exec-plans" docs/INDEX.md || { echo "docs/INDEX.md must reference exec-plans" >&2; exit 1; }
28+
29+
echo "agent docs check: OK"

0 commit comments

Comments
 (0)