---

name: onboard-claude description: Initialize memory bank structure for a new project workspace

Onboard Claude

Initialize the memory bank structure and work logging for a new project workspace. Run this once when setting up Claude for a new project.

Prerequisites

• A workspace directory (can be a git repo or standalone)
• Basic understanding of what the project is about

Steps

1. Check Existing Setup

Check if .claude/memorybank/ already exists:

• If exists: Ask user "Memory bank already exists. Reinitialize? (This will overwrite existing files)"
• If user declines: Exit with "Setup cancelled. Use /review to see current state."

2. Auto-Discovery (New)

Before asking the user, attempt to auto-discover project information from common files.

Check for Project Files

Look for these files in workspace root (use Read tool to check):

Extraction Rules

For package.json (Node.js):

Copy{
  "name": "my-project",
  "description": "A cool project",
  "dependencies": {...},
  "scripts": {...}
}

Extract:

• Project name from name
• Purpose from description
• Tech stack: "Node.js" + framework hints from dependencies (react, vue, express, etc.)
• Structure hints from scripts (test, build, dev suggest common patterns)

For pyproject.toml (Python):

Copy[project]
name = "my-project"
description = "A cool project"
dependencies = [...]

[tool.poetry]
name = "my-project"

Extract:

• Project name from project.name or tool.poetry.name
• Purpose from project.description or tool.poetry.description
• Tech stack: "Python" + framework from dependencies (django, flask, fastapi, etc.)

For Cargo.toml (Rust):

Copy[package]
name = "my-project"
description = "A cool project"

Extract:

• Project name from package.name
• Purpose from package.description
• Tech stack: "Rust" + crate hints from dependencies

For Git Remote:

Copygit config --get remote.origin.url

Extract repository URL for overview.md

For README.md / README.rst / README:

Look for README files in workspace root. Extract:

• Project description (first paragraph after title)
• Architecture/structure information (look for sections like "Architecture", "Structure", "Components")
• Key features (look for "Features" section)
• Dependencies/tech stack (look for "Requirements", "Dependencies", "Built With" sections)
• Conventions (look for "Development", "Contributing" sections)

Example extraction:

Copy# My Project

A web application for tracking tasks.

## Features
- User authentication
- Task management
- Real-time updates

## Tech Stack
- React + TypeScript
- Node.js + Express
- PostgreSQL

Extract:

• Name: "My Project"
• Purpose: "A web application for tracking tasks"
• Tech Stack: "React, TypeScript, Node.js, Express, PostgreSQL"
• Key Features: List from Features section
• Work Areas (suggested): auth, task-management, real-time

Priority: README is lower priority than package manifests. If both exist, prefer manifest for name/description, but use README for additional context.

Present Findings

Show what was discovered:

Copy## Auto-Discovery Results

Found project information:
- **Name**: [detected name or "Not found"]
- **Description**: [detected description or "Not found"]
- **Tech Stack**: [detected stack or "Not found"]
- **Repository**: [git remote URL or "Not found"]
- **Dependencies**: [count] detected

Use this information? (Yes / Edit / Ignore)

If user selects "Yes": Use detected information and skip to gaps If user selects "Edit": Present editable version, then proceed If user selects "Ignore": Skip auto-discovery, ask all questions manually

3. Gather Project Context

Fill in any gaps from auto-discovery by asking the user (conversationally, not with AskUserQuestion):

If auto-discovery successful:

• Only ask about missing fields
• Example: "I found the project info in package.json. What are the main work areas?"

If auto-discovery failed or user chose "Ignore":

1. "What is the project name?"
2. "Brief description - what's the purpose? (1-2 sentences)"
3. "What's the tech stack? (languages, frameworks, key dependencies)"
4. "What are the main work areas or modules?" (optional, can be added later)
5. "Any key constraints or conventions I should know about?" (optional)

4. Create Directory Structure

Copymkdir -p .claude/memorybank
mkdir -p logs

5. Create overview.md

This is the stable reference document - rarely changes after initial setup.

Copy# [Project Name] Overview

## Project Identity
- **Name**: [project name]
- **Purpose**: [user's description]
- **Scope**: [in/out of scope - ask if unclear, or "To be defined"]
- **Repository**: [workspace path or git remote URL]

## Architecture
- **Tech stack**: [from user input]
- **Structure**: [brief description or "See docs/"]
- **Key modules**: [from user input, or "To be defined"]

## Work Areas

| Area | Description | Status |
|------|-------------|--------|
| [area-1] | [what it covers] | active |

## Conventions
- **Commit format**: [e.g., "scope: description" or "To be defined"]
- **Branch strategy**: [e.g., "feature branches off main"]
- **Code style**: [link or brief rules]

## Key Patterns Discovered
[Populated over time - leave empty initially]

## Constraints & Decisions
[From user input, or empty]
- [Any constraints mentioned during setup]

## External Resources
[Empty - populated as resources are found]

## Evaluation Criteria
[What "done" looks like - optional, can add later]

---
*Initialized: [timestamp]*
*Last updated: [timestamp]*

Section purposes:

6. Create progress.md

Copy# [Project Name] Progress

## Session: [date]

### Initial Setup

**Status**: Memory bank initialized

---
*Last updated: [timestamp]*

7. Create session.md

Copy# Current Session

## Focus Area
Initial setup complete - ready for work

## Recent Work ([date])

### Completed
1. Memory bank initialized via `/onboard-claude`

## Next Steps
- [ ] Define initial tasks
- [ ] Begin work

## Blockers
None

## Notes
- Run `/review` to check status anytime
- Run `/document` after completing significant work
- Run `/logwork start` to begin time tracking
- Run `/handoff` at session end for git commit

---
*Last updated: [timestamp]*

8. Create logs/log_index.yaml

Copycurrent: null
sessions: []

9. Update or Create CLAUDE.md

If CLAUDE.md exists in workspace root:

• Add memory bank section if not present

If no CLAUDE.md:

• Create minimal version with memory bank reference

Template to add:

Copy## Session Continuity

### Memory Bank (`.claude/memorybank/`)

| File | Content | Update Frequency |
|------|---------|------------------|
| `overview.md` | What the project IS (identity, architecture, patterns) | Rarely |
| `progress.md` | What was DONE (cumulative session logs) | Per session |
| `session.md` | What's HAPPENING (current focus, next steps) | Frequently |

### Work Logs (`logs/`)
- `log_index.yaml` - Session index with timestamps
- `{date}_{n}.md` - Individual session logs

**Session start**: Read `session.md` to restore context
**Session end**: Run `/document` then `/handoff`

10. Display Summary

Copy## Memory Bank Initialized

**Project**: [name]
**Location**: [workspace path]

### Structure Created

| File | Purpose | Updates |
|------|---------|---------|
| `.claude/memorybank/overview.md` | What the project IS | Rarely |
| `.claude/memorybank/progress.md` | What was DONE | Per session |
| `.claude/memorybank/session.md` | What's HAPPENING | Frequently |
| `logs/log_index.yaml` | Session index | Auto |

### Available Skills

| Skill | When to Use |
|-------|-------------|
| `/review` | Check current state (read-only) |
| `/plan` | Create/update implementation plan |
| `/clarify` | Resolve ambiguity through guided questions |
| `/logwork start` | Begin time tracking |
| `/logwork end` | End time tracking session |
| `/document` | Record progress, decisions, learnings |
| `/handoff` | Prepare git commit at session end |

### Recommended Workflow

**Starting a session:**
1. Read `session.md` (Claude does this automatically if instructed in CLAUDE.md)
2. `/logwork start` - Begin time tracking
3. `/review` - Quick status check (optional)

**During work:**
- `/clarify [topic]` - When decisions need input
- `/document` - After significant milestones

**Ending a session:**
1. `/document` - Record what was done
2. `/logwork end` - Close time tracking
3. `/handoff` - Prepare git commit

### Quick Commands

- "What's the current status?" → triggers `/review`
- "Let's plan the next steps" → triggers `/plan`
- "I need to clarify X" → triggers `/clarify X`
- "Log my work" → triggers `/logwork`
- "Record this progress" → triggers `/document`
- "I'm done for today" → triggers `/handoff`

---
Memory bank ready. Start with `/logwork start` to begin tracking.

Notes

• All timestamps use format: YYYY-MM-DD HH:MM:SS TZ
• Always get timestamp from system: date '+%Y-%m-%d %H:%M:%S %Z'
• This skill should only be run once per workspace
• For multi-project workspaces, run from the workspace root (not inside a project subdirectory)