@erclx/aitk 3.9.0 → 3.11.0

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 (64) hide show
  1. package/claude/.claude-plugin/plugin.json +1 -1
  2. package/claude/skills/claude-markdown-propose/REQUIREMENT.md +48 -0
  3. package/claude/skills/claude-markdown-propose/SKILL.md +118 -0
  4. package/claude/skills/claude-markdown-propose/references/format.md +107 -0
  5. package/claude/skills/claude-pr-review/SKILL.md +1 -1
  6. package/claude/skills/claude-teach/SKILL.md +1 -1
  7. package/claude/skills/claude-worktree/SKILL.md +1 -1
  8. package/claude/skills/create-snippet/SKILL.md +1 -1
  9. package/claude/skills/git-branch/SKILL.md +1 -1
  10. package/claude/skills/git-commit/SKILL.md +1 -1
  11. package/claude/skills/git-issue/SKILL.md +2 -2
  12. package/claude/skills/git-pr/SKILL.md +5 -5
  13. package/claude/skills/git-split/SKILL.md +2 -2
  14. package/claude/skills/git-stage/SKILL.md +1 -1
  15. package/claude/skills/toolkit-cli/SKILL.md +0 -2
  16. package/docs/agents/audits.md +4 -4
  17. package/docs/agents/census.md +23 -0
  18. package/docs/agents/commands.md +1 -0
  19. package/docs/agents/index.md +1 -0
  20. package/docs/agents/records.md +1 -1
  21. package/docs/agents/teach.md +1 -1
  22. package/docs/ai-workflow.md +7 -6
  23. package/package.json +1 -1
  24. package/scripts/core/check-skill-paths.sh +1 -2
  25. package/scripts/core/verify.sh +0 -5
  26. package/src/audits/catalog.ts +48 -0
  27. package/src/census/count.ts +113 -0
  28. package/src/claude/skills-audit.ts +7 -0
  29. package/src/cli.ts +4 -0
  30. package/src/commands/census.ts +105 -0
  31. package/src/commands/claude.ts +20 -6
  32. package/src/commands/comments.ts +6 -0
  33. package/src/commands/context.ts +32 -7
  34. package/src/commands/gov.ts +2 -2
  35. package/src/commands/markdown.ts +18 -2
  36. package/src/context/audit.ts +16 -0
  37. package/src/gov/test-order.ts +31 -7
  38. package/src/markdown/files.ts +10 -0
  39. package/src/records/backup.ts +1 -0
  40. package/src/records/validate.ts +1 -3
  41. package/{claude/skills/git-split/references → standards}/branch.md +0 -1
  42. package/{claude/skills/git-commit/references → standards}/commit.md +0 -1
  43. package/{claude/skills/claude-teach/references → standards}/glossary.md +0 -1
  44. package/standards/index.md +6 -0
  45. package/standards/{bundled/issue.md → issue.md} +0 -1
  46. package/standards/{bundled/pr.md → pr.md} +0 -1
  47. package/standards/{bundled/snippets.md → snippets.md} +0 -1
  48. package/tooling/base/manifest.toml +0 -2
  49. package/tooling/base/reference.md +12 -12
  50. package/tooling/base/seeds/.claude/context/development.md +4 -6
  51. package/claude/skills/claude-worktree/references/branch.md +0 -60
  52. package/claude/skills/create-snippet/references/snippets.md +0 -78
  53. package/claude/skills/git-branch/references/branch.md +0 -60
  54. package/claude/skills/git-issue/references/issue.md +0 -95
  55. package/claude/skills/git-pr/references/branch.md +0 -60
  56. package/claude/skills/git-pr/references/pr.md +0 -139
  57. package/claude/skills/git-split/references/pr.md +0 -139
  58. package/claude/skills/git-stage/references/commit.md +0 -73
  59. package/scripts/core/regen-skill-references.sh +0 -27
  60. package/standards/bundled/branch.md +0 -60
  61. package/standards/bundled/commit.md +0 -73
  62. package/standards/bundled/glossary.md +0 -76
  63. package/tooling/base/configs/scripts/clean.sh +0 -45
  64. package/tooling/base/configs/scripts/update.sh +0 -49
@@ -1,139 +0,0 @@
1
- ---
2
- title: Pull request reference
3
- description: Pull request title and body conventions
4
- consumers: git-split, git-pr
5
- ---
6
-
7
- # Pull request reference
8
-
9
- ## Scope
10
-
11
- Governs a pull request title and body: their format and the sections the body carries.
12
-
13
- Does not govern:
14
-
15
- - Commit subject format, which shares the title form: `commit.md`
16
- - Branch naming: `branch.md`
17
- - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
18
- - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
19
- - Punctuation, formatting, and banned words in pull request prose: `markdown.md`
20
-
21
- ## Title
22
-
23
- - Format: `<type>(<scope>): <subject>`
24
- - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
25
- - Length: 72 characters maximum
26
-
27
- ## Content
28
-
29
- - Use imperative mood for all content (`add`, `fix`, `refactor`)
30
- - Do not start with "This PR," "This commit," "Included are," or "I have"
31
- - Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
32
- - Do not describe historical behavior or unchanged code. Describe new behavior only.
33
- - Do not include future promises or speculative documentation
34
- - Do not explain obvious changes (formatting, renaming variables)
35
- - Do not duplicate commit messages verbatim
36
-
37
- ## Sections
38
-
39
- - `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
40
- - `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
41
- - `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
42
- - Omit Technical Context for docs, config, or trivial changes
43
- - Use bullet points for multiple reasons, one sentence for a single reason
44
- - `## Testing` (optional): specify exact commands or test cases run
45
- - Omit Testing for docs, config, or trivial sync changes
46
- - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
47
- - `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
48
- - Visuals: include only when they clarify architecture, UI, or complex logic flows
49
-
50
- ## Testing discipline
51
-
52
- - Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
53
- - Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
54
- - Quote the count or output the run reported, never a figure carried from elsewhere.
55
- - Leave a box unchecked only when a human is required, and name which human and why on the same line.
56
- - Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
57
- - What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
58
- - A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
59
- - A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
60
- - Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
61
-
62
- ## Formatting
63
-
64
- - End every bullet point with a period
65
-
66
- ## Examples
67
-
68
- ### Template
69
-
70
- ```markdown
71
- ## Summary
72
-
73
- <Action Verb> <Direct Object> to <Result>.
74
-
75
- ## Key Changes
76
-
77
- - <Verb> <specific component/file/function> (<reason if non-obvious>)
78
- - <Verb> <specific component/file/function>
79
-
80
- ## Technical Context
81
-
82
- - <Architectural reasoning explaining why, not what>
83
-
84
- ## Testing
85
-
86
- - [x] <Command run> <observed result>
87
- - [x] <Edge case verified> <what was observed>
88
- - [ ] <Human-only check> (<which human, why>)
89
-
90
- ## For the reviewer
91
-
92
- - <What the reviewer should confirm>
93
- ```
94
-
95
- ### Correct
96
-
97
- ```markdown
98
- ## Summary
99
-
100
- Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
101
-
102
- ## Key Changes
103
-
104
- - Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
105
- - Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
106
-
107
- ## Technical Context
108
-
109
- - Migration to stateless session management for horizontal scalability. # why, not what
110
-
111
- ## Testing
112
-
113
- - [x] `npm run test:auth` passes, 42 tests. # command run + observed result
114
- - [x] Expired token rejected with a 401 against a local server. # edge case + what happened
115
- - [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
116
-
117
- ## For the reviewer
118
-
119
- - Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
120
- ```
121
-
122
- ### Incorrect
123
-
124
- ```markdown
125
- ## Summary
126
-
127
- This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
128
-
129
- ## Key Changes
130
-
131
- - Updated auth middleware files # vague, no specific component, no period
132
- - The old system used to check tokens differently # describes historical behavior
133
-
134
- ## Testing
135
-
136
- - Tested manually # no specific command or case
137
- - [ ] `npm run test:auth` # unchecked box for a check the agent can run
138
- - [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
139
- ```
@@ -1,139 +0,0 @@
1
- ---
2
- title: Pull request reference
3
- description: Pull request title and body conventions
4
- consumers: git-split, git-pr
5
- ---
6
-
7
- # Pull request reference
8
-
9
- ## Scope
10
-
11
- Governs a pull request title and body: their format and the sections the body carries.
12
-
13
- Does not govern:
14
-
15
- - Commit subject format, which shares the title form: `commit.md`
16
- - Branch naming: `branch.md`
17
- - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
18
- - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
19
- - Punctuation, formatting, and banned words in pull request prose: `markdown.md`
20
-
21
- ## Title
22
-
23
- - Format: `<type>(<scope>): <subject>`
24
- - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
25
- - Length: 72 characters maximum
26
-
27
- ## Content
28
-
29
- - Use imperative mood for all content (`add`, `fix`, `refactor`)
30
- - Do not start with "This PR," "This commit," "Included are," or "I have"
31
- - Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
32
- - Do not describe historical behavior or unchanged code. Describe new behavior only.
33
- - Do not include future promises or speculative documentation
34
- - Do not explain obvious changes (formatting, renaming variables)
35
- - Do not duplicate commit messages verbatim
36
-
37
- ## Sections
38
-
39
- - `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
40
- - `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
41
- - `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
42
- - Omit Technical Context for docs, config, or trivial changes
43
- - Use bullet points for multiple reasons, one sentence for a single reason
44
- - `## Testing` (optional): specify exact commands or test cases run
45
- - Omit Testing for docs, config, or trivial sync changes
46
- - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
47
- - `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
48
- - Visuals: include only when they clarify architecture, UI, or complex logic flows
49
-
50
- ## Testing discipline
51
-
52
- - Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
53
- - Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
54
- - Quote the count or output the run reported, never a figure carried from elsewhere.
55
- - Leave a box unchecked only when a human is required, and name which human and why on the same line.
56
- - Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
57
- - What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
58
- - A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
59
- - A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
60
- - Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
61
-
62
- ## Formatting
63
-
64
- - End every bullet point with a period
65
-
66
- ## Examples
67
-
68
- ### Template
69
-
70
- ```markdown
71
- ## Summary
72
-
73
- <Action Verb> <Direct Object> to <Result>.
74
-
75
- ## Key Changes
76
-
77
- - <Verb> <specific component/file/function> (<reason if non-obvious>)
78
- - <Verb> <specific component/file/function>
79
-
80
- ## Technical Context
81
-
82
- - <Architectural reasoning explaining why, not what>
83
-
84
- ## Testing
85
-
86
- - [x] <Command run> <observed result>
87
- - [x] <Edge case verified> <what was observed>
88
- - [ ] <Human-only check> (<which human, why>)
89
-
90
- ## For the reviewer
91
-
92
- - <What the reviewer should confirm>
93
- ```
94
-
95
- ### Correct
96
-
97
- ```markdown
98
- ## Summary
99
-
100
- Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
101
-
102
- ## Key Changes
103
-
104
- - Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
105
- - Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
106
-
107
- ## Technical Context
108
-
109
- - Migration to stateless session management for horizontal scalability. # why, not what
110
-
111
- ## Testing
112
-
113
- - [x] `npm run test:auth` passes, 42 tests. # command run + observed result
114
- - [x] Expired token rejected with a 401 against a local server. # edge case + what happened
115
- - [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
116
-
117
- ## For the reviewer
118
-
119
- - Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
120
- ```
121
-
122
- ### Incorrect
123
-
124
- ```markdown
125
- ## Summary
126
-
127
- This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
128
-
129
- ## Key Changes
130
-
131
- - Updated auth middleware files # vague, no specific component, no period
132
- - The old system used to check tokens differently # describes historical behavior
133
-
134
- ## Testing
135
-
136
- - Tested manually # no specific command or case
137
- - [ ] `npm run test:auth` # unchecked box for a check the agent can run
138
- - [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
139
- ```
@@ -1,73 +0,0 @@
1
- ---
2
- title: Commit reference
3
- description: Commit message format and type conventions
4
- consumers: git-commit, git-stage
5
- ---
6
-
7
- # Commit message reference
8
-
9
- ## Scope
10
-
11
- Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
12
-
13
- Does not govern:
14
-
15
- - Branch naming, which shares the type vocabulary: `branch.md`
16
- - Pull request title and body, which share the subject form: `pr.md`
17
- - Whether a phase label or a semver tag may appear in a subject: `versioning.md`
18
-
19
- ## Format
20
-
21
- - Structure: `<type>(<scope>): <subject>`
22
- - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
23
- - Subject: 72 characters maximum, no trailing period
24
-
25
- ## Types
26
-
27
- - `feat`: new feature or capability
28
- - `fix`: bug fix
29
- - `refactor`: structural changes (not a fix or feature)
30
- - `docs`: documentation only (README)
31
- - `chore`: maintenance tasks (deps, tooling, configs)
32
- - `perf`: performance improvements
33
- - `test`: add or modify tests
34
- - `style`: code formatting (whitespace, semicolons)
35
- - `build`: build system changes (webpack, npm scripts)
36
- - `ci`: CI/CD pipeline changes (GitHub Actions)
37
- - `revert`: revert a previous commit
38
-
39
- ## Scope vocabulary
40
-
41
- - Single lowercase word representing a system component
42
- - Prefer single word
43
- - Use kebab-case only when two words are genuinely needed for specificity
44
- - Do not use specific filenames as scopes
45
- - Do not use a scope that duplicates the type
46
- - Write scopes for release readability. They surface in `changelogithub` release notes.
47
-
48
- ## Subject
49
-
50
- - Use imperative mood (`add` not `added`)
51
- - Describe the actual technical change, not that something changed
52
- - Do not use vague verbs (`improve`, `refine`, `enhance`)
53
- - Do not repeat the scope in the subject line
54
- - Use single quotes if quoting
55
- - No backslash escaping or internal double quotes
56
- - No conversational filler or introductory phrases
57
-
58
- ## Examples
59
-
60
- ### Correct
61
-
62
- ```plaintext
63
- feat(api): add retry logic for failed webhooks # specific verb + clear change
64
- fix(auth): update 'UserSession' validation logic # scoped + imperative + single quotes
65
- ```
66
-
67
- ### Incorrect
68
-
69
- ```plaintext
70
- fix(user-auth): Fixed the redirect loop. # wrong casing + period + multi-word scope
71
- docs(docs): update the readme. # duplicate scope + period
72
- docs(api): improve documentation # vague verb + lacks specificity
73
- ```
@@ -1,27 +0,0 @@
1
- #!/usr/bin/env bash
2
- set -e
3
- set -o pipefail
4
-
5
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
6
- PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
7
-
8
- source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
9
-
10
- BUNDLED_DIR="$PROJECT_ROOT/standards/bundled"
11
- SKILLS_DIR="$PROJECT_ROOT/claude/skills"
12
-
13
- [ -d "$BUNDLED_DIR" ] || exit 0
14
-
15
- while IFS= read -r file; do
16
- filename="$(basename "$file")"
17
- consumers="$(read_frontmatter_field "$file" "consumers")"
18
- [ -z "$consumers" ] && continue
19
- IFS=',' read -ra skills <<<"$consumers"
20
- for skill in "${skills[@]}"; do
21
- skill="${skill// /}"
22
- [ -z "$skill" ] && continue
23
- dest_dir="$SKILLS_DIR/$skill/references"
24
- mkdir -p "$dest_dir"
25
- cp "$file" "$dest_dir/$filename"
26
- done
27
- done < <(find "$BUNDLED_DIR" -type f -name "*.md" | sort)
@@ -1,60 +0,0 @@
1
- ---
2
- title: Branch reference
3
- description: Branch naming format and type conventions
4
- consumers: git-branch, git-split, git-pr, claude-worktree
5
- ---
6
-
7
- # Branch reference
8
-
9
- ## Scope
10
-
11
- Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
12
-
13
- Does not govern:
14
-
15
- - Commit subject format, which shares the type vocabulary: `commit.md`
16
- - Pull request title and body: `pr.md`
17
- - Whether a phase label may appear in a branch name: `versioning.md`
18
- - Deriving a slug from a branch name for use in an output filename: `slug.md`
19
-
20
- ## Format
21
-
22
- - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
23
- - Length: 50 characters maximum
24
- - Casing: kebab-case only, no underscores or camelCase
25
- - Description: 2 words maximum, 3 only when genuinely needed for specificity
26
- - Capture the core change, not the commit message verbatim
27
- - For branches with multiple commits, use the unifying concern as the description.
28
- - Do not duplicate type in description (e.g., `feat/feature-login`)
29
-
30
- ## Types
31
-
32
- - `feat`: new feature or capability
33
- - `fix`: bug fix
34
- - `refactor`: structural changes (not a fix or feature)
35
- - `docs`: documentation only (README)
36
- - `chore`: maintenance tasks (deps, tooling, configs)
37
- - `perf`: performance improvements
38
- - `test`: add or modify tests
39
- - `style`: code formatting (whitespace, semicolons)
40
- - `build`: build system changes (webpack, npm scripts)
41
- - `ci`: CI/CD pipeline changes (GitHub Actions)
42
- - `revert`: revert a previous commit
43
-
44
- ## Examples
45
-
46
- ### Correct
47
-
48
- ```plaintext
49
- feat/jwt-expiration # clear feature scope
50
- fix/AUTH-123-connection-pool # includes ticket ID
51
- refactor/remove-deprecated-endpoints # clear refactor intent
52
- ```
53
-
54
- ### Incorrect
55
-
56
- ```plaintext
57
- feature/auth_stuff # wrong type + underscore
58
- feat/feature-add-login # duplicates type in description
59
- fix/DB-456-fix-the-database-connection-pool-memory-leak # exceeds 50 chars + verbatim message
60
- ```
@@ -1,73 +0,0 @@
1
- ---
2
- title: Commit reference
3
- description: Commit message format and type conventions
4
- consumers: git-commit, git-stage
5
- ---
6
-
7
- # Commit message reference
8
-
9
- ## Scope
10
-
11
- Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
12
-
13
- Does not govern:
14
-
15
- - Branch naming, which shares the type vocabulary: `branch.md`
16
- - Pull request title and body, which share the subject form: `pr.md`
17
- - Whether a phase label or a semver tag may appear in a subject: `versioning.md`
18
-
19
- ## Format
20
-
21
- - Structure: `<type>(<scope>): <subject>`
22
- - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
23
- - Subject: 72 characters maximum, no trailing period
24
-
25
- ## Types
26
-
27
- - `feat`: new feature or capability
28
- - `fix`: bug fix
29
- - `refactor`: structural changes (not a fix or feature)
30
- - `docs`: documentation only (README)
31
- - `chore`: maintenance tasks (deps, tooling, configs)
32
- - `perf`: performance improvements
33
- - `test`: add or modify tests
34
- - `style`: code formatting (whitespace, semicolons)
35
- - `build`: build system changes (webpack, npm scripts)
36
- - `ci`: CI/CD pipeline changes (GitHub Actions)
37
- - `revert`: revert a previous commit
38
-
39
- ## Scope vocabulary
40
-
41
- - Single lowercase word representing a system component
42
- - Prefer single word
43
- - Use kebab-case only when two words are genuinely needed for specificity
44
- - Do not use specific filenames as scopes
45
- - Do not use a scope that duplicates the type
46
- - Write scopes for release readability. They surface in `changelogithub` release notes.
47
-
48
- ## Subject
49
-
50
- - Use imperative mood (`add` not `added`)
51
- - Describe the actual technical change, not that something changed
52
- - Do not use vague verbs (`improve`, `refine`, `enhance`)
53
- - Do not repeat the scope in the subject line
54
- - Use single quotes if quoting
55
- - No backslash escaping or internal double quotes
56
- - No conversational filler or introductory phrases
57
-
58
- ## Examples
59
-
60
- ### Correct
61
-
62
- ```plaintext
63
- feat(api): add retry logic for failed webhooks # specific verb + clear change
64
- fix(auth): update 'UserSession' validation logic # scoped + imperative + single quotes
65
- ```
66
-
67
- ### Incorrect
68
-
69
- ```plaintext
70
- fix(user-auth): Fixed the redirect loop. # wrong casing + period + multi-word scope
71
- docs(docs): update the readme. # duplicate scope + period
72
- docs(api): improve documentation # vague verb + lacks specificity
73
- ```
@@ -1,76 +0,0 @@
1
- ---
2
- title: Glossary reference
3
- description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
4
- consumers: claude-teach
5
- ---
6
-
7
- # Glossary reference
8
-
9
- Applies to a glossary, the file holding one entry per term a body of material defines. It changes whenever the material names a concept a reader cannot look up yet, and it is revised in place rather than appended to.
10
-
11
- ## Scope
12
-
13
- Governs a glossary at `.claude/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
14
-
15
- Does not govern:
16
-
17
- - The folder a learning workspace lays out around its glossary, and the other files in it: `teach.md`
18
- - Which surface a glossary moves to once it leaves the material that produced it, which belongs to the surface driving that move
19
- - Voice, rhythm, and sentence construction: the `write-human` skill
20
- - Headings, punctuation, word choice, and file references: `markdown.md`
21
-
22
- ## What a working glossary looks like
23
-
24
- A glossary works when a reader who meets a term in the material settles it here without opening the page that introduced it:
25
-
26
- - Which word does this material use for the concept, and which words does it deliberately not use?
27
- - What does the term mean, stated without leaning on the term itself?
28
- - Where does the term appear, so a reader can see it used rather than only defined?
29
- - Does every entry carry a term the material actually uses?
30
-
31
- A glossary failing these is non-conforming even when it satisfies every shape rule below.
32
-
33
- ## Frontmatter
34
-
35
- - `title` (required): names the material the terms come from, in sentence case
36
- - `description` (required): one line naming what a reader gets from the entries
37
-
38
- ## Entries
39
-
40
- - Write one entry per term, as a single bullet.
41
- - Lead the bullet with the term as a bolded span, then the definition in one or two sentences.
42
- - Define the term without using it. A definition that spends the term explains nothing to the reader who arrived not knowing it.
43
- - Name where the term first appears, so a reader can reach one use of it in context.
44
- - Keep an entry to the meaning. Worked detail belongs on the page that teaches the term.
45
- - Sort entries alphabetically, so a reader who knows only the word finds it without reading the file.
46
-
47
- ## Which terms it carries
48
-
49
- - Add a term once the material has used it, never ahead of that. A glossary front-loaded with terms nothing has introduced is a syllabus rather than a reference.
50
- - Pick one word per concept and use that word everywhere. A glossary carrying two words for one thing hands the reader a choice it exists to remove.
51
- - List each rejected synonym as an alias to avoid inside the entry that won, so a reader arriving with the wrong word lands on the right one.
52
- - Use the glossary's own terms inside other definitions. A definition reaching for a synonym of a term defined two entries down teaches the reader a word the material does not use.
53
- - Revise an entry the material has moved under rather than adding a second one narrating the change.
54
-
55
- ## Grouping
56
-
57
- - Keep a short glossary as one alphabetical list under the title. Grouping a handful of entries costs a heading per category and saves no lookup.
58
- - Group a glossary long enough that one list stops helping under `##` headings by category, sorted alphabetically within each. Roughly two screens of entries is the signal.
59
- - Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
60
- - State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
61
-
62
- ## Template
63
-
64
- ```markdown
65
- ---
66
- title: <Material the terms come from>
67
- description: <one line naming what a reader gets from these entries>
68
- ---
69
-
70
- # <Material the terms come from>
71
-
72
- <One line on which material these terms come from and when the file changes.>
73
-
74
- - **<Term>**: <the meaning in one or two sentences, written without using the term>. Avoid <rejected synonym>. First appears in `<page or lesson>`.
75
- - **<Term>**: <the meaning in one or two sentences, written without using the term>. First appears in `<page or lesson>`.
76
- ```
@@ -1,45 +0,0 @@
1
- #!/bin/bash
2
- set -e
3
- set -o pipefail
4
-
5
- GREEN='\033[0;32m'
6
- RED='\033[0;31m'
7
- WHITE='\033[1;37m'
8
- GREY='\033[0;90m'
9
- NC='\033[0m'
10
-
11
- log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
12
- log_error() {
13
- echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
14
- exit 1
15
- }
16
- log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
17
- log_rem() { echo -e "${GREY}│${NC} ${RED}-${NC} $1"; }
18
-
19
- check_dependencies() {
20
- command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
21
- }
22
-
23
- main() {
24
- check_dependencies
25
-
26
- echo -e "${GREY}┌${NC}"
27
-
28
- echo -e "${GREY}├${NC} ${WHITE}Cleaning artifacts${NC}"
29
- rm -rf node_modules
30
-
31
- log_rem "node_modules/"
32
-
33
- log_step "Cleaning cache"
34
- bun pm cache rm
35
- log_info "Package manager cache cleared"
36
-
37
- log_step "Rehydrating project"
38
- bun install
39
- log_info "Dependencies installed"
40
-
41
- echo -e "${GREY}└${NC}\n"
42
- echo -e "${GREEN}✓ Clean complete${NC}"
43
- }
44
-
45
- main "$@"
@@ -1,49 +0,0 @@
1
- #!/bin/bash
2
- set -e
3
- set -o pipefail
4
-
5
- GREEN='\033[0;32m'
6
- YELLOW='\033[0;33m'
7
- RED='\033[0;31m'
8
- WHITE='\033[1;37m'
9
- GREY='\033[0;90m'
10
- NC='\033[0m'
11
-
12
- log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
13
- log_warn() { echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1"; }
14
- log_error() {
15
- echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
16
- exit 1
17
- }
18
- log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
19
-
20
- pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC} $line"; done; }
21
-
22
- check_dependencies() {
23
- command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
24
- }
25
-
26
- main() {
27
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
28
-
29
- check_dependencies
30
-
31
- echo -e "${GREY}┌${NC}"
32
-
33
- echo -e "${GREY}├${NC} ${WHITE}Interactive dependency update${NC}"
34
- echo -e "${GREY}│${NC}"
35
- bun update --interactive
36
-
37
- log_step "Verifying project health"
38
- if [ -f "$SCRIPT_DIR/verify.sh" ]; then
39
- VERIFY_NESTED=true "$SCRIPT_DIR/verify.sh"
40
- log_info "All checks passed"
41
- else
42
- log_warn "Verification script not found, skipping."
43
- fi
44
-
45
- echo -e "${GREY}└${NC}\n"
46
- echo -e "${GREEN}✓ Update complete${NC}"
47
- }
48
-
49
- main "$@"