@phren/cli 0.0.1

package/skills/consolidate/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: consolidate
+description: Find patterns across project findings and surface insights that apply everywhere.
+dependencies:
+  - git
+---
+# phren-consolidate - Cross-project synthesis
+
+> Find patterns across project findings and surface insights that apply everywhere.
+
+Read every project's FINDINGS.md, find patterns that show up across multiple projects, and write them to a shared global findings file.
+
+The point: something you learned on one project probably applies elsewhere. Phren connects those fragments across projects.
+
+## Prerequisites
+
+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.
+
+**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.
+
+## When to run
+
+- Monthly, or when the user asks
+- After a burst of work across multiple projects
+- When starting a new project (to seed it with relevant cross-cutting knowledge)
+
+## What to do
+
+### 1. Find the phren directory
+
+```bash
+PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
+ls "$PHREN_DIR" 2>/dev/null
+```
+
+If it doesn't exist, tell the user:
+> "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."
+
+### 2. Gather ALL findings
+
+Try the profile-aware path first, fall back to scanning all directories:
+
+```bash
+MACHINE=$(cat ~/.phren/.machine-id 2>/dev/null || hostname)
+# look up profile in machines.yaml to get the project list
+
+# fallback: scan all project directories
+FINDINGS_FILES=()
+for dir in "$PHREN_DIR"/*/; do
+  if [ -f "$dir/FINDINGS.md" ]; then
+    PROJECT_NAME=$(basename "$dir")
+    FINDINGS_FILES+=("$PROJECT_NAME:$dir/FINDINGS.md")
+  fi
+done
+```
+
+Read **every** FINDINGS.md file found. Don't sample or skip any. For each file, track which project it came from.
+
+If no FINDINGS.md files exist anywhere, tell the user:
+> "No FINDINGS.md files found in any project. Use `add_finding()` during a work session to start capturing findings."
+
+If only one project has a FINDINGS.md, tell the user:
+> "Only found findings for <project>. Need at least two projects to find cross-cutting patterns. Use `add_finding()` in other projects first."
+
+### 3. Find cross-cutting patterns
+
+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.
+
+Be specific. Not "testing is important" but "mocking at service boundaries instead of HTTP layer caught integration bugs in both my-app and backend."
+
+Common categories (use only the ones that have actual matches):
+
+- **Build and tooling**: cache issues, config pitfalls, CI patterns
+- **Testing**: mocking strategies, fixture patterns, what to test vs skip
+- **TypeScript/JS**: type tricks, async pitfalls, framework quirks
+- **State management**: reactivity pitfalls, update ordering, stale closures
+- **API patterns**: error handling, retry logic, auth flows
+- **Performance**: what actually mattered vs premature optimization
+- **Git and workflow**: branching patterns, commit conventions, release steps
+- **Dependencies**: version conflicts, peer dep issues, lock file handling
+
+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.
+
+### 4. Check existing global findings
+
+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.
+
+### 5. Write global findings
+
+File: `$PHREN_DIR/global/FINDINGS.md`
+
+```markdown
+# Cross-project findings
+
+Last consolidated: <date>
+Sources: <list of project names scanned>
+
+## Build and tooling
+- Clear dist/ after any tsconfig change, the build cache doesn't invalidate (my-app, backend)
+- Lock file conflicts: delete and regenerate, don't try to merge (my-app, frontend)
+
+## Testing
+- Mock at the service boundary, not the HTTP layer (backend, frontend)
+- Session-scoped fixtures cause flaky parallel tests (backend, my-app)
+```
+
+Rules for each entry:
+- Include which projects it came from in parentheses
+- Be specific enough that someone could act on it without reading the original findings
+- If two projects describe the same thing differently, synthesize into one clear statement
+- Keep entries to 1-2 lines max
+
+### 6. Report
+
+```
+phren-consolidate
+
+Scanned: my-app (12 findings), backend (8 findings), frontend (5 findings)
+
+Found 6 cross-cutting patterns:
+  Build: 2 patterns (cache invalidation, lock file handling)
+  Testing: 2 patterns (mock boundaries, fixture scoping)
+  TypeScript: 2 patterns (strict nulls, path aliases)
+
+New patterns added: 4
+Existing patterns updated: 2 (added new project evidence)
+Skipped: 0 (already captured)
+
+Updated: $PHREN_DIR/global/FINDINGS.md
+```
+
+### 7. Commit (if git repo)
+
+```bash
+cd "$PHREN_DIR"
+git add global/FINDINGS.md
+git commit -m "update global findings"
+git push  # only if remote exists
+```
+
+## What not to do
+
+- Don't include findings that only apply to one project. Those stay in the project's own file.
+- Don't water down specifics to make them "general." If it's about Angular signals specifically, say so.
+- Don't duplicate what's already in global findings. Update existing entries if there's new evidence.
+- Don't create a wall of text. Keep it scannable. Bullet points, grouped by theme.
+- Don't invent patterns. If two findings use the same word but describe different problems, they're not a pattern.
+
+## Related skills
+
+- `add_finding()`: capture findings during a session via MCP
+- `phren-sync`: sync the consolidated findings to other machines

package/skills/discover/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: discover
+description: Audit your phren repo and tell you exactly what needs attention.
+dependencies:
+  - git
+  - gh
+---
+# phren-discover - Phren health check
+
+> Let phren audit your project store and tell you exactly what needs attention.
+
+Phren scans your project directory for missing files, stale content, skill gaps, and stuck task items. He outputs a concrete, prioritized action list.
+
+**Works standalone.** Just needs a phren directory.
+
+## When to run
+
+- Weekly or monthly maintenance
+- When you feel like things are getting messy
+- Before starting a new project (to see what you've been neglecting)
+- When the user asks "what should I work on"
+
+## What to do
+
+### 1. Find the phren directory
+
+```bash
+PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
+ls "$PHREN_DIR" 2>/dev/null
+```
+
+If it doesn't exist:
+> "No phren directory found at ~/.phren. Run `phren-init` to set one up."
+
+### 2. Scan all projects
+
+For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):
+
+```bash
+for dir in "$PHREN_DIR"/*/; do
+  PROJECT=$(basename "$dir")
+  [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
+
+  [ -f "$dir/CLAUDE.md" ]    && echo "$PROJECT: has CLAUDE.md"    || echo "$PROJECT: MISSING CLAUDE.md"
+  [ -f "$dir/summary.md" ]   && echo "$PROJECT: has summary.md"   || echo "$PROJECT: MISSING summary.md"
+  [ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
+  [ -f "$dir/tasks.md" ]   && echo "$PROJECT: has tasks.md"   || echo "$PROJECT: MISSING tasks.md"
+done
+```
+
+### 3. Check staleness
+
+For projects that are in a git-tracked phren, check when files were last modified:
+
+```bash
+cd "$PHREN_DIR"
+for dir in */; do
+  PROJECT=$(basename "$dir")
+  [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
+
+  if [ -f "$dir/FINDINGS.md" ]; then
+    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)
+    echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
+  fi
+
+  if [ -f "$dir/CLAUDE.md" ]; then
+    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)
+    echo "$PROJECT/CLAUDE.md: last updated $LAST_MODIFIED"
+  fi
+done
+```
+
+Flag anything not updated in 30+ days as stale.
+
+### 4. Detect skill gaps
+
+Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
+- Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
+- A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
+- A task item keeps getting deferred, and might need a skill to make it easier
+
+Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.
+
+### 5. Check task health
+
+For each project with a tasks.md:
+- Count total items, completed items, items with no recent progress
+- Flag tasks where nothing has been completed recently
+- Flag tasks with items older than 60 days that haven't moved
+
+### 6. Scaffold missing summary.md files
+
+For each project with a missing summary.md, output the template and offer to create it:
+
+```
+Project: myapp
+MISSING: summary.md
+
+Template:
+```
+# myapp
+
+What:
+Stack:
+Status: active
+Run:
+Watch out:
+```
+
+Want me to fill this in for myapp?
+```
+
+If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.
+
+### 7. Output the report
+
+```
+phren-discover
+
+## Section 1: Missing files
+
+Projects without core files:
+
+| Project | CLAUDE.md | summary.md | FINDINGS.md | tasks.md |
+|---------|-----------|------------|--------------|------------|
+| myapp   | ok        | MISSING    | MISSING      | ok         |
+| api     | ok        | ok         | ok           | MISSING    |
+
+## Section 2: Stale content
+
+Files not updated in 30+ days:
+- my-app/FINDINGS.md: last updated 45 days ago
+- frontend/CLAUDE.md: last updated 62 days ago
+
+## Section 3: Skill gaps
+
+Things you do repeatedly that could be skills:
+- "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
+- my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.
+
+## Section 4: Task health
+
+- my-app: 12 items (3 completed, 2 stale > 60 days)
+- backend: 5 items (0 completed, all stale)
+- frontend: 8 items (6 completed, healthy)
+
+Stuck items:
+- backend#2: "Add rate limiting" (added 90 days ago, no progress)
+- my-app#7: "Improve query performance" (added 75 days ago, no progress)
+
+## Top 3 things to work on next
+
+1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
+2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
+3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
+```
+
+The "Top 3" section is the most important part. Make these:
+- Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
+- Prioritized (highest impact first)
+- Actionable (someone could start right now)
+
+## What not to do
+
+- Don't flag missing files in projects that are archived or inactive
+- Don't recommend creating files just for completeness; only flag what would actually help
+- Don't be vague in the Top 3. Every item should be a clear next action.
+- Don't pad the report with things that are fine. Focus on what needs attention.
+
+## Related skills
+
+- `phren-init`: scaffold missing files for a project
+- `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
+- `phren-consolidate`: synthesize cross-project patterns
+- `/tasks`: work on stuck task items

package/skills/init/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: init
+description: Set up a new project in phren with summary, CLAUDE.md, task, and skill templates.
+dependencies:
+  - git
+---
+# phren-init - Scaffold a new project
+
+> Set up a new project in phren with summary, CLAUDE.md, task, and skill templates.
+
+Tell phren about a new project, or bootstrap phren himself if you're starting fresh.
+
+## Usage
+
+```
+phren-init my-new-project    # scaffold a specific project
+phren-init                   # list existing projects, suggest unconfigured ones
+```
+
+## First: find or create the phren directory
+
+```bash
+PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
+ls "$PHREN_DIR" 2>/dev/null
+```
+
+If the phren directory doesn't exist, offer to create it:
+> "No phren repo found. Want me to create one at ~/.phren? This will set up the base directory structure (global/, profiles/, machines.yaml)."
+
+If the user says yes, create the base structure:
+```bash
+mkdir -p "$PHREN_DIR"/{global/skills,profiles}
+# Create a starter machines.yaml
+# Create a starter profile
+```
+
+Then continue with the project scaffolding below.
+
+## With a project name
+
+### 1. Check it doesn't already exist
+
+```bash
+ls "$PHREN_DIR/<project-name>/" 2>/dev/null
+```
+
+If it exists, tell the user and ask if they want to reset it or just update specific files.
+
+### 2. Create the project directory
+
+```bash
+mkdir -p "$PHREN_DIR/<project-name>/skills"
+```
+
+### 3. Create summary.md
+
+This is the project's identity card. Five lines, no more.
+
+```markdown
+# <project-name>
+
+What: <one sentence about what this project does>
+Stack: <languages, frameworks, key deps>
+Status: <active / maintenance / new / archived>
+Run: <the main command to start it, e.g. "npm run dev">
+Watch out: <the one thing that trips people up>
+```
+
+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.
+
+### 4. Create CLAUDE.md
+
+```markdown
+# <project-name>
+
+<One paragraph: what this project is and what it does.>
+
+## Commands
+
+```
+<dev command>
+<build command>
+<test command>
+```
+
+## Architecture
+
+<!-- Fill this in as the project grows -->
+
+## Conventions
+
+<!-- Project-specific rules, patterns, naming conventions -->
+```
+
+Pre-fill from the project's existing README or package.json if available. Leave architecture and conventions as placeholders with the HTML comments.
+
+### 5. Create tasks.md
+
+```markdown
+# <project-name> tasks
+
+## Active
+
+## Queue
+
+## Done
+```
+
+### 6. Create skills README
+
+```markdown
+# <project-name> skills
+
+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.
+```
+
+Write this to `$PHREN_DIR/<project-name>/skills/README.md`.
+
+### 7. Add to profile(s)
+
+Check if profiles exist:
+```bash
+ls "$PHREN_DIR/profiles/"*.yaml 2>/dev/null
+```
+
+If profiles exist, ask: "Which profile should this project be in?" and show the options.
+
+If no profiles exist, offer to create one:
+> "No profiles set up yet. Want me to create a 'default' profile with this project in it?"
+
+Then add the project name to the chosen profile's `projects` list.
+
+### 8. Commit (if git repo)
+
+```bash
+cd "$PHREN_DIR"
+git add <project-name>/
+git add profiles/  # if modified
+git commit -m "add <project-name>"
+git push  # only if remote exists
+```
+
+If phren isn't a git repo yet, walk them through the full setup:
+
+```bash
+cd "$PHREN_DIR"
+git init
+git add -A
+git commit -m "initial phren setup"
+```
+
+Then check if `gh` is available:
+
+```bash
+which gh && gh auth status
+```
+
+If yes, offer to create the GitHub repo:
+> "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."
+
+If they say yes:
+```bash
+gh repo create my-phren --private --source=. --push
+```
+
+If `gh` isn't available, show the manual steps:
+> "Create a private repo at github.com/new, then:
+>   git remote add origin git@github.com:YOU/my-phren.git
+>   git push -u origin main
+>
+> Once it's on GitHub, clone it on any machine and run `phren-sync` to activate."
+
+### 9. Report
+
+```
+phren-init <project-name>
+
+Created:
+  $PHREN_DIR/<project-name>/summary.md
+  $PHREN_DIR/<project-name>/CLAUDE.md
+  $PHREN_DIR/<project-name>/tasks.md
+  $PHREN_DIR/<project-name>/skills/README.md
+
+Added to profile: default
+
+Run phren-sync to activate on this machine.
+```
+
+## Without a project name
+
+When user just runs `phren-init` with no args:
+
+1. If phren directory exists, list all directories that have a `summary.md` (configured projects)
+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
+3. Show both lists and suggest adding unconfigured ones
+
+```
+phren-init: project scan
+
+Configured in phren:
+  myapp, api-server
+
+Found on this machine but not in phren:
+  ~/side-project (has package.json)
+  ~/experiments/rust-thing (has Cargo.toml)
+
+Run phren-init <name> to add one.
+```
+
+If phren doesn't exist at all, offer to bootstrap it from scratch.
+
+## Related skills
+
+- `phren-sync`: activate the new project on this machine after init
+- `phren-discover`: find what to build next in a project
+- `/tasks`: manage the project's task queue

package/skills/profiles/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: profiles
+description: Manage machine-to-profile and profile-to-project mappings in phren.
+dependencies:
+  - git
+---
+# phren-profiles - Manage your profiles
+
+> **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.
+
+> Add projects to profiles, move projects between profiles, create new profiles, and check what's in each one.
+
+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.
+
+## Prerequisites
+
+You need a phren repo. The profiles live in `~/.phren/profiles/` and machine mappings live in `~/.phren/machines.yaml`.
+
+```
+~/.phren/
+  profiles/
+    work.yaml
+    personal.yaml
+  machines.yaml
+```
+
+If you don't have a phren repo yet, start with `phren-init`.
+
+## What's a profile?
+
+A profile is a YAML file listing projects for a machine role. Example:
+
+```yaml
+name: work
+description: Work laptop with company projects
+projects:
+  - global
+  - my-api
+  - frontend
+```
+
+When you sync on a machine mapped to this profile, only those projects appear. Personal projects stay off work machines.
+
+## How to use it
+
+### "Add a project to a profile"
+
+User says: "add my-project to my work profile"
+
+1. Find the profile file: `~/.phren/profiles/work.yaml`
+2. Read it and find the `projects:` list
+3. Add the project name if it's not already there
+4. Commit the change
+
+### "Create a new profile"
+
+User says: "create a new profile called staging"
+
+1. Create a new file: `~/.phren/profiles/staging.yaml`
+2. Fill it with the required structure:
+
+```yaml
+name: staging
+description: Staging servers and experiments
+projects:
+  - global
+```
+
+3. Ask which projects should be in this new profile (can add more later)
+4. Commit the file
+
+### "Show me what's in a profile"
+
+User says: "what's in my personal profile?"
+
+1. Find `~/.phren/profiles/personal.yaml`
+2. Read it and display the projects list
+
+### "Move a project between profiles"
+
+User says: "move my-project from personal to work"
+
+1. Find `~/.phren/profiles/personal.yaml` and remove the project
+2. Find `~/.phren/profiles/work.yaml` and add the project
+3. Commit both changes
+
+### "Set this machine's profile"
+
+User says: "this machine is my work laptop"
+
+1. Get the current machine name: `cat ~/.phren/.machine-id` or `hostname`
+2. Ask which profile to use (show available profiles from `~/.phren/profiles/`)
+3. Add/update the line in `~/.phren/machines.yaml`: `work-laptop: work`
+4. Commit the change
+5. Run `phren-sync` to activate
+
+### "List my profiles"
+
+If the user asks what profiles exist:
+
+1. List all files in `~/.phren/profiles/`
+2. For each one, read the name and description fields
+3. Show which machine is mapped to each profile (from `machines.yaml`)
+
+## After making changes
+
+Always commit to the phren git repo:
+
+```bash
+cd ~/.phren
+git add profiles/ machines.yaml
+git commit -m "update profiles"
+git push  # only if remote exists
+```
+
+Then suggest running `phren-sync` to activate changes on this machine.
+
+## Related skills
+
+- `phren-sync`: sync your profiles to this machine and activate them
+- `phren-init`: create a new project or bootstrap phren from scratch