codewhale.history 2.11.9 → 2.11.10
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/CHANGELOG.md +5 -0
- package/README.md +177 -171
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,172 +1,178 @@
|
|
|
1
|
-
# CodeWhale Tools Pack
|
|
2
|
-
|
|
3
|
-
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
4
|
-
|
|
5
|
-
A portable pack of global CodeWhale commands: `//tools`, `//history`, `//snapshot`, and `//teach-me`.
|
|
6
|
-
|
|
7
|
-
Cross-platform — works on Windows, Mac, Linux.
|
|
8
|
-
|
|
9
|
-
## What's inside
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
tools_for_codewhale/
|
|
13
|
-
├── _list_sessions.js # codewhale-history command (Node.js)
|
|
14
|
-
├── package.json # npm package config
|
|
15
|
-
├── tools-install.js # Cross-platform installer (skills + instructions)
|
|
16
|
-
├── skills/
|
|
17
|
-
│ ├── history/SKILL.md # //history — calls codewhale-history
|
|
18
|
-
│ ├── snapshot/SKILL.md # //snapshot — pre-edit file backups
|
|
19
|
-
│ ├── teach-me/SKILL.md # //teach-me — interactive code quiz
|
|
20
|
-
│ └── tools/tools-skill/SKILL.md # //tools — lists all available tools
|
|
21
|
-
├── instructions.md # Trigger config (drop into any .codewhale/)
|
|
22
|
-
└── README.md # This file
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Install
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
codewhale
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
the
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
- **
|
|
95
|
-
- **
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
|
104
|
-
|
|
105
|
-
| `teach me
|
|
106
|
-
| `teach me
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
`
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
|
120
|
-
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
|
127
|
-
|
|
128
|
-
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
1
|
+
# CodeWhale Tools Pack
|
|
2
|
+
|
|
3
|
+
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
4
|
+
|
|
5
|
+
A portable pack of global CodeWhale commands: `//tools`, `//history`, `//snapshot`, and `//teach-me`.
|
|
6
|
+
|
|
7
|
+
Cross-platform — works on Windows, Mac, Linux.
|
|
8
|
+
|
|
9
|
+
## What's inside
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
tools_for_codewhale/
|
|
13
|
+
├── _list_sessions.js # codewhale-history command (Node.js)
|
|
14
|
+
├── package.json # npm package config
|
|
15
|
+
├── tools-install.js # Cross-platform installer (skills + instructions)
|
|
16
|
+
├── skills/
|
|
17
|
+
│ ├── history/SKILL.md # //history — calls codewhale-history
|
|
18
|
+
│ ├── snapshot/SKILL.md # //snapshot — pre-edit file backups
|
|
19
|
+
│ ├── teach-me/SKILL.md # //teach-me — interactive code quiz
|
|
20
|
+
│ └── tools/tools-skill/SKILL.md # //tools — lists all available tools
|
|
21
|
+
├── instructions.md # Trigger config (drop into any .codewhale/)
|
|
22
|
+
└── README.md # This file
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
1. Open a terminal (Windows Terminal, PowerShell, or Mac/Linux shell).
|
|
28
|
+
2. Navigate to your project folder (the codebase you want to use these commands with):
|
|
29
|
+
```bash
|
|
30
|
+
cd /path/to/your/project
|
|
31
|
+
```
|
|
32
|
+
3. Run the install command:
|
|
33
|
+
```bash
|
|
34
|
+
npm install -g codewhale.history
|
|
35
|
+
```
|
|
36
|
+
The installer detects your current working directory and sets up workspace triggers automatically. `//tools`, `//history`, `//snapshot`, and `//teach-me` work immediately.
|
|
37
|
+
|
|
38
|
+
### IMPORTANT
|
|
39
|
+
If you already have codewhale.history installed and want to update to the latest version in that folder, delete the `.codewhale/instructions.md` file before running `npm install -g codewhale.history`
|
|
40
|
+
|
|
41
|
+
### Per-workspace install (add triggers to another workspace)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
codewhale-tools-install # current workspace
|
|
45
|
+
codewhale-tools-install -p <target-path> # specific workspace
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## After install
|
|
49
|
+
|
|
50
|
+
### `//tools`
|
|
51
|
+
Lists every tool available in the current session, grouped by category (File I/O,
|
|
52
|
+
Search, Git, Sub-agents, Shell, Planning, etc.), with a brief description of what
|
|
53
|
+
each tool does. Read-only — no files touched.
|
|
54
|
+
|
|
55
|
+
**`//tools help`** or **`//tools readme`** — displays this full README inside any
|
|
56
|
+
CodeWhale session, so you can always reference the command docs without leaving
|
|
57
|
+
the terminal.
|
|
58
|
+
|
|
59
|
+
### `//history`
|
|
60
|
+
Lists all chat sessions for the current workspace. Each session row shows:
|
|
61
|
+
|
|
62
|
+
- **Date/time** — when the session was created
|
|
63
|
+
- **Title** — session title
|
|
64
|
+
- **Messages** — message count for that session
|
|
65
|
+
- **Tokens** — tokens consumed (with thousands separators)
|
|
66
|
+
- **Cost** — session cost in USD (to 4 decimal places)
|
|
67
|
+
- **Model** — which model was used
|
|
68
|
+
|
|
69
|
+
A **TOTAL** row at the bottom summarizes the number of sessions, total messages,
|
|
70
|
+
total tokens, and total cost across all sessions.
|
|
71
|
+
|
|
72
|
+
### `//snapshot`
|
|
73
|
+
Toggle pre-edit file backups: `//snapshot on`, `//snapshot off`,
|
|
74
|
+
`//snapshot status`.
|
|
75
|
+
|
|
76
|
+
**Why you'll want this:** Snapshot is designed for folders that are **not** Git
|
|
77
|
+
repos — especially folders full of Office documents (`.docx`, `.pptx`, `.xlsx`,
|
|
78
|
+
`.pdf`) that an AI agent is about to edit. Before every file modification,
|
|
79
|
+
snapshot saves a timestamped copy into `_snapshots/` so you can always get back
|
|
80
|
+
to the pre-AI version:
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
report.docx → _snapshots/report.2026-06-21_14-30-00.docx
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
If the workspace already has a `.git` directory, snapshot politely declines —
|
|
87
|
+
Git already has your back.
|
|
88
|
+
|
|
89
|
+
### `//teach-me`
|
|
90
|
+
An interactive code-teaching quiz that randomly selects real snippets from your
|
|
91
|
+
current project. Two independent dimensions across five difficulty levels:
|
|
92
|
+
|
|
93
|
+
**Response mode** (how you answer):
|
|
94
|
+
- **Passive** (default) — Describe your answer in the console.
|
|
95
|
+
- **Interactive** (`teach me interactive`) — Edit the actual file, say `done`.
|
|
96
|
+
|
|
97
|
+
**Content theme** (what it's about):
|
|
98
|
+
- **Standard** (default) — Code comprehension or line reconstruction.
|
|
99
|
+
- **SOLID** (`teach me solid`) — Anti-pattern detection and design restoration.
|
|
100
|
+
- **Spec** (`teach me spec`) — Spec-to-code traceability using office docs as source.
|
|
101
|
+
- **BA-Gates** (`teach me ba`) — BA documentation quality analysis (ambiguity, AC completeness, edge case coverage).
|
|
102
|
+
|
|
103
|
+
| Trigger | Response | Theme | What happens |
|
|
104
|
+
|---------|----------|-------|-------------|
|
|
105
|
+
| `teach me` | passive | standard | Present code; you explain it |
|
|
106
|
+
| `teach me interactive` | interactive | standard | Lines removed; you restore them |
|
|
107
|
+
| `teach me solid` | passive | solid | Degraded code; you describe fixes |
|
|
108
|
+
| `teach me solid interactive` | interactive | solid | Degraded code; you edit to fix it |
|
|
109
|
+
| `teach me spec` | passive | spec | Spec or code presented; you trace the link |
|
|
110
|
+
| `teach me spec interactive` | interactive | spec | Trace spec to code; you edit code to match |
|
|
111
|
+
| `teach me ba` | passive | ba-gates | BA doc fragment; you identify quality gate violations |
|
|
112
|
+
| `teach me ba interactive` | interactive | ba-gates | BA doc with issues; you edit to fix them |
|
|
113
|
+
|
|
114
|
+
**Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
|
|
115
|
+
`drill me`
|
|
116
|
+
|
|
117
|
+
**Modifiers (combine freely):**
|
|
118
|
+
|
|
119
|
+
| Modifier | Example | What it does |
|
|
120
|
+
|----------|---------|-------------|
|
|
121
|
+
| Language | `teach me python` | Restrict to Python, TypeScript, Rust, Go, Java… |
|
|
122
|
+
| Level | `teach me level 3` or `teach me l3` | Set difficulty 1–5 (default: 3) |
|
|
123
|
+
| Response | `teach me interactive` | Edit the file instead of describing |
|
|
124
|
+
| Theme | `teach me solid` | Anti-pattern detection — fix degraded design |
|
|
125
|
+
| Theme | `teach me spec` | Spec-to-code traceability via office docs |
|
|
126
|
+
| Theme | `teach me ba` | BA documentation quality analysis |
|
|
127
|
+
| Scope | `teach me services/` | Narrow to a specific file or folder |
|
|
128
|
+
| Concept | `teach me decorators` | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |
|
|
129
|
+
|
|
130
|
+
**Difficulty levels:**
|
|
131
|
+
|
|
132
|
+
| Level | Line range | What you'll face |
|
|
133
|
+
|-------|-----------|------------------|
|
|
134
|
+
| 1 | 5–15 | Straight-line logic, `if`/`else`, basic function calls |
|
|
135
|
+
| 2 | 8–20 | Loops, list/dict operations, simple `try`/`except` |
|
|
136
|
+
| 3 | 12–30 | Comprehensions, decorators, `with` statements, multiple branches |
|
|
137
|
+
| 4 | 18–45 | Generators, `async`/`await`, descriptors, threading, closures |
|
|
138
|
+
| 5 | 25–55 | Metaclasses, complex async patterns, multi-threading, architectural glue |
|
|
139
|
+
|
|
140
|
+
**Mid-round commands:** `hint` (get a nudge) · `skip` (see the answer) ·
|
|
141
|
+
`next` (draw a new snippet) · `level N` · `easier` · `harder` ·
|
|
142
|
+
`interactive` · `passive` · `solid` · `spec` · `ba` · `done` (verify work) · `stop`
|
|
143
|
+
|
|
144
|
+
**At the end** you get a session summary: rounds completed, mode, files covered,
|
|
145
|
+
what you're strong on, what to review, and a suggested next level.
|
|
146
|
+
|
|
147
|
+
In **SOLID theme**: the model rewrites code with deliberate anti-patterns
|
|
148
|
+
(STUPID, WET, god objects, tight coupling), presents the degraded code, and you
|
|
149
|
+
restore good design. Files are always restored with `git checkout` after each
|
|
150
|
+
round.
|
|
151
|
+
|
|
152
|
+
In **Spec theme**: the model scans your office documents (`.docx`, `.pptx`,
|
|
153
|
+
`.xlsx`) and source code, then quizzes you on the correlation between them.
|
|
154
|
+
Each round randomly picks one direction — either "what code implements this
|
|
155
|
+
spec?" or "what spec does this code satisfy?" — testing whether you truly
|
|
156
|
+
understand how requirements map to implementation. In interactive mode, you
|
|
157
|
+
edit the code to satisfy the spec; in passive mode, you describe the link.
|
|
158
|
+
|
|
159
|
+
In **BA-Gates theme**: the model runs a two-pass analysis over your BA documentation
|
|
160
|
+
files (`.docx`, `.pptx`, `.xlsx`, `.md`, `.feature`, `.txt`). Pass 1 uses regex
|
|
161
|
+
triage to flag fragments against three quality gates — **Ambiguity**
|
|
162
|
+
(unmeasurable terms, passive states), **Acceptance Criteria Completeness**
|
|
163
|
+
(missing structure, unverifiable outcomes), and **Edge Case Coverage** (missing
|
|
164
|
+
negative scenarios, error states). Pass 2 runs an LLM interpretation per
|
|
165
|
+
fragment at round time to generate quiz material and concrete improvement
|
|
166
|
+
options. You identify which gates a fragment triggers and describe the developer
|
|
167
|
+
impact. On skip or strike-3, the model presents 2–3 domain-specific rewrites per
|
|
168
|
+
issue with a best-fit recommendation.
|
|
169
|
+
|
|
170
|
+
## Want to take this further
|
|
171
|
+
If you've enjoyed using //teach-me and want to audit your entire specification repository and get a formatted report with readiness scores, band distributions, and ranked improvement recommendations, check out our licensed product //spec-analysis. Contact the developer for more info.
|
|
172
|
+
|
|
173
|
+
## Requirements
|
|
174
|
+
- Node.js (for the `codewhale-history` command)
|
|
175
|
+
- [CodeWhale](https://codewhale.net/en/docs)
|
|
176
|
+
|
|
177
|
+
## Contact Developer
|
|
172
178
|
[species8472](mailto:swyuri@yahoo.com)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codewhale.history",
|
|
3
|
-
"version": "2.11.
|
|
3
|
+
"version": "2.11.10",
|
|
4
4
|
"description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
|
|
5
5
|
"bin": {
|
|
6
6
|
"codewhale-history": "./_list_sessions.js",
|