---
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
