@justestif/pk 0.1.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/README.md +94 -0
- package/dist/index.js +3109 -0
- package/package.json +35 -0
- package/skill/SKILL.md +68 -0
- package/skill/assets/templates/decision.md +29 -0
- package/skill/assets/templates/index.md +25 -0
- package/skill/assets/templates/note.md +25 -0
- package/skill/assets/templates/question.md +25 -0
- package/skill/assets/templates/source.md +21 -0
- package/skill/references/git-workflow.md +77 -0
- package/skill/references/knowledge-model.md +127 -0
- package/skill/references/source-principles.md +73 -0
package/README.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# pk
|
|
2
|
+
|
|
3
|
+
Project knowledge CLI — structured intake, search, and recall over `knowledge/`.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @justestif/pk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires [Bun](https://bun.sh).
|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cd your-project
|
|
17
|
+
pk init # Claude Code (default)
|
|
18
|
+
pk init --harness pi # Pi / Oh My Pi
|
|
19
|
+
pk init --harness opencode # OpenCode
|
|
20
|
+
pk init --harness cursor # Cursor
|
|
21
|
+
pk init --harness codex # Codex CLI
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Creates `knowledge/`, copies the skill to `.agents/skills/pk/`, and installs
|
|
25
|
+
the harness adapter. Each harness injects current project context (open questions,
|
|
26
|
+
recent decisions, active notes) automatically into every session.
|
|
27
|
+
|
|
28
|
+
| Harness | Mechanism | Files generated |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| `claude` | `UserPromptSubmit` hook | `.claude/hooks/pk-*.ts` + `settings.json` |
|
|
31
|
+
| `pi` | `before_agent_start` extension | `.pi/extensions/pk.ts` |
|
|
32
|
+
| `opencode` | `experimental.chat.system.transform` | `.opencode/plugins/pk.ts` |
|
|
33
|
+
| `cursor` | Agent rule | `.cursor/rules/pk.mdc` |
|
|
34
|
+
| `codex` | `AGENTS.md` block | `AGENTS.md` |
|
|
35
|
+
|
|
36
|
+
## Commands
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pk new <type> <title> [--tags tag1,tag2]
|
|
40
|
+
pk search <query> [--context] [--limit 5]
|
|
41
|
+
pk synthesize [query] [--all] [--session-start]
|
|
42
|
+
pk index
|
|
43
|
+
pk lint
|
|
44
|
+
pk instructions <command>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Note types
|
|
48
|
+
|
|
49
|
+
| Type | Purpose |
|
|
50
|
+
|---|---|
|
|
51
|
+
| `note` | Durable project knowledge |
|
|
52
|
+
| `decision` | Chosen direction with rationale and consequences |
|
|
53
|
+
| `question` | Unresolved uncertainty that blocks or informs work |
|
|
54
|
+
| `source` | Raw input preserved for provenance |
|
|
55
|
+
|
|
56
|
+
### Example
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
pk new decision "Use SQLite for search index" --tags search,architecture
|
|
60
|
+
pk new question "Should we support multi-project mode?" --tags scope
|
|
61
|
+
pk index
|
|
62
|
+
pk search "sqlite"
|
|
63
|
+
pk synthesize --session-start
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Knowledge structure
|
|
67
|
+
|
|
68
|
+
Notes live in `knowledge/` as plain markdown files — human-editable,
|
|
69
|
+
git-diffable, readable without any tool.
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
knowledge/
|
|
73
|
+
notes/
|
|
74
|
+
decisions/
|
|
75
|
+
questions/
|
|
76
|
+
sources/
|
|
77
|
+
indexes/ ← generated by pk index
|
|
78
|
+
.index.db ← FTS5 search index, gitignored
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Search is powered by SQLite FTS5 with BM25 ranking and porter stemming.
|
|
82
|
+
The index is a derived artifact — delete it and run `pk index` to rebuild.
|
|
83
|
+
|
|
84
|
+
## Agent hook
|
|
85
|
+
|
|
86
|
+
`pk init` installs `.claude/hooks/pk-user-prompt-submit.ts` and registers it
|
|
87
|
+
in `.claude/settings.json`. The hook calls `pk synthesize --session-start`
|
|
88
|
+
on every prompt and injects the result as additional context.
|
|
89
|
+
|
|
90
|
+
To install for other harnesses, contributions welcome.
|
|
91
|
+
|
|
92
|
+
## License
|
|
93
|
+
|
|
94
|
+
MIT
|