|
1 | 1 | --- |
2 | | -description: Extending hawk-eco — how to write AGENTS.md files, custom specialists, skills, hooks, MCP servers, and plugins. |
3 | | -globs: "*.go, *.js, *.md, *.json, *.toml, *.yaml, *.yml" |
4 | | -alwaysApply: false |
5 | | ---- |
6 | | - |
7 | | -# Extending hawk-eco |
8 | | - |
9 | | -hawk-eco is an open-source code intelligence platform. This document describes how to extend it with custom tools, skills, hooks, and integrations. |
10 | | - |
11 | | -## 1. Drop a project `AGENTS.md` |
12 | | - |
13 | | -When hawk-eco starts in a directory, it looks for project-level instructions and injects them into the system prompt. The lookup walks from your current working directory **up to the nearest git root** and reads the first matching file at each level — general rules at the repo root, more specific rules in sub-trees. Files are labeled with their directory in the prompt (e.g. `## Project guidelines (services/api/AGENTS.md)`). |
14 | | - |
15 | | -Accepted file names, in priority order at each level: |
16 | | - |
17 | | -| Path | Notes | |
18 | | -| --- | --- | |
19 | | -| `./AGENTS.md` | The classic spot — committed to your repo, shared with the team. | |
20 | | -| `./ZERO.md` | Brand-specific alias. Same format, lower priority. | |
21 | | -| `./.zero/AGENTS.md` | Project-local, hidden, gitignored. Personal notes that stay out of git. | |
22 | | - |
23 | | -Matching is **case-insensitive** on the basename, so `AGENTS.md`, `Agents.md`, and `agents.md` resolve to the same file on Windows and macOS. The git-tracked filename in this repo is `AGENTS.md` — keep that on case-sensitive filesystems (Linux, the WSL filesystem, or a CI runner) to match what the loader looks for. |
24 | | - |
25 | | -Both files use the same format. YAML frontmatter is optional; the markdown body is loaded as instructions for the agent. hawk-eco reads the file once at session start, so changes take effect on the next launch — not mid-session. |
26 | | - |
27 | | -```markdown |
28 | | -# Project conventions for <your project> |
29 | | - |
30 | | -- Build with `make`, not `go build` directly. |
31 | | -- Tests live next to the source file (`foo_test.go` next to `foo.go`). |
32 | | -- Run `make lint` before opening a PR. |
33 | | -- Never edit files under `third_party/` — those are vendored. |
34 | | -``` |
35 | | - |
36 | | -Tips: |
37 | | - |
38 | | -- Keep each file under ~8 KiB. hawk-eco caps the **total** across all matched files at 32 KiB; everything past the cap is dropped. |
39 | | -- Re-state rules in the imperative voice: "Run `make lint`", not "you should consider running the linter". |
40 | | -- Don't put secrets, model IDs, or environment-specific paths in `AGENTS.md`. Use config files for those. |
41 | | -- In a monorepo, drop a narrower `AGENTS.md` in each sub-tree (e.g. `services/api/AGENTS.md`). hawk-eco picks those up automatically when you launch from inside the sub-tree. |
42 | | -- A YAML frontmatter block (`---\n...\n---`) at the top is preserved verbatim in the injected prompt but is not parsed for `globs:` or `alwaysApply:` scoping today — keep the body self-contained. |
43 | | - |
44 | | -### Personal guidelines, across every project |
45 | | - |
46 | | -For preferences that follow *you*, not a specific repo (tone, tooling habits, workflow), drop a `ZERO.md` in your user config directory: `~/.config/hawk-eco/ZERO.md` on Linux/macOS, `%AppData%\Roaming\hawk-eco\ZERO.md` on Windows — the same directory as config files and your personal specialists. Same format and 8 KiB cap as the project files above, and the same case-insensitive basename match. |
47 | | - |
48 | | -This file is injected as its own `## User guidelines` section, before the project's `AGENTS.md`/`ZERO.md`, and is labeled as personal preference in the prompt: project guidelines are the later, more specific instruction and take precedence over it when the two conflict. |
49 | | - |
50 | | -## 2. Custom specialists |
51 | | - |
52 | | -Specialists are hawk-eco's sub-agents. Three scopes, in priority order: |
53 | | - |
54 | | -| Scope | Path | Shared? | |
55 | | -| --- | --- | --- | |
56 | | -| Built-in | compiled into hawk-eco | yes | |
57 | | -| User | `~/.config/hawk-eco/specialists/*.md` | no — your machine only | |
58 | | -| Project | `./.zero/specialists/*.md` | yes — the repo team | |
59 | | - |
60 | | -Project overrides user overrides built-in when names collide. |
61 | | - |
62 | | -A specialist is a markdown manifest with frontmatter and a system prompt: |
63 | | - |
64 | | -```markdown |
65 | | ---- |
66 | | -description: Reviews API changes for breaking-change risk and missing tests. |
67 | | -tools: read-only,plan |
68 | | ---- |
69 | | - |
70 | | -You review API changes. For every changed hunk in `internal/api/` or any file |
71 | | -that ends in `_api.go`: |
72 | | - |
73 | | -1. Confirm the public signature is backward-compatible, or note the breaking |
74 | | - change explicitly with the migration path. |
75 | | -2. Confirm a corresponding test exists in `internal/api/*_test.go` and that |
76 | | - the new behaviour is exercised. |
77 | | -3. Flag any new exported symbol without a doc comment. |
78 | | - |
79 | | -Reply with one JSON object per finding: `{"file", "line", "severity", "message", "fix"}`. |
80 | | -``` |
81 | | - |
82 | | -CLI management: |
83 | | - |
84 | | -```bash |
85 | | -hawk-eco specialist list |
86 | | -hawk-eco specialist show api-reviewer |
87 | | -hawk-eco specialist create api-reviewer \ |
88 | | - --project \ |
89 | | - --description "Reviews API changes" \ |
90 | | - --tools read-only,plan \ |
91 | | - --prompt "$(cat api-reviewer.md)" |
92 | | -hawk-eco specialist edit api-reviewer --project |
93 | | -hawk-eco specialist delete api-reviewer --project |
94 | | -hawk-eco specialist path # prints the resolved specialists directory |
95 | | -``` |
96 | | - |
97 | | -## 3. Skills |
98 | | - |
99 | | -Skills are markdown instruction files that extend agent capabilities. They can be: |
100 | | -- Project-scoped: dropped in `./.zero/skills/` or `./skills/` |
101 | | -- User-scoped: dropped in `~/.config/hawk-eco/skills/` |
102 | | - |
103 | | -A skill manifest: |
104 | | - |
105 | | -```markdown |
106 | | ---- |
107 | | -description: How to review Go code for security issues |
| 2 | +description: inspect — website audit library build and test conventions. |
108 | 3 | globs: "*.go" |
109 | | -alwaysApply: true |
| 4 | +alwaysApply: false |
110 | 5 | --- |
111 | 6 |
|
112 | | -When reviewing Go code for security: |
113 | | - |
114 | | -1. Check for SQL injection patterns |
115 | | -2. Verify error handling doesn't expose sensitive data |
116 | | -3. Confirm secrets are not hardcoded |
117 | | -4. Validate input sanitization |
118 | | -``` |
119 | | - |
120 | | -## 4. Hooks |
121 | | - |
122 | | -Hooks allow custom commands to run at specific lifecycle points: |
123 | | -- `beforeReview` — runs before code review starts |
124 | | -- `afterReview` — runs after code review completes |
125 | | -- `sessionStart` — runs at session initialization |
126 | | -- `sessionEnd` — runs at session teardown |
127 | | - |
128 | | -```bash |
129 | | -hawk-eco hook add beforeReview --command "lint-check" |
130 | | -hawk-eco hook remove beforeReview |
131 | | -hawk-eco hook list |
132 | | -``` |
133 | | - |
134 | | -## 5. MCP integration |
135 | | - |
136 | | -MCP (Model Context Protocol) servers can expose tools to hawk-eco: |
| 7 | +# inspect Conventions |
137 | 8 |
|
138 | | -```bash |
139 | | -hawk-eco mcp add --name server --url http://localhost:8080 |
140 | | -hawk-eco mcp remove server |
141 | | -hawk-eco mcp list |
142 | | -``` |
| 9 | +Live website auditor for accessibility, TLS, cookies, and security headers. |
143 | 10 |
|
144 | | -## 6. Plugins |
145 | | - |
146 | | -Plugins extend hawk-eco with custom tools and capabilities: |
| 11 | +## Build & Test |
147 | 12 |
|
148 | 13 | ```bash |
149 | | -hawk-eco plugin add --name my-plugin --path ./my-plugin |
150 | | -hawk-eco plugin remove my-plugin |
151 | | -hawk-eco plugin list |
| 14 | +go build ./... # Build library |
| 15 | +go test ./... # Run tests |
| 16 | +go test -race ./... # Race detector |
| 17 | +go vet ./... # Static analysis |
152 | 18 | ``` |
153 | 19 |
|
154 | | -## 7. Verification |
| 20 | +## Architecture |
155 | 21 |
|
156 | | -hawk-eco includes a self-verification system to validate local changes before contributing: |
| 22 | +- Go library + MCP server (no standalone CLI binary) |
| 23 | +- Analyzes live HTTP/browser targets, not source code |
| 24 | +- `browser/` sub-module: headless Chromium via `rod` (optional, heavy dependency) |
157 | 25 |
|
158 | | -```bash |
159 | | -hawk-eco verify |
160 | | -hawk-eco verify --fix |
161 | | -``` |
| 26 | +## Ecosystem Boundaries |
162 | 27 |
|
163 | | -## Development |
| 28 | +- Use `hawk-core-contracts` for cross-repo shared types |
| 29 | +- Do not import `hawk/internal/*` or legacy `hawk/shared/types` |
| 30 | +- Do not import other engines (`eyrie`, `yaad`, `tok`, `trace`, `sight`) |
164 | 31 |
|
165 | | -```bash |
166 | | -make lint |
167 | | -hawk-eco verify |
168 | | -``` |
| 32 | +For full hawk-eco extension guidelines, see [hawk/AGENTS.md](https://github.com/GrayCodeAI/hawk/blob/main/AGENTS.md). |
0 commit comments