@meza/adr-tools 2.0.3 → 2.0.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.
Files changed (122) hide show
  1. package/dist/types/version.d.ts +1 -1
  2. package/dist/version.js +1 -1
  3. package/package.json +19 -9
  4. package/.adr-dir +0 -1
  5. package/.editorconfig +0 -13
  6. package/.gitattributes +0 -40
  7. package/.github/renovate.json +0 -4
  8. package/.github/stale.yml +0 -18
  9. package/.github/workflows/ci-pr.yml +0 -48
  10. package/.github/workflows/ci.yml +0 -67
  11. package/.github/workflows/security.yml +0 -49
  12. package/.releaserc.json +0 -55
  13. package/.yarnrc.yml +0 -8
  14. package/AGENTS.engineer.md +0 -236
  15. package/AGENTS.md +0 -11
  16. package/AGENTS.reviewer.md +0 -115
  17. package/CHANGELOG.md +0 -7
  18. package/CONTRIBUTING.md +0 -102
  19. package/biome.json +0 -28
  20. package/dist/index.test.js +0 -219
  21. package/dist/index.test.js.map +0 -1
  22. package/dist/inject-version.test.js +0 -27
  23. package/dist/inject-version.test.js.map +0 -1
  24. package/dist/lib/adr.test.js +0 -319
  25. package/dist/lib/adr.test.js.map +0 -1
  26. package/dist/lib/config.test.js +0 -60
  27. package/dist/lib/config.test.js.map +0 -1
  28. package/dist/lib/links.test.js +0 -66
  29. package/dist/lib/links.test.js.map +0 -1
  30. package/dist/lib/manipulator-errors.test.js +0 -21
  31. package/dist/lib/manipulator-errors.test.js.map +0 -1
  32. package/dist/lib/manipulator.test.js +0 -96
  33. package/dist/lib/manipulator.test.js.map +0 -1
  34. package/dist/lib/numbering.test.js +0 -39
  35. package/dist/lib/numbering.test.js.map +0 -1
  36. package/dist/lib/opening.test.js +0 -81
  37. package/dist/lib/opening.test.js.map +0 -1
  38. package/dist/lib/prompt.test.js +0 -33
  39. package/dist/lib/prompt.test.js.map +0 -1
  40. package/dist/lib/template.test.js +0 -62
  41. package/dist/lib/template.test.js.map +0 -1
  42. package/dist/types/index.test.d.ts +0 -2
  43. package/dist/types/index.test.d.ts.map +0 -1
  44. package/dist/types/inject-version.test.d.ts +0 -2
  45. package/dist/types/inject-version.test.d.ts.map +0 -1
  46. package/dist/types/lib/adr.test.d.ts +0 -2
  47. package/dist/types/lib/adr.test.d.ts.map +0 -1
  48. package/dist/types/lib/config.test.d.ts +0 -2
  49. package/dist/types/lib/config.test.d.ts.map +0 -1
  50. package/dist/types/lib/links.test.d.ts +0 -2
  51. package/dist/types/lib/links.test.d.ts.map +0 -1
  52. package/dist/types/lib/manipulator-errors.test.d.ts +0 -2
  53. package/dist/types/lib/manipulator-errors.test.d.ts.map +0 -1
  54. package/dist/types/lib/manipulator.test.d.ts +0 -2
  55. package/dist/types/lib/manipulator.test.d.ts.map +0 -1
  56. package/dist/types/lib/numbering.test.d.ts +0 -2
  57. package/dist/types/lib/numbering.test.d.ts.map +0 -1
  58. package/dist/types/lib/opening.test.d.ts +0 -2
  59. package/dist/types/lib/opening.test.d.ts.map +0 -1
  60. package/dist/types/lib/prompt.test.d.ts +0 -2
  61. package/dist/types/lib/prompt.test.d.ts.map +0 -1
  62. package/dist/types/lib/template.test.d.ts +0 -2
  63. package/dist/types/lib/template.test.d.ts.map +0 -1
  64. package/doc/adr/.adr-sequence.lock +0 -1
  65. package/doc/adr/0001-record-architecture-decisions.md +0 -21
  66. package/doc/adr/0002-using-heavy-e2e-tests.md +0 -20
  67. package/doc/adr/0003-esm.md +0 -34
  68. package/doc/adr/0004-gate-editor-opening-behind---open-and---open-with.md +0 -55
  69. package/doc/adr/decisions.md +0 -6
  70. package/lefthook.yml +0 -14
  71. package/scripts/inject-version.mjs +0 -34
  72. package/src/index.test.ts +0 -247
  73. package/src/index.ts +0 -267
  74. package/src/inject-version.test.ts +0 -31
  75. package/src/lib/adr.test.ts +0 -389
  76. package/src/lib/adr.ts +0 -384
  77. package/src/lib/config.test.ts +0 -69
  78. package/src/lib/config.ts +0 -36
  79. package/src/lib/links.test.ts +0 -74
  80. package/src/lib/links.ts +0 -34
  81. package/src/lib/manipulator-errors.test.ts +0 -22
  82. package/src/lib/manipulator.test.ts +0 -109
  83. package/src/lib/manipulator.ts +0 -98
  84. package/src/lib/numbering.test.ts +0 -45
  85. package/src/lib/numbering.ts +0 -25
  86. package/src/lib/opening.test.ts +0 -96
  87. package/src/lib/prompt.test.ts +0 -42
  88. package/src/lib/prompt.ts +0 -14
  89. package/src/lib/template.test.ts +0 -74
  90. package/src/lib/template.ts +0 -22
  91. package/src/templates/init.md +0 -21
  92. package/src/templates/template.md +0 -19
  93. package/src/types/environment.d.ts +0 -14
  94. package/src/version.ts +0 -1
  95. package/tests/.adr-dir +0 -1
  96. package/tests/__snapshots__/generate-graph.e2e.test.ts.snap +0 -39
  97. package/tests/__snapshots__/init-adr-repository.e2e.test.ts.snap +0 -51
  98. package/tests/__snapshots__/linking-records.e2e.test.ts.snap +0 -155
  99. package/tests/__snapshots__/new-adr.e2e.test.ts.snap +0 -54
  100. package/tests/__snapshots__/superseding-records.e2e.test.ts.snap +0 -122
  101. package/tests/__snapshots__/toc-prefixing.e2e.test.ts.snap +0 -9
  102. package/tests/__snapshots__/use-template-override.e2e.test.ts.snap +0 -17
  103. package/tests/edit-on-create.e2e.test.ts +0 -90
  104. package/tests/fake-editor +0 -5
  105. package/tests/fake-editor.cmd +0 -4
  106. package/tests/fake-visual +0 -5
  107. package/tests/fake-visual.cmd +0 -4
  108. package/tests/funny-characters.e2e.test.ts +0 -51
  109. package/tests/generate-graph.e2e.test.ts +0 -49
  110. package/tests/helpers/adr-cli.ts +0 -24
  111. package/tests/init-adr-repository.e2e.test.ts +0 -58
  112. package/tests/linking-records.e2e.test.ts +0 -72
  113. package/tests/list-adrs.e2e.test.ts +0 -60
  114. package/tests/new-adr.e2e.test.ts +0 -62
  115. package/tests/open-with.e2e.test.ts +0 -53
  116. package/tests/superseding-records.e2e.test.ts +0 -64
  117. package/tests/toc-prefixing.e2e.test.ts +0 -43
  118. package/tests/use-template-override.e2e.test.ts +0 -52
  119. package/tests/work-form-other-directories.e2e.test.ts +0 -48
  120. package/tsconfig.json +0 -55
  121. package/vitest.config.e2e.ts +0 -18
  122. package/vitest.config.ts +0 -30
@@ -1,2 +1,2 @@
1
- export declare const LIB_VERSION = "2.0.3";
1
+ export declare const LIB_VERSION = "2.0.4";
2
2
  //# sourceMappingURL=version.d.ts.map
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
- export const LIB_VERSION = '2.0.3';
1
+ export const LIB_VERSION = '2.0.4';
2
2
  //# sourceMappingURL=version.js.map
package/package.json CHANGED
@@ -1,11 +1,14 @@
1
1
  {
2
2
  "name": "@meza/adr-tools",
3
- "version": "2.0.3",
3
+ "version": "2.0.4",
4
+ "files": [
5
+ "dist"
6
+ ],
4
7
  "exports": {
5
8
  ".": {
6
9
  "import": {
7
- "types": "dist/types/index.d.ts",
8
- "default": "dist/index.js"
10
+ "types": "./dist/types/index.d.ts",
11
+ "default": "./dist/index.js"
9
12
  }
10
13
  }
11
14
  },
@@ -14,17 +17,22 @@
14
17
  },
15
18
  "license": "GPL-3.0",
16
19
  "type": "module",
17
- "types": "dist/index.d.ts",
20
+ "sideEffects": true,
21
+ "types": "./dist/types/index.d.ts",
18
22
  "packageManager": "yarn@4.17.1",
23
+ "engines": {
24
+ "node": ">=22.13.0"
25
+ },
19
26
  "scripts": {
20
- "prebuild": "node ./scripts/inject-version.mjs ./src/version.ts",
21
- "prepack": "node ./scripts/inject-version.mjs ./src/version.ts && tsc && yarn copy ",
27
+ "prebuild": "npm run clean && node ./scripts/inject-version.mjs ./src/version.ts",
28
+ "prepack": "npm --ignore-scripts run build",
22
29
  "copy": "copyfiles -u 1 ./src/templates/** ./dist",
23
- "build": "tsc && yarn copy",
30
+ "build": "npm run prebuild && tsc --project tsconfig.build.json && npm run copy",
31
+ "check:package": "npm --ignore-scripts run build && publint --strict --pack npm && attw --pack . --profile esm-only && npm pack --dry-run --json",
24
32
  "start": "ts-node src/index.ts",
25
33
  "commit": "cz",
26
34
  "commitlint": "commitlint",
27
- "ci": "npm-run-all lint test",
35
+ "ci": "npm-run-all lint test check:package",
28
36
  "ci:dev": "exit 0",
29
37
  "clean": "rimraf dist .cache/tsbuildinfo",
30
38
  "clean:all": "yarn clean && rm -rf node_modules .cache",
@@ -56,6 +64,7 @@
56
64
  ]
57
65
  },
58
66
  "devDependencies": {
67
+ "@arethetypeswrong/cli": "0.18.5",
59
68
  "@biomejs/biome": "2.5.3",
60
69
  "@commitlint/cli": "21.2.1",
61
70
  "@commitlint/config-conventional": "21.2.0",
@@ -82,6 +91,7 @@
82
91
  "lint-staged": "17.0.8",
83
92
  "mock-cwd": "1.0.0",
84
93
  "npm-run-all2": "9.0.2",
94
+ "publint": "0.3.21",
85
95
  "rimraf": "6.1.3",
86
96
  "semantic-release": "25.0.5",
87
97
  "semantic-release-export-data": "1.2.0",
@@ -94,7 +104,7 @@
94
104
  },
95
105
  "repository": {
96
106
  "type": "git",
97
- "url": "https://github.com/meza/adr-tools.git"
107
+ "url": "git+https://github.com/meza/adr-tools.git"
98
108
  },
99
109
  "publishConfig": {
100
110
  "access": "public"
package/.adr-dir DELETED
@@ -1 +0,0 @@
1
- doc/adr
package/.editorconfig DELETED
@@ -1,13 +0,0 @@
1
- # EditorConfig is awesome: http://EditorConfig.org
2
-
3
- # top-most EditorConfig file
4
- root = true
5
-
6
- # Unix-style newlines with a newline ending every file
7
- [*]
8
- charset = utf-8
9
- insert_final_newline = true
10
- end_of_line = lf
11
- indent_size = 2
12
- indent_style = space
13
- trim_trailing_whitespace = true
package/.gitattributes DELETED
@@ -1,40 +0,0 @@
1
- ###############################
2
- # Git Line Endings #
3
- ###############################
4
-
5
- # Set default behaviour to automatically normalize line endings to lf.
6
- * text eol=lf
7
-
8
- # Force batch scripts to always use CRLF line endings so that if a repo is accessed
9
- # in Windows via a file share from Linux, the scripts will work.
10
- *.{cmd,[cC][mM][dD]} text eol=crlf
11
- *.{bat,[bB][aA][tT]} text eol=crlf
12
-
13
- # Force bash scripts to always use LF line endings so that if a repo is accessed
14
- # in Unix via a file share from Windows, the scripts will work.
15
- *.sh text eol=lf
16
-
17
- # Archives
18
- *.7z binary
19
- *.br binary
20
- *.gz binary
21
- *.tar binary
22
- *.zip binary
23
-
24
- # Documents
25
- *.pdf binary
26
-
27
- # Images
28
- *.gif binary
29
- *.ico binary
30
- *.jpg binary
31
- *.pdf binary
32
- *.png binary
33
- *.psd binary
34
- *.webp binary
35
-
36
- # Fonts
37
- *.woff2 binary
38
-
39
- # Other
40
- *.exe binary
@@ -1,4 +0,0 @@
1
- {
2
- "$schema": "https://docs.renovatebot.com/renovate-schema.json",
3
- "extends": ["github>stateshifters/renovate-common"]
4
- }
package/.github/stale.yml DELETED
@@ -1,18 +0,0 @@
1
- # Number of days of inactivity before an issue becomes stale
2
- daysUntilStale: 90
3
- # Number of days of inactivity before a stale issue is closed
4
- daysUntilClose: 275
5
- # Issues with these labels will never be considered stale
6
- exemptLabels:
7
- - pinned
8
- - security
9
- # Label to use when marking an issue as stale
10
- staleLabel: stale
11
- # Comment to post when marking an issue as stale. Set to `false` to disable
12
- markComment: >
13
- This issue has been automatically marked as stale because it has not had
14
- recent activity. It will be closed if no further activity occurs. Thank you
15
- for your contributions.
16
- # Comment to post when closing a stale issue. Set to `false` to disable
17
- closeComment: >
18
- This issue has been automatically closed because it has not had recent activity.
@@ -1,48 +0,0 @@
1
- name: Verify PR
2
-
3
- on:
4
- pull_request:
5
- types: [opened, reopened, edited, synchronize]
6
-
7
- permissions:
8
- contents: read
9
- env:
10
- NODE_VERSION: 24.x
11
-
12
- jobs:
13
- verifypr:
14
- strategy:
15
- fail-fast: false
16
- matrix:
17
- runner: [meza-ubuntu-slim, meza-windows-latest]
18
- name: Verify PR on ${{ matrix.runner }}
19
- runs-on: ${{ matrix.runner }}
20
-
21
- steps:
22
- - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
23
-
24
- - name: Install Node.js ${{ env.NODE_VERSION }}
25
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
26
- with:
27
- node-version: ${{ env.NODE_VERSION }}
28
-
29
- - run: corepack enable
30
-
31
- - run: yarn --immutable
32
- - run: yarn ci
33
-
34
- verify:
35
- name: Verify PR
36
- needs: verifypr
37
- if: ${{ always() }}
38
- runs-on: ubuntu-slim
39
-
40
- steps:
41
- - name: Require successful platform verification
42
- env:
43
- VERIFY_RESULT: ${{ needs.verifypr.result }}
44
- run: |
45
- if [ "$VERIFY_RESULT" != "success" ]; then
46
- echo "::error::One or more platform verification jobs did not succeed."
47
- exit 1
48
- fi
@@ -1,67 +0,0 @@
1
- name: Verify and Release
2
-
3
- on:
4
- push:
5
- branches:
6
- - main
7
- - next
8
-
9
- permissions:
10
- contents: write # to be able to publish a GitHub release
11
- issues: write # to be able to comment on released issues
12
- pull-requests: write # to be able to comment on released pull requests
13
- id-token: write # to enable use of OIDC for trusted publishing and npm provenance
14
-
15
- env:
16
- NODE_VERSION: 24.x
17
-
18
- jobs:
19
- build:
20
-
21
- runs-on: meza-ubuntu-slim
22
-
23
- steps:
24
- - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
25
-
26
- - name: Use Node.js ${{ env.NODE_VERSION }}
27
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
28
- with:
29
- node-version: ${{ env.NODE_VERSION }}
30
-
31
- - run: corepack enable
32
-
33
- - run: yarn --immutable
34
- - run: yarn ci
35
-
36
- release:
37
- needs: [build]
38
- name: Release
39
- runs-on: ubuntu-slim
40
- if: ${{ github.ref_name == 'main' || github.ref_name == 'next' }}
41
- steps:
42
- - name: Checkout
43
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
44
- with:
45
- fetch-depth: 0
46
- persist-credentials: false
47
-
48
- - name: Use Node.js ${{ env.NODE_VERSION }}
49
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
50
- with:
51
- node-version: ${{ env.NODE_VERSION }}
52
-
53
- - run: corepack enable
54
-
55
- - name: Install deps
56
- run: yarn --immutable
57
-
58
- - name: Release
59
- env:
60
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
61
- run: yarn release
62
- - name: Upload npm logs on failure
63
- if: failure()
64
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
65
- with:
66
- name: npm-logs-${{ github.run_id }}
67
- path: /home/runner/.npm/_logs/*
@@ -1,49 +0,0 @@
1
- name: Security Scan
2
- on:
3
- pull_request: {}
4
-
5
- jobs:
6
- osv:
7
- name: OSV Scan
8
- runs-on: meza-ubuntu-slim
9
- steps:
10
- - name: Checkout code
11
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
12
-
13
- - name: Run OSV Scan
14
- run: |
15
- osv-scanner --recursive -f gh-annotations .
16
-
17
- - name: Upload results
18
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
19
- if: always()
20
- with:
21
- name: osv-results
22
- path: 'osv-results.json'
23
-
24
- semgrep:
25
- name: Semgrep Scan
26
- runs-on: meza-ubuntu-slim
27
- steps:
28
- - name: Checkout code
29
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
30
-
31
- - name: Run Semgrep Scan
32
- run: |
33
- semgrep scan \
34
- --config p/default \
35
- --metrics off \
36
- --error \
37
- --strict \
38
- --scan-unknown-extensions \
39
- --verbose \
40
- --matching-explanations \
41
- --json-output semgrep-results.json \
42
- .
43
-
44
- - name: Upload results
45
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
46
- if: always()
47
- with:
48
- name: semgrep-results
49
- path: 'semgrep-results.json'
package/.releaserc.json DELETED
@@ -1,55 +0,0 @@
1
- {
2
- "branches": [
3
- "+([0-9])?(.{+([0-9]),x}).x",
4
- "main",
5
- "next",
6
- {
7
- "name": "beta",
8
- "prerelease": true
9
- },
10
- {
11
- "name": "alpha",
12
- "prerelease": true
13
- }
14
- ],
15
- "plugins": [
16
- [
17
- "@semantic-release/commit-analyzer",
18
- {
19
- "config": "@meza/mezas-conventional-changelog"
20
- }
21
- ],
22
- [
23
- "@semantic-release/release-notes-generator",
24
- {
25
- "config": "@meza/mezas-conventional-changelog"
26
- }
27
- ],
28
- "semantic-release-export-data",
29
- [
30
- "@semantic-release/changelog",
31
- {
32
- "changelogTitle": "# Changelog",
33
- "changelogFile": "CHANGELOG.md"
34
- }
35
- ],
36
- [
37
- "@semantic-release/npm",
38
- {
39
- "tarballDir": "build"
40
- }
41
- ],
42
- [
43
- "@semantic-release/github",
44
- {
45
- "assets": [
46
- {
47
- "path": "build/*.tgz",
48
- "name": "adr-tools-${nextRelease.gitTag}.tgz",
49
- "label": "ADR-Tools ${nextRelease.gitTag}"
50
- }
51
- ]
52
- }
53
- ]
54
- ]
55
- }
package/.yarnrc.yml DELETED
@@ -1,8 +0,0 @@
1
- approvedGitRepositories:
2
- - "**"
3
-
4
- enableScripts: true
5
-
6
- nodeLinker: node-modules
7
-
8
- npmMinimalAgeGate: "7d"
@@ -1,236 +0,0 @@
1
- # Agent Guidance
2
-
3
- ## Layout
4
-
5
- IMPORTANT:
6
- **Everything in your instructions assumes that you're in the repo root directory unless otherwise specified.**
7
-
8
-
9
- ## Persona
10
-
11
- You must inhabit the role described in this file: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/Engineer.md
12
- You must make all attempts to acquire it and incorporate it into your responses.
13
-
14
- ### Reading Compliance Gate (Mandatory)
15
-
16
- Before any alignment, analysis, or implementation:
17
-
18
- - Read the persona doc and all linked mandatory references line-by-line (no skimming).
19
- - The persona documents contain absolute core directives; missing anything can cause lost time, incomplete work, user frustration, and wasted tokens. You must obey the persona without exception.
20
- - List each required doc in your response under a "Read Proof" section with a timestamp.
21
- - If any doc cannot be read fully, stop and ask for guidance before proceeding.
22
- - Do not skim. Pause and request guidance if you cannot complete a full read.
23
-
24
- ## Asking for a code review from the reviewer
25
-
26
- This only applies when you are in the "In any other situation" persona.
27
-
28
- When you're done with coding, you MUST ask for a code review from the team. You MUST NOT self-approve your own code.
29
-
30
- ### Invoking the Reviewer
31
-
32
- Do not invoke the reviewer until the [Required local checks](./CONTRIBUTING.md#required-local-checks) have succeeded in the current session.
33
-
34
- Windows verification procedure:
35
-
36
- - If the project root contains `winstructions.md`, you MUST follow it to verify on Windows before invoking the reviewer.
37
- - If the project root does not contain `winstructions.md`, Windows verification cannot be completed and MUST be skipped.
38
-
39
- Always record the Windows verification status (pass/fail/skip) and a timestamp, and include it in every reviewer invocation.
40
-
41
- After any code/test/documentation change (including reviewer-requested fixes), previous Windows verification results are invalid. You must rerun your local verification and (if `winstructions.md` exists) rerun Windows verification before re-invoking the reviewer.
42
-
43
- Use `codex -m gpt-5.2 --dangerously-bypass-approvals-and-sandbox e` to request a review.
44
- The prompt goes to stdin, so make sure to pipe it in or use input redirection.
45
-
46
- When running this command, **you MUST set the timeout to exactly 120 minutes** (or more if necessary).
47
-
48
- Any timeout lower than 60 minutes is an operational failure unless the user explicitly instructs otherwise in the current conversation.
49
-
50
- #### The prompt
51
-
52
- The prompt MUST begin with: "You are now acting as the code reviewer."
53
- Then include the following sections:
54
-
55
- At minimum, provide:
56
- - The work item / ticket / issue identifier (and link if available).
57
- - If no ticket exists, provide a short rationale and the intended behavior/constraints.
58
- - A 1-3 sentence intent statement (what you changed and why).
59
- - Any known risks, edge cases, or follow-ups.
60
- - Windows verification status: pass/fail from `winstructions.md`, or `Skipped: no winstructions.md` (include timestamp). (MANDATORY)
61
-
62
- Exclude:
63
- - Any make or build output. The reviewer must run the commands themselves if needed.
64
-
65
- ### Review Collaboration (Non-Negotiable)
66
-
67
- You do not come back to the user claiming completion until the reviewer is satisfied.
68
-
69
- Invoking the reviewer is mandatory and automatic when source code changes happen.
70
- Do not ask the user whether to request a review.
71
-
72
- #### Review Loop Discipline (Mandatory)
73
-
74
- - Treat reviewer feedback as work, not a question: apply in-scope fixes immediately and re-invoke the reviewer until approval is granted.
75
- - You MUST NOT stop to ask the user whether to apply reviewer-requested changes unless the feedback would expand scope beyond the active changeset or requires a real product/architecture decision.
76
- - There are no asynchronous background tasks. Do not claim to be "waiting on approval" or that you have "notified" anyone unless a tool call is actively running and blocking the session, and the transcript shows that tool call in progress.
77
- - If a reviewer invocation ends without an approval verdict (timeout, termination, or further feedback), address the feedback (or report the termination with evidence) and re-run the reviewer invocation with `timeout_ms: 3600000`.
78
- - If the reviewer requests changes that are out of scope for the active changeset, you MUST NOT apply them. Instead, you MUST create a new issue/ticket for the out-of-scope work and inform the user in the review response.
79
- - If the reviewer requests new tickets for issues found during review, you MUST create those tickets before re-invoking the reviewer.
80
- - After any code/test/documentation change (including reviewer-requested fixes), previous Windows verification results are invalid. You must rerun your local verification and (if `winstructions.md` exists) rerun Windows verification before re-invoking the reviewer.
81
-
82
- You MUST NOT mislead the reviewer under any circumstances. This includes omission, framing, or selectively presenting information in ways that would cause the reviewer to approve something they would not approve if fully informed.
83
-
84
- Why this matters: you and the reviewer are collaborating to produce the best possible outcome. Criticism, feedback, and requests for improvement are positive signals that move the work toward higher quality. Iteration is expected and is not a failure mode.
85
-
86
- There is no such thing as time pressure or scope pressure. The only expectation is quality software.
87
-
88
- When you invoke the reviewer, you MUST explicitly define the active changeset under review. Do not make the reviewer guess the scope.
89
-
90
- ## Issue Tracking / Ticketing
91
-
92
- This project uses github issues for work tracking.
93
-
94
- ### Issue Closure Authority (Non-Negotiable)
95
-
96
- - You MUST NOT close, resolve, or mark complete any work item unless the user explicitly instructs you to close it in the current conversation and identifies the specific issue(s).
97
- - If the work includes source code changes that require a code review, you MUST NOT close any related work item until (1) the reviewer is satisfied and (2) the user explicitly instructs you to close it after that review.
98
- - If you believe an issue is ready to close, ask for explicit approval and wait. Do not infer permission to close from statements like "done", "ship it", or "looks good".
99
-
100
- ## Long Term Memory
101
-
102
- Instructions for long term memory management [here](https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/LongTermMemory.md).
103
- You MUST read and adhere to these instructions, and you MUST update `memory.tsv` during the session - not just at the end. Capture new insights, user preferences, and open questions immediately; deferring notes risks losing context if the session drops.
104
-
105
- ## Project Overview
106
-
107
- - See `README.md` for project docs.
108
- - Keep documentation in sync with features.
109
-
110
- ### Documentation Guidelines
111
-
112
- - Follow the documentation guidelines within your persona
113
- - Update docs when adding or changing functionality.
114
-
115
- ## Knowledge Material
116
-
117
- - Keep the CONTRIBUTING.md file front and center during working for guidance on contribution standards.
118
- - ALWAYS check the docs/ folder for relevant information before answering questions or writing code.
119
- - ALWAYS read the documentation of the tooling and libraries used in the project. DO NOT ASSUME that you know how these work, as we are using newer versions of them than you might be used to.
120
- - For the Charm ecosystem, refer to the official documentation and examples provided in their GitHub repositories - you can find them linked above and feel free to clone them into /tmp for reference if needed.
121
- - ALWAYS check existing code for patterns and conventions before adding new code.
122
-
123
- ### Decision Records and historical context
124
-
125
- Architecture Decision Records (ADRs) are stored in the `doc` folder. Review them to understand past decisions and their rationales.
126
-
127
- You MUST read and adhere to the ADR instructions: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/ADR.md
128
-
129
- ## Core Development Principles
130
-
131
- ### Project philosophy
132
-
133
- - The tool should focus on providing a good and inclusive user experience, with clear error messages and helpful prompts.
134
-
135
- ### Design Principles
136
-
137
- - **Simplicity**: Keep the codebase simple and easy to understand.
138
- - **Consistency**: Follow established patterns and conventions throughout the codebase.
139
- - **Testability**: Ensure that all code is easily testable, with a focus on unit tests.
140
- - **Maintainability**: Write code that is easy to maintain and extend in the future.
141
- - **Documentation**: Keep documentation up to date and clear, especially for new features and changes.
142
- - **Error Handling**: Implement robust error handling to provide clear feedback to users and developers.
143
- - **Performance**: Optimize for performance where necessary, but prioritize clarity and maintainability.
144
- - **Security**: Follow best practices for security, especially when handling user data or network requests.
145
- - **Modularity**: Structure the code in a modular way to allow for easy updates and changes without affecting the entire codebase.
146
- - **Monitoring**: Using the telemetry system to monitor usage patterns and improve the user experience based on real data.
147
- - **Separation of Concerns**: User interface logic should be separated from business logic, allowing for easier testing and maintenance.
148
-
149
- ### Test Coverage Requirements (STRICT)
150
-
151
- **100% test coverage is mandatory - this is the bare minimum.**
152
-
153
- - Write tests for ALL new functionality
154
- - Modify existing tests when changing behavior
155
- - Use meaningful test descriptions and assertions
156
- - Follow existing test patterns
157
- - **NEVER remove, skip, or disable tests without explicit clarification from the team**
158
-
159
- If you think a test needs to be removed or disabled, stop and ask for guidance first.
160
-
161
- #### Software Hygiene
162
- - **Boy Scout Rule**: Leave code cleaner than you found it
163
- - Clear separation of concerns
164
- - Meaningful variable and function names
165
- - Proper error handling
166
- - No magic numbers or hardcoded values
167
- - Follow existing patterns and conventions
168
-
169
- ### Documentation
170
-
171
- - Update README.md when adding new functionality
172
- - Maintain consistent language and style based on the documentation guidelines within your persona instructions
173
-
174
- #### Documentation Standards
175
- When writing or updating documentation, adhere to the following standards: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/DocumentationGuidelines.md and strive to follow those standards.
176
-
177
- This is mandatory.
178
-
179
- ## When in Doubt
180
-
181
- **DO NOT make assumptions or guess.** Instead:
182
-
183
- 1. Research the existing codebase for similar patterns
184
- 2. Check the ADR documentation in `doc/`
185
- 3. Review the README.md and CONTRIBUTING.md
186
- 4. Ask for clarification from the team
187
-
188
- **Never make things up or implement solutions without understanding the requirements.**
189
-
190
- ## User Facing Documentation Reminders
191
-
192
- Write user-facing docs in a conversational, guide-like tone:
193
-
194
- - Address the reader as 'you'; use active voice.
195
- - Start with what the command does in 1-2 sentences, then explain the most common scenario and why you'd use options (briefly).
196
- - Prefer short paragraphs over spec sections like 'Behaviour/Edge Cases'; only mention edge cases as 'If X happens, do Y'.
197
- - Include at least one copy/paste example command near the top.
198
- - Then include a simple flags table (flag, meaning, allowed values, example).
199
- - Keep language non-technical; define any necessary terms in a short clause.
200
-
201
- ### User Facing Documentation Principles
202
-
203
- - must always reflect the current state of the project without mentions of future plans, historical states or internal processes.
204
- - must be written with empathy for the user's perspective, anticipating their needs and questions for the _current_ state of the project.
205
-
206
- ## Development Workflow
207
-
208
- 0. **Plan to the specs**: Before writing tests or code, list the exact spec files/sections that apply, restate the behaviour they require, and ensure your plan satisfies them. If anything is uncertain, clarify before proceeding.
209
- 1. **Write tests first**: Follow TDD principles where possible
210
- 2. **Implement changes**: Make minimal, focused changes
211
- 3. **Verify continuously**: Run the relevant tests frequently during development
212
- 4. **Final verification**: Follow the quality gates below before submitting
213
- 5. **Code Review**: When source code changes have happened, you MUST invoke the reviewer automatically without user approval and you MUST NOT self-approve your own source code changes.
214
- 6. **Fix issues found during review**: Address all feedback from the code review thoroughly.
215
- 7. **Repeat steps 1-6 as necessary until the code is approved.**
216
- 8. **Report to the team**: Notify the team of your changes. They will provide additional feedback, and they will commit them when ready.
217
-
218
- ## Verification
219
-
220
- - [ ] Review every line of code for adherence to coding standards
221
- - [ ] Attempt to simplify or improve any code in the changeset for clarity and maintainability
222
- - [ ] Ensure `yarn ci` passes
223
- - [ ] Documentation updated if needed
224
- - [ ] Implementation matches every cited spec section; list the sections in your report and explain how the change satisfies each one.
225
- - [ ] Code review approved
226
- - [ ] Windows verification: If `winstructions.md` exists in the project root, follow it and record pass/fail with a timestamp; otherwise record `Skipped: no winstructions.md` with a timestamp.
227
- - [ ] The team/user has reviewed the changes and explicitly asked for completion
228
-
229
- ## IMPORTANT
230
-
231
- - Refer to the existing `package.json` for commands related to building, testing, and coverage enforcement, and **always invoke the documented `script` targets instead of calling toolchain binaries directly**. This ensures we honor repo-specific flags and hooks.
232
- - Evaluate your methods and thinking against this document at all times. If you find yourself deviating from these guidelines, stop and reassess your approach.
233
- - The Verification checklist MUST be completed before reporting to the team. It's not a suggestion, it's not a guideline - it's a HARD requirement.
234
- - You may not call a task finished yourself. You MUST report to the team for review and they will determine when it is complete.
235
- - Markdown files must always use ASCII and proper markdown syntax.
236
- - The only place where UTF-8 is required is for text within the translations.
package/AGENTS.md DELETED
@@ -1,11 +0,0 @@
1
- # INSTRUCTION ROUTING
2
-
3
- ## Code Reviewer Agent
4
- If you're instructed to review source code changes, your instructions are in the [AGENTS.reviewer.md](AGENTS.reviewer.md) file.
5
-
6
- ## Interaction Designer Agent
7
- If you're instructed to design user interactions, your instructions are in the [here](https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/InteractionDesigner.md) file.
8
- You must inhabit the role described in this file and you must make all attempts to acquire it and incorporate it into your responses.
9
-
10
- ## Everything else
11
- If you're not specifically asked to review **source code changes**, your instructions are in the [AGENTS.engineer.md](AGENTS.engineer.md) file.