First Project

Your first WorkPilot AI project

This tutorial walks you step by step through creating your first autonomous task: from choosing a project to merging the agent-generated code.

---

🧭 Journey overview

1. Open an existing Git project
2. Connect an AI provider
3. Create a task in natural language
4. Approve the spec generated by the AI
5. Watch the agents work (Kanban + terminals)
6. Review the generated PR and merge

Estimated time: 10–15 minutes for a simple task.

---

Step 1 — Open a project

1. Launch WorkPilot AI
2. Click "Open project"
3. Select the root folder of an existing Git repository

💡 For a first try, use a test project (or clone a small public repo). That way you can experiment without risk.

On open, WorkPilot AI analyzes your project: language, framework, test tools, folder structure. This detection feeds the context sent to agents.

---

Step 2 — Check the AI connection

On the top banner, check that an AI provider is connected (small green indicator). Otherwise:

1. Open Settings → AI Providers
2. Click "Add profile"
3. Pick Claude (OAuth recommended) or another provider

👉 Tip: register multiple accounts or providers. WorkPilot AI auto-switches on rate limits.

---

Step 3 — Create your first task

1. In the Kanban Board, click "New task"

2. Describe your goal in natural language, for example:

   "Add a REST endpoint /api/health returning {status: 'ok'} and uptime duration, with an integration test."

3. (Optional) Add detailed acceptance criteria

4. Click "Generate spec"

What happens behind the scenes

The Spec Creator agent assesses complexity and categorizes into 3 tiers:

Tier	Phases	When
SIMPLE	3	1-2 files, quick fix, text change
STANDARD	6	3-10 files, 1-2 services, minor integrations
COMPLEX	8	10+ files, multi-service, external integrations

The agent then produces a detailed spec (spec.md), with:

• A summary of changes
• Files to touch
• Acceptance criteria
• An implementation plan broken into phases

---

Step 4 — Approve (or adjust) the spec

Once generated, the spec appears in the "Spec Review" column.

You can:

• ✅ Approve — the pipeline starts
• ✏️ Adjust — add comments the AI will incorporate
• ❌ Reject — task is archived

🔐 Why this step? It's your human checkpoint before agents modify code. Take the time to re-read.

---

Step 5 — Watch the autonomous pipeline

Once approved, the task moves to "In Progress". Agents get to work in a dedicated git worktree (.worktrees/workpilot-ai/) — your main branch stays untouched.

What you see

• Kanban — task progresses from column to column
• Agent terminal — live logs, thinking and actions
• Mission Control (optional) — consolidated view of all active agents

Pipeline phases

Planner → Coder → QA Reviewer → QA Fixer (loop if needed) → Ready to merge

• Planner decomposes into ordered subtasks
• Coder implements (may spawn parallel subagents)
• QA Reviewer validates acceptance criteria
• On failure → QA Fixer corrects, then Reviewer re-checks (up to 50 iterations)

👉 More details: Multi-agent pipeline

---

Step 6 — Review the result

The task reaches "Human Review". You can now:

🔍 Preview the app

The Preview (screen icon) button runs your app in the built-in App Emulator — visually test the change before merge.

📄 View the diff

"Changes" tab: full diff file by file, syntax-highlighted, agent comments.

🤖 Request an AI review

AI Review runs the diff through an independent review agent — comments, suggestions, potential regression detection.

---

Step 7 — Merge

Three options:

A. Local merge (recommended for beginners)

"Merge to main" button: WorkPilot AI uses the AI semantic merge engine to integrate the worktree into your default branch.

B. Create a Pull Request

"Create PR" button: automatically creates the GitHub/GitLab PR with:

• Auto-generated title and description
• Spec link
• Acceptance criteria as checklist

C. Discard

"Discard" button: removes the worktree without touching main. Perfect if the result isn't right.

---

🎯 What you learned

• WorkPilot AI turns a natural-language description into tested code
• The Planner → Coder → QA pipeline is autonomous but controllable
• Worktrees guarantee your main branch is never at risk
• You keep human control at two key stages: spec approval and merge

---

Next steps

• 🧠 Understand key concepts
• 🖥 Explore the UI
• 🔌 Connect your tools (GitHub, Jira, Linear…)
• 🎛 Use Mission Control for multiple agents