@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.
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/claude-markdown-propose/REQUIREMENT.md +48 -0
- package/claude/skills/claude-markdown-propose/SKILL.md +118 -0
- package/claude/skills/claude-markdown-propose/references/format.md +107 -0
- package/claude/skills/claude-pr-review/SKILL.md +1 -1
- package/claude/skills/claude-teach/SKILL.md +1 -1
- package/claude/skills/claude-worktree/SKILL.md +1 -1
- package/claude/skills/create-snippet/SKILL.md +1 -1
- package/claude/skills/git-branch/SKILL.md +1 -1
- package/claude/skills/git-commit/SKILL.md +1 -1
- package/claude/skills/git-issue/SKILL.md +2 -2
- package/claude/skills/git-pr/SKILL.md +5 -5
- package/claude/skills/git-split/SKILL.md +2 -2
- package/claude/skills/git-stage/SKILL.md +1 -1
- package/claude/skills/toolkit-cli/SKILL.md +0 -2
- package/docs/agents/audits.md +4 -4
- package/docs/agents/census.md +23 -0
- package/docs/agents/commands.md +1 -0
- package/docs/agents/index.md +1 -0
- package/docs/agents/records.md +1 -1
- package/docs/agents/teach.md +1 -1
- package/docs/ai-workflow.md +7 -6
- package/package.json +1 -1
- package/scripts/core/check-skill-paths.sh +1 -2
- package/scripts/core/verify.sh +0 -5
- package/src/audits/catalog.ts +48 -0
- package/src/census/count.ts +113 -0
- package/src/claude/skills-audit.ts +7 -0
- package/src/cli.ts +4 -0
- package/src/commands/census.ts +105 -0
- package/src/commands/claude.ts +20 -6
- package/src/commands/comments.ts +6 -0
- package/src/commands/context.ts +32 -7
- package/src/commands/gov.ts +2 -2
- package/src/commands/markdown.ts +18 -2
- package/src/context/audit.ts +16 -0
- package/src/gov/test-order.ts +31 -7
- package/src/markdown/files.ts +10 -0
- package/src/records/backup.ts +1 -0
- package/src/records/validate.ts +1 -3
- package/{claude/skills/git-split/references → standards}/branch.md +0 -1
- package/{claude/skills/git-commit/references → standards}/commit.md +0 -1
- package/{claude/skills/claude-teach/references → standards}/glossary.md +0 -1
- package/standards/index.md +6 -0
- package/standards/{bundled/issue.md → issue.md} +0 -1
- package/standards/{bundled/pr.md → pr.md} +0 -1
- package/standards/{bundled/snippets.md → snippets.md} +0 -1
- package/tooling/base/manifest.toml +0 -2
- package/tooling/base/reference.md +12 -12
- package/tooling/base/seeds/.claude/context/development.md +4 -6
- package/claude/skills/claude-worktree/references/branch.md +0 -60
- package/claude/skills/create-snippet/references/snippets.md +0 -78
- package/claude/skills/git-branch/references/branch.md +0 -60
- package/claude/skills/git-issue/references/issue.md +0 -95
- package/claude/skills/git-pr/references/branch.md +0 -60
- package/claude/skills/git-pr/references/pr.md +0 -139
- package/claude/skills/git-split/references/pr.md +0 -139
- package/claude/skills/git-stage/references/commit.md +0 -73
- package/scripts/core/regen-skill-references.sh +0 -27
- package/standards/bundled/branch.md +0 -60
- package/standards/bundled/commit.md +0 -73
- package/standards/bundled/glossary.md +0 -76
- package/tooling/base/configs/scripts/clean.sh +0 -45
- 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 "$@"
|