# Init

> Bootstrap new projects or add the agents-workflow system to existing projects. Use for new project scaffolding (Next.js, Python, Rust) or adding workflow capabilities to any git repository.

- Skill: `l3wi/init` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add l3wi/init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l3wi/init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: l3wi (https://skillmd.com/u/l3wi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l3wi/init

---


# Project Initialization Skill

Unified entry point for project bootstrapping. Handles both new project creation (scaffold + workflow) and adding the workflow system to existing projects. Step 0 before feature planning.

## Usage

```bash
/skill:init                              # Interactive — auto-detects context
/skill:init nextjs my-app                # New Next.js project
/skill:init python my-service            # New Python project
/skill:init rust my-crate                # New Rust project
/skill:init --setup                      # Add workflow to existing project
```

## Mode Detection

If no arguments provided, auto-detect the appropriate mode:

| Context | Mode | Action |
|---------|------|--------|
| No project directory specified | Ask user | New project or setup existing? |
| Stack + name provided (`nextjs my-app`) | New project | Scaffold + setup workflow |
| `--setup` flag | Setup only | Add workflow to current project |
| Current dir has code but no `.pi/` | Suggest setup | Offer to add workflow system |
| Current dir already has `.pi/` | Warn | Offer to update/overwrite |

## Mode 1: New Project

### Supported Stacks

| Stack | Runtime | Testing | Linting |
|-------|---------|---------|---------|
| `nextjs` | Bun, Next.js 15 App Router, Tailwind v4, Zustand, TanStack Query | Vitest + RTL + Playwright | Biome |
| `python` | uv, src layout | pytest | Ruff + pyright |
| `rust` | Cargo workspace | cargo-nextest | clippy + rustfmt |

### Steps

1. **Select stack** — ask if not specified
2. **Validate name** — lowercase, hyphens, no spaces; check if dir exists
3. **Scaffold project** — create structure using stack templates from `templates/`
4. **Setup workflow** — run Mode 2 (below) in the new project
5. **Install dependencies** — `bun install` / `uv sync` / `cargo build`
6. **Verify** — `lint` + `build`/`test` pass

### Stack Templates

Stack-specific config files are in the `templates/` directory:
- `templates/nextjs/` — package.json, biome.json, vitest.config, etc.
- `templates/python/` — pyproject.toml
- `templates/rust/` — Cargo.toml, clippy.toml, rustfmt.toml

Use template variables: `{{PROJECT_NAME}}`, `{{PROJECT_NAME_SNAKE}}`, `{{PROJECT_NAME_PASCAL}}`, `{{YEAR}}`, `{{DATE}}`

### Output

```
Created: {project-name}/
├── .pi/               # Agents workflow system
├── docs/              # Documentation templates
├── src/               # Source code
└── [config files]     # Stack-specific

Next: cd {project-name} && /skill:plan your-first-feature
```

## Mode 2: Setup Workflow (Existing Project)

Add the agents-workflow system to any existing git repository. Uses `implementation.ts` for the actual file operations.

### Prerequisites

- Must be a git repository (`.git/` exists)
- Write permissions to target directory

### Git Branch Setup

The init skill automatically configures git branches for the workflow:

| Scenario | Action |
|----------|--------|
| Fresh repo (no commits) | Create initial commit, main branch, dev branch |
| Has `master` only | Rename to `main`, create `dev` from it |
| Has `main` only | Create `dev` from `main` |
| Has both `main` and `dev` | No changes needed |

After setup:
- **`main`** — Production branch (protected, only receives PRs)
- **`dev`** — Working branch (where you develop, default checkout)

### Worktrunk Configuration

For the worktree-based swarm workflow, the init skill configures:

1. **User config** (`~/.config/worktrunk/config.toml`):
   ```toml
   worktree-path = ".worktrees/{{ branch | sanitize }}"
   ```
   This creates worktrees inside the repo, keeping main repo on `dev`.

2. **`.gitignore`** — adds `.worktrees/` to ignore worktree directories

### Symlink Strategy

The init skill **always symlinks** agents, extensions, skills, prompts, and scripts from the agents-workflow root into the target project's `.pi/` directory. This avoids duplicating files across projects and ensures all projects use the same up-to-date workflow definitions.

The symlinks are for **agent spawn** — spawned agents need to find `worker.md` and other definitions relative to the project. Extensions and skills are **not** referenced in the project `settings.json` because they're already loaded globally via `~/.pi/agent/settings.json`. Adding them to project settings would cause tool conflicts.

### What Gets Created

| Category | Type | Destination |
|----------|------|-------------|
| Agents | **symlink** → agents-workflow | `.pi/agents/` |
| Prompts | **symlink** → agents-workflow | `.pi/prompts/` |
| Scripts | **symlink** → agents-workflow | `.pi/scripts/` |
| Config | `settings.json` (project-specific, no extensions/skills) | `.pi/` |
| Context | `AGENTS.md` (project-specific stub) | `.pi/` |
| Directories | Empty scaffolding | `docs/{prds,specs,plans,tasks,decisions,reviews,research}/` |

Only `agents`, `prompts`, and `scripts` are symlinked — these are needed for agent spawn to find `worker.md` and templates. Extensions and skills are **not** symlinked because they're loaded globally via `~/.pi/agent/settings.json`. Symlinking them would cause tool conflicts.

### Project AGENTS.md

The project `.pi/AGENTS.md` is **not** a copy of the global workflow guide. It's a **project-specific stub** with placeholders for:
- Tech stack (language, framework, package manager)
- Commands (dev, test, lint, build)
- Project structure (key directories)
- Project-specific conventions

This stub gets automatically enriched by `/skill:plan` during its codebase analysis phase. Pi loads both the global AGENTS.md (workflow rules, agent tools) and the project AGENTS.md (project context) into every session.

### Directory Structure Created

```
.pi/
├── settings.json     # Configuration (project-specific)
├── AGENTS.md         # Project-specific context (stub, enriched by /skill:plan)
├── agents/           # → symlink to agents-workflow (for agent spawn)
├── prompts/          # → symlink to agents-workflow
└── scripts/          # → symlink to agents-workflow

docs/
├── prds/             # Product Requirements
├── specs/            # Technical Specifications
├── plans/            # Orchestration Plans
├── research/         # Research Reports
├── tasks/            # Phase Task Files
├── decisions/        # Architecture Decisions
└── reviews/          # Codebase Reviews

.worktrees/           # Created during /skill:swarm (gitignored)
├── feat-xxx/         # Feature branch worktrees
└── feat-xxx-phase-N/ # Phase worktrees
```

### Git Branches Created

```
main                  # Production (protected)
└── dev               # Working branch (default checkout)
    └── feat/xxx      # Feature branches (in worktrees)
```

### Git Integration

Updates `.gitignore` to exclude:
- `.orchestration-state.json`
- `.agent-state.json`

### Verification

```bash
pi --verbose                # Check skills and extensions loaded (global or project)
ls -la docs/                # Documentation directories created
```

### Output

```
✅ Setup complete! Available skills:

  /skill:plan            # PRD → Spec → Tasks
  /skill:swarm           # Parallel agent execution
  /skill:feature         # Single-phase implementation
  /skill:review-codebase # Quality analysis
  /skill:validate-plan   # Spec compliance verification

📖 See .pi/AGENTS.md for workflow documentation.
```

## Post-Init: What's Next?

> For guidance on which workflow to use, read the [Workflow Guide](references/workflow-guide.md).

```bash
/skill:plan feature-name       # Plan features (PRD → Spec → Tasks)
/skill:swarm feature-name      # Implement with parallel agents
/skill:validate-plan feature-name   # Validate before merge
```

## Error Handling

| Error | Resolution |
|-------|------------|
| Not a git repo | Run `git init` first |
| Permission denied | Check directory permissions |
| Source files not found | Run from agents-workflow project |
| Directory exists (new project) | Confirm overwrite or choose new name |
| `.pi/` already exists (setup) | Offer to update or skip |

## Related Skills

- `/skill:plan` — Plan features (next step after init)
- `/skill:swarm` — Parallel agent execution
- `/skill:feature` — Single-phase implementation