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

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

Mode 1: New Project

Supported Stacks

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:

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

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

Related Skills

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