@technomoron/agent-brain 0.1.3 → 0.1.4

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.
@@ -10,10 +10,11 @@ const { githubReviews } = require('../dist/brain/github-reviews');
10
10
  const { listTodos } = require('../dist/brain/todos');
11
11
  const { getSkills } = require('../dist/brain/skills');
12
12
  const { createProfileMarker } = require('@technomoron/agent-run/dist/manifest');
13
- const config = require('../dist/brain/remote-policy').readRemoteConfig('/etc/agent-mcp/remote.jsonc');
13
+ const layout = require('./layout.cjs');
14
+ const config = require('../dist/brain/remote-policy').readRemoteConfig(layout.configFile);
14
15
  const data = config.dataRoot,
15
- state = '/var/lib/agent-mcp/config-deploy',
16
- catalog = '/var/lib/agent-mcp/catalogs/agent-brain-config';
16
+ state = config.gitSync?.state ?? layout.state,
17
+ catalog = config.gitSync?.catalog ?? layout.catalog;
17
18
  fs.mkdirSync(state, { recursive: true, mode: 0o700 });
18
19
  // Run a Git command against the private configuration catalog.
19
20
  function git(args) {
@@ -63,7 +64,7 @@ function copyData(destination) {
63
64
  // Check staged knowledge, skills, tasks and per-repository registrations.
64
65
  function validate(candidate, selection) {
65
66
  for (const repo of selection.repositories) {
66
- const cwd = path.join('/var/lib/agent-mcp/checkouts', ...repo.id.split('/'));
67
+ const cwd = path.join(layout.checkouts, ...repo.id.split('/'));
67
68
  fs.mkdirSync(cwd, { recursive: true, mode: 0o700 });
68
69
  createProfileMarker(path.join(candidate, 'projects', repo.id));
69
70
  const store = new BrainStore(candidate, cwd);
@@ -134,7 +134,7 @@ function validateDocument(name, text) {
134
134
  if (parts.includes('todo') && scope !== 'project') throw Error('Tasks must remain per repository: ' + name);
135
135
  }
136
136
  // Collect deployable configuration and map projects to server checkout paths.
137
- function readSnapshot(root, selection, { required = true, checkouts = '/var/lib/agent-mcp/checkouts' } = {}) {
137
+ function readSnapshot(root, selection, { required = true, checkouts = '/usr/local/agent-brain/checkouts' } = {}) {
138
138
  const result = {};
139
139
  let defaultChecks;
140
140
  const defaultsName = 'agent-run.defaults.jsonc';
@@ -162,6 +162,17 @@ function readSnapshot(root, selection, { required = true, checkouts = '/var/lib/
162
162
  if (fs.existsSync(path.join(root, scope, name)))
163
163
  result[scope + '/' + name] = readFile(root, scope + '/' + name);
164
164
  }
165
+ const globalReview = 'global/review.jsonc';
166
+ if (fs.existsSync(path.join(root, globalReview))) {
167
+ const errors = [];
168
+ const text = readFile(root, globalReview), review = parseJsonc(text, errors);
169
+ if (errors.length || !review || review.backend !== 'github' ||
170
+ (review.tokenEnv !== undefined && (typeof review.tokenEnv !== 'string' || !/^[A-Z_][A-Z0-9_]*$/.test(review.tokenEnv))) ||
171
+ (review.writesEnabled !== undefined && typeof review.writesEnabled !== 'boolean') ||
172
+ Object.keys(review).some((key) => !['backend', 'tokenEnv', 'writesEnabled'].includes(key)))
173
+ throw Error('Invalid global GitHub review configuration: ' + globalReview);
174
+ result[globalReview] = text;
175
+ }
165
176
  for (const repo of selection.repositories) {
166
177
  const name = 'projects/' + repo.id + '/config.yaml';
167
178
  if (!fs.existsSync(path.join(root, name))) {
@@ -205,6 +216,15 @@ function readSnapshot(root, selection, { required = true, checkouts = '/var/lib/
205
216
  throw Error('Invalid per-repository GitHub review configuration: ' + reviewName);
206
217
  result[reviewName] = text;
207
218
  }
219
+ const standardName = 'projects/' + repo.id + '/issue-standard.jsonc';
220
+ if (fs.existsSync(path.join(root, standardName))) {
221
+ const errors = [];
222
+ const text = readFile(root, standardName);
223
+ const standard = parseJsonc(text, errors, { allowTrailingComma: true });
224
+ if (errors.length) throw Error('Invalid issue-standard.jsonc: ' + standardName);
225
+ require('../dist/brain/issue-configuration').issueStandardSchema.parse(standard);
226
+ result[standardName] = text;
227
+ }
208
228
  }
209
229
  if (fs.existsSync(path.join(root, 'brain.jsonc'))) {
210
230
  const errors = [];
package/ops/layout.cjs ADDED
@@ -0,0 +1,13 @@
1
+ 'use strict';
2
+ const path = require('node:path');
3
+ const base = '/usr/local/agent-brain';
4
+ module.exports = {
5
+ base,
6
+ configFile: path.join(base, 'conf', 'remote.jsonc'),
7
+ sshConfig: path.join(base, 'conf', 'ssh', 'config'),
8
+ catalog: path.join(base, 'brain-config'),
9
+ state: path.join(base, 'deploy'),
10
+ checkouts: path.join(base, 'checkouts'),
11
+ maintenance: path.join(base, 'run', 'config-deploy-maintenance'),
12
+ worker: path.join(base, 'current', 'node_modules', '@technomoron', 'agent-brain', 'ops', 'config-deploy.cjs')
13
+ };
package/package.json CHANGED
@@ -5,9 +5,9 @@
5
5
  },
6
6
  "author": "Bjorn Erik Jacobsen",
7
7
  "license": "MIT",
8
- "copyright": "Copyright (c) 2026 Bj\u00f8rn Erik Jacobsen / Technomoron.com",
8
+ "copyright": "Copyright (c) 2026 Bjørn Erik Jacobsen / Technomoron.com",
9
9
  "name": "@technomoron/agent-brain",
10
- "version": "0.1.3",
10
+ "version": "0.1.4",
11
11
  "description": "Project knowledge and skills MCP server extracted from agent-run",
12
12
  "bin": {
13
13
  "agent-brain": "dist/agent-brain.js",
@@ -28,14 +28,16 @@
28
28
  "test": "pnpm build && pnpm test:integration",
29
29
  "prepack": "pnpm build",
30
30
  "test:integration": "node scripts/test.cjs",
31
- "release:preflight": "pnpm build && pnpm test:integration"
31
+ "release:preflight": "pnpm build && pnpm test:integration",
32
+ "release:check": "node ../../scripts/release.cjs check agent-brain",
33
+ "release": "node ../../scripts/release.cjs tag agent-brain"
32
34
  },
33
35
  "dependencies": {
34
36
  "@modelcontextprotocol/sdk": "^1.30.0",
35
37
  "@technomoron/apicore-server": "^1.1.0",
36
38
  "yaml": "^2.9.0",
37
39
  "zod": "^4.5.4",
38
- "@technomoron/agent-run": "^0.99.46",
40
+ "@technomoron/agent-run": "^0.99.48",
39
41
  "jsonc-parser": "^3.3.1"
40
42
  },
41
43
  "devDependencies": {
@@ -45,9 +47,10 @@
45
47
  },
46
48
  "repository": {
47
49
  "type": "git",
48
- "url": "git+https://github.com/technomoron/agent-brain.git"
50
+ "url": "git+https://github.com/technomoron/agent-brain.git",
51
+ "directory": "packages/agent-brain"
49
52
  },
50
- "homepage": "https://github.com/technomoron/agent-brain#readme",
53
+ "homepage": "https://github.com/technomoron/agent-brain/tree/main/packages/agent-brain#readme",
51
54
  "bugs": {
52
55
  "url": "https://github.com/technomoron/agent-brain/issues"
53
56
  },
@@ -1,6 +1,6 @@
1
- # code-review
1
+ # Code review
2
2
 
3
- Review code using project context from brain. Track findings as GitHub issues with type `Code Review`, issue-number identities, category labels, a Severity field, evidence, and verified closure.
3
+ Review code using project context from Brain. Track findings in GitHub Issues with origin label `Code Review`, a work type, Priority, evidence and verified closure.
4
4
 
5
5
  Use for a new review or follow-up on an existing issue. GitHub is the only findings tracker for this workflow.
6
6
 
@@ -3,24 +3,56 @@ name: code-review
3
3
  description: Review code and track actionable findings as GitHub issues; follow up on existing issues and verify fixes.
4
4
  ---
5
5
 
6
- Use brain for project constraints and context; use GitHub Issues as the record of findings.
6
+ GitHub Issues in the affected repository are the sole authoritative record of review findings, discussion, status and resolution. Read the current issue before follow-up and resolve conflicting copies in favor of GitHub. Never persist findings or duplicate issue backlogs in Brain knowledge/reviews/todos, local Markdown files, review archives or another tracker. Do not use a Brain review-write tool unless its configured backend is verified to write directly to the same GitHub repository. If GitHub is unavailable or saving is unauthorized, report findings only in the reply and clearly state they are unsaved; do not create a fallback store.
7
+
8
+ Use Brain for project constraints, specifications and reusable knowledge, not issue records. A confirmed general lesson may be saved under the memory workflow, with a link to the GitHub issue, but must not copy the finding or maintain its status elsewhere.
9
+
10
+ Use Brain MCP for issue handling in the affected repository. List with `issue_list(origin="Code Review")`, paginate all relevant states, read with `issue_get` and paginate discussion with `issue_comments`. Create with `issue_create` (origin, type, Priority and a stable retry key), edit with `issue_update` using the current revision, and discuss with `issue_comment` or `issue_comment_update`. Close/reopen using `issue_update` state and state_reason. These tools write ordinary GitHub issues without a managed review block. Only when the required Brain backend or capability is unavailable, disclose that limitation and use the connector or `gh` as an explicit fallback. Never bypass permission or scope denials.
11
+
12
+ Use `issue_search` for duplicate searches with structured origin/type/Priority filters; use `issue_metadata` to inspect definitions. Link follow-ups through `issue_relations`/`issue_relation_update` where supported. Configuration alignment requires explicit authorization: obtain `issue_config_preview`, review affected issues and organisation-wide usage, resolve mapping blockers, then apply with `issue_config_reconcile` using the exact preview revision. No setup skill or local GitHub credentials are required; never bypass a scope, permission or outside-usage blocker.
7
13
 
8
14
  1. Confirm the repository and requested review scope. Retrieve relevant brain context, inspect the changes, and run checks that help verify suspected defects.
9
- 2. Retrieve open GitHub issues with type `Code Review` by default. Search closed issues and other types when relevant to prior decisions, regressions or duplicate detection. Read matching issues and update the existing issue when it describes the same problem.
15
+ 2. Retrieve open GitHub issues with origin label `Code Review` by default. Search closed issues and other types when relevant to prior decisions, regressions or duplicate detection. Read matching issues and update the existing issue when it describes the same problem.
10
16
  3. Report actionable defects with severity, evidence, affected file links, and reproduction or verification steps. Distinguish confirmed failures from suspected risks.
11
- 4. When authorized to save findings, use the available GitHub connector or `gh` to create or update ordinary issues. Use GitHub issue numbers as permanent identities instead of H1/M1 numbering. Keep titles descriptive and use category labels such as bug or enhancement. Set an organization-level Severity field with Critical, High, Medium and Low options when available; create it when missing and authorized with the required permissions. If the field is unavailable or cannot be configured, create any missing `severity:critical`, `severity:high`, `severity:medium`, and `severity:low` repository labels and apply the matching label to each finding. Authorization to save findings includes creating and applying these fallback labels. If permissions prevent this, report the failed operation and retain severity in the issue body. Put evidence in the issue body and preserve unrelated content and discussion. Do not create a second brain record or private metadata block.
12
- 5. For follow-up, read the current issue and relevant code. After an authorized fix passes relevant checks, record the verification and close the issue as completed. Close as not planned only on the user's decision; deferral leaves it open. Keep resolved issues for history; do not delete them.
17
+ 4. When authorized to save findings, use Brain MCP `issue_create` or `issue_update` to create or update ordinary GitHub issues; direct GitHub access is only the disclosed fallback described above. Use GitHub issue numbers as permanent identities instead of H1/M1 numbering. Keep titles descriptive and classify origin and work type separately as specified below. Use the existing organization-level `Priority` issue field with `Urgent`, `High`, `Medium` and `Low` options. Map critical severity to `Urgent`, and high, medium and low severity to the corresponding Priority values. Do not create a separate Severity field or severity/priority labels. If the Priority field cannot be read or set, report the failed operation and retain the assessed severity and intended Priority in the issue body. Put evidence in the issue body and preserve unrelated content and discussion. Do not create a second brain record or private metadata block.
18
+ 5. For follow-up, read the current issue and relevant code. After an authorized fix passes relevant checks, add an issue fix comment and close the issue as completed. This applies whether a person or AI made the fix. Close as not planned only on the user's decision; deferral leaves it open. Keep resolved issues for history; do not delete them.
19
+
20
+ Write issue fix comments as a concise bullet list. Each item states what was fixed and links to the corresponding commit. Optionally append the version in parentheses. A single concise note at the bottom may describe how the fix was tested. Do not include headings, introductions, conclusions, deployment status, or unrelated outstanding work. Do not label the list “TL;DR”.
21
+
22
+ Example:
23
+
24
+ - Keep content centered when sidebar ads are missing. [7742e93](commit-url) (1.0.46-rc.1)
25
+
26
+ End each actual code review finding's issue body or review note with this attribution on its own final line:
27
+
28
+ `Reported by: <agent> (<provider> <model> <reasoning>)`
13
29
 
14
- Set review findings to issue type `Code Review`, never `Feature`, including findings labeled `enhancement`. Feature requests belong to todo-manager with type `Feature`. Create the organization-level `Code Review` type when missing and authorized with the required permissions. If issue types are unavailable, report the limitation; do not silently substitute a label or classify a review as a feature.
30
+ Example: `Reported by: Codex (OpenAI gpt-6.1-sol default)`
15
31
 
16
- Use these standard labels where applicable:
32
+ Use the reporting agent's name, provider, exact model identifier and reasoning setting. Use `default` only when the default reasoning setting is known to apply; use `unknown` for any unavailable value rather than guessing. Attribute delegated findings to the agent and model that reported them. This attribution applies only to the text reporting a review finding, never to fix comments, resolution notes or other content. It never overrides any other restriction on AI mentions, agent authorship or coauthors; if an applicable restriction prohibits this attribution, omit it.
17
33
 
18
- - `bug`: incorrect behavior; `enhancement`: an improvement or new capability; `documentation`: documentation changes; `question`: clarification needed.
19
- - `duplicate`: an existing issue already tracks the finding; link that issue. `invalid`: the reported problem is not valid. `wontfix`: the user decided not to address it.
20
- - `help wanted`: outside help is requested; `good first issue`: a bounded task suitable for a newcomer.
34
+ When an authorized second opinion differs about an existing review issue, add a separate comment to that issue explaining the differing assessment and supporting evidence. Preserve the original finding and discussion. End the comment with the same attribution format, identifying the agent and model giving the second opinion, subject to the same AI mention restrictions. Do not treat disagreement alone as a fix or close the issue automatically.
21
35
 
22
- Reuse existing equivalent labels and create missing standard labels only when authorized with the required permissions. Apply only relevant labels and preserve unrelated labels. Keep severity in the Severity field when available; otherwise use the matching `severity:*` label as required above.
36
+ Classify issues using three independent fields:
37
+
38
+ | Field | Allowed values | Rule |
39
+ | --- | --- | --- |
40
+ | Origin label | `Code Review`, `Bug Report`, `Feature Request`, `ToDo`, `Question` | Exactly one of these labels per issue. |
41
+ | Issue type | `Bug`, `Security`, `Feature`, `Task`, `Inconsistency`, `Question`, `Documentation` | Exactly one; describes the work, not its origin. |
42
+ | Priority | `Urgent`, `High`, `Medium`, `Low` | Existing organization issue field, independent of origin and type. |
43
+
44
+ A defect discovered during review has label `Code Review` and type `Bug`; a user-reported defect has label `Bug Report` and type `Bug`. Use type `Security` for vulnerabilities or security weaknesses, including authentication or authorization failures, credential exposure and unsafe handling of untrusted input. Keep the origin label and Priority independent; do not add a security label or combine issue types. A requested capability has label `Feature Request` and type `Feature`. A manual task or follow-up task created while fixing a review finding has label `ToDo` and type `Task`; link follow-ups to their original issue. A review finding about contradictory behavior or configuration may use type `Inconsistency`. Work to correct or improve documentation uses type `Documentation`. A question has origin label `Question` and type `Question` unless it originated in a review, in which case retain origin `Code Review`.
45
+
46
+ Do not use `Code Review` as an issue type. Do not combine origin labels. Do not add category labels such as `bug` or `enhancement` that duplicate the work type. The five origin labels are the entire allowed label set. Do not create or apply additional labels unless the user explicitly requests them. Close as not planned only on the user's decision.
47
+
48
+ Use the code-review skill for review findings and todo-manager for feature requests and tasks. Filter review lists by origin label `Code Review`, and feature-request lists by origin label `Feature Request`; type `Feature` alone can also include improvements discovered during review.
49
+
50
+ Keep assessed defect severity in the finding text and map critical severity to Priority `Urgent`, with high/medium/low mapping to the corresponding Priority value. Do not create a parallel Severity field or severity/priority label system. Inspect available types, fields and labels before saving. Create missing origin labels and work types when authorized with the required permissions; report unavailable capabilities rather than silently substituting a different scheme.
51
+
52
+ Read back saved issues and verify exactly one origin label, the work type and Priority. Report any permission or API limitation explicitly; body text is only a disclosed fallback when Priority cannot be set. During authorized follow-up, check classification too. Do not reclassify unrelated backlog or remove existing fields or labels without authorization.
23
53
 
24
54
  Report findings and issue links relevant to the requested scope, checks performed, and limitations. Reassess unrelated backlog only when requested. GitHub owns issue history; no separate review files, archive, or severity-based numbering is needed.
25
55
 
26
56
  A request to review code permits inspection and a report; it does not itself authorize creating GitHub issues. Reuse authorization already given. If GitHub access is unavailable, report findings in the reply and state that they were not saved. Do not silently switch to the legacy brain review backend. Historical C1/H1 references require locating the old record; they are not GitHub issue numbers.
57
+
58
+ The listed origin labels, work types and Priority options are exhaustive. Do not create or use additional values unless the user explicitly requests them. When authorized to align repositories, remove obsolete entries; check organization-wide entries for use outside the authorized repositories before removal.
@@ -1,5 +1,5 @@
1
- # todo-manager
1
+ # Todo manager
2
2
 
3
- Track feature requests and planned work in GitHub Issues. Use issue types to keep features, tasks and code-review findings separate.
3
+ Track feature requests and planned work in GitHub Issues. Use one origin label, one work type and the existing Priority field.
4
4
 
5
5
  [Agent instructions](SKILL.md)
@@ -3,12 +3,16 @@ name: todo-manager
3
3
  description: Track feature requests and planned work in GitHub Issues without a separate local todo list.
4
4
  ---
5
5
 
6
- Use GitHub Issues in the affected repository as the task backlog. Use the available GitHub connector or `gh`; do not create a separate local todo list or duplicate brain task records.
6
+ Use Brain MCP for all todo and issue handling, with GitHub Issues in the affected repository as the authoritative backlog. Use Brain's ordinary `issue_*` tools, not the local `todo_*` store. Use `issue_list` (paginate open and closed issues), `issue_get`, `issue_create`, `issue_update`, `issue_comments`, `issue_comment` and `issue_comment_update`. Supply origin, type and Priority on creation; reuse retry keys and read current revisions before edits. Comments paginate separately. Close/reopen through `issue_update`. Only when the required Brain backend or capability is unavailable, disclose that limitation and use the GitHub connector or `gh` as an explicit fallback. Never bypass permission or scope denials. Never create a separate local todo list or duplicate brain task records.
7
+
8
+ Use `issue_search` for literal text and structured filters, `issue_metadata` for available definitions/assignees/milestones, and `issue_relations`/`issue_relation_update` for parents, sub-issues and dependencies. For explicitly authorized configuration alignment, call `issue_config_preview`, review changes, affected issues and blockers, then call `issue_config_reconcile` with the same settings, preview revision and confirmation. Supply explicit migration mappings for ambiguous values; do not bypass outside-usage or permission blockers. Brain performs this workflow through its server-held GitHub credential without an LLM or local GitHub login.
7
9
 
8
10
  1. Confirm the repository and requested task. Retrieve open issues of the relevant type by default; search existing open and closed issues before creating a request to avoid duplicates.
9
11
  2. Create or update issues only when requested or authorized by the current workflow. Use issue numbers as permanent IDs, descriptive titles, and clear requirements or acceptance criteria. Read the current issue before updates and preserve unrelated content and discussion.
10
- 3. Set feature requests to issue type `Feature` with the `enhancement` label. Use `Task` for other planned work. Create missing types or labels only when authorized with the required permissions; report unavailable capabilities rather than silently substituting a local list.
11
- 4. Code review findings use type `Code Review`, never `Feature`; use the code-review skill for that workflow. Filter feature-request lists by type `Feature` so review findings remain separate even when they have an `enhancement` label.
12
+ 3. Use exactly one origin label: `Feature Request` for a requested capability, `ToDo` for a manually added task or a follow-up task triggered by a review issue fix, `Bug Report` for a reported defect, `Question` for a question, or `Code Review` for a review finding. Link review-fix follow-up tasks to the original issue.
13
+ 4. Set exactly one work type independently of origin: `Bug`, `Security`, `Feature`, `Task`, `Inconsistency`, `Question` or `Documentation`. A feature request normally has type `Feature`; a manual or follow-up task normally has type `Task`. `Code Review` is an origin label, never an issue type. Do not add `bug` or `enhancement` category labels that duplicate type. The five origin labels are the entire allowed label set; do not create or apply additional labels unless the user explicitly requests them. Use the existing `Priority` field (`Urgent`, `High`, `Medium`, `Low`), without creating severity/priority labels or a separate Severity field. Create missing origin labels or work types only when authorized with the required permissions. Read back origin, type and Priority after saving and report unavailable capabilities. Use code-review for review findings. Filter feature-request lists by origin label `Feature Request`, not type alone.
12
14
  5. Leave unfinished or deferred requests open. After an authorized implementation passes relevant checks, record verification and close the issue as completed. Close as not planned only on the user's decision. Preserve closed issues for history rather than deleting them.
13
15
 
14
16
  A request to do work does not by itself authorize creating a saved task or GitHub issue. Reuse authorization already given. Do not migrate or delete existing local tasks without authorization. If GitHub is unavailable, report the limitation and unsaved requests in the reply.
17
+
18
+ The listed origin labels, work types and Priority options are exhaustive. Do not create or use additional values unless the user explicitly requests them. When authorized to align repositories, remove obsolete entries; check organization-wide entries for use outside the authorized repositories before removal.
@@ -80,7 +80,10 @@ follow-up. Never use "cleanup" to justify fixing unrelated bugs.
80
80
  Keep intentionally independent contracts separate: an external DTO may correctly remain
81
81
  separate from an internal model even when their fields happen to match today.
82
82
 
83
- 8. **Comments that restate the code.** Keep comments explaining domain rules, invariants,
83
+ 8. **Comments that restate the code.** Add or keep a concise TL;DR-style comment
84
+ immediately above every method and function in the cleanup scope, describing what it
85
+ does. Prefer one line. Preserve these summaries when removing redundant comments.
86
+ Keep comments explaining domain rules, invariants,
84
87
  compatibility constraints, incident-derived defensive behavior, or why odd-looking code
85
88
  has to stay.
86
89