@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
|
@@ -1,152 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: consolidate
|
|
3
|
-
description: Find patterns across project findings and surface insights that apply everywhere.
|
|
4
|
-
dependencies:
|
|
5
|
-
- git
|
|
6
|
-
---
|
|
7
|
-
# phren-consolidate - Cross-project synthesis
|
|
8
|
-
|
|
9
|
-
> Find patterns across project findings and surface insights that apply everywhere.
|
|
10
|
-
|
|
11
|
-
Read every project's FINDINGS.md, find patterns that show up across multiple projects, and write them to a shared global findings file.
|
|
12
|
-
|
|
13
|
-
The point: something you learned on one project probably applies elsewhere. Phren connects those fragments across projects.
|
|
14
|
-
|
|
15
|
-
## Prerequisites
|
|
16
|
-
|
|
17
|
-
This skill needs at least two projects with FINDINGS.md files to be useful. If you haven't captured any findings yet, use `add_finding()` during a session first.
|
|
18
|
-
|
|
19
|
-
**Works with or without profiles.** If profiles are set up, it scans projects in the active profile. If not, it scans all project directories in the phren repo.
|
|
20
|
-
|
|
21
|
-
## When to run
|
|
22
|
-
|
|
23
|
-
- Monthly, or when the user asks
|
|
24
|
-
- After a burst of work across multiple projects
|
|
25
|
-
- When starting a new project (to seed it with relevant cross-cutting knowledge)
|
|
26
|
-
|
|
27
|
-
## What to do
|
|
28
|
-
|
|
29
|
-
### 1. Find the phren directory
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
33
|
-
ls "$PHREN_DIR" 2>/dev/null
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
If it doesn't exist, tell the user:
|
|
37
|
-
> "No phren directory found at ~/.phren. This skill needs a phren repo with project findings. Run `phren-init` to set one up, or set PHREN_DIR if yours is elsewhere."
|
|
38
|
-
|
|
39
|
-
### 2. Gather ALL findings
|
|
40
|
-
|
|
41
|
-
Try the profile-aware path first, fall back to scanning all directories:
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
MACHINE=$(cat ~/.phren/.machine-id 2>/dev/null || hostname)
|
|
45
|
-
# look up profile in machines.yaml to get the project list
|
|
46
|
-
|
|
47
|
-
# fallback: scan all project directories
|
|
48
|
-
FINDINGS_FILES=()
|
|
49
|
-
for dir in "$PHREN_DIR"/*/; do
|
|
50
|
-
if [ -f "$dir/FINDINGS.md" ]; then
|
|
51
|
-
PROJECT_NAME=$(basename "$dir")
|
|
52
|
-
FINDINGS_FILES+=("$PROJECT_NAME:$dir/FINDINGS.md")
|
|
53
|
-
fi
|
|
54
|
-
done
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Read **every** FINDINGS.md file found. Don't sample or skip any. For each file, track which project it came from.
|
|
58
|
-
|
|
59
|
-
If no FINDINGS.md files exist anywhere, tell the user:
|
|
60
|
-
> "No FINDINGS.md files found in any project. Use `add_finding()` during a work session to start capturing findings."
|
|
61
|
-
|
|
62
|
-
If only one project has a FINDINGS.md, tell the user:
|
|
63
|
-
> "Only found findings for <project>. Need at least two projects to find cross-cutting patterns. Use `add_finding()` in other projects first."
|
|
64
|
-
|
|
65
|
-
### 3. Find cross-cutting patterns
|
|
66
|
-
|
|
67
|
-
Compare findings across all projects. A pattern counts as cross-cutting when the **same insight, technique, or pitfall** appears in 2+ projects. Don't just look for keyword overlap; look for conceptual overlap.
|
|
68
|
-
|
|
69
|
-
Be specific. Not "testing is important" but "mocking at service boundaries instead of HTTP layer caught integration bugs in both my-app and backend."
|
|
70
|
-
|
|
71
|
-
Common categories (use only the ones that have actual matches):
|
|
72
|
-
|
|
73
|
-
- **Build and tooling**: cache issues, config pitfalls, CI patterns
|
|
74
|
-
- **Testing**: mocking strategies, fixture patterns, what to test vs skip
|
|
75
|
-
- **TypeScript/JS**: type tricks, async pitfalls, framework quirks
|
|
76
|
-
- **State management**: reactivity pitfalls, update ordering, stale closures
|
|
77
|
-
- **API patterns**: error handling, retry logic, auth flows
|
|
78
|
-
- **Performance**: what actually mattered vs premature optimization
|
|
79
|
-
- **Git and workflow**: branching patterns, commit conventions, release steps
|
|
80
|
-
- **Dependencies**: version conflicts, peer dep issues, lock file handling
|
|
81
|
-
|
|
82
|
-
Don't force categories. If only one project mentions something, it stays project-specific. If a pattern genuinely spans projects, include it even if it doesn't fit a neat category.
|
|
83
|
-
|
|
84
|
-
### 4. Check existing global findings
|
|
85
|
-
|
|
86
|
-
Before writing, read `$PHREN_DIR/global/FINDINGS.md` if it exists. Don't duplicate entries that are already there. Update existing entries if there's new evidence or additional projects that confirm the pattern.
|
|
87
|
-
|
|
88
|
-
### 5. Write global findings
|
|
89
|
-
|
|
90
|
-
File: `$PHREN_DIR/global/FINDINGS.md`
|
|
91
|
-
|
|
92
|
-
```markdown
|
|
93
|
-
# Cross-project findings
|
|
94
|
-
|
|
95
|
-
Last consolidated: <date>
|
|
96
|
-
Sources: <list of project names scanned>
|
|
97
|
-
|
|
98
|
-
## Build and tooling
|
|
99
|
-
- Clear dist/ after any tsconfig change, the build cache doesn't invalidate (my-app, backend)
|
|
100
|
-
- Lock file conflicts: delete and regenerate, don't try to merge (my-app, frontend)
|
|
101
|
-
|
|
102
|
-
## Testing
|
|
103
|
-
- Mock at the service boundary, not the HTTP layer (backend, frontend)
|
|
104
|
-
- Session-scoped fixtures cause flaky parallel tests (backend, my-app)
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
Rules for each entry:
|
|
108
|
-
- Include which projects it came from in parentheses
|
|
109
|
-
- Be specific enough that someone could act on it without reading the original findings
|
|
110
|
-
- If two projects describe the same thing differently, synthesize into one clear statement
|
|
111
|
-
- Keep entries to 1-2 lines max
|
|
112
|
-
|
|
113
|
-
### 6. Report
|
|
114
|
-
|
|
115
|
-
```
|
|
116
|
-
phren-consolidate
|
|
117
|
-
|
|
118
|
-
Scanned: my-app (12 findings), backend (8 findings), frontend (5 findings)
|
|
119
|
-
|
|
120
|
-
Found 6 cross-cutting patterns:
|
|
121
|
-
Build: 2 patterns (cache invalidation, lock file handling)
|
|
122
|
-
Testing: 2 patterns (mock boundaries, fixture scoping)
|
|
123
|
-
TypeScript: 2 patterns (strict nulls, path aliases)
|
|
124
|
-
|
|
125
|
-
New patterns added: 4
|
|
126
|
-
Existing patterns updated: 2 (added new project evidence)
|
|
127
|
-
Skipped: 0 (already captured)
|
|
128
|
-
|
|
129
|
-
Updated: $PHREN_DIR/global/FINDINGS.md
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
### 7. Commit (if git repo)
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
cd "$PHREN_DIR"
|
|
136
|
-
git add global/FINDINGS.md
|
|
137
|
-
git commit -m "update global findings"
|
|
138
|
-
git push # only if remote exists
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
## What not to do
|
|
142
|
-
|
|
143
|
-
- Don't include findings that only apply to one project. Those stay in the project's own file.
|
|
144
|
-
- Don't water down specifics to make them "general." If it's about Angular signals specifically, say so.
|
|
145
|
-
- Don't duplicate what's already in global findings. Update existing entries if there's new evidence.
|
|
146
|
-
- Don't create a wall of text. Keep it scannable. Bullet points, grouped by theme.
|
|
147
|
-
- Don't invent patterns. If two findings use the same word but describe different problems, they're not a pattern.
|
|
148
|
-
|
|
149
|
-
## Related skills
|
|
150
|
-
|
|
151
|
-
- `add_finding()`: capture findings during a session via MCP
|
|
152
|
-
- `phren-sync`: sync the consolidated findings to other machines
|
package/skills/discover/SKILL.md
DELETED
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: discover
|
|
3
|
-
description: Audit your phren repo and tell you exactly what needs attention.
|
|
4
|
-
dependencies:
|
|
5
|
-
- git
|
|
6
|
-
- gh
|
|
7
|
-
---
|
|
8
|
-
# phren-discover - Phren health check
|
|
9
|
-
|
|
10
|
-
> Let phren audit your project store and tell you exactly what needs attention.
|
|
11
|
-
|
|
12
|
-
Phren scans your project directory for missing files, stale content, skill gaps, and stuck task items. He outputs a concrete, prioritized action list.
|
|
13
|
-
|
|
14
|
-
**Works standalone.** Just needs a phren directory.
|
|
15
|
-
|
|
16
|
-
## When to run
|
|
17
|
-
|
|
18
|
-
- Weekly or monthly maintenance
|
|
19
|
-
- When you feel like things are getting messy
|
|
20
|
-
- Before starting a new project (to see what you've been neglecting)
|
|
21
|
-
- When the user asks "what should I work on"
|
|
22
|
-
|
|
23
|
-
## What to do
|
|
24
|
-
|
|
25
|
-
### 1. Find the phren directory
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
29
|
-
ls "$PHREN_DIR" 2>/dev/null
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
If it doesn't exist:
|
|
33
|
-
> "No phren directory found at ~/.phren. Run `phren-init` to set one up."
|
|
34
|
-
|
|
35
|
-
### 2. Scan all projects
|
|
36
|
-
|
|
37
|
-
For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
for dir in "$PHREN_DIR"/*/; do
|
|
41
|
-
PROJECT=$(basename "$dir")
|
|
42
|
-
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
43
|
-
|
|
44
|
-
[ -f "$dir/CLAUDE.md" ] && echo "$PROJECT: has CLAUDE.md" || echo "$PROJECT: MISSING CLAUDE.md"
|
|
45
|
-
[ -f "$dir/summary.md" ] && echo "$PROJECT: has summary.md" || echo "$PROJECT: MISSING summary.md"
|
|
46
|
-
[ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
|
|
47
|
-
[ -f "$dir/tasks.md" ] && echo "$PROJECT: has tasks.md" || echo "$PROJECT: MISSING tasks.md"
|
|
48
|
-
done
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
### 3. Check staleness
|
|
52
|
-
|
|
53
|
-
For projects that are in a git-tracked phren, check when files were last modified:
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
cd "$PHREN_DIR"
|
|
57
|
-
for dir in */; do
|
|
58
|
-
PROJECT=$(basename "$dir")
|
|
59
|
-
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
60
|
-
|
|
61
|
-
if [ -f "$dir/FINDINGS.md" ]; then
|
|
62
|
-
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/FINDINGS.md" 2>/dev/null || stat -c %Y "$dir/FINDINGS.md" 2>/dev/null || stat -f %m "$dir/FINDINGS.md" 2>/dev/null)
|
|
63
|
-
echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
|
|
64
|
-
fi
|
|
65
|
-
|
|
66
|
-
if [ -f "$dir/CLAUDE.md" ]; then
|
|
67
|
-
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/CLAUDE.md" 2>/dev/null || stat -c %Y "$dir/CLAUDE.md" 2>/dev/null || stat -f %m "$dir/CLAUDE.md" 2>/dev/null)
|
|
68
|
-
echo "$PROJECT/CLAUDE.md: last updated $LAST_MODIFIED"
|
|
69
|
-
fi
|
|
70
|
-
done
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Flag anything not updated in 30+ days as stale.
|
|
74
|
-
|
|
75
|
-
### 4. Detect skill gaps
|
|
76
|
-
|
|
77
|
-
Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
|
|
78
|
-
- Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
|
|
79
|
-
- A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
|
|
80
|
-
- A task item keeps getting deferred, and might need a skill to make it easier
|
|
81
|
-
|
|
82
|
-
Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.
|
|
83
|
-
|
|
84
|
-
### 5. Check task health
|
|
85
|
-
|
|
86
|
-
For each project with a tasks.md:
|
|
87
|
-
- Count total items, completed items, items with no recent progress
|
|
88
|
-
- Flag tasks where nothing has been completed recently
|
|
89
|
-
- Flag tasks with items older than 60 days that haven't moved
|
|
90
|
-
|
|
91
|
-
### 6. Scaffold missing summary.md files
|
|
92
|
-
|
|
93
|
-
For each project with a missing summary.md, output the template and offer to create it:
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
Project: myapp
|
|
97
|
-
MISSING: summary.md
|
|
98
|
-
|
|
99
|
-
Template:
|
|
100
|
-
```
|
|
101
|
-
# myapp
|
|
102
|
-
|
|
103
|
-
What:
|
|
104
|
-
Stack:
|
|
105
|
-
Status: active
|
|
106
|
-
Run:
|
|
107
|
-
Watch out:
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
Want me to fill this in for myapp?
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.
|
|
114
|
-
|
|
115
|
-
### 7. Output the report
|
|
116
|
-
|
|
117
|
-
```
|
|
118
|
-
phren-discover
|
|
119
|
-
|
|
120
|
-
## Section 1: Missing files
|
|
121
|
-
|
|
122
|
-
Projects without core files:
|
|
123
|
-
|
|
124
|
-
| Project | CLAUDE.md | summary.md | FINDINGS.md | tasks.md |
|
|
125
|
-
|---------|-----------|------------|--------------|------------|
|
|
126
|
-
| myapp | ok | MISSING | MISSING | ok |
|
|
127
|
-
| api | ok | ok | ok | MISSING |
|
|
128
|
-
|
|
129
|
-
## Section 2: Stale content
|
|
130
|
-
|
|
131
|
-
Files not updated in 30+ days:
|
|
132
|
-
- my-app/FINDINGS.md: last updated 45 days ago
|
|
133
|
-
- frontend/CLAUDE.md: last updated 62 days ago
|
|
134
|
-
|
|
135
|
-
## Section 3: Skill gaps
|
|
136
|
-
|
|
137
|
-
Things you do repeatedly that could be skills:
|
|
138
|
-
- "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
|
|
139
|
-
- my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.
|
|
140
|
-
|
|
141
|
-
## Section 4: Task health
|
|
142
|
-
|
|
143
|
-
- my-app: 12 items (3 completed, 2 stale > 60 days)
|
|
144
|
-
- backend: 5 items (0 completed, all stale)
|
|
145
|
-
- frontend: 8 items (6 completed, healthy)
|
|
146
|
-
|
|
147
|
-
Stuck items:
|
|
148
|
-
- backend#2: "Add rate limiting" (added 90 days ago, no progress)
|
|
149
|
-
- my-app#7: "Improve query performance" (added 75 days ago, no progress)
|
|
150
|
-
|
|
151
|
-
## Top 3 things to work on next
|
|
152
|
-
|
|
153
|
-
1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
|
|
154
|
-
2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
|
|
155
|
-
3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
The "Top 3" section is the most important part. Make these:
|
|
159
|
-
- Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
|
|
160
|
-
- Prioritized (highest impact first)
|
|
161
|
-
- Actionable (someone could start right now)
|
|
162
|
-
|
|
163
|
-
## What not to do
|
|
164
|
-
|
|
165
|
-
- Don't flag missing files in projects that are archived or inactive
|
|
166
|
-
- Don't recommend creating files just for completeness; only flag what would actually help
|
|
167
|
-
- Don't be vague in the Top 3. Every item should be a clear next action.
|
|
168
|
-
- Don't pad the report with things that are fine. Focus on what needs attention.
|
|
169
|
-
|
|
170
|
-
## Related skills
|
|
171
|
-
|
|
172
|
-
- `phren-init`: scaffold missing files for a project
|
|
173
|
-
- `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
|
|
174
|
-
- `phren-consolidate`: synthesize cross-project patterns
|
|
175
|
-
- `/tasks`: work on stuck task items
|
package/skills/docs.md
DELETED
|
@@ -1,170 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: docs
|
|
3
|
-
description: Update and verify all phren documentation surfaces after code changes.
|
|
4
|
-
dependencies:
|
|
5
|
-
- git
|
|
6
|
-
---
|
|
7
|
-
# phren-docs - Documentation accuracy check and update
|
|
8
|
-
|
|
9
|
-
> Keep all phren documentation surfaces in sync with the code after any change.
|
|
10
|
-
|
|
11
|
-
Invoke this after adding tools, changing CLI commands, bumping versions, or editing hooks. It walks every documentation surface, checks what's stale, and updates `docs/documentation.html` (the canonical public-facing reference).
|
|
12
|
-
|
|
13
|
-
## When to run
|
|
14
|
-
|
|
15
|
-
- After adding, removing, or renaming MCP tools
|
|
16
|
-
- After changing CLI commands or their flags
|
|
17
|
-
- After bumping the version number
|
|
18
|
-
- After changing hook names, events, or behavior
|
|
19
|
-
- Before publishing to npm
|
|
20
|
-
- When the user says "update the docs" or "check the docs"
|
|
21
|
-
|
|
22
|
-
## Documentation surfaces
|
|
23
|
-
|
|
24
|
-
| File | What it contains | What to check |
|
|
25
|
-
|------|-----------------|---------------|
|
|
26
|
-
| `README.md` | Project overview, install steps, quick-start | Tool count, version badge, CLI examples |
|
|
27
|
-
| `CLAUDE.md` | In-repo instructions for Claude | Tool count (heading says "MCP Tools (N)"), CLI command list, key file list |
|
|
28
|
-
| `AGENTS.md` | Agent-facing instructions | Tool count, hook table, CLI commands |
|
|
29
|
-
| `CONTRIBUTING.md` | Dev setup, build/test commands | `npm run build`, `npm test`, publish steps |
|
|
30
|
-
| `CHANGELOG.md` | Release history | Latest version matches `package.json` version |
|
|
31
|
-
| `docs/index.html` | GitHub Pages landing page | Install commands, version references, feature list |
|
|
32
|
-
| `docs/documentation.html` | Full reference doc (primary surface) | Tool count, CLI commands, hook table, env vars table |
|
|
33
|
-
| `docs/api-reference.md` | API / tool reference | Tool signatures, return shapes |
|
|
34
|
-
| `docs/architecture.md` | Data-flow diagrams and architecture | File paths, hook names, flow descriptions |
|
|
35
|
-
| `docs/faq.md` | Common questions and answers | References to commands, file paths |
|
|
36
|
-
| `docs/llms.txt` | Short LLM-friendly summary | Tool count, version, install command |
|
|
37
|
-
| `docs/llms-full.txt` | Full LLM-readable reference | Complete tool list, CLI commands, env vars |
|
|
38
|
-
| `mcp/README.md` | MCP server README | Tool count, server entry point |
|
|
39
|
-
| `vscode-extension/README.md` | VS Code extension README | Feature list, commands |
|
|
40
|
-
|
|
41
|
-
## Step-by-step
|
|
42
|
-
|
|
43
|
-
### 1. Read the source of truth
|
|
44
|
-
|
|
45
|
-
The source of truth for counts and signatures lives in the code, not the docs:
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
# Count exported MCP tools in index.ts
|
|
49
|
-
grep -c 'server\.tool(' mcp/src/index.ts
|
|
50
|
-
|
|
51
|
-
# Current version
|
|
52
|
-
node -p "require('./package.json').version"
|
|
53
|
-
|
|
54
|
-
# CLI commands (scan cli.ts / index.ts for subcommand registrations)
|
|
55
|
-
grep 'program\.' mcp/src/cli.ts | head -40
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Record: **tool count**, **version**, and the list of top-level CLI subcommands.
|
|
59
|
-
|
|
60
|
-
### 2. Check each documentation surface
|
|
61
|
-
|
|
62
|
-
For each surface in the table above:
|
|
63
|
-
|
|
64
|
-
1. Read the file
|
|
65
|
-
2. Find every place it mentions a tool count (e.g. "65 tools", "MCP Tools (65)")
|
|
66
|
-
3. Find every place it mentions the version number
|
|
67
|
-
4. Find every CLI command listing
|
|
68
|
-
5. Find the hook table (event names, what each hook does)
|
|
69
|
-
6. Note any stale references (old file paths, renamed tools, removed commands)
|
|
70
|
-
|
|
71
|
-
### 3. Spot-check critical numbers
|
|
72
|
-
|
|
73
|
-
These numbers appear in multiple files and must all agree:
|
|
74
|
-
|
|
75
|
-
| Item | Where to verify |
|
|
76
|
-
|------|----------------|
|
|
77
|
-
| MCP tool count | `mcp/src/index.ts`: count `server.tool(` calls |
|
|
78
|
-
| CLI subcommand count | `mcp/src/cli.ts`: count `program.command(` calls |
|
|
79
|
-
| Version | `package.json` → `version` field |
|
|
80
|
-
| Hook events | `mcp/src/init.ts`: look for hook registration |
|
|
81
|
-
|
|
82
|
-
Run `/parity` if it is installed to automate numeric cross-checking across surfaces.
|
|
83
|
-
|
|
84
|
-
### 4. Update `docs/documentation.html`
|
|
85
|
-
|
|
86
|
-
This is the primary public reference. It must reflect the current state of the code.
|
|
87
|
-
|
|
88
|
-
Sections to verify and update:
|
|
89
|
-
|
|
90
|
-
- **Tool reference table**: every tool name, description, and parameter signature
|
|
91
|
-
- **CLI commands block**: every `phren <subcommand>` with flags and description
|
|
92
|
-
- **Hooks table**: event name, what it runs, what it does
|
|
93
|
-
- **Environment variables table**: variable name, default, description
|
|
94
|
-
- **Version number** in the page title, install command snippets, and any badges
|
|
95
|
-
- **Tool count** in any summary sentence (e.g. "65 MCP tools")
|
|
96
|
-
|
|
97
|
-
When updating the HTML:
|
|
98
|
-
- Keep existing structure and CSS classes. Do not restructure the page
|
|
99
|
-
- Update text content only; do not rewrite layout
|
|
100
|
-
- Preserve the `<details>` blocks for env var categories if they exist
|
|
101
|
-
|
|
102
|
-
### 5. Update `docs/llms.txt` and `docs/llms-full.txt`
|
|
103
|
-
|
|
104
|
-
These files are consumed by LLMs directly. Keep them plain text with no HTML.
|
|
105
|
-
|
|
106
|
-
`llms.txt`, short summary (under 60 lines):
|
|
107
|
-
- Tool count
|
|
108
|
-
- Install command
|
|
109
|
-
- One-line description of what phren does
|
|
110
|
-
|
|
111
|
-
`llms-full.txt`, comprehensive reference:
|
|
112
|
-
- All MCP tool signatures with descriptions
|
|
113
|
-
- All CLI commands
|
|
114
|
-
- All environment variables
|
|
115
|
-
- Directory structure
|
|
116
|
-
|
|
117
|
-
### 6. Update `CLAUDE.md` (in-repo)
|
|
118
|
-
|
|
119
|
-
The heading `## MCP Tools (N)` must match the actual tool count. Update N if it changed.
|
|
120
|
-
|
|
121
|
-
The CLI commands block must list every top-level command. Add or remove lines to match.
|
|
122
|
-
|
|
123
|
-
### 7. Sync version references
|
|
124
|
-
|
|
125
|
-
`CHANGELOG.md`: the top entry's version must match `package.json`. If a new version was bumped but the changelog has no entry yet, note it. Do not fabricate one.
|
|
126
|
-
|
|
127
|
-
`README.md` and `docs/index.html`: update any hardcoded version strings (badges, `npm install @phren/cli@X.Y.Z`, etc.).
|
|
128
|
-
|
|
129
|
-
### 8. Report
|
|
130
|
-
|
|
131
|
-
After reviewing and updating, output:
|
|
132
|
-
|
|
133
|
-
```
|
|
134
|
-
phren-docs
|
|
135
|
-
|
|
136
|
-
Version: 0.0.8
|
|
137
|
-
MCP tools: 65
|
|
138
|
-
CLI subcommands: 22
|
|
139
|
-
|
|
140
|
-
Surfaces checked: 14
|
|
141
|
-
|
|
142
|
-
Changes made:
|
|
143
|
-
- docs/documentation.html: updated tool count (64→65), added new env var PHREN_X
|
|
144
|
-
- CLAUDE.md: updated MCP Tools heading (64→65)
|
|
145
|
-
- docs/llms-full.txt: added PHREN_X to env vars section
|
|
146
|
-
|
|
147
|
-
No changes needed:
|
|
148
|
-
- README.md: version and tool count already correct
|
|
149
|
-
- CHANGELOG.md: top entry matches package.json version
|
|
150
|
-
- mcp/README.md: tool count correct
|
|
151
|
-
|
|
152
|
-
Warnings:
|
|
153
|
-
- docs/faq.md: references `phren init`, command was renamed to `phren link` in v0.0.7
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
List every file checked. Be specific about what changed and what line/section.
|
|
157
|
-
|
|
158
|
-
## What not to do
|
|
159
|
-
|
|
160
|
-
- Do not restructure or reformat documentation for style. Only fix accuracy
|
|
161
|
-
- Do not add new sections or features to the docs without user direction
|
|
162
|
-
- Do not fabricate changelog entries for unreleased versions
|
|
163
|
-
- Do not silently skip a surface because it looks "probably fine". Check all of them
|
|
164
|
-
- Do not guess tool counts. Always derive from `grep` on the source file
|
|
165
|
-
|
|
166
|
-
## Related skills
|
|
167
|
-
|
|
168
|
-
- `/parity`: numeric cross-check across all documentation surfaces
|
|
169
|
-
- `/consolidate`: surface cross-project patterns before updating architecture docs
|
|
170
|
-
- `/discover`: find gaps in project documentation
|