@phren/cli 0.1.53 → 0.2.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.
@@ -1,216 +0,0 @@
1
- ---
2
- name: init
3
- description: Set up a new project in phren with summary, CLAUDE.md, task, and skill templates.
4
- dependencies:
5
- - git
6
- ---
7
- # phren-init - Scaffold a new project
8
-
9
- > Set up a new project in phren with summary, CLAUDE.md, task, and skill templates.
10
-
11
- Tell phren about a new project, or bootstrap phren himself if you're starting fresh.
12
-
13
- ## Usage
14
-
15
- ```
16
- phren-init my-new-project # scaffold a specific project
17
- phren-init # list existing projects, suggest unconfigured ones
18
- ```
19
-
20
- ## First: find or create the phren directory
21
-
22
- ```bash
23
- PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
24
- ls "$PHREN_DIR" 2>/dev/null
25
- ```
26
-
27
- If the phren directory doesn't exist, offer to create it:
28
- > "No phren repo found. Want me to create one at ~/.phren? This will set up the base directory structure (global/, profiles/, machines.yaml)."
29
-
30
- If the user says yes, create the base structure:
31
- ```bash
32
- mkdir -p "$PHREN_DIR"/{global/skills,profiles}
33
- # Create a starter machines.yaml
34
- # Create a starter profile
35
- ```
36
-
37
- Then continue with the project scaffolding below.
38
-
39
- ## With a project name
40
-
41
- ### 1. Check it doesn't already exist
42
-
43
- ```bash
44
- ls "$PHREN_DIR/<project-name>/" 2>/dev/null
45
- ```
46
-
47
- If it exists, tell the user and ask if they want to reset it or just update specific files.
48
-
49
- ### 2. Create the project directory
50
-
51
- ```bash
52
- mkdir -p "$PHREN_DIR/<project-name>/skills"
53
- ```
54
-
55
- ### 3. Create summary.md
56
-
57
- This is the project's identity card. Five lines, no more.
58
-
59
- ```markdown
60
- # <project-name>
61
-
62
- What: <one sentence about what this project does>
63
- Stack: <languages, frameworks, key deps>
64
- Status: <active / maintenance / new / archived>
65
- Run: <the main command to start it, e.g. "npm run dev">
66
- Watch out: <the one thing that trips people up>
67
- ```
68
-
69
- Ask the user for these if you can't figure them out from the project directory. If the project directory exists on disk (e.g. `~/<project-name>/`), read its package.json, pyproject.toml, README, or similar to pre-fill.
70
-
71
- ### 4. Create CLAUDE.md
72
-
73
- ```markdown
74
- # <project-name>
75
-
76
- <One paragraph: what this project is and what it does.>
77
-
78
- ## Commands
79
-
80
- ```
81
- <dev command>
82
- <build command>
83
- <test command>
84
- ```
85
-
86
- ## Architecture
87
-
88
- <!-- Fill this in as the project grows -->
89
-
90
- ## Conventions
91
-
92
- <!-- Project-specific rules, patterns, naming conventions -->
93
- ```
94
-
95
- Pre-fill from the project's existing README or package.json if available. Leave architecture and conventions as placeholders with the HTML comments.
96
-
97
- ### 5. Create tasks.md
98
-
99
- ```markdown
100
- # <project-name> tasks
101
-
102
- ## Active
103
-
104
- ## Queue
105
-
106
- ## Done
107
- ```
108
-
109
- ### 6. Create skills README
110
-
111
- ```markdown
112
- # <project-name> skills
113
-
114
- Project-specific skills go here. Add `.md` files and phren will resolve them together with global skills, then mirror the effective set into the project's `.claude/skills/` directory on sync.
115
- ```
116
-
117
- Write this to `$PHREN_DIR/<project-name>/skills/README.md`.
118
-
119
- ### 7. Add to profile(s)
120
-
121
- Check if profiles exist:
122
- ```bash
123
- ls "$PHREN_DIR/profiles/"*.yaml 2>/dev/null
124
- ```
125
-
126
- If profiles exist, ask: "Which profile should this project be in?" and show the options.
127
-
128
- If no profiles exist, offer to create one:
129
- > "No profiles set up yet. Want me to create a 'default' profile with this project in it?"
130
-
131
- Then add the project name to the chosen profile's `projects` list.
132
-
133
- ### 8. Commit (if git repo)
134
-
135
- ```bash
136
- cd "$PHREN_DIR"
137
- git add <project-name>/
138
- git add profiles/ # if modified
139
- git commit -m "add <project-name>"
140
- git push # only if remote exists
141
- ```
142
-
143
- If phren isn't a git repo yet, walk them through the full setup:
144
-
145
- ```bash
146
- cd "$PHREN_DIR"
147
- git init
148
- git add -A
149
- git commit -m "initial phren setup"
150
- ```
151
-
152
- Then check if `gh` is available:
153
-
154
- ```bash
155
- which gh && gh auth status
156
- ```
157
-
158
- If yes, offer to create the GitHub repo:
159
- > "Your phren isn't on GitHub yet. Want me to create a private repo and push it? That's what lets you sync across machines."
160
-
161
- If they say yes:
162
- ```bash
163
- gh repo create my-phren --private --source=. --push
164
- ```
165
-
166
- If `gh` isn't available, show the manual steps:
167
- > "Create a private repo at github.com/new, then:
168
- > git remote add origin git@github.com:YOU/my-phren.git
169
- > git push -u origin main
170
- >
171
- > Once it's on GitHub, clone it on any machine and run `phren-sync` to activate."
172
-
173
- ### 9. Report
174
-
175
- ```
176
- phren-init <project-name>
177
-
178
- Created:
179
- $PHREN_DIR/<project-name>/summary.md
180
- $PHREN_DIR/<project-name>/CLAUDE.md
181
- $PHREN_DIR/<project-name>/tasks.md
182
- $PHREN_DIR/<project-name>/skills/README.md
183
-
184
- Added to profile: default
185
-
186
- Run phren-sync to activate on this machine.
187
- ```
188
-
189
- ## Without a project name
190
-
191
- When user just runs `phren-init` with no args:
192
-
193
- 1. If phren directory exists, list all directories that have a `summary.md` (configured projects)
194
- 2. Look for directories in `~/` that look like projects (have package.json, pyproject.toml, Cargo.toml, go.mod, etc.) but don't have a phren entry
195
- 3. Show both lists and suggest adding unconfigured ones
196
-
197
- ```
198
- phren-init: project scan
199
-
200
- Configured in phren:
201
- myapp, api-server
202
-
203
- Found on this machine but not in phren:
204
- ~/side-project (has package.json)
205
- ~/experiments/rust-thing (has Cargo.toml)
206
-
207
- Run phren-init <name> to add one.
208
- ```
209
-
210
- If phren doesn't exist at all, offer to bootstrap it from scratch.
211
-
212
- ## Related skills
213
-
214
- - `phren-sync`: activate the new project on this machine after init
215
- - `phren-discover`: find what to build next in a project
216
- - `/tasks`: manage the project's task queue
@@ -1,121 +0,0 @@
1
- ---
2
- name: profiles
3
- description: Manage machine-to-profile and profile-to-project mappings in phren.
4
- dependencies:
5
- - git
6
- ---
7
- # phren-profiles - Manage your profiles
8
-
9
- > **Multi-machine only.** This skill is for users who sync phren across multiple machines and need to control which projects appear where. If you only use one machine, you can skip this -- `phren-sync` handles everything you need.
10
-
11
- > Add projects to profiles, move projects between profiles, create new profiles, and check what's in each one.
12
-
13
- Manage which projects appear on which machines by editing your profile definitions. Each machine maps to one profile, and each profile is a list of projects.
14
-
15
- ## Prerequisites
16
-
17
- You need a phren repo. The profiles live in `~/.phren/profiles/` and machine mappings live in `~/.phren/machines.yaml`.
18
-
19
- ```
20
- ~/.phren/
21
- profiles/
22
- work.yaml
23
- personal.yaml
24
- machines.yaml
25
- ```
26
-
27
- If you don't have a phren repo yet, start with `phren-init`.
28
-
29
- ## What's a profile?
30
-
31
- A profile is a YAML file listing projects for a machine role. Example:
32
-
33
- ```yaml
34
- name: work
35
- description: Work laptop with company projects
36
- projects:
37
- - global
38
- - my-api
39
- - frontend
40
- ```
41
-
42
- When you sync on a machine mapped to this profile, only those projects appear. Personal projects stay off work machines.
43
-
44
- ## How to use it
45
-
46
- ### "Add a project to a profile"
47
-
48
- User says: "add my-project to my work profile"
49
-
50
- 1. Find the profile file: `~/.phren/profiles/work.yaml`
51
- 2. Read it and find the `projects:` list
52
- 3. Add the project name if it's not already there
53
- 4. Commit the change
54
-
55
- ### "Create a new profile"
56
-
57
- User says: "create a new profile called staging"
58
-
59
- 1. Create a new file: `~/.phren/profiles/staging.yaml`
60
- 2. Fill it with the required structure:
61
-
62
- ```yaml
63
- name: staging
64
- description: Staging servers and experiments
65
- projects:
66
- - global
67
- ```
68
-
69
- 3. Ask which projects should be in this new profile (can add more later)
70
- 4. Commit the file
71
-
72
- ### "Show me what's in a profile"
73
-
74
- User says: "what's in my personal profile?"
75
-
76
- 1. Find `~/.phren/profiles/personal.yaml`
77
- 2. Read it and display the projects list
78
-
79
- ### "Move a project between profiles"
80
-
81
- User says: "move my-project from personal to work"
82
-
83
- 1. Find `~/.phren/profiles/personal.yaml` and remove the project
84
- 2. Find `~/.phren/profiles/work.yaml` and add the project
85
- 3. Commit both changes
86
-
87
- ### "Set this machine's profile"
88
-
89
- User says: "this machine is my work laptop"
90
-
91
- 1. Get the current machine name: `cat ~/.phren/.machine-id` or `hostname`
92
- 2. Ask which profile to use (show available profiles from `~/.phren/profiles/`)
93
- 3. Add/update the line in `~/.phren/machines.yaml`: `work-laptop: work`
94
- 4. Commit the change
95
- 5. Run `phren-sync` to activate
96
-
97
- ### "List my profiles"
98
-
99
- If the user asks what profiles exist:
100
-
101
- 1. List all files in `~/.phren/profiles/`
102
- 2. For each one, read the name and description fields
103
- 3. Show which machine is mapped to each profile (from `machines.yaml`)
104
-
105
- ## After making changes
106
-
107
- Always commit to the phren git repo:
108
-
109
- ```bash
110
- cd ~/.phren
111
- git add profiles/ machines.yaml
112
- git commit -m "update profiles"
113
- git push # only if remote exists
114
- ```
115
-
116
- Then suggest running `phren-sync` to activate changes on this machine.
117
-
118
- ## Related skills
119
-
120
- - `phren-sync`: sync your profiles to this machine and activate them
121
- - `phren-init`: create a new project or bootstrap phren from scratch
@@ -1,261 +0,0 @@
1
- ---
2
- name: sync
3
- description: Sync your Claude skills and project config across machines using profiles.
4
- dependencies:
5
- - git
6
- ---
7
- # phren-sync - Profile-aware sync
8
-
9
- > Sync your Claude skills and project config across machines using profiles that control what goes where.
10
-
11
- Phren carries your skills and project config between machines. Profile-aware: he 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, phren only brings over the projects in your machine's profile.
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
203
-
204
- ```bash
205
- cd "$PHREN_DIR"
206
- git add -A
207
- git commit -m "<project> updates from <machine-name>"
208
- git push
209
- ```
210
-
211
- ## Conversational shortcuts
212
-
213
- These should work naturally in conversation:
214
-
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 |
223
-
224
- ## New machine setup
225
-
226
- First time on a new machine:
227
-
228
- ```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
239
- ```
240
-
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.
252
-
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).
254
-
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.
256
-
257
- ## Related skills
258
-
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