@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.
- package/dist/cli/config.js +28 -0
- package/dist/cli-registry.js +1 -0
- package/dist/governance/policy.js +6 -2
- package/dist/index.js +19 -35
- package/dist/init/preferences.d.ts +6 -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.d.ts +1 -1
- package/dist/shared.js +1 -1
- 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
package/skills/init/SKILL.md
DELETED
|
@@ -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
|
package/skills/profiles/SKILL.md
DELETED
|
@@ -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
|
package/skills/sync/SKILL.md
DELETED
|
@@ -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
|