@technomoron/agent-brain 0.1.3 → 0.1.6
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 +15 -0
- package/README.md +141 -136
- package/dist/brain/cli.js +12 -43
- package/dist/brain/config.js +1 -0
- package/dist/brain/github-client.js +78 -0
- package/dist/brain/github-issues.js +332 -0
- package/dist/brain/issue-configuration-tools.js +29 -0
- package/dist/brain/issue-configuration.js +398 -0
- package/dist/brain/issue-tools.js +61 -0
- package/dist/brain/remote-policy.js +7 -6
- package/dist/brain/remote-server.js +108 -19
- package/dist/brain/repository-discovery.js +36 -2
- package/dist/brain/server.js +11 -63
- package/dist/brain/skills.js +18 -5
- package/dist/brain/todos.js +3 -99
- package/ops/config-deploy-entry.sh +1 -1
- package/ops/config-deploy-root.cjs +8 -6
- package/ops/config-deploy.cjs +7 -6
- package/ops/config-policy.cjs +23 -1
- package/ops/layout.cjs +13 -0
- package/package.json +9 -6
- package/skills/brain-memory/SKILL.md +5 -5
- package/skills/changelog/SKILL.md +25 -0
- package/skills/code-review/README.md +2 -2
- package/skills/code-review/SKILL.md +48 -12
- package/skills/git-workflow/SKILL.md +12 -2
- package/skills/github-issue-cleanup/SKILL.md +20 -0
- package/skills/github-release/SKILL.md +14 -0
- package/skills/package-integrity-check/SKILL.md +3 -2
- package/skills/todo-manager/README.md +2 -2
- package/skills/todo-manager/SKILL.md +11 -5
- package/skills/unslop/SKILL.md +4 -1
- package/dist/brain/connectors.js +0 -65
- package/dist/brain/github-reviews.js +0 -187
package/ops/config-policy.cjs
CHANGED
|
@@ -31,6 +31,8 @@ const coreSkills = new Set([
|
|
|
31
31
|
'brain-consolidate',
|
|
32
32
|
'code-review',
|
|
33
33
|
'git-workflow',
|
|
34
|
+
'changelog',
|
|
35
|
+
'github-release',
|
|
34
36
|
'package-integrity-check',
|
|
35
37
|
'node-cleanup',
|
|
36
38
|
'unslop',
|
|
@@ -134,7 +136,7 @@ function validateDocument(name, text) {
|
|
|
134
136
|
if (parts.includes('todo') && scope !== 'project') throw Error('Tasks must remain per repository: ' + name);
|
|
135
137
|
}
|
|
136
138
|
// Collect deployable configuration and map projects to server checkout paths.
|
|
137
|
-
function readSnapshot(root, selection, { required = true, checkouts = '/
|
|
139
|
+
function readSnapshot(root, selection, { required = true, checkouts = '/usr/local/agent-brain/checkouts' } = {}) {
|
|
138
140
|
const result = {};
|
|
139
141
|
let defaultChecks;
|
|
140
142
|
const defaultsName = 'agent-run.defaults.jsonc';
|
|
@@ -162,6 +164,17 @@ function readSnapshot(root, selection, { required = true, checkouts = '/var/lib/
|
|
|
162
164
|
if (fs.existsSync(path.join(root, scope, name)))
|
|
163
165
|
result[scope + '/' + name] = readFile(root, scope + '/' + name);
|
|
164
166
|
}
|
|
167
|
+
const globalReview = 'global/review.jsonc';
|
|
168
|
+
if (fs.existsSync(path.join(root, globalReview))) {
|
|
169
|
+
const errors = [];
|
|
170
|
+
const text = readFile(root, globalReview), review = parseJsonc(text, errors);
|
|
171
|
+
if (errors.length || !review || review.backend !== 'github' ||
|
|
172
|
+
(review.tokenEnv !== undefined && (typeof review.tokenEnv !== 'string' || !/^[A-Z_][A-Z0-9_]*$/.test(review.tokenEnv))) ||
|
|
173
|
+
(review.writesEnabled !== undefined && typeof review.writesEnabled !== 'boolean') ||
|
|
174
|
+
Object.keys(review).some((key) => !['backend', 'tokenEnv', 'writesEnabled'].includes(key)))
|
|
175
|
+
throw Error('Invalid global GitHub review configuration: ' + globalReview);
|
|
176
|
+
result[globalReview] = text;
|
|
177
|
+
}
|
|
165
178
|
for (const repo of selection.repositories) {
|
|
166
179
|
const name = 'projects/' + repo.id + '/config.yaml';
|
|
167
180
|
if (!fs.existsSync(path.join(root, name))) {
|
|
@@ -205,6 +218,15 @@ function readSnapshot(root, selection, { required = true, checkouts = '/var/lib/
|
|
|
205
218
|
throw Error('Invalid per-repository GitHub review configuration: ' + reviewName);
|
|
206
219
|
result[reviewName] = text;
|
|
207
220
|
}
|
|
221
|
+
const standardName = 'projects/' + repo.id + '/issue-standard.jsonc';
|
|
222
|
+
if (fs.existsSync(path.join(root, standardName))) {
|
|
223
|
+
const errors = [];
|
|
224
|
+
const text = readFile(root, standardName);
|
|
225
|
+
const standard = parseJsonc(text, errors, { allowTrailingComma: true });
|
|
226
|
+
if (errors.length) throw Error('Invalid issue-standard.jsonc: ' + standardName);
|
|
227
|
+
require('../dist/brain/issue-configuration').issueStandardSchema.parse(standard);
|
|
228
|
+
result[standardName] = text;
|
|
229
|
+
}
|
|
208
230
|
}
|
|
209
231
|
if (fs.existsSync(path.join(root, 'brain.jsonc'))) {
|
|
210
232
|
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
|
|
8
|
+
"copyright": "Copyright (c) 2026 Bjørn Erik Jacobsen / Technomoron.com",
|
|
9
9
|
"name": "@technomoron/agent-brain",
|
|
10
|
-
"version": "0.1.
|
|
10
|
+
"version": "0.1.6",
|
|
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.
|
|
40
|
+
"@technomoron/agent-run": "^0.99.49",
|
|
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
|
},
|
|
@@ -15,7 +15,7 @@ Remote Brain source paths identify server files, not paths on the client filesys
|
|
|
15
15
|
|
|
16
16
|
Do not create, edit, rename, move, or delete files inside the agent-run configuration directory yourself whenever a brain tool can do it. The tools keep the metadata, ids, revisions, index, and write lock consistent; direct file writes bypass those checks and can leave individual records unreadable.
|
|
17
17
|
|
|
18
|
-
Use remember to add knowledge, amend_knowledge to revise it, deprecate_knowledge to retire it, promote to copy it to another scope,
|
|
18
|
+
Use remember to add knowledge, amend_knowledge to revise it, deprecate_knowledge to retire it, promote to copy it to another scope, issue_update to close a GitHub review issue, and the bundled todo-manager workflow for tasks. If you want a specific file name, pass filename to remember rather than writing or renaming the file afterwards; the id in the front matter is the identity, so the name is free to change but the tools should be the ones changing it.
|
|
19
19
|
|
|
20
20
|
This covers generated runtime state as well: never hand-edit anything under a profile's live/ directory. Regenerate it with agent-run instead.
|
|
21
21
|
|
|
@@ -54,13 +54,13 @@ Do not begin a historical import merely because a correction was saved.
|
|
|
54
54
|
|
|
55
55
|
Use remember for durable knowledge when the user asks to remember it or authorizes a workflow that records it. Use global scope only for explicit intent that applies everywhere; otherwise use the active project or default scope. Preserve uncertainty with authority=inferred and type=observation. Never persist secrets, raw transcripts, or temporary task state. Load complete skills with get_skill when needed. Promotion requires explicit confirmation.
|
|
56
56
|
|
|
57
|
-
Search before writing so you do not create a near-duplicate. When existing knowledge is nearly right, amend it with amend_knowledge and its last-read revision instead of adding a second item that says almost the same thing. Amending keeps the id, file name, and history; scope, type,
|
|
57
|
+
Search before writing so you do not create a near-duplicate. When existing knowledge is nearly right, amend it with amend_knowledge and its last-read revision instead of adding a second item that says almost the same thing. Amending keeps the id, file name, and history; scope, type, and authority are deliberately not amendable, so if one of those is wrong, deprecate the item and write a corrected one.
|
|
58
58
|
|
|
59
|
-
Choose the knowledge type by content: preferences for user choices, constraints for requirements, conventions for established practices, decisions for confirmed choices, specs for confirmed specifications,
|
|
59
|
+
Choose the knowledge type by content: preferences for user choices, constraints for requirements, conventions for established practices, decisions for confirmed choices, specs for confirmed specifications, memory for durable reference and history, and observations for code-derived facts or deductions. Rules use type=rule. Only explicit user instructions or confirmation justify authority=user; an import request alone does not make source documents authoritative. MCP maps the singular type to the matching storage directory, so pass scope and type rather than choosing a file path.
|
|
60
60
|
|
|
61
|
-
Use the bundled code-review skill for
|
|
61
|
+
Use review_context for review guidance and the bundled code-review skill for reporting, severity mapping, attribution, validation and resolution. Use issue_* tools for findings and history. Track new findings in GitHub Issues; do not create duplicate brain knowledge records.
|
|
62
62
|
|
|
63
|
-
Use the bundled todo-manager skill for tasks and
|
|
63
|
+
Use the bundled todo-manager skill and issue_* tools for tasks; manual todos use origin ToDo, normally type Task, and Priority. Preserve external identities and historical task data. Reusable workflows belong in skills/<name>/SKILL.md; actual reusable templates belong in templates/. These are separate from knowledge items, and remember does not install skills or templates. Keep source references and distinguish current behavior from historical notes and planned features. Keep project-specific content in project scope; default is only for work outside configured projects.
|
|
64
64
|
|
|
65
65
|
Pool scope: `global/` is server-wide, `pools/<name>/` is shared by the active pool, and `projects/<owner>/<repo>/` belongs to one repository. Use `scope: pool` only for deliberately shared pool knowledge. Keep review findings and tasks in their individual repository. Global intent must still be explicit.
|
|
66
66
|
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: changelog
|
|
3
|
+
description: Create, update or validate CHANGES and CHANGES.md entries and formatting, including release notes.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Changelog
|
|
7
|
+
|
|
8
|
+
Use the configured changelog path in the active working tree; otherwise use the package-local CHANGES.md or CHANGES. Use CHANGES.md for new changelogs, preserve an existing CHANGES filename, and never keep both in one package.
|
|
9
|
+
|
|
10
|
+
Use this format for a new changelog:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
CHANGES
|
|
14
|
+
========
|
|
15
|
+
|
|
16
|
+
vX.Y.Z (YYYY-MM-DD)
|
|
17
|
+
-------------------
|
|
18
|
+
* Concise description of the change.
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Keep a blank line between headings and entries. Underline the title with equals signs and version headings with dashes. Put the newest version first, use ISO dates and `*` bullets, and keep entries to the minimum useful description of changed behavior. Group related changes; omit implementation narration.
|
|
22
|
+
|
|
23
|
+
Preserve an existing `Version X.Y.Z (YYYY-MM-DD)` heading convention and historical entries. For package releases, the newest version must match package.json and its date must be the release date. Do not invent a release version or date for unreleased work.
|
|
24
|
+
|
|
25
|
+
Before pushing, ensure the relevant changelog covers the changes. If it is missing, report that and ask to create it unless creation is already authorized. Updating release notes does not authorize version bumps, commits, tags, pushes, publishing or GitHub Releases; use github-release for release work.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Code review
|
|
2
2
|
|
|
3
|
-
Review code using project context from
|
|
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,60 @@ 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
|
|
6
|
+
Use GitHub Issues for code reviews by default unless the user explicitly states otherwise. 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. Use the ordinary `issue_*` tools for review tracking; the legacy review tracking API is retired. 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
7
|
|
|
8
|
-
|
|
9
|
-
|
|
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. Use Brain MCP exclusively for issue reads, searches, metadata, comments and writes, and `list_repositories` for repository discovery. Do not use `gh` or a direct GitHub connector for these operations without explicit user approval for that fallback. If Brain lacks a capability, disclose the limitation and ask before using a fallback; unavailable tools alone are not approval. 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. For repository label, work type and Priority cleanup, discover and load `github-issue-cleanup` with `list_skills`/`get_skill`.
|
|
13
|
+
|
|
14
|
+
For findings spanning related repositories, use `list_repositories` to check accessible destinations. Explain the proposed issues and ask before creating them in additional repositories. After confirmation, select each affected repository, check for duplicates, create its issue and cross-link related issues. Access alone is not authorization; keep each repository’s backlog separate.
|
|
15
|
+
|
|
16
|
+
An authorized request to file an issue, including the default code-review workflow, also authorizes creating its missing allowed origin label in that repository. Inspect labels with `issue_metadata`; if the required label is absent, call `issue_label_ensure(origin=..., confirmed=true)` and verify the result, then create the issue. If `issue_create` reports a missing label, check for an existing issue before retrying with the same key and content. This authorization covers only the required label, not reconciliation, label deletion, existing issue migration or organisation types/fields. Ask separately for missing organisation definitions and broader cleanup; do not run `issue_config_reconcile` merely to unblock filing.
|
|
17
|
+
|
|
18
|
+
1. Confirm the repository and requested review scope. Use `review_context` for constraints, decisions and path-specific knowledge; use `issue_list`/`issue_search` and `issue_comments` for findings and discussion. Inspect the changes, and run checks that help verify suspected defects.
|
|
19
|
+
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
20
|
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
|
|
12
|
-
5. For follow-up, read the current issue and relevant code.
|
|
21
|
+
4. When authorized to save findings, use Brain MCP `issue_create` or `issue_update` to create or update ordinary GitHub issues; direct GitHub access requires the explicit fallback approval 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.
|
|
22
|
+
5. For follow-up, read the current issue and relevant code. For an explicit request such as “Fix issue #14”, load git-workflow and make one atomic commit per issue (one per affected repository for a cross-repository fix), including the relevant tests and no unrelated changes. The request authorizes those commits, pushing them to the existing upstream, and the fix comment/closure unless the user says otherwise; opening a PR still requires authorization. Follow git-workflow to fetch and, when behind or diverged, try to pull before committing without automatic rebasing. Verify the push before linking the commit and closing; a failed push leaves the issue open. Run relevant checks after the fix and any pull/merge, before committing and pushing. Follow git-workflow’s validation and closure gates, including its limited heads-up exception; add the linked fix comment before closing through `issue_update`, then read back the comment and closed state. Never close an unfinished fix. 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.
|
|
23
|
+
|
|
24
|
+
Write issue fix comments as a concise bullet list. Each item states what was fixed and links to the corresponding commit or PR. 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”.
|
|
25
|
+
|
|
26
|
+
Example:
|
|
27
|
+
|
|
28
|
+
- Keep content centered when sidebar ads are missing. [7742e93](commit-url) (1.0.46-rc.1)
|
|
29
|
+
|
|
30
|
+
End each actual code review finding's issue body or review note with this attribution on its own final line:
|
|
13
31
|
|
|
14
|
-
|
|
32
|
+
`Reported by: <agent> (<provider> <model> <reasoning>)`
|
|
15
33
|
|
|
16
|
-
|
|
34
|
+
Example: `Reported by: Codex (OpenAI gpt-6.1-sol default)`
|
|
17
35
|
|
|
18
|
-
|
|
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.
|
|
36
|
+
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.
|
|
21
37
|
|
|
22
|
-
|
|
38
|
+
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.
|
|
39
|
+
|
|
40
|
+
Classify issues using three independent fields:
|
|
41
|
+
|
|
42
|
+
| Field | Allowed values | Rule |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| Origin label | `Code Review`, `Bug Report`, `Feature Request`, `ToDo`, `Question` | Exactly one of these labels per issue. |
|
|
45
|
+
| Issue type | `Bug`, `Security`, `Feature`, `Task`, `Inconsistency`, `Question`, `Documentation` | Exactly one; describes the work, not its origin. |
|
|
46
|
+
| Priority | `Urgent`, `High`, `Medium`, `Low` | Existing organization issue field, independent of origin and type. |
|
|
47
|
+
|
|
48
|
+
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`.
|
|
49
|
+
|
|
50
|
+
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.
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
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 the required missing origin label with `issue_label_ensure` under the filing authorization above; organisation work types require separate authorization and permissions; report unavailable capabilities rather than silently substituting a different scheme.
|
|
55
|
+
|
|
56
|
+
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
57
|
|
|
24
58
|
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
59
|
|
|
26
|
-
A request to review code
|
|
60
|
+
A request to review code uses GitHub Issues for actionable findings in the reviewed repository by default, unless the user requests a report only or otherwise overrides this workflow. Ask before filing in additional repositories. Reuse authorization already given. If GitHub access is unavailable, report findings in the reply and state that they were not saved. Do not fall back to local review storage. Historical C1/H1 references require locating the old record; they are not GitHub issue numbers.
|
|
61
|
+
|
|
62
|
+
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,14 +1,24 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: git-workflow
|
|
3
|
-
description: Inspect Git changes,
|
|
3
|
+
description: Inspect Git changes, commit and push within authorization; make atomic commits for explicit issue-fix requests.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
Before every commit, inspect the branch, upstream, status and diff. Fetch the upstream and check whether the branch is ahead, behind or diverged. If out of sync because it is behind or diverged, try to pull before committing. Use `git pull --ff-only` when a fast-forward is possible; for divergence, inspect both histories and use an appropriate merge-based pull (`git pull --no-rebase`) when safe. Never rebase indiscriminately, force-push or rewrite shared history. Preserve local work; if it prevents a safe pull or conflicts remain, report the blocker instead of committing over an unsynchronized branch. If only ahead, no pull is needed. If there is no upstream or fetch/pull fails, disclose that before proceeding.
|
|
7
|
+
|
|
6
8
|
Inspect status and the diff before staging. Preserve unrelated work; stage only the authorized scope unless the user explicitly asks to commit everything.
|
|
7
9
|
|
|
8
|
-
|
|
10
|
+
An explicit request such as “Fix issue #14” authorizes one atomic commit for that issue, including its relevant tests. Keep separate issues in separate commits and exclude unrelated changes. For a cross-repository fix, make a separate commit for the issue in each affected repository. Read the issue first and identify it with a neutral reference such as `Refs acme/catalog-api#14` in the commit message. Do not use GitHub auto-closing keywords (fix/fixes/fixed, close/closes/closed, resolve/resolves/resolved followed by an issue reference) in commit messages or PR titles/descriptions; closure must follow the fix comment and checks through `issue_update`. The request also authorizes pushing the issue commit to the existing upstream and linking it to the issue before closure. Opening a PR, tagging, publishing or releasing still requires authorization; follow any explicit user override.
|
|
11
|
+
|
|
12
|
+
Do not commit, push, tag, publish, or release without user authorization, including the issue-fix authorization above. Reuse authorization already given; do not ask again for the same action. Before committing, show the changed files and exact commit message. Use the release skills for versioning, publishing and releases.
|
|
9
13
|
|
|
10
14
|
Write short, plain commit messages without category prefixes unless requested or required by the project. Never add AI-related attribution or mentions to commit messages or source code, and never add agent author or coauthor identities. Preserve the user's configured Git identity.
|
|
11
15
|
|
|
12
16
|
Keep agent configuration and generated runtime files outside project repositories. Do not stage agent-only files or add agent-only ignore entries. Follow the global agent-file-storage constraint when available.
|
|
13
17
|
|
|
14
18
|
Run configured project checks and relevant tests before committing. Resolve failures or clearly report blockers; do not claim unrun checks passed. For an authorized push, inspect the branch and upstream, push without rewriting shared history, and verify the result. Report commit IDs, push status, and any remaining changes.
|
|
19
|
+
|
|
20
|
+
For an issue fix, use this order: finish the fix and any pull/merge, run relevant checks on the final changes, commit, push and verify the remote commit, add the linked bullet-list fix comment, then close through Brain MCP `issue_update` using the current revision. Read back the comment and closed state. If code changes after testing, rerun the affected checks before committing or pushing. A failed push leaves the issue open.
|
|
21
|
+
|
|
22
|
+
A heads-up about checks is an exception for unavailable checks or demonstrated unrelated failures when other evidence verifies the issue's acceptance criteria. Give the user that explanation before committing/pushing and record it in the fix comment before closure. Failing checks caused by the fix, unmet acceptance criteria or uncertainty whether the issue is fixed keep the issue open; a heads-up alone does not make an incomplete fix complete. Never claim unrun or failing checks passed. Follow an explicit user decision to defer closure.
|
|
23
|
+
|
|
24
|
+
Use code-review for review findings and todo-manager for other issues; preserve their existing resolution mechanism and concise bullet-list fix-comment format. Use Brain MCP for issue handling; `gh` and direct GitHub connectors require explicit user approval even for read-only fallback checks.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: github-issue-cleanup
|
|
3
|
+
description: Inspect and reconcile GitHub repository labels, issue types and Priority definitions, migrating existing issues. Use for issue configuration cleanup or alignment.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Use Brain MCP in the selected repository. This skill is available through `list_skills` and `get_skill`, including discovery before repository selection. Select the intended repository before calling its `issue_*` tools. Ordinary issue edits belong to todo-manager or code-review.
|
|
7
|
+
|
|
8
|
+
For a missing origin label needed to file an authorized issue, call `issue_label_ensure` with the required `origin` and `confirmed: true`. Filing authorization includes this narrow setup step, including default review filing. The tool creates only that missing allowed label, preserves existing labels and issues, and never touches organisation types or fields. It is safe to repeat; verify its result. Do not invoke full reconciliation for a missing label. If required types or Priority definitions are missing, report them and ask for separately scoped setup/cleanup authorization.
|
|
9
|
+
|
|
10
|
+
Use Brain MCP exclusively for issue operations. Do not use `gh` or direct GitHub connectors, including read-only checks, without explicit user approval for the fallback; missing Brain capabilities do not grant approval.
|
|
11
|
+
|
|
12
|
+
For explicitly requested broader cleanup, call `issue_config_preview` with `settings` to inspect the configuration, proposed operations, affected issues, organisation impact and blockers without writes. Brain uses its server-held GitHub credential; no local GitHub login is needed.
|
|
13
|
+
|
|
14
|
+
The standard allows exactly one origin label per issue: Code Review, Bug Report, Feature Request, ToDo or Question. Work types are Bug, Security, Feature, Task, Inconsistency, Question and Documentation. Priority is independent: Urgent, High, Medium or Low. Severity maps critical to Urgent and high/medium/low to the matching Priority. Do not add category, severity or priority labels. Milestones are outside this workflow.
|
|
15
|
+
|
|
16
|
+
Resolve ambiguous values with explicit `label_migrations`, `type_migrations`, `priority_migrations`, `field_migrations` or per-issue `issue_overrides`. Use `defaults` only when the same classification is justified for every otherwise unresolved issue. A null label/field mapping acknowledges dropping that source value. Review `remove_fields` (which defaults to Severity) and `prune_types` (which defaults to true); include their effects in the reviewed scope. Optional profile `issue-standard.jsonc` changes presentation metadata, not the allowed taxonomy.
|
|
17
|
+
|
|
18
|
+
Show the concrete preview and obtain authorization for its mutations unless the user already authorized that scope. Organisation types and fields can affect other repositories; do not infer organisation-wide authorization from a repository cleanup request. Never bypass permission, outside-usage, incomplete-access or mapping blockers.
|
|
19
|
+
|
|
20
|
+
Apply with `issue_config_reconcile`, passing the same settings, exact preview `revision` and `confirmed: true`. Brain migrates issues before removing obsolete definitions and verifies the result. A stale revision, partial result or failure requires a fresh preview; inspect completed changes and remaining blockers before retrying. Report the verified outcome and any unresolved changes. Do not claim cleanup succeeded from a preview alone.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: github-release
|
|
3
|
+
description: Prepare version bumps, tags, package publishing and GitHub Releases.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GitHub Release
|
|
7
|
+
|
|
8
|
+
Load changelog for change-note paths, formatting and entries. Load package-integrity-check for package validation and git-workflow for release commits and pushes.
|
|
9
|
+
|
|
10
|
+
Establish the requested release scope, version and destination from the user's instructions and project release workflow. Reuse authorization already given; get confirmation before any version bump, commit, tag, push, publication or GitHub Release that is not yet authorized. A release request does not imply unrelated changes.
|
|
11
|
+
|
|
12
|
+
Prepare the changelog and version metadata together, keeping package versions, lockfiles and release notes consistent. Run configured checks and relevant tests on the final changes before commits, tags and pushes. Follow the project's release tooling and dependency order for packages released separately.
|
|
13
|
+
|
|
14
|
+
After authorized release actions, verify the resulting remote tag, package or GitHub Release. Report the released version and any failed or incomplete steps; do not claim publication from a successful local build alone.
|
|
@@ -6,14 +6,15 @@ description: Use before package releases and publish-ready changes to verify pac
|
|
|
6
6
|
# Package Integrity Check
|
|
7
7
|
|
|
8
8
|
Use this skill for release and package policy checks that are not covered by normal project test commands.
|
|
9
|
+
Load changelog for changelog filenames, formatting and entry rules.
|
|
9
10
|
For package release or publish-ready work, verify the relevant package directory before finalizing:
|
|
10
11
|
|
|
11
12
|
- The directory contains `package.json` and is inside a git repository.
|
|
12
13
|
- The repository path follows `<org>/<repo>`, and `package.json.name` is `@<org>/<package-dir-name>`.
|
|
13
14
|
- `package.json.version`, `package.json.license`, and `package.json.copyright` are present and non-empty.
|
|
14
15
|
- A package-local `LICENSE` file exists and contains the exact copyright string from `package.json.copyright`.
|
|
15
|
-
- A package-local changelog exists
|
|
16
|
-
-
|
|
16
|
+
- A package-local changelog exists and follows the changelog skill.
|
|
17
|
+
- Its newest version heading matches `package.json.version` and uses the release date.
|
|
17
18
|
- The year in the top changelog version line appears in `package.json.copyright`.
|
|
18
19
|
- The git `origin` remote matches `<org>/<repo>`.
|
|
19
20
|
- The current branch has an upstream configured and is in sync with it after fetching.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Todo manager
|
|
2
2
|
|
|
3
|
-
Track feature requests and planned work in GitHub Issues. Use
|
|
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)
|
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: todo-manager
|
|
3
|
-
description: Track feature requests and
|
|
3
|
+
description: Track feature requests and tasks in GitHub Issues; fix numbered issues with atomic commits, linked fix comments and closure.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Use GitHub Issues in the affected repository as the
|
|
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. The legacy `todo_*` tools and local task imports are retired. Historical task files remain read-only and are never migrated or deleted automatically. 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`. Use Brain MCP exclusively for issue reads, searches, metadata, comments and writes, and `list_repositories` for repository discovery. Do not use `gh` or a direct GitHub connector for these operations without explicit user approval for that fallback. If Brain lacks a capability, disclose the limitation and ask before using a fallback; unavailable tools alone are not approval. 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 repository label, work type and Priority cleanup, discover and load `github-issue-cleanup` with `list_skills`/`get_skill`.
|
|
9
|
+
|
|
10
|
+
An authorized request to file an issue, including the default code-review workflow, also authorizes creating its missing allowed origin label in that repository. Inspect labels with `issue_metadata`; if the required label is absent, call `issue_label_ensure(origin=..., confirmed=true)` and verify the result, then create the issue. If `issue_create` reports a missing label, check for an existing issue before retrying with the same key and content. This authorization covers only the required label, not reconciliation, label deletion, existing issue migration or organisation types/fields. Ask separately for missing organisation definitions and broader cleanup; do not run `issue_config_reconcile` merely to unblock filing.
|
|
7
11
|
|
|
8
12
|
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
13
|
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.
|
|
11
|
-
4.
|
|
12
|
-
5. Leave unfinished or deferred requests open.
|
|
14
|
+
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.
|
|
15
|
+
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. Use `issue_label_ensure` for the required missing origin label under the filing authorization above; organisation work types require separate authorization and permissions. Read back origin, type and Priority after saving and report unavailable capabilities. Use code-review for review findings; GitHub Issues are the default unless the user explicitly states otherwise. For findings spanning related accessible repositories, ask before filing in additional repositories, then keep and cross-link the issues in their affected repositories. Filter feature-request lists by origin label `Feature Request`, not type alone.
|
|
16
|
+
5. Leave unfinished or deferred requests open. An explicit request such as “Fix issue #14” authorizes one atomic commit per issue, pushing to the existing upstream, and its fix comment/closure unless the user says otherwise; load git-workflow to fetch and try to pull when behind or diverged before committing, without automatic rebasing. Verify the push before linking and closing; a failed push leaves the issue open. Keep unrelated issues in separate commits, with one commit per affected repository for cross-repository fixes. Run relevant checks after the fix and any pull/merge, before committing and pushing. Follow git-workflow’s validation and closure gates, including its limited heads-up exception; add a concise bullet-list fix comment linking the corresponding commit or authorized PR and record verification or check limitations before closing through `issue_update` with the current revision. Read back the comment and closed state. Close as not planned only on the user's decision. Preserve closed issues for history rather than deleting them.
|
|
13
17
|
|
|
14
18
|
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.
|
|
19
|
+
|
|
20
|
+
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.
|
package/skills/unslop/SKILL.md
CHANGED
|
@@ -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.**
|
|
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
|
|
package/dist/brain/connectors.js
DELETED
|
@@ -1,65 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.syncConnector = syncConnector;
|
|
4
|
-
const zod_1 = require("zod");
|
|
5
|
-
const config_1 = require("./config");
|
|
6
|
-
const todos_1 = require("./todos");
|
|
7
|
-
const githubIssue = zod_1.z.object({ number: zod_1.z.number().int(), title: zod_1.z.string(), body: zod_1.z.string().nullable(), state: zod_1.z.enum(['open', 'closed']),
|
|
8
|
-
html_url: zod_1.z.url(), pull_request: zod_1.z.unknown().optional(), labels: zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.object({ name: zod_1.z.string() })])) });
|
|
9
|
-
const trelloCard = zod_1.z.object({ id: zod_1.z.string(), name: zod_1.z.string(), desc: zod_1.z.string(), closed: zod_1.z.boolean(), dueComplete: zod_1.z.boolean(), due: zod_1.z.string().nullable(),
|
|
10
|
-
url: zod_1.z.url(), labels: zod_1.z.array(zod_1.z.object({ name: zod_1.z.string() })) });
|
|
11
|
-
// Fetch connector JSON with bounded requests and sanitized network errors.
|
|
12
|
-
async function readRemote(url, headers) {
|
|
13
|
-
let response;
|
|
14
|
-
try {
|
|
15
|
-
response = await fetch(url, { headers, redirect: 'error', signal: AbortSignal.timeout(30000) });
|
|
16
|
-
}
|
|
17
|
-
catch {
|
|
18
|
-
throw new Error(`Could not reach ${url.hostname}; check connector credentials and network access.`);
|
|
19
|
-
}
|
|
20
|
-
if (!response.ok)
|
|
21
|
-
throw new Error(`Connector ${url.hostname} returned HTTP ${response.status}`);
|
|
22
|
-
return response.json();
|
|
23
|
-
}
|
|
24
|
-
// Import configured GitHub issues or Trello cards as local tasks.
|
|
25
|
-
async function syncConnector(store, name, scope) {
|
|
26
|
-
store.scopeDirectory(scope);
|
|
27
|
-
const connector = (0, config_1.readBrainConfig)(store.configRoot)?.connectors[name];
|
|
28
|
-
if (!connector)
|
|
29
|
-
throw new Error(`Connector not configured: ${name}`);
|
|
30
|
-
const tasks = [];
|
|
31
|
-
if (connector.type === 'github') {
|
|
32
|
-
const token = process.env[connector.tokenEnv];
|
|
33
|
-
for (let page = 1;; page += 1) {
|
|
34
|
-
if (page > 100)
|
|
35
|
-
throw new Error('GitHub import exceeds 10000 issues; split the task source before importing.');
|
|
36
|
-
const url = new URL(`https://api.github.com/repos/${connector.repository}/issues`);
|
|
37
|
-
url.search = new URLSearchParams({ state: 'all', per_page: '100', page: String(page) }).toString();
|
|
38
|
-
const issues = zod_1.z.array(githubIssue).parse(await readRemote(url, { accept: 'application/vnd.github+json', 'user-agent': 'agent-brain', ...(token ? { authorization: `Bearer ${token}` } : {}) }));
|
|
39
|
-
for (const issue of issues.filter((issue) => !issue.pull_request))
|
|
40
|
-
tasks.push({
|
|
41
|
-
scope, title: issue.title, description: issue.body ?? '', status: issue.state === 'closed' ? 'done' : 'todo',
|
|
42
|
-
labels: issue.labels.map((label) => typeof label === 'string' ? label : label.name),
|
|
43
|
-
source: { type: 'github', external_id: `${connector.repository}#${issue.number}`, url: issue.html_url }
|
|
44
|
-
});
|
|
45
|
-
if (issues.length < 100)
|
|
46
|
-
break;
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
else {
|
|
50
|
-
const key = process.env[connector.keyEnv];
|
|
51
|
-
const token = process.env[connector.tokenEnv];
|
|
52
|
-
if (!key || !token)
|
|
53
|
-
throw new Error(`Set ${connector.keyEnv} and ${connector.tokenEnv} before importing Trello tasks.`);
|
|
54
|
-
const url = new URL(`https://api.trello.com/1/boards/${connector.board}/cards/all`);
|
|
55
|
-
url.search = new URLSearchParams({ key, token, fields: 'id,name,desc,closed,dueComplete,due,url,labels' }).toString();
|
|
56
|
-
const cards = zod_1.z.array(trelloCard).parse(await readRemote(url, {}));
|
|
57
|
-
for (const card of cards)
|
|
58
|
-
tasks.push({ scope, title: card.name, description: card.desc,
|
|
59
|
-
status: card.dueComplete ? 'done' : card.closed ? 'cancelled' : 'todo',
|
|
60
|
-
...(card.due ? { due: card.due.slice(0, 10) } : {}), labels: card.labels.map((label) => label.name),
|
|
61
|
-
source: { type: 'trello', external_id: card.id, url: card.url }
|
|
62
|
-
});
|
|
63
|
-
}
|
|
64
|
-
return (0, todos_1.importTodos)(store, tasks);
|
|
65
|
-
}
|