Project Onboarding Flows

Planu has two different onboarding paths:

1. Existing project — Planu should inspect what is already there before asking you to choose a language or framework.
2. New project — Planu should ask what you want to build and where the app should live before it initializes anything.

This separation prevents the most common setup mistake: starting your AI assistant from a parent workspace such as Documents/desarrollo and accidentally initializing Planu in that parent folder instead of the actual app folder.

Existing Project

When a project already exists, Planu should be evidence-first. It scans manifests, lockfiles, config files, source structure, and existing agent instructions. If the stack is clear, it suggests what it found. If the stack is ambiguous, it asks you to confirm the primary language/framework.

flowchart TD
  A["User asks Planu to work in an existing repo"] --> B["Scan project evidence"]
  B --> C{"Language/framework clear?"}
  C -- "Yes" --> D["Suggest detected stack with evidence"]
  C -- "No or ambiguous" --> E["Ask user to confirm primary stack"]
  D --> F["Verify official docs and versions"]
  E --> F
  F --> G["Persist stack decision in spec"]
  G --> H["Agents implement only the approved contract"]

The result should feel like:

Planu detected TypeScript, Node, and an MCP SDK from package.json, tsconfig.json, and the lockfile. Confirm this is the primary stack before creating the spec.

Planu should not silently switch frameworks, pick a popular default, or let the model choose a stack because it prefers one.

New Project

When you are starting from a parent workspace, Planu should not initialize that parent directory. It should confirm the app folder first, then initialize Planu inside that folder only.

flowchart TD
  A["User starts from parent workspace"] --> B["Detect new project request"]
  B --> C["Ask app name and target folder"]
  C --> D["Ask language/framework or suggest from goal"]
  D --> E["Verify official docs and versions"]
  E --> F["Create or confirm project folder"]
  F --> G["Run init_project inside project folder only"]
  G --> H["Create initial spec before production code"]

Example:

Current folder:
/workspace/Documents/desarrollo

User request:
"Use Planu and create an appointments API"

Correct project folder:
/workspace/Documents/desarrollo/citas-api

Planu should initialize citas-api, not desarrollo.

Technology Selection Contract

Planu should pass stack decisions to agents as a contract, not as hardcoded product preference.

Situation	Planu behavior
Existing project with clear evidence	Detect first, then suggest with evidence
Existing project with conflicts	Ask which language/framework is primary
New project	Ask for app name, folder, language, framework, and platform
User is unsure	Suggest options from the goal and official sources
Versions or APIs matter	Verify against official docs before approval
Agent implementation starts	Use only the approved stack decision

Forbidden behavior:

• choosing a framework because the LLM likes it;
• hardcoding a default stack in Planu code;
• initializing a parent workspace when the user wants a new app folder;
• treating a fallback or guess as an official decision.

What Planu Creates

When init_project runs inside the correct project folder, Planu may create:

Planu canonical state

Path	Purpose
planu.json	Project-level Planu configuration
planu/conventions.json	Detected conventions and project scan summary
planu/context.md	Portable project context for agents to resume quickly
planu/project.json	Portable logical project identity; operational session state remains external
planu/releases/pending.json	Pending release metadata when a release is being prepared
planu/specs/SPEC-XXX-slug/spec.md	The unified spec file created by create_spec

Host-native adapters

Planu does not store agents, skills, or rules as primary files under planu/. Those files are generated where each host actually reads them.

Path	Purpose
.planu/skill-registry.json	Local skill registry metadata
AGENTS.md	Universal agent instructions for hosts that read AGENTS.md
.cursorrules / .windsurfrules	Cursor and Windsurf workflow hints
.openai/config.toml	Codex workspace config when Codex is detected
.agents/skills/*	Codex skills when Codex is detected
.codex/agents/*	Codex role agents when Codex supports local role files
.cursor/rules/planu.mdc	Cursor project rule when Cursor is detected
.claude/rules/*	Claude Code rules when Claude Code is detected
.claude/skills/*	Claude Code workflow skills when Claude Code is detected
.claude/agents/*	Claude Code subagents when Claude Code is detected
.claude/hooks/*	Claude Code hooks when Claude Code is detected
GEMINI.md / .gemini/skills/*	Gemini instructions and skills when Gemini is detected

Runtime project memory is stored outside the repo under the user-level Planu data directory, keyed by the project path. The checked-in project files stay focused on specs, config, rules, skills, and host instructions.

Practical Rule

If you are in a parent folder and ask for a new app, expect Planu to ask:

• What should the app folder be called?
• Which language and framework do you want to use?
• Should Planu create the folder now?
• Should Planu initialize specs inside that folder?

If you are inside an existing repo, expect Planu to inspect first and ask only when the detected stack is incomplete or ambiguous.

Next: read the SDD Workflow to see how the approved spec moves through implementation and validation.