@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/starter/global/CLAUDE.md
CHANGED
|
@@ -1,99 +1,35 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Instructions for the agent
|
|
2
2
|
|
|
3
|
-
<!--
|
|
4
|
-
<!-- This becomes ~/.claude/CLAUDE.md after syncing. Claude reads it at the start of every session. -->
|
|
3
|
+
<!-- phren copies this to ~/.phren/global/CLAUDE.md and links it as ~/.claude/CLAUDE.md. Every session reads it, so keep it short and addressed to the agent. Fill in "How I work"; leave the rest. -->
|
|
5
4
|
|
|
6
|
-
## Memory
|
|
5
|
+
## Memory lives in phren
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
phren already knows this user's projects. Ask it before asking them to repeat themselves, and tell it what you learn as you go, not at the end.
|
|
9
8
|
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
9
|
+
- Recall: `search_knowledge(query)`, then `get_memory_detail(id)` for the full entry. `get_project_summary(project)` when starting on a project.
|
|
10
|
+
- Save: `add_finding(project, finding, findingType?)` the moment you learn something non-obvious that would save time next session. `kind: "note"` for a lightweight daily note.
|
|
11
|
+
- Tasks: `get_tasks(project)`, `add_task(project, item)`, `manage_task(action: "complete", project, item)`. Tasks live in phren, not in chat.
|
|
12
|
+
- Sessions: `session(action: "start", project)` for substantial work, `session(action: "end", summary)` when done. Hooks do not do this for you.
|
|
13
|
+
- Everything else: `phren_admin(action: …)`; `phren_admin(action: "list_actions")` lists it.
|
|
14
|
+
- Do not write to `~/.claude/projects/*/memory/`. phren is the memory.
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
Worth saving: decisions and why, pitfalls with the fix, patterns that worked, measurements. Not worth saving: secrets or personal data, one-off facts, narration of what happened, anything obvious from the code. Fewer, sharper entries beat volume.
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
<!-- "Write human from the start. No em dashes. No double hyphens. No AI buzzwords." -->
|
|
19
|
-
<!-- "Think visually. If it looks like a template, it's not done." -->
|
|
20
|
-
<!-- "Finish the job. Changelog, README, tests. Don't wait to be asked." -->
|
|
18
|
+
## How I work
|
|
21
19
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
### Phren skills (manage your project store)
|
|
27
|
-
|
|
28
|
-
| Skill | What it does |
|
|
29
|
-
|-------|-------------|
|
|
30
|
-
| `/phren-sync` | Pull phren to a new machine or push config changes back to the repo |
|
|
31
|
-
| `/phren-init` | Scaffold a new project with summary, CLAUDE.md, tasks |
|
|
32
|
-
| `/phren-discover` | Research what's missing in a project and surface gaps and opportunities |
|
|
33
|
-
| `/phren-consolidate` | Find patterns across all project FINDINGS.md files |
|
|
34
|
-
| `/phren-profiles` | Manages machine-to-profile mapping |
|
|
35
|
-
|
|
36
|
-
### Your own skills
|
|
37
|
-
|
|
38
|
-
Put personal workflow skills in `~/.phren/global/skills/` and list them here. See [phren](https://github.com/alaarab/phren) for examples.
|
|
39
|
-
|
|
40
|
-
<!-- Example:
|
|
41
|
-
| `/humanize` | Strip AI language from writing and code |
|
|
42
|
-
| `/release` | Version bump, changelog, tag, publish |
|
|
43
|
-
-->
|
|
44
|
-
|
|
45
|
-
## Agent coordination
|
|
46
|
-
|
|
47
|
-
<!-- If you use team agents, document your coordination pattern here. Example: -->
|
|
48
|
-
<!-- "Never use fire-and-forget background agents. Always use TeamCreate/TaskCreate/SendMessage." -->
|
|
49
|
-
|
|
50
|
-
- Team agents follow the same phren rules as the primary agent.
|
|
51
|
-
- Before handing work back or stopping, tell phren about non-obvious bugs, patterns, tradeoffs, or decisions with `add_finding(...)`.
|
|
52
|
-
- Do not wait for the user to explicitly say "save this as a finding" if the insight will matter next session.
|
|
53
|
-
|
|
54
|
-
## Project store
|
|
20
|
+
<!-- Your rules, in your words. Examples: -->
|
|
21
|
+
<!-- - Lead with the answer. Don't over-engineer. Scope to what I asked. -->
|
|
22
|
+
<!-- - Draft emails and comms for me, don't send. -->
|
|
23
|
+
<!-- - Save findings as we go, not at the end. -->
|
|
55
24
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
If you're using `phren init --mode project-local`, the root is `<repo>/.phren` instead. Project-local mode does not use profiles, machine mappings, or global hooks.
|
|
59
|
-
|
|
60
|
-
- `~/.phren/global/`: skills and config that apply everywhere
|
|
61
|
-
- `~/.phren/<project>/`: per-project CLAUDE.md, skills, tasks, findings
|
|
62
|
-
- `~/.phren/profiles/`: YAML files mapping project sets to machine roles
|
|
63
|
-
- `~/.phren/machines.yaml`: maps machine hostnames to profiles
|
|
64
|
-
|
|
65
|
-
Run `/phren-sync` to pull everything down or push changes back.
|
|
66
|
-
|
|
67
|
-
## MCP tools
|
|
68
|
-
|
|
69
|
-
The phren MCP server is running. Phren already knows a lot. Ask him before asking the user to repeat themselves.
|
|
70
|
-
|
|
71
|
-
- **At session start:** ask phren what's active: `list_projects()`, then `get_project_summary(name)` for the relevant project
|
|
72
|
-
- **When the user mentions a project, codebase, or task:** ask phren first: `search_knowledge(query)` before asking questions
|
|
73
|
-
- **When the user asks about commands, architecture, conventions, or past decisions:** check with phren: `search_knowledge(query)`
|
|
74
|
-
- **When the user mentions a task or todo:** ask phren what's tracked: `get_tasks(project)`
|
|
75
|
-
- **When you discover a non-obvious pattern, bug, or workaround:** tell phren immediately: `add_finding(project, insight)`
|
|
76
|
-
- **When the user says they want to do something later:** tell phren to remember it: `add_task(project, item)` instead of listing it in chat
|
|
77
|
-
- **When a task is finished:** tell phren it's done: `complete_task(project, item)` without being asked
|
|
78
|
-
|
|
79
|
-
**What NOT to tell phren:**
|
|
80
|
-
- Credentials, API keys, tokens, passwords, or anything that looks like a secret
|
|
81
|
-
- Personal or sensitive data: SSNs, financial info, health info, PII of any kind
|
|
82
|
-
- One-off facts that won't apply next session ("the server was down today")
|
|
83
|
-
- Narration of what happened ("fixed the login bug"): only save the actual insight
|
|
84
|
-
- Things obvious from reading the code or docs
|
|
85
|
-
|
|
86
|
-
If you're unsure whether something is worth telling phren, skip it. High-signal entries beat volume.
|
|
87
|
-
|
|
88
|
-
The goal: phren should already have the context before the user has to explain it. Tasks stay in files, not buried in chat history.
|
|
25
|
+
## Skills
|
|
89
26
|
|
|
90
|
-
|
|
27
|
+
`/phren-sync`, `/phren-init`, `/phren-discover`, `/phren-consolidate`, `/phren-profiles` manage the store. Your own skills live in `~/.phren/global/skills/` and are listed by `phren skills list`; invoke them by name rather than expecting them to appear as memory.
|
|
91
28
|
|
|
92
|
-
|
|
93
|
-
<!-- Auto-generated by /phren-sync. Don't edit manually. -->
|
|
29
|
+
## Team agents
|
|
94
30
|
|
|
95
|
-
|
|
31
|
+
Every agent follows these rules, and tells phren about non-obvious findings before handing work back.
|
|
96
32
|
|
|
97
|
-
##
|
|
33
|
+
## Where things are
|
|
98
34
|
|
|
99
|
-
|
|
35
|
+
`~/.phren` (or `$PHREN_PATH`) is a git repo: `global/` for everything-everywhere, `<project>/` for each project's CLAUDE.md, findings, tasks and skills, `profiles/` and `machines.yaml` for which projects belong on which machine. `phren doctor` explains anything that is off. If the MCP server is not running, phren still injects context through hooks; the CLI (`phren search`, `phren add-finding`) does the rest.
|
|
@@ -1,121 +1,29 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: phren-profiles
|
|
3
|
-
description: Manage machine-to-profile and profile-to-project mappings in phren.
|
|
3
|
+
description: Manage machine-to-profile and profile-to-project mappings in phren. Multi-machine users only.
|
|
4
4
|
dependencies:
|
|
5
5
|
- git
|
|
6
6
|
---
|
|
7
|
-
# phren-profiles
|
|
7
|
+
# /phren-profiles
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
A profile is a YAML file in `~/.phren/profiles/` with a `projects:` list. `machines.yaml` maps machine names to profiles. On each machine, phren links only the projects in that machine's profile. Single-machine users can ignore all of this.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Look
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
13
|
+
```bash
|
|
14
|
+
phren config machines # machine → profile
|
|
15
|
+
phren config profiles # profile → projects
|
|
67
16
|
```
|
|
68
17
|
|
|
69
|
-
|
|
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"
|
|
18
|
+
## Change
|
|
88
19
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
```
|
|
20
|
+
- **Move this machine to a profile:** `phren profile switch <name>` (then `phren init -y` to relink).
|
|
21
|
+
- **Add a project to a profile:** edit `~/.phren/profiles/<name>.yaml`, add the project name under `projects:`, commit.
|
|
22
|
+
- **New profile:** copy an existing YAML, rename `name:`, set its `projects:`, commit. Then map a machine to it.
|
|
23
|
+
- **Register a project that is on this machine but not linked:** `phren add <path>`.
|
|
115
24
|
|
|
116
|
-
|
|
25
|
+
Commit and push the store after changes (`/phren-sync` push), so the other machines pick them up.
|
|
117
26
|
|
|
118
|
-
##
|
|
27
|
+
## Conversational shortcuts
|
|
119
28
|
|
|
120
|
-
|
|
121
|
-
- `phren-init`: create a new project or bootstrap phren from scratch
|
|
29
|
+
"add X to my work profile", "what's on this machine?", "switch to personal" all map to the commands above. Show the YAML you changed.
|
|
@@ -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.
|