@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,152 +0,0 @@
1
- ---
2
- name: consolidate
3
- description: Find patterns across project findings and surface insights that apply everywhere.
4
- dependencies:
5
- - git
6
- ---
7
- # phren-consolidate - Cross-project synthesis
8
-
9
- > Find patterns across project findings and surface insights that apply everywhere.
10
-
11
- Read every project's FINDINGS.md, find patterns that show up across multiple projects, and write them to a shared global findings file.
12
-
13
- The point: something you learned on one project probably applies elsewhere. Phren connects those fragments across projects.
14
-
15
- ## Prerequisites
16
-
17
- This skill needs at least two projects with FINDINGS.md files to be useful. If you haven't captured any findings yet, use `add_finding()` during a session first.
18
-
19
- **Works with or without profiles.** If profiles are set up, it scans projects in the active profile. If not, it scans all project directories in the phren repo.
20
-
21
- ## When to run
22
-
23
- - Monthly, or when the user asks
24
- - After a burst of work across multiple projects
25
- - When starting a new project (to seed it with relevant cross-cutting knowledge)
26
-
27
- ## What to do
28
-
29
- ### 1. Find the phren directory
30
-
31
- ```bash
32
- PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
33
- ls "$PHREN_DIR" 2>/dev/null
34
- ```
35
-
36
- If it doesn't exist, tell the user:
37
- > "No phren directory found at ~/.phren. This skill needs a phren repo with project findings. Run `phren-init` to set one up, or set PHREN_DIR if yours is elsewhere."
38
-
39
- ### 2. Gather ALL findings
40
-
41
- Try the profile-aware path first, fall back to scanning all directories:
42
-
43
- ```bash
44
- MACHINE=$(cat ~/.phren/.machine-id 2>/dev/null || hostname)
45
- # look up profile in machines.yaml to get the project list
46
-
47
- # fallback: scan all project directories
48
- FINDINGS_FILES=()
49
- for dir in "$PHREN_DIR"/*/; do
50
- if [ -f "$dir/FINDINGS.md" ]; then
51
- PROJECT_NAME=$(basename "$dir")
52
- FINDINGS_FILES+=("$PROJECT_NAME:$dir/FINDINGS.md")
53
- fi
54
- done
55
- ```
56
-
57
- Read **every** FINDINGS.md file found. Don't sample or skip any. For each file, track which project it came from.
58
-
59
- If no FINDINGS.md files exist anywhere, tell the user:
60
- > "No FINDINGS.md files found in any project. Use `add_finding()` during a work session to start capturing findings."
61
-
62
- If only one project has a FINDINGS.md, tell the user:
63
- > "Only found findings for <project>. Need at least two projects to find cross-cutting patterns. Use `add_finding()` in other projects first."
64
-
65
- ### 3. Find cross-cutting patterns
66
-
67
- Compare findings across all projects. A pattern counts as cross-cutting when the **same insight, technique, or pitfall** appears in 2+ projects. Don't just look for keyword overlap; look for conceptual overlap.
68
-
69
- Be specific. Not "testing is important" but "mocking at service boundaries instead of HTTP layer caught integration bugs in both my-app and backend."
70
-
71
- Common categories (use only the ones that have actual matches):
72
-
73
- - **Build and tooling**: cache issues, config pitfalls, CI patterns
74
- - **Testing**: mocking strategies, fixture patterns, what to test vs skip
75
- - **TypeScript/JS**: type tricks, async pitfalls, framework quirks
76
- - **State management**: reactivity pitfalls, update ordering, stale closures
77
- - **API patterns**: error handling, retry logic, auth flows
78
- - **Performance**: what actually mattered vs premature optimization
79
- - **Git and workflow**: branching patterns, commit conventions, release steps
80
- - **Dependencies**: version conflicts, peer dep issues, lock file handling
81
-
82
- Don't force categories. If only one project mentions something, it stays project-specific. If a pattern genuinely spans projects, include it even if it doesn't fit a neat category.
83
-
84
- ### 4. Check existing global findings
85
-
86
- Before writing, read `$PHREN_DIR/global/FINDINGS.md` if it exists. Don't duplicate entries that are already there. Update existing entries if there's new evidence or additional projects that confirm the pattern.
87
-
88
- ### 5. Write global findings
89
-
90
- File: `$PHREN_DIR/global/FINDINGS.md`
91
-
92
- ```markdown
93
- # Cross-project findings
94
-
95
- Last consolidated: <date>
96
- Sources: <list of project names scanned>
97
-
98
- ## Build and tooling
99
- - Clear dist/ after any tsconfig change, the build cache doesn't invalidate (my-app, backend)
100
- - Lock file conflicts: delete and regenerate, don't try to merge (my-app, frontend)
101
-
102
- ## Testing
103
- - Mock at the service boundary, not the HTTP layer (backend, frontend)
104
- - Session-scoped fixtures cause flaky parallel tests (backend, my-app)
105
- ```
106
-
107
- Rules for each entry:
108
- - Include which projects it came from in parentheses
109
- - Be specific enough that someone could act on it without reading the original findings
110
- - If two projects describe the same thing differently, synthesize into one clear statement
111
- - Keep entries to 1-2 lines max
112
-
113
- ### 6. Report
114
-
115
- ```
116
- phren-consolidate
117
-
118
- Scanned: my-app (12 findings), backend (8 findings), frontend (5 findings)
119
-
120
- Found 6 cross-cutting patterns:
121
- Build: 2 patterns (cache invalidation, lock file handling)
122
- Testing: 2 patterns (mock boundaries, fixture scoping)
123
- TypeScript: 2 patterns (strict nulls, path aliases)
124
-
125
- New patterns added: 4
126
- Existing patterns updated: 2 (added new project evidence)
127
- Skipped: 0 (already captured)
128
-
129
- Updated: $PHREN_DIR/global/FINDINGS.md
130
- ```
131
-
132
- ### 7. Commit (if git repo)
133
-
134
- ```bash
135
- cd "$PHREN_DIR"
136
- git add global/FINDINGS.md
137
- git commit -m "update global findings"
138
- git push # only if remote exists
139
- ```
140
-
141
- ## What not to do
142
-
143
- - Don't include findings that only apply to one project. Those stay in the project's own file.
144
- - Don't water down specifics to make them "general." If it's about Angular signals specifically, say so.
145
- - Don't duplicate what's already in global findings. Update existing entries if there's new evidence.
146
- - Don't create a wall of text. Keep it scannable. Bullet points, grouped by theme.
147
- - Don't invent patterns. If two findings use the same word but describe different problems, they're not a pattern.
148
-
149
- ## Related skills
150
-
151
- - `add_finding()`: capture findings during a session via MCP
152
- - `phren-sync`: sync the consolidated findings to other machines
@@ -1,175 +0,0 @@
1
- ---
2
- name: discover
3
- description: Audit your phren repo and tell you exactly what needs attention.
4
- dependencies:
5
- - git
6
- - gh
7
- ---
8
- # phren-discover - Phren health check
9
-
10
- > Let phren audit your project store and tell you exactly what needs attention.
11
-
12
- Phren scans your project directory for missing files, stale content, skill gaps, and stuck task items. He outputs a concrete, prioritized action list.
13
-
14
- **Works standalone.** Just needs a phren directory.
15
-
16
- ## When to run
17
-
18
- - Weekly or monthly maintenance
19
- - When you feel like things are getting messy
20
- - Before starting a new project (to see what you've been neglecting)
21
- - When the user asks "what should I work on"
22
-
23
- ## What to do
24
-
25
- ### 1. Find the phren directory
26
-
27
- ```bash
28
- PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
29
- ls "$PHREN_DIR" 2>/dev/null
30
- ```
31
-
32
- If it doesn't exist:
33
- > "No phren directory found at ~/.phren. Run `phren-init` to set one up."
34
-
35
- ### 2. Scan all projects
36
-
37
- For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):
38
-
39
- ```bash
40
- for dir in "$PHREN_DIR"/*/; do
41
- PROJECT=$(basename "$dir")
42
- [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
43
-
44
- [ -f "$dir/CLAUDE.md" ] && echo "$PROJECT: has CLAUDE.md" || echo "$PROJECT: MISSING CLAUDE.md"
45
- [ -f "$dir/summary.md" ] && echo "$PROJECT: has summary.md" || echo "$PROJECT: MISSING summary.md"
46
- [ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
47
- [ -f "$dir/tasks.md" ] && echo "$PROJECT: has tasks.md" || echo "$PROJECT: MISSING tasks.md"
48
- done
49
- ```
50
-
51
- ### 3. Check staleness
52
-
53
- For projects that are in a git-tracked phren, check when files were last modified:
54
-
55
- ```bash
56
- cd "$PHREN_DIR"
57
- for dir in */; do
58
- PROJECT=$(basename "$dir")
59
- [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
60
-
61
- if [ -f "$dir/FINDINGS.md" ]; then
62
- LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/FINDINGS.md" 2>/dev/null || stat -c %Y "$dir/FINDINGS.md" 2>/dev/null || stat -f %m "$dir/FINDINGS.md" 2>/dev/null)
63
- echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
64
- fi
65
-
66
- if [ -f "$dir/CLAUDE.md" ]; then
67
- LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/CLAUDE.md" 2>/dev/null || stat -c %Y "$dir/CLAUDE.md" 2>/dev/null || stat -f %m "$dir/CLAUDE.md" 2>/dev/null)
68
- echo "$PROJECT/CLAUDE.md: last updated $LAST_MODIFIED"
69
- fi
70
- done
71
- ```
72
-
73
- Flag anything not updated in 30+ days as stale.
74
-
75
- ### 4. Detect skill gaps
76
-
77
- Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
78
- - Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
79
- - A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
80
- - A task item keeps getting deferred, and might need a skill to make it easier
81
-
82
- Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.
83
-
84
- ### 5. Check task health
85
-
86
- For each project with a tasks.md:
87
- - Count total items, completed items, items with no recent progress
88
- - Flag tasks where nothing has been completed recently
89
- - Flag tasks with items older than 60 days that haven't moved
90
-
91
- ### 6. Scaffold missing summary.md files
92
-
93
- For each project with a missing summary.md, output the template and offer to create it:
94
-
95
- ```
96
- Project: myapp
97
- MISSING: summary.md
98
-
99
- Template:
100
- ```
101
- # myapp
102
-
103
- What:
104
- Stack:
105
- Status: active
106
- Run:
107
- Watch out:
108
- ```
109
-
110
- Want me to fill this in for myapp?
111
- ```
112
-
113
- If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.
114
-
115
- ### 7. Output the report
116
-
117
- ```
118
- phren-discover
119
-
120
- ## Section 1: Missing files
121
-
122
- Projects without core files:
123
-
124
- | Project | CLAUDE.md | summary.md | FINDINGS.md | tasks.md |
125
- |---------|-----------|------------|--------------|------------|
126
- | myapp | ok | MISSING | MISSING | ok |
127
- | api | ok | ok | ok | MISSING |
128
-
129
- ## Section 2: Stale content
130
-
131
- Files not updated in 30+ days:
132
- - my-app/FINDINGS.md: last updated 45 days ago
133
- - frontend/CLAUDE.md: last updated 62 days ago
134
-
135
- ## Section 3: Skill gaps
136
-
137
- Things you do repeatedly that could be skills:
138
- - "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
139
- - my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.
140
-
141
- ## Section 4: Task health
142
-
143
- - my-app: 12 items (3 completed, 2 stale > 60 days)
144
- - backend: 5 items (0 completed, all stale)
145
- - frontend: 8 items (6 completed, healthy)
146
-
147
- Stuck items:
148
- - backend#2: "Add rate limiting" (added 90 days ago, no progress)
149
- - my-app#7: "Improve query performance" (added 75 days ago, no progress)
150
-
151
- ## Top 3 things to work on next
152
-
153
- 1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
154
- 2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
155
- 3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
156
- ```
157
-
158
- The "Top 3" section is the most important part. Make these:
159
- - Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
160
- - Prioritized (highest impact first)
161
- - Actionable (someone could start right now)
162
-
163
- ## What not to do
164
-
165
- - Don't flag missing files in projects that are archived or inactive
166
- - Don't recommend creating files just for completeness; only flag what would actually help
167
- - Don't be vague in the Top 3. Every item should be a clear next action.
168
- - Don't pad the report with things that are fine. Focus on what needs attention.
169
-
170
- ## Related skills
171
-
172
- - `phren-init`: scaffold missing files for a project
173
- - `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
174
- - `phren-consolidate`: synthesize cross-project patterns
175
- - `/tasks`: work on stuck task items
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