@phren/cli 0.1.53 → 0.2.1
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/dist/cli/config.js +28 -0
- package/dist/cli/govern.d.ts +5 -0
- package/dist/cli/govern.js +66 -1
- package/dist/cli/hooks.js +26 -2
- package/dist/cli-registry.js +2 -0
- package/dist/content/summarize.d.ts +83 -0
- package/dist/content/summarize.js +298 -0
- package/dist/governance/policy.js +6 -2
- package/dist/index.js +19 -35
- package/dist/init/preferences.d.ts +6 -0
- package/dist/link/doctor.js +26 -0
- package/dist/mcp/profile.d.ts +80 -0
- package/dist/mcp/profile.js +282 -0
- package/dist/phren-paths.d.ts +2 -0
- package/dist/phren-paths.js +5 -0
- package/dist/shared/index.js +17 -14
- package/dist/shared/retrieval.d.ts +6 -0
- package/dist/shared/retrieval.js +9 -0
- package/dist/shared.d.ts +1 -1
- package/dist/shared.js +1 -1
- package/dist/status.js +9 -0
- package/dist/store-weight.d.ts +28 -0
- package/dist/store-weight.js +80 -0
- package/package.json +1 -1
- package/starter/global/CLAUDE.md +22 -86
- package/starter/global/skills/phren-profiles/SKILL.md +15 -107
- package/starter/global/skills/phren-sync/SKILL.md +17 -240
- package/skills/README.md +0 -7
- package/skills/consolidate/SKILL.md +0 -152
- package/skills/discover/SKILL.md +0 -175
- package/skills/docs.md +0 -170
- package/skills/init/SKILL.md +0 -216
- package/skills/profiles/SKILL.md +0 -121
- package/skills/sync/SKILL.md +0 -261
|
@@ -1,261 +1,38 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: phren-sync
|
|
3
|
-
description:
|
|
3
|
+
description: Pull your phren store onto this machine or push local changes back. Thin wrapper around the CLI, which does the linking.
|
|
4
4
|
dependencies:
|
|
5
5
|
- git
|
|
6
6
|
---
|
|
7
|
-
# phren-sync
|
|
7
|
+
# /phren-sync
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
phren's store is a git repo (`~/.phren`, or `$PHREN_PATH`) that syncs across machines through profiles: a profile lists projects, `machines.yaml` maps a machine to a profile, and the CLI links whatever the profile says belongs here. **Do not create symlinks or write `MEMORY.md` by hand.** The CLI owns the wiring and `phren doctor` checks it.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## Prerequisites
|
|
14
|
-
|
|
15
|
-
This skill requires a phren repository. If you don't have one yet, see "New machine setup" at the bottom.
|
|
16
|
-
|
|
17
|
-
**Expected structure:**
|
|
18
|
-
```
|
|
19
|
-
~/.phren/ # or wherever your phren repo lives
|
|
20
|
-
global/ # skills and config for all projects
|
|
21
|
-
skills/ # global skill files (.md)
|
|
22
|
-
CLAUDE.md # global Claude instructions
|
|
23
|
-
<project>/ # per-project config
|
|
24
|
-
CLAUDE.md
|
|
25
|
-
skills/
|
|
26
|
-
summary.md
|
|
27
|
-
profiles/ # machine profile definitions
|
|
28
|
-
work.yaml
|
|
29
|
-
personal.yaml
|
|
30
|
-
machines.yaml # maps machine names to profiles
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
If any of these are missing, the skill will tell you what to create and how.
|
|
34
|
-
|
|
35
|
-
## How it works
|
|
36
|
-
|
|
37
|
-
Phren uses profiles to decide what goes where. A profile is a list of projects. A machine is mapped to a profile. When you sync, only the projects in your machine's profile get linked.
|
|
38
|
-
|
|
39
|
-
## Sync down (pull to this machine)
|
|
40
|
-
|
|
41
|
-
When the user says "get my skills", "sync my config", "pull from phren", or just "phren-sync":
|
|
42
|
-
|
|
43
|
-
### 1. Find the phren directory
|
|
44
|
-
|
|
45
|
-
```bash
|
|
46
|
-
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
47
|
-
ls "$PHREN_DIR" 2>/dev/null
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
If the directory doesn't exist, tell the user:
|
|
51
|
-
> "No phren repo found at ~/.phren. Clone yours with `git clone <your-repo-url> ~/.phren`, or set `PHREN_DIR` to point to a different location."
|
|
52
|
-
|
|
53
|
-
### 2. Figure out which machine this is
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
cat ~/.phren/.machine-id 2>/dev/null || hostname
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
If `~/.phren/.machine-id` doesn't exist, ask the user to pick a name:
|
|
60
|
-
> "I need a machine name to look up your profile. What should I call this machine? (e.g. 'work-laptop', 'home-desktop')"
|
|
61
|
-
|
|
62
|
-
Then save it:
|
|
63
|
-
```bash
|
|
64
|
-
mkdir -p ~/.phren && echo "work-laptop" > ~/.phren/.machine-id
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### 3. Look up the profile
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
cat "$PHREN_DIR/machines.yaml"
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
If the machine name isn't in `machines.yaml`, tell the user:
|
|
74
|
-
> "Machine 'work-laptop' isn't in machines.yaml yet. Which profile should it use?"
|
|
75
|
-
> Then show available profiles: `ls "$PHREN_DIR/profiles/"*.yaml`
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
cat "$PHREN_DIR/profiles/<profile-name>.yaml"
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
The profile YAML has:
|
|
82
|
-
```yaml
|
|
83
|
-
name: work
|
|
84
|
-
description: Work laptop setup
|
|
85
|
-
projects:
|
|
86
|
-
- myapp
|
|
87
|
-
- api-server
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
If no profiles exist yet, offer to create one with `phren-init`.
|
|
91
|
-
|
|
92
|
-
### 4. Pull latest
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
cd "$PHREN_DIR" && git pull
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
If this fails (not a git repo, no remote), tell the user. Don't silently skip.
|
|
99
|
-
|
|
100
|
-
### 5. Refresh the machine with the supported flow
|
|
101
|
-
|
|
102
|
-
Run init against the pulled phren repo so hooks, MCP registration, and machine/profile wiring are refreshed:
|
|
103
|
-
|
|
104
|
-
```bash
|
|
105
|
-
PHREN_PATH="$PHREN_DIR" phren init -y
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
If the user is in an untracked repo afterward, tell them to open a session there and let the agent ask, or run `phren add` from that directory.
|
|
109
|
-
|
|
110
|
-
Only mention `phren link` if the user is explicitly repairing an older pre-init install.
|
|
111
|
-
|
|
112
|
-
### 6. Build the context file
|
|
113
|
-
|
|
114
|
-
Write `~/.phren-context.md` with a summary of what's active on this machine:
|
|
115
|
-
|
|
116
|
-
```markdown
|
|
117
|
-
# Phren context: <machine-name> (<profile-name>)
|
|
118
|
-
|
|
119
|
-
Machine: <machine-name>
|
|
120
|
-
Profile: <profile-name>
|
|
121
|
-
Last synced: <date>
|
|
122
|
-
|
|
123
|
-
## Active projects
|
|
124
|
-
- myapp: Description from summary.md
|
|
125
|
-
- api-server: Description from summary.md
|
|
126
|
-
|
|
127
|
-
## Global skills
|
|
128
|
-
phren-sync, phren-init, phren-consolidate, phren-discover
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Pull project descriptions from each project's `summary.md` if it exists.
|
|
132
|
-
|
|
133
|
-
### 7. Rebuild MEMORY.md
|
|
134
|
-
|
|
135
|
-
Regenerate `~/.claude/projects/*/memory/MEMORY.md` with cross-project awareness from the active profile. Pull key facts from each project's `summary.md`.
|
|
136
|
-
|
|
137
|
-
### 8. Check project health
|
|
138
|
-
|
|
139
|
-
After syncing, check each active project in the phren directory for missing files. Print a one-line status per project. Informational only, does not block the sync.
|
|
140
|
-
|
|
141
|
-
**Required files** (warn if missing):
|
|
142
|
-
- `summary.md`: project description used by context file and memory
|
|
143
|
-
- `CLAUDE.md`: project-level Claude instructions
|
|
144
|
-
|
|
145
|
-
**Recommended files** (note if missing, don't warn):
|
|
146
|
-
- `tasks.md`: persistent task queue
|
|
147
|
-
- `FINDINGS.md`: captured session findings
|
|
148
|
-
|
|
149
|
-
For each project in the profile, check `$PHREN_DIR/<project>/` for these files and print:
|
|
150
|
-
|
|
151
|
-
```
|
|
152
|
-
Project health:
|
|
153
|
-
+ my-app: all files present
|
|
154
|
-
~ backend: missing recommended: FINDINGS.md
|
|
155
|
-
! new-project: missing required: summary.md, CLAUDE.md
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
Legend: `+` all good, `~` missing recommended files, `!` missing required files.
|
|
159
|
-
|
|
160
|
-
Skip the "global" entry since it has a different structure. Only check actual project directories.
|
|
161
|
-
|
|
162
|
-
### 9. Report
|
|
163
|
-
|
|
164
|
-
```
|
|
165
|
-
phren-sync down: <machine-name> (<profile-name>)
|
|
166
|
-
|
|
167
|
-
Synced:
|
|
168
|
-
- myapp (CLAUDE.md + 3 skills)
|
|
169
|
-
- api-server (CLAUDE.md + 1 skill)
|
|
170
|
-
- global (CLAUDE.md + 11 skills)
|
|
171
|
-
|
|
172
|
-
Skipped (not in profile):
|
|
173
|
-
- old-project
|
|
174
|
-
|
|
175
|
-
Project health:
|
|
176
|
-
+ myapp: all files present
|
|
177
|
-
~ api-server: missing recommended: FINDINGS.md
|
|
178
|
-
|
|
179
|
-
Context: ~/.phren-context.md updated
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
## Sync up (push changes back)
|
|
183
|
-
|
|
184
|
-
When the user says "sync this back", "push to phren", "save this to my phren":
|
|
185
|
-
|
|
186
|
-
### 1. Find what changed
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
diff "$PHREN_DIR/<project>/CLAUDE.md" ./<project-path>/CLAUDE.md
|
|
190
|
-
diff -r "$PHREN_DIR/<project>/skills/" ./<project-path>/.claude/skills/
|
|
191
|
-
|
|
192
|
-
Remember: `.claude/skills/` is a generated mirror. The source-of-truth lives in Phren `skills/`, and the project mirror also includes inherited global skills after resolution.
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
If files are symlinked (same inode), they're already in sync. Just commit from the phren directory.
|
|
196
|
-
|
|
197
|
-
If files are regular copies that differ, copy them back:
|
|
198
|
-
```bash
|
|
199
|
-
cp <changed-file> "$PHREN_DIR/<project>/<corresponding-path>"
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
### 2. Commit and push
|
|
11
|
+
## Pull (new machine, or "sync my config")
|
|
203
12
|
|
|
204
13
|
```bash
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
14
|
+
git -C ~/.phren pull --rebase # or on a new machine: git clone <store-url> ~/.phren
|
|
15
|
+
phren profile switch <profile> # maps this machine (hostname) to a profile in machines.yaml
|
|
16
|
+
phren init -y # wires MCP, hooks, skill mirrors, project links for that profile
|
|
17
|
+
phren doctor # anything still red is either a repo not cloned here or a team store to join
|
|
209
18
|
```
|
|
210
19
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
These should work naturally in conversation:
|
|
20
|
+
If `machines.yaml` has no entry for this machine, ask which profile to use (`ls ~/.phren/profiles/`), then run the switch. If a profile project's repo is not on disk, that is expected on a new machine; clone it and run `phren add <path>`.
|
|
214
21
|
|
|
215
|
-
|
|
216
|
-
|-----------|-----------|
|
|
217
|
-
| "add myapp to my work profile" | Edit the profile YAML, add to projects list, commit |
|
|
218
|
-
| "show me my personal profile" | Read and display the profile YAML |
|
|
219
|
-
| "what's on this machine?" | Read and display `~/.phren-context.md` |
|
|
220
|
-
| "remove old-project from work" | Edit the profile YAML, commit |
|
|
221
|
-
| "switch to personal profile" | Update the machine mapping in `machines.yaml`, re-run sync down |
|
|
222
|
-
| "create a new profile called travel" | Create a new profile YAML with empty projects list, ask what to include |
|
|
22
|
+
## Push ("save this to my phren", "sync back")
|
|
223
23
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
First time on a new machine:
|
|
24
|
+
Store files are the linked originals, so edits made through `~/.claude/skills/*` or a project's `CLAUDE.md` are already in the store. Commit and push from there:
|
|
227
25
|
|
|
228
26
|
```bash
|
|
229
|
-
|
|
230
|
-
git clone <your-repo-url> ~/.phren
|
|
231
|
-
|
|
232
|
-
# 2. Name this machine
|
|
233
|
-
mkdir -p ~/.phren && echo "my-machine-name" > ~/.phren/.machine-id
|
|
234
|
-
|
|
235
|
-
# 3. Map it to a profile in machines.yaml
|
|
236
|
-
# Add a line: my-machine-name: work
|
|
237
|
-
|
|
238
|
-
# 4. Run phren-sync
|
|
27
|
+
git -C ~/.phren add -A && git -C ~/.phren commit -m "<what changed> from $(hostname)" && git -C ~/.phren push
|
|
239
28
|
```
|
|
240
29
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
## Conflict resolution
|
|
244
|
-
|
|
245
|
-
When two machines edit the same phren file before syncing, `git pull` will hit a merge conflict. Here's how to handle each file type:
|
|
246
|
-
|
|
247
|
-
**tasks.md**: Take both changes. Task items from both machines are valid. Concat them, deduplicate if needed, commit.
|
|
248
|
-
|
|
249
|
-
**FINDINGS.md**: Take both changes. Keep entries in chronological order. If both machines added entries on the same date, interleave or group them under the same date heading.
|
|
250
|
-
|
|
251
|
-
**CLAUDE.md**: Manual merge. Ask the user which version they want, or show both and let them pick. These files contain preferences and instructions where intent matters, so don't auto-resolve.
|
|
30
|
+
The stop hook auto-saves too; a manual push is only for "I want it on the other machine now".
|
|
252
31
|
|
|
253
|
-
|
|
32
|
+
## Conflicts
|
|
254
33
|
|
|
255
|
-
|
|
34
|
+
`git pull --rebase` may conflict when two machines edited the same file. `tasks.md` and `FINDINGS.md`: keep both sides. `CLAUDE.md` and skills: show the user both and let them choose. Never drop a side silently.
|
|
256
35
|
|
|
257
|
-
## Related
|
|
36
|
+
## Related
|
|
258
37
|
|
|
259
|
-
-
|
|
260
|
-
- `add_finding()`: capture findings via MCP (synced across machines by `push_changes()`)
|
|
261
|
-
- `phren-consolidate`: synthesize findings across projects
|
|
38
|
+
`/phren-profiles` to change what a profile contains. `phren config machines` and `phren config profiles` to see the mappings.
|
package/skills/README.md
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
# skills/
|
|
2
|
-
|
|
3
|
-
Phren slash commands that users invoke with `phren-<name>` (e.g. `phren-init`, `phren-sync`).
|
|
4
|
-
|
|
5
|
-
Each subdirectory contains a `SKILL.md` file with the full prompt that Claude executes when the skill is invoked. These are global skills shipped with the phren package -- they work across all projects.
|
|
6
|
-
|
|
7
|
-
Users interact with this directory when adding custom global skills or reading what built-in skills do. For project-specific skills, use `~/.phren/<project>/skills/` instead.
|
|
@@ -1,152 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: consolidate
|
|
3
|
-
description: Find patterns across project findings and surface insights that apply everywhere.
|
|
4
|
-
dependencies:
|
|
5
|
-
- git
|
|
6
|
-
---
|
|
7
|
-
# phren-consolidate - Cross-project synthesis
|
|
8
|
-
|
|
9
|
-
> Find patterns across project findings and surface insights that apply everywhere.
|
|
10
|
-
|
|
11
|
-
Read every project's FINDINGS.md, find patterns that show up across multiple projects, and write them to a shared global findings file.
|
|
12
|
-
|
|
13
|
-
The point: something you learned on one project probably applies elsewhere. Phren connects those fragments across projects.
|
|
14
|
-
|
|
15
|
-
## Prerequisites
|
|
16
|
-
|
|
17
|
-
This skill needs at least two projects with FINDINGS.md files to be useful. If you haven't captured any findings yet, use `add_finding()` during a session first.
|
|
18
|
-
|
|
19
|
-
**Works with or without profiles.** If profiles are set up, it scans projects in the active profile. If not, it scans all project directories in the phren repo.
|
|
20
|
-
|
|
21
|
-
## When to run
|
|
22
|
-
|
|
23
|
-
- Monthly, or when the user asks
|
|
24
|
-
- After a burst of work across multiple projects
|
|
25
|
-
- When starting a new project (to seed it with relevant cross-cutting knowledge)
|
|
26
|
-
|
|
27
|
-
## What to do
|
|
28
|
-
|
|
29
|
-
### 1. Find the phren directory
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
33
|
-
ls "$PHREN_DIR" 2>/dev/null
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
If it doesn't exist, tell the user:
|
|
37
|
-
> "No phren directory found at ~/.phren. This skill needs a phren repo with project findings. Run `phren-init` to set one up, or set PHREN_DIR if yours is elsewhere."
|
|
38
|
-
|
|
39
|
-
### 2. Gather ALL findings
|
|
40
|
-
|
|
41
|
-
Try the profile-aware path first, fall back to scanning all directories:
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
MACHINE=$(cat ~/.phren/.machine-id 2>/dev/null || hostname)
|
|
45
|
-
# look up profile in machines.yaml to get the project list
|
|
46
|
-
|
|
47
|
-
# fallback: scan all project directories
|
|
48
|
-
FINDINGS_FILES=()
|
|
49
|
-
for dir in "$PHREN_DIR"/*/; do
|
|
50
|
-
if [ -f "$dir/FINDINGS.md" ]; then
|
|
51
|
-
PROJECT_NAME=$(basename "$dir")
|
|
52
|
-
FINDINGS_FILES+=("$PROJECT_NAME:$dir/FINDINGS.md")
|
|
53
|
-
fi
|
|
54
|
-
done
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Read **every** FINDINGS.md file found. Don't sample or skip any. For each file, track which project it came from.
|
|
58
|
-
|
|
59
|
-
If no FINDINGS.md files exist anywhere, tell the user:
|
|
60
|
-
> "No FINDINGS.md files found in any project. Use `add_finding()` during a work session to start capturing findings."
|
|
61
|
-
|
|
62
|
-
If only one project has a FINDINGS.md, tell the user:
|
|
63
|
-
> "Only found findings for <project>. Need at least two projects to find cross-cutting patterns. Use `add_finding()` in other projects first."
|
|
64
|
-
|
|
65
|
-
### 3. Find cross-cutting patterns
|
|
66
|
-
|
|
67
|
-
Compare findings across all projects. A pattern counts as cross-cutting when the **same insight, technique, or pitfall** appears in 2+ projects. Don't just look for keyword overlap; look for conceptual overlap.
|
|
68
|
-
|
|
69
|
-
Be specific. Not "testing is important" but "mocking at service boundaries instead of HTTP layer caught integration bugs in both my-app and backend."
|
|
70
|
-
|
|
71
|
-
Common categories (use only the ones that have actual matches):
|
|
72
|
-
|
|
73
|
-
- **Build and tooling**: cache issues, config pitfalls, CI patterns
|
|
74
|
-
- **Testing**: mocking strategies, fixture patterns, what to test vs skip
|
|
75
|
-
- **TypeScript/JS**: type tricks, async pitfalls, framework quirks
|
|
76
|
-
- **State management**: reactivity pitfalls, update ordering, stale closures
|
|
77
|
-
- **API patterns**: error handling, retry logic, auth flows
|
|
78
|
-
- **Performance**: what actually mattered vs premature optimization
|
|
79
|
-
- **Git and workflow**: branching patterns, commit conventions, release steps
|
|
80
|
-
- **Dependencies**: version conflicts, peer dep issues, lock file handling
|
|
81
|
-
|
|
82
|
-
Don't force categories. If only one project mentions something, it stays project-specific. If a pattern genuinely spans projects, include it even if it doesn't fit a neat category.
|
|
83
|
-
|
|
84
|
-
### 4. Check existing global findings
|
|
85
|
-
|
|
86
|
-
Before writing, read `$PHREN_DIR/global/FINDINGS.md` if it exists. Don't duplicate entries that are already there. Update existing entries if there's new evidence or additional projects that confirm the pattern.
|
|
87
|
-
|
|
88
|
-
### 5. Write global findings
|
|
89
|
-
|
|
90
|
-
File: `$PHREN_DIR/global/FINDINGS.md`
|
|
91
|
-
|
|
92
|
-
```markdown
|
|
93
|
-
# Cross-project findings
|
|
94
|
-
|
|
95
|
-
Last consolidated: <date>
|
|
96
|
-
Sources: <list of project names scanned>
|
|
97
|
-
|
|
98
|
-
## Build and tooling
|
|
99
|
-
- Clear dist/ after any tsconfig change, the build cache doesn't invalidate (my-app, backend)
|
|
100
|
-
- Lock file conflicts: delete and regenerate, don't try to merge (my-app, frontend)
|
|
101
|
-
|
|
102
|
-
## Testing
|
|
103
|
-
- Mock at the service boundary, not the HTTP layer (backend, frontend)
|
|
104
|
-
- Session-scoped fixtures cause flaky parallel tests (backend, my-app)
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
Rules for each entry:
|
|
108
|
-
- Include which projects it came from in parentheses
|
|
109
|
-
- Be specific enough that someone could act on it without reading the original findings
|
|
110
|
-
- If two projects describe the same thing differently, synthesize into one clear statement
|
|
111
|
-
- Keep entries to 1-2 lines max
|
|
112
|
-
|
|
113
|
-
### 6. Report
|
|
114
|
-
|
|
115
|
-
```
|
|
116
|
-
phren-consolidate
|
|
117
|
-
|
|
118
|
-
Scanned: my-app (12 findings), backend (8 findings), frontend (5 findings)
|
|
119
|
-
|
|
120
|
-
Found 6 cross-cutting patterns:
|
|
121
|
-
Build: 2 patterns (cache invalidation, lock file handling)
|
|
122
|
-
Testing: 2 patterns (mock boundaries, fixture scoping)
|
|
123
|
-
TypeScript: 2 patterns (strict nulls, path aliases)
|
|
124
|
-
|
|
125
|
-
New patterns added: 4
|
|
126
|
-
Existing patterns updated: 2 (added new project evidence)
|
|
127
|
-
Skipped: 0 (already captured)
|
|
128
|
-
|
|
129
|
-
Updated: $PHREN_DIR/global/FINDINGS.md
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
### 7. Commit (if git repo)
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
cd "$PHREN_DIR"
|
|
136
|
-
git add global/FINDINGS.md
|
|
137
|
-
git commit -m "update global findings"
|
|
138
|
-
git push # only if remote exists
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
## What not to do
|
|
142
|
-
|
|
143
|
-
- Don't include findings that only apply to one project. Those stay in the project's own file.
|
|
144
|
-
- Don't water down specifics to make them "general." If it's about Angular signals specifically, say so.
|
|
145
|
-
- Don't duplicate what's already in global findings. Update existing entries if there's new evidence.
|
|
146
|
-
- Don't create a wall of text. Keep it scannable. Bullet points, grouped by theme.
|
|
147
|
-
- Don't invent patterns. If two findings use the same word but describe different problems, they're not a pattern.
|
|
148
|
-
|
|
149
|
-
## Related skills
|
|
150
|
-
|
|
151
|
-
- `add_finding()`: capture findings during a session via MCP
|
|
152
|
-
- `phren-sync`: sync the consolidated findings to other machines
|
package/skills/discover/SKILL.md
DELETED
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: discover
|
|
3
|
-
description: Audit your phren repo and tell you exactly what needs attention.
|
|
4
|
-
dependencies:
|
|
5
|
-
- git
|
|
6
|
-
- gh
|
|
7
|
-
---
|
|
8
|
-
# phren-discover - Phren health check
|
|
9
|
-
|
|
10
|
-
> Let phren audit your project store and tell you exactly what needs attention.
|
|
11
|
-
|
|
12
|
-
Phren scans your project directory for missing files, stale content, skill gaps, and stuck task items. He outputs a concrete, prioritized action list.
|
|
13
|
-
|
|
14
|
-
**Works standalone.** Just needs a phren directory.
|
|
15
|
-
|
|
16
|
-
## When to run
|
|
17
|
-
|
|
18
|
-
- Weekly or monthly maintenance
|
|
19
|
-
- When you feel like things are getting messy
|
|
20
|
-
- Before starting a new project (to see what you've been neglecting)
|
|
21
|
-
- When the user asks "what should I work on"
|
|
22
|
-
|
|
23
|
-
## What to do
|
|
24
|
-
|
|
25
|
-
### 1. Find the phren directory
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
29
|
-
ls "$PHREN_DIR" 2>/dev/null
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
If it doesn't exist:
|
|
33
|
-
> "No phren directory found at ~/.phren. Run `phren-init` to set one up."
|
|
34
|
-
|
|
35
|
-
### 2. Scan all projects
|
|
36
|
-
|
|
37
|
-
For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
for dir in "$PHREN_DIR"/*/; do
|
|
41
|
-
PROJECT=$(basename "$dir")
|
|
42
|
-
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
43
|
-
|
|
44
|
-
[ -f "$dir/CLAUDE.md" ] && echo "$PROJECT: has CLAUDE.md" || echo "$PROJECT: MISSING CLAUDE.md"
|
|
45
|
-
[ -f "$dir/summary.md" ] && echo "$PROJECT: has summary.md" || echo "$PROJECT: MISSING summary.md"
|
|
46
|
-
[ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
|
|
47
|
-
[ -f "$dir/tasks.md" ] && echo "$PROJECT: has tasks.md" || echo "$PROJECT: MISSING tasks.md"
|
|
48
|
-
done
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
### 3. Check staleness
|
|
52
|
-
|
|
53
|
-
For projects that are in a git-tracked phren, check when files were last modified:
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
cd "$PHREN_DIR"
|
|
57
|
-
for dir in */; do
|
|
58
|
-
PROJECT=$(basename "$dir")
|
|
59
|
-
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
60
|
-
|
|
61
|
-
if [ -f "$dir/FINDINGS.md" ]; then
|
|
62
|
-
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/FINDINGS.md" 2>/dev/null || stat -c %Y "$dir/FINDINGS.md" 2>/dev/null || stat -f %m "$dir/FINDINGS.md" 2>/dev/null)
|
|
63
|
-
echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
|
|
64
|
-
fi
|
|
65
|
-
|
|
66
|
-
if [ -f "$dir/CLAUDE.md" ]; then
|
|
67
|
-
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/CLAUDE.md" 2>/dev/null || stat -c %Y "$dir/CLAUDE.md" 2>/dev/null || stat -f %m "$dir/CLAUDE.md" 2>/dev/null)
|
|
68
|
-
echo "$PROJECT/CLAUDE.md: last updated $LAST_MODIFIED"
|
|
69
|
-
fi
|
|
70
|
-
done
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Flag anything not updated in 30+ days as stale.
|
|
74
|
-
|
|
75
|
-
### 4. Detect skill gaps
|
|
76
|
-
|
|
77
|
-
Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
|
|
78
|
-
- Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
|
|
79
|
-
- A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
|
|
80
|
-
- A task item keeps getting deferred, and might need a skill to make it easier
|
|
81
|
-
|
|
82
|
-
Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.
|
|
83
|
-
|
|
84
|
-
### 5. Check task health
|
|
85
|
-
|
|
86
|
-
For each project with a tasks.md:
|
|
87
|
-
- Count total items, completed items, items with no recent progress
|
|
88
|
-
- Flag tasks where nothing has been completed recently
|
|
89
|
-
- Flag tasks with items older than 60 days that haven't moved
|
|
90
|
-
|
|
91
|
-
### 6. Scaffold missing summary.md files
|
|
92
|
-
|
|
93
|
-
For each project with a missing summary.md, output the template and offer to create it:
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
Project: myapp
|
|
97
|
-
MISSING: summary.md
|
|
98
|
-
|
|
99
|
-
Template:
|
|
100
|
-
```
|
|
101
|
-
# myapp
|
|
102
|
-
|
|
103
|
-
What:
|
|
104
|
-
Stack:
|
|
105
|
-
Status: active
|
|
106
|
-
Run:
|
|
107
|
-
Watch out:
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
Want me to fill this in for myapp?
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.
|
|
114
|
-
|
|
115
|
-
### 7. Output the report
|
|
116
|
-
|
|
117
|
-
```
|
|
118
|
-
phren-discover
|
|
119
|
-
|
|
120
|
-
## Section 1: Missing files
|
|
121
|
-
|
|
122
|
-
Projects without core files:
|
|
123
|
-
|
|
124
|
-
| Project | CLAUDE.md | summary.md | FINDINGS.md | tasks.md |
|
|
125
|
-
|---------|-----------|------------|--------------|------------|
|
|
126
|
-
| myapp | ok | MISSING | MISSING | ok |
|
|
127
|
-
| api | ok | ok | ok | MISSING |
|
|
128
|
-
|
|
129
|
-
## Section 2: Stale content
|
|
130
|
-
|
|
131
|
-
Files not updated in 30+ days:
|
|
132
|
-
- my-app/FINDINGS.md: last updated 45 days ago
|
|
133
|
-
- frontend/CLAUDE.md: last updated 62 days ago
|
|
134
|
-
|
|
135
|
-
## Section 3: Skill gaps
|
|
136
|
-
|
|
137
|
-
Things you do repeatedly that could be skills:
|
|
138
|
-
- "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
|
|
139
|
-
- my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.
|
|
140
|
-
|
|
141
|
-
## Section 4: Task health
|
|
142
|
-
|
|
143
|
-
- my-app: 12 items (3 completed, 2 stale > 60 days)
|
|
144
|
-
- backend: 5 items (0 completed, all stale)
|
|
145
|
-
- frontend: 8 items (6 completed, healthy)
|
|
146
|
-
|
|
147
|
-
Stuck items:
|
|
148
|
-
- backend#2: "Add rate limiting" (added 90 days ago, no progress)
|
|
149
|
-
- my-app#7: "Improve query performance" (added 75 days ago, no progress)
|
|
150
|
-
|
|
151
|
-
## Top 3 things to work on next
|
|
152
|
-
|
|
153
|
-
1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
|
|
154
|
-
2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
|
|
155
|
-
3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
The "Top 3" section is the most important part. Make these:
|
|
159
|
-
- Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
|
|
160
|
-
- Prioritized (highest impact first)
|
|
161
|
-
- Actionable (someone could start right now)
|
|
162
|
-
|
|
163
|
-
## What not to do
|
|
164
|
-
|
|
165
|
-
- Don't flag missing files in projects that are archived or inactive
|
|
166
|
-
- Don't recommend creating files just for completeness; only flag what would actually help
|
|
167
|
-
- Don't be vague in the Top 3. Every item should be a clear next action.
|
|
168
|
-
- Don't pad the report with things that are fine. Focus on what needs attention.
|
|
169
|
-
|
|
170
|
-
## Related skills
|
|
171
|
-
|
|
172
|
-
- `phren-init`: scaffold missing files for a project
|
|
173
|
-
- `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
|
|
174
|
-
- `phren-consolidate`: synthesize cross-project patterns
|
|
175
|
-
- `/tasks`: work on stuck task items
|