@technomoron/agent-brain 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGES.md +18 -0
- package/LICENSE +21 -0
- package/README.md +855 -2
- package/dist/agent-brain.js +6 -0
- package/dist/brain/built-in-skills.js +24 -0
- package/dist/brain/cli.js +265 -0
- package/dist/brain/config.js +92 -0
- package/dist/brain/connectors.js +63 -0
- package/dist/brain/consolidation-skill.js +5 -0
- package/dist/brain/consolidation.js +134 -0
- package/dist/brain/git.js +139 -0
- package/dist/brain/github-reviews.js +174 -0
- package/dist/brain/projects.js +136 -0
- package/dist/brain/remote-policy.js +126 -0
- package/dist/brain/remote-server.js +211 -0
- package/dist/brain/repositories.js +28 -0
- package/dist/brain/repository-discovery.js +76 -0
- package/dist/brain/server.js +283 -0
- package/dist/brain/skills.js +54 -0
- package/dist/brain/store.js +499 -0
- package/dist/brain/todos.js +155 -0
- package/dist/brain/windows-pipe.js +19 -0
- package/dist/version.js +22 -0
- package/examples/brain.jsonc +7 -0
- package/examples/remote.jsonc +22 -0
- package/ops/config-deploy-entry.sh +3 -0
- package/ops/config-deploy-root.cjs +111 -0
- package/ops/config-deploy.cjs +176 -0
- package/ops/config-policy.cjs +220 -0
- package/ops/config-sync.cjs +72 -0
- package/ops/systemd/agent-brain.service +14 -0
- package/package.json +55 -4
- package/skills/brain-consolidate/SKILL.md +42 -0
- package/skills/brain-import/SKILL.md +56 -0
- package/skills/brain-memory/SKILL.md +73 -0
- package/skills/brain-review/SKILL.md +38 -0
- package/skills/code-review-organizer/SKILL.md +150 -0
- package/skills/review-items/SKILL.md +43 -0
- package/skills/todo-manager/SKILL.md +8 -0
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: code-review-organizer
|
|
3
|
+
description: Use for code reviews and review follow-up. Maintains one cumulative list of open findings across all reviews as numbered, prioritized agent-brain items.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
## Review backend selection
|
|
8
|
+
|
|
9
|
+
Before conducting a review or modifying findings, call `brain_status`. Its
|
|
10
|
+
`reviewBackend` selects the destination. For `github`, findings are issues in the
|
|
11
|
+
active repository shown by `repository`; use `review_list`, `review_get`,
|
|
12
|
+
`review_create`, `review_update`, `resolve_review`, and `review_history`.
|
|
13
|
+
This backend selection takes precedence over internal-storage instructions below.
|
|
14
|
+
Do not use `remember`, `get_knowledge`, or `amend_knowledge` for GitHub findings,
|
|
15
|
+
and do not create an internal duplicate or silently fall back when GitHub fails.
|
|
16
|
+
Each repository keeps its own issues; split findings that affect different repos.
|
|
17
|
+
Use a stable, repository-specific retry `key` for `review_create`. Remote writes
|
|
18
|
+
require user authorization, enabled GitHub writes, and `confirmed: true` for
|
|
19
|
+
creation or updates. Read the current issue revision before updating or closing.
|
|
20
|
+
Preserve discussion outside the managed finding block. Closing requires verified
|
|
21
|
+
fixes or the user's explicit decision to drop a finding; deferral leaves it open.
|
|
22
|
+
GitHub retains closed history, so do not call `review_archive` for this backend.
|
|
23
|
+
For `internal`, retain the existing knowledge storage and closure workflow below.
|
|
24
|
+
Read-only listing can call `review_list` or `review_history` directly without
|
|
25
|
+
loading this workflow. Never enable writes or migrate old findings implicitly.
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
# Code Review Organizer
|
|
29
|
+
|
|
30
|
+
Review findings live in agent-brain as a numbered, prioritized list. Each finding is one
|
|
31
|
+
knowledge item of type `review` with a severity, and the store gives it a label. There is
|
|
32
|
+
no consolidated review file, no dated review file, and no done file. Never write review
|
|
33
|
+
notes into the project repository.
|
|
34
|
+
|
|
35
|
+
If agent-brain is unavailable, say so and report the findings in the reply. Do not fall
|
|
36
|
+
back to writing review files.
|
|
37
|
+
|
|
38
|
+
## One cumulative list
|
|
39
|
+
|
|
40
|
+
There is a single list of open findings for the project. It is not per review. A finding
|
|
41
|
+
raised in any earlier review stays on it until someone actively closes it, no matter how
|
|
42
|
+
old it is or which session raised it. Nothing ages out, and nothing is dropped for being
|
|
43
|
+
stale, minor, or inconvenient.
|
|
44
|
+
|
|
45
|
+
Every review updates that whole list, not just the part it happened to touch.
|
|
46
|
+
|
|
47
|
+
## Before reviewing
|
|
48
|
+
|
|
49
|
+
1. Call `review_context` with the task and the paths you are about to review. It returns
|
|
50
|
+
the project constraints, decisions, and path-specific knowledge that apply.
|
|
51
|
+
2. Call `review_list` for every open finding, from every past review. This is your
|
|
52
|
+
starting list, and you are responsible for all of it, not only what you add today.
|
|
53
|
+
3. Re-check each open finding against the current code. Code moves, so a finding can be
|
|
54
|
+
already fixed, partly fixed, changed shape, or wrong.
|
|
55
|
+
- Still accurate: leave it alone.
|
|
56
|
+
- Details drifted, such as moved line numbers or a changed mechanism: `amend_knowledge`
|
|
57
|
+
so the finding matches the code as it is now.
|
|
58
|
+
- Fixed by an authorized task: close it after relevant verification.
|
|
59
|
+
- Looks wrong or appears fixed by unrelated work: present the evidence for the user to decide.
|
|
60
|
+
4. Read the generated agent instructions for the project.
|
|
61
|
+
5. Do not re-report something already on the list. Amend the existing finding instead of
|
|
62
|
+
raising a second one for the same defect.
|
|
63
|
+
|
|
64
|
+
## Saving findings
|
|
65
|
+
|
|
66
|
+
One `remember` call per finding, with `type: review` and `authority: inferred`. A finding
|
|
67
|
+
is a suspicion until the user confirms it; never save one as a constraint, rule, or
|
|
68
|
+
decision without being asked.
|
|
69
|
+
|
|
70
|
+
- `severity`: `critical`, `high`, `medium`, or `low`. Required for reviews, and rejected
|
|
71
|
+
on every other type. Judge it by what happens if the defect is left alone, not by how
|
|
72
|
+
much code it touches. Data loss, credential exposure, and corruption are critical or
|
|
73
|
+
high. Style, dead code, and small inefficiencies are low.
|
|
74
|
+
- `title`: the claim in one line, no label prefix. The store assigns the label.
|
|
75
|
+
- `content`: what is wrong, the file and line, how it fails in practice, and what would
|
|
76
|
+
fix it. Include a reproduction when you have one, and say plainly whether you confirmed
|
|
77
|
+
the failure or are reasoning from the code.
|
|
78
|
+
- `applies_to`: the files the finding is about. This is the field that earns its keep, as
|
|
79
|
+
the finding resurfaces through `get_context` the next time anyone works on those files.
|
|
80
|
+
- `tags`: the review date as `YYYY-MM-DD` and the component.
|
|
81
|
+
|
|
82
|
+
Do not put the label in the title yourself and do not pass one. `remember` returns the
|
|
83
|
+
assigned `finding` (`C1`, `H1`, `M1`, `L1`), numbered per severity within the scope.
|
|
84
|
+
Numbers are never reused, so a label always means the same finding.
|
|
85
|
+
|
|
86
|
+
Save the session record separately, as `type: memory`, not as a review. It covers what was
|
|
87
|
+
reviewed, at which commit, which checks you ran, and what they returned, including checks
|
|
88
|
+
that failed or that you could not run. Keep it short; the findings carry the detail.
|
|
89
|
+
|
|
90
|
+
Call `remember` one at a time. Brain writes take an exclusive lock, so concurrent calls
|
|
91
|
+
fail with a lock error rather than queueing. The failure is clean and writes nothing.
|
|
92
|
+
|
|
93
|
+
`remember` names each file after the item id. That is expected. Do not rename or hand-edit
|
|
94
|
+
those files as part of a review.
|
|
95
|
+
|
|
96
|
+
## Reporting
|
|
97
|
+
|
|
98
|
+
Report the whole open list, every time, most severe first, with the label, the file and
|
|
99
|
+
line, and the claim. That means findings carried over from earlier reviews as well as
|
|
100
|
+
anything new, in one list. `review_list` already returns them in that order. Never report
|
|
101
|
+
only the findings from the current session: the user should be able to read the reply and
|
|
102
|
+
see everything that is open, without going back through old sessions.
|
|
103
|
+
|
|
104
|
+
Mark new findings clearly. Report findings closed during the task separately with the change and verification. Propose closure for findings whose status still needs a user decision.
|
|
105
|
+
|
|
106
|
+
The saved items are the record; the reply is how the user reads them. State which checks
|
|
107
|
+
you ran and what they returned.
|
|
108
|
+
|
|
109
|
+
## Follow-up
|
|
110
|
+
|
|
111
|
+
When the user says "in code review", "review finding", "check H1", "fix M2", "address
|
|
112
|
+
C1/C2", or names a label like `C1`, `H1`, `M1`, or `L1`, they mean a saved finding, not a
|
|
113
|
+
GitHub pull request comment. Only use GitHub review tools if the user explicitly mentions
|
|
114
|
+
GitHub, pull requests, review comments, or CI.
|
|
115
|
+
|
|
116
|
+
To act on one:
|
|
117
|
+
|
|
118
|
+
1. `review_list` for the open findings, or `search_knowledge` with the label if you want a
|
|
119
|
+
specific one. Labels are indexed, so searching `H2` finds it.
|
|
120
|
+
2. `get_knowledge` for the full text and its current revision.
|
|
121
|
+
3. Read the files and lines it names, and confirm the finding still stands before acting
|
|
122
|
+
on it. Findings go stale.
|
|
123
|
+
|
|
124
|
+
## Resolving a finding
|
|
125
|
+
|
|
126
|
+
A request to fix a finding authorizes closing it as `fixed` once the change is complete
|
|
127
|
+
and relevant checks pass. A request to clean up finished findings authorizes closing
|
|
128
|
+
verified completed fixes and compacting existing closed records. Do not ask again for
|
|
129
|
+
permission already given. Record limitations when a relevant platform could not be tested.
|
|
130
|
+
|
|
131
|
+
Call `resolve_review` with the id, current revision, state, and a short reason:
|
|
132
|
+
|
|
133
|
+
- `fixed`: what changed and how it was verified.
|
|
134
|
+
- `wontfix`: the user's decision to drop, reject, or accept the finding and why.
|
|
135
|
+
|
|
136
|
+
Postponing an issue ("later", "ignore for now") keeps it open. Do not close an issue
|
|
137
|
+
because of age, severity, or convenience. If you merely suspect unrelated work fixed it,
|
|
138
|
+
verify and propose closure rather than silently dropping it.
|
|
139
|
+
|
|
140
|
+
Closing writes a compact record to the scope's `review-history.jsonl` and removes the
|
|
141
|
+
full finding file. Separate counters preserve labels. Use `review_archive` with an
|
|
142
|
+
explicit scope when asked to clean up previously closed files. It leaves unresolved
|
|
143
|
+
findings alone. Never make separate done lists or copies of full finished findings.
|
|
144
|
+
|
|
145
|
+
Use `review_history` for old fixes and dropped findings; filter by query (label, id,
|
|
146
|
+
title, or reason), scope, or state, and paginate with offset/limit when needed. Ordinary
|
|
147
|
+
review_list, get_context, and knowledge search are for current work. If a requested
|
|
148
|
+
label is absent from review_list, check review_history before claiming it is missing.
|
|
149
|
+
Git can retain full details only if the original files were committed before cleanup.
|
|
150
|
+
Closing findings does not authorize a Git commit, push, or changes to remote issues.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: review-items
|
|
3
|
+
description: MUST use when the user asks to list, show, fix, address, check, resolve, close, or summarize review items, outstanding review issues, review findings, review IDs like C1/H1/M1/L1, or saved code review follow-ups.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
## Review backend selection
|
|
8
|
+
|
|
9
|
+
Before conducting a review or modifying findings, call `brain_status`. Its
|
|
10
|
+
`reviewBackend` selects the destination. For `github`, findings are issues in the
|
|
11
|
+
active repository shown by `repository`; use `review_list`, `review_get`,
|
|
12
|
+
`review_create`, `review_update`, `resolve_review`, and `review_history`.
|
|
13
|
+
This backend selection takes precedence over internal-storage instructions below.
|
|
14
|
+
Do not use `remember`, `get_knowledge`, or `amend_knowledge` for GitHub findings,
|
|
15
|
+
and do not create an internal duplicate or silently fall back when GitHub fails.
|
|
16
|
+
Each repository keeps its own issues; split findings that affect different repos.
|
|
17
|
+
Use a stable, repository-specific retry `key` for `review_create`. Remote writes
|
|
18
|
+
require user authorization, enabled GitHub writes, and `confirmed: true` for
|
|
19
|
+
creation or updates. Read the current issue revision before updating or closing.
|
|
20
|
+
Preserve discussion outside the managed finding block. Closing requires verified
|
|
21
|
+
fixes or the user's explicit decision to drop a finding; deferral leaves it open.
|
|
22
|
+
GitHub retains closed history, so do not call `review_archive` for this backend.
|
|
23
|
+
For `internal`, retain the existing knowledge storage and closure workflow below.
|
|
24
|
+
Read-only listing can call `review_list` or `review_history` directly without
|
|
25
|
+
loading this workflow. Never enable writes or migrate old findings implicitly.
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
# Review Items
|
|
29
|
+
|
|
30
|
+
Saved review labels refer to agent-brain findings, not GitHub issues or PR comments,
|
|
31
|
+
unless the user explicitly gives that context. Follow code-review-organizer for the
|
|
32
|
+
review workflow and closure rules.
|
|
33
|
+
|
|
34
|
+
Use `review_list` for open findings, then `get_knowledge` for a finding's details and
|
|
35
|
+
current revision. Inspect the referenced code before acting. Use `review_history` to
|
|
36
|
+
recall fixed or dropped findings, including labels absent from the open list.
|
|
37
|
+
|
|
38
|
+
Finish an authorized fix with relevant checks and `resolve_review`, recording what
|
|
39
|
+
changed and verification. Explicitly dropped findings use `wontfix`; deferred findings
|
|
40
|
+
stay open. Closing stores a compact record and removes the full finding file. Use
|
|
41
|
+
`review_archive` with an explicit scope for requested cleanup of already closed files.
|
|
42
|
+
Do not create consolidated, dated, or done review files. Brain storage stays outside
|
|
43
|
+
the source repository. Git history is optional and commits require separate authorization.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: todo-manager
|
|
3
|
+
description: Manage local tasks and import externally tracked tasks without duplicates.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Use todo_list and todo_get to inspect current work. Create tasks only when requested or authorized by the current workflow. Update using the current revision to avoid overwriting concurrent changes. Distinguish todo, doing, blocked, done, and cancelled. Imported tasks retain their external source identity. Local changes do not imply permission to update remote systems.
|
|
7
|
+
|
|
8
|
+
A request to do work does not by itself authorize creating a saved task.
|