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

/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):

   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

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.

/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