@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.
@@ -1,261 +1,38 @@
1
1
  ---
2
2
  name: phren-sync
3
- description: Sync your Claude skills and project config across machines using profiles.
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 - Profile-aware sync
7
+ # /phren-sync
8
8
 
9
- > Sync your Claude skills and project config across machines using profiles that control what goes where.
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
- Bidirectional sync between your personal phren instance and the machines you work on. Profile-aware: only syncs what belongs on this machine.
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
- cd "$PHREN_DIR"
206
- git add -A
207
- git commit -m "<project> updates from <machine-name>"
208
- git push
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
- ## Conversational shortcuts
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
- | User says | What to do |
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
- ## New machine setup
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
- # 1. Clone your phren repo
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
- If you don't have a phren repo yet, start with `phren-init` to create one from scratch.
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
- **skills/ files**: If the same skill was edited on both machines, show the user a diff and let them choose. If different skills were edited, git handles this automatically (no conflict).
32
+ ## Conflicts
254
33
 
255
- **General approach**: Run `git pull --rebase` during sync. If conflicts appear, tell the user which files conflict and apply the rules above. Don't silently drop changes from either side.
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 skills
36
+ ## Related
258
37
 
259
- - `phren-init`: create a new project or set up phren from scratch
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
@@ -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