@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-beta.9

package/dist/commands/init.js

@@ -12,6 +12,7 @@ import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
 import { VERSION } from "../constants/version.js";
 import { agentsMdContent } from "../templates/markdown/index.js";
 import { setWriteMode, writeFile, } from "../utils/file-writer.js";
+import { emptyTaskJson } from "../utils/task-json.js";
 import { detectProjectType, detectMonorepo, sanitizePkgName, } from "../utils/project-detector.js";
 import { initializeHashes } from "../utils/template-hash.js";
 import { fetchTemplateIndex, probeRegistryIndex, downloadTemplateById, downloadRegistryDirect, parseRegistrySource, TIMEOUTS, TEMPLATE_INDEX_URL, } from "../utils/template-fetcher.js";
@@ -65,29 +66,120 @@ function getPythonCommand() {
 // Bootstrap Task Creation
 // =============================================================================
 const BOOTSTRAP_TASK_NAME = "00-bootstrap-guidelines";
+/**
+ * Slugify a developer name for safe use in task directory names.
+ *
+ * Unlike `sanitizePkgName` (which only strips npm @scope/ prefixes), this
+ * handles arbitrary developer input: spaces, Unicode letters, punctuation,
+ * path separators. Returns "user" fallback when input slugifies to empty.
+ *
+ * Exported for unit testing; not part of the public API.
+ */
+export function slugifyDeveloperName(name) {
+    const slug = name
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "user";
+}
+/**
+ * Write a task skeleton (task.json + prd.md + .current-task pointer).
+ *
+ * Idempotent: if the task dir already exists, returns true without touching
+ * anything. Shared by both creator bootstrap and joiner onboarding flows.
+ */
+function writeTaskSkeleton(cwd, taskName, taskJson, prdContent) {
+    const taskDir = path.join(cwd, PATHS.TASKS, taskName);
+    if (fs.existsSync(taskDir))
+        return true; // idempotent
+    try {
+        fs.mkdirSync(taskDir, { recursive: true });
+        fs.writeFileSync(path.join(taskDir, FILE_NAMES.TASK_JSON), JSON.stringify(taskJson, null, 2), "utf-8");
+        fs.writeFileSync(path.join(taskDir, FILE_NAMES.PRD), prdContent, "utf-8");
+        fs.writeFileSync(path.join(cwd, PATHS.CURRENT_TASK_FILE), `${PATHS.TASKS}/${taskName}`, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compute the bootstrap checklist items (previously stored as structured
+ * `subtasks: [{name, status}]` in task.json). Per task 04-21-task-schema-unify
+ * (D1), these live as markdown `- [ ]` items in prd.md instead, so task.json
+ * stays canonical with `subtasks: string[]` (child task dir names, same as
+ * task_store.py).
+ */
+function getBootstrapChecklistItems(projectType, packages) {
+    if (packages && packages.length > 0) {
+        const items = packages.map((pkg) => `Fill guidelines for ${pkg.name}`);
+        items.push("Add code examples");
+        return items;
+    }
+    if (projectType === "frontend") {
+        return ["Fill frontend guidelines", "Add code examples"];
+    }
+    if (projectType === "backend") {
+        return ["Fill backend guidelines", "Add code examples"];
+    }
+    return [
+        "Fill backend guidelines",
+        "Fill frontend guidelines",
+        "Add code examples",
+    ];
+}
+function getBootstrapRelatedFiles(projectType, packages) {
+    if (packages && packages.length > 0) {
+        return packages.map((pkg) => `.trellis/spec/${sanitizePkgName(pkg.name)}/`);
+    }
+    if (projectType === "frontend") {
+        return [".trellis/spec/frontend/"];
+    }
+    if (projectType === "backend") {
+        return [".trellis/spec/backend/"];
+    }
+    return [".trellis/spec/backend/", ".trellis/spec/frontend/"];
+}
 function getBootstrapPrdContent(projectType, packages) {
-    const header = `# Bootstrap: Fill Project Development Guidelines
+    const checklistItems = getBootstrapChecklistItems(projectType, packages);
+    const checklistMarkdown = checklistItems
+        .map((item) => `- [ ] ${item}`)
+        .join("\n");
+    const header = `# Bootstrap Task: Fill Project Development Guidelines
 
-## Purpose
+**You (the AI) are running this task. The developer does not read this file.**
 
-Welcome to Trellis! This is your first task.
+The developer just ran \`trellis init\` on this project for the first time.
+\`.trellis/\` now exists with empty spec scaffolding, and this task has been
+set as their current task. They'll open their AI tool, run \`/trellis:continue\`,
+and you'll land here.
 
-AI agents use \`.trellis/spec/\` to understand YOUR project's coding conventions.
-**Starting from scratch = AI writes generic code that doesn't match your project style.**
+**Your job**: help them populate \`.trellis/spec/\` with the team's real
+coding conventions. Every future AI session — this project's
+\`trellis-implement\` and \`trellis-check\` sub-agents — auto-loads spec files
+listed in per-task jsonl manifests. Empty spec = sub-agents write generic
+code. Real spec = sub-agents match the team's actual patterns.
 
-Filling these guidelines is a one-time setup that pays off for every future AI session.
+Don't dump instructions. Open with a short greeting, figure out if the repo
+has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive
+the rest conversationally.
 
 ---
 
-## Your Task
+## Status (update the checkboxes as you complete each item)
+
+${checklistMarkdown}
+
+---
 
-Fill in the guideline files based on your **existing codebase**.
+## Spec files to populate
 `;
     const backendSection = `
 
-### Backend Guidelines
+### Backend guidelines
 
-| File | What to Document |
+| File | What to document |
 |------|------------------|
 | \`.trellis/spec/backend/directory-structure.md\` | Where different file types go (routes, services, utils) |
 | \`.trellis/spec/backend/database-guidelines.md\` | ORM, migrations, query patterns, naming conventions |
@@ -97,9 +189,9 @@ Fill in the guideline files based on your **existing codebase**.
 `;
     const frontendSection = `
 
-### Frontend Guidelines
+### Frontend guidelines
 
-| File | What to Document |
+| File | What to document |
 |------|------------------|
 | \`.trellis/spec/frontend/directory-structure.md\` | Component/page/hook organization |
 | \`.trellis/spec/frontend/component-guidelines.md\` | Component patterns, props conventions |
@@ -110,18 +202,20 @@ Fill in the guideline files based on your **existing codebase**.
 `;
     const footer = `
 
-### Thinking Guides (Optional)
+### Thinking guides (already populated)
 
-The \`.trellis/spec/guides/\` directory contains thinking guides that are already
-filled with general best practices. You can customize them for your project if needed.
+\`.trellis/spec/guides/\` contains general thinking guides pre-filled with
+best practices. Customize only if something clearly doesn't fit this project.
 
 ---
 
-## How to Fill Guidelines
+## How to fill the spec
 
-### Step 0: Import from Existing Specs (Recommended)
+### Step 1: Import from existing convention files first (preferred)
 
-Many projects already have coding conventions documented. **Check these first** before writing from scratch:
+Search the repo for existing convention docs. If any exist, read them and
+extract the relevant rules into the matching \`.trellis/spec/\` files —
+usually much faster than documenting from scratch.
 
 | File / Directory | Tool |
 |------|------|
@@ -138,50 +232,60 @@ Many projects already have coding conventions documented. **Check these first**
 | \`CONTRIBUTING.md\` | General project conventions |
 | \`.editorconfig\` | Editor formatting rules |
 
-If any of these exist, read them first and extract the relevant coding conventions into the corresponding \`.trellis/spec/\` files. This saves significant effort compared to writing everything from scratch.
+### Step 2: Analyze the codebase for anything not covered by existing docs
 
-### Step 1: Analyze the Codebase
+Scan real code to discover patterns. Before writing each spec file:
+- Find 2-3 real examples of each pattern in the codebase.
+- Reference real file paths (not hypothetical ones).
+- Document anti-patterns the team clearly avoids.
 
-Ask AI to help discover patterns from actual code:
+### Step 3: Document reality, not ideals
 
-- "Read all existing config files (CLAUDE.md, .cursorrules, etc.) and extract coding conventions into .trellis/spec/"
-- "Analyze my codebase and document the patterns you see"
-- "Find error handling / component / API patterns and document them"
+**Critical**: write what the code *actually does*, not what it should do.
+Sub-agents match the spec, so aspirational patterns that don't exist in the
+codebase will cause sub-agents to write code that looks out of place.
 
-### Step 2: Document Reality, Not Ideals
+If the team has known tech debt, document the current state — improvement
+is a separate conversation, not a bootstrap concern.
 
-Write what your codebase **actually does**, not what you wish it did.
-AI needs to match existing patterns, not introduce new ones.
+---
 
-- **Look at existing code** - Find 2-3 examples of each pattern
-- **Include file paths** - Reference real files as examples
-- **List anti-patterns** - What does your team avoid?
+## Quick explainer of the runtime (share when they ask "why do we need spec at all")
 
----
+- Every AI coding task spawns two sub-agents: \`trellis-implement\` (writes
+  code) and \`trellis-check\` (verifies quality).
+- Each task has \`implement.jsonl\` / \`check.jsonl\` manifests listing which
+  spec files to load.
+- The platform hook auto-injects those spec files + the task's \`prd.md\`
+  into every sub-agent prompt, so the sub-agent codes/reviews per team
+  conventions without anyone pasting them manually.
+- Source of truth: \`.trellis/spec/\`. That's why filling it well now pays
+  off forever.
 
-## Completion Checklist
+---
 
-- [ ] Guidelines filled for your project type
-- [ ] At least 2-3 real code examples in each guideline
-- [ ] Anti-patterns documented
+## Completion
 
-When done:
+When the developer confirms the checklist items above are done with real
+examples (not placeholders), guide them to run:
 
 \`\`\`bash
 python3 ./.trellis/scripts/task.py finish
 python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
 \`\`\`
 
----
+After archive, every new developer who joins this project will get a
+\`00-join-<slug>\` onboarding task instead of this bootstrap task.
 
-## Why This Matters
+---
 
-After completing this task:
+## Suggested opening line
 
-1. AI will write code that matches your project style
-2. Relevant \`/trellis:before-*-dev\` commands will inject real context
-3. \`/trellis:check-*\` commands will validate against your actual standards
-4. Future developers (human or AI) will onboard faster
+"Welcome to Trellis! Your init just set me up to help you fill the project
+spec — a one-time setup so every future AI session follows the team's
+conventions instead of writing generic code. Before we start, do you have
+any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md,
+etc.) I can pull from, or should I scan the codebase from scratch?"
 `;
     let content = header;
     if (packages && packages.length > 0) {
@@ -214,43 +318,15 @@ After completing this task:
 }
 function getBootstrapTaskJson(developer, projectType, packages) {
     const today = new Date().toISOString().split("T")[0];
-    let subtasks;
-    let relatedFiles;
-    if (packages && packages.length > 0) {
-        // Monorepo: subtask per package
-        subtasks = packages.map((pkg) => ({
-            name: `Fill guidelines for ${pkg.name}`,
-            status: "pending",
-        }));
-        subtasks.push({ name: "Add code examples", status: "pending" });
-        relatedFiles = packages.map((pkg) => `.trellis/spec/${sanitizePkgName(pkg.name)}/`);
-    }
-    else if (projectType === "frontend") {
-        subtasks = [
-            { name: "Fill frontend guidelines", status: "pending" },
-            { name: "Add code examples", status: "pending" },
-        ];
-        relatedFiles = [".trellis/spec/frontend/"];
-    }
-    else if (projectType === "backend") {
-        subtasks = [
-            { name: "Fill backend guidelines", status: "pending" },
-            { name: "Add code examples", status: "pending" },
-        ];
-        relatedFiles = [".trellis/spec/backend/"];
-    }
-    else {
-        // fullstack
-        subtasks = [
-            { name: "Fill backend guidelines", status: "pending" },
-            { name: "Fill frontend guidelines", status: "pending" },
-            { name: "Add code examples", status: "pending" },
-        ];
-        relatedFiles = [".trellis/spec/backend/", ".trellis/spec/frontend/"];
-    }
-    return {
+    const relatedFiles = getBootstrapRelatedFiles(projectType, packages);
+    // Canonical 24-field shape via emptyTaskJson factory.
+    // Checklist items (previously stored as structured `subtasks`) are now
+    // rendered as `- [ ]` items in prd.md; task.json.subtasks is always
+    // string[] (child task dir names) per the canonical schema.
+    return emptyTaskJson({
         id: BOOTSTRAP_TASK_NAME,
-        name: "Bootstrap Guidelines",
+        name: BOOTSTRAP_TASK_NAME,
+        title: "Bootstrap Guidelines",
         description: "Fill in project development guidelines for AI agents",
         status: "in_progress",
         dev_type: "docs",
@@ -258,43 +334,166 @@ function getBootstrapTaskJson(developer, projectType, packages) {
         creator: developer,
         assignee: developer,
         createdAt: today,
-        completedAt: null,
-        commit: null,
-        subtasks,
-        children: [],
-        parent: null,
         relatedFiles,
         notes: `First-time setup task created by trellis init (${projectType} project)`,
-        meta: {},
-    };
+    });
 }
 /**
  * Create bootstrap task for first-time setup
  */
 function createBootstrapTask(cwd, developer, projectType, packages) {
-    const taskDir = path.join(cwd, PATHS.TASKS, BOOTSTRAP_TASK_NAME);
-    const taskRelativePath = `${PATHS.TASKS}/${BOOTSTRAP_TASK_NAME}`;
-    // Check if already exists
-    if (fs.existsSync(taskDir)) {
-        return true; // Already exists, not an error
-    }
-    try {
-        // Create task directory
-        fs.mkdirSync(taskDir, { recursive: true });
-        // Write task.json
-        const taskJson = getBootstrapTaskJson(developer, projectType, packages);
-        fs.writeFileSync(path.join(taskDir, FILE_NAMES.TASK_JSON), JSON.stringify(taskJson, null, 2), "utf-8");
-        // Write prd.md
-        const prdContent = getBootstrapPrdContent(projectType, packages);
-        fs.writeFileSync(path.join(taskDir, FILE_NAMES.PRD), prdContent, "utf-8");
-        // Set as current task
-        const currentTaskFile = path.join(cwd, PATHS.CURRENT_TASK_FILE);
-        fs.writeFileSync(currentTaskFile, taskRelativePath, "utf-8");
-        return true;
-    }
-    catch {
-        return false;
-    }
+    const taskJson = getBootstrapTaskJson(developer, projectType, packages);
+    const prdContent = getBootstrapPrdContent(projectType, packages);
+    return writeTaskSkeleton(cwd, BOOTSTRAP_TASK_NAME, taskJson, prdContent);
+}
+// =============================================================================
+// Joiner Onboarding Task Creation
+// =============================================================================
+/**
+ * task.json factory for joiner onboarding. Mirrors the bootstrap factory but
+ * uses dev_type "docs", higher priority "P1", and the developer-specific task
+ * name (so multiple joiners in the same checkout don't collide).
+ */
+function getJoinerTaskJson(developer, taskName) {
+    const today = new Date().toISOString().split("T")[0];
+    return emptyTaskJson({
+        id: taskName,
+        name: taskName,
+        title: `Joining: Onboard to this Trellis project (${developer})`,
+        description: "Onboard a new developer to an existing Trellis project: learn the workflow, conventions, and find assigned work",
+        status: "in_progress",
+        dev_type: "docs",
+        priority: "P1",
+        creator: developer,
+        assignee: developer,
+        createdAt: today,
+        notes: "Generated by trellis init for a new developer joining an existing Trellis project",
+    });
+}
+/**
+ * PRD content for joiner onboarding. Kept concise (~80 lines) — deeper
+ * guidance lives in skills and docs.
+ */
+function getJoinerPrdContent(developer) {
+    const slug = slugifyDeveloperName(developer);
+    return `# Joiner Onboarding Task
+
+**You (the AI) are running this task. The developer does not read this file.**
+
+\`${developer}\` just ran \`trellis init\` on a fresh clone, saw "Developer
+initialized", and will now start asking you questions in chat. This task is
+already set as their current task (\`.trellis/.current-task\` points here), so
+when they run \`/trellis:continue\` you'll land back on this PRD.
+
+Your job is to orient them to Trellis. Don't dump all of this at them — open
+with a short greeting, ask where they want to start, and fill in the rest as
+they engage.
+
+---
+
+## Topics to cover (adapt order to their questions)
+
+### 1. What Trellis is + the workflow
+
+Trellis is a workflow layer over Claude Code / Cursor / etc. that keeps AI
+agents consistent with project-specific conventions instead of writing generic
+code every session.
+
+- **Three phases**: Plan (brainstorm → \`prd.md\`) → Execute (code + check) →
+  Finish (capture + wrap). Full reference: \`.trellis/workflow.md\`.
+- **Task lifecycle**: planning → in_progress → done → archive, under
+  \`.trellis/tasks/\`.
+- **Core slash commands**:
+  - \`/trellis:continue\` — resume the current task (their primary entry,
+    since current-task is already set to this onboarding task)
+  - \`/trellis:finish-work\` — wrap up a finished task
+  - \`/trellis:start\` — session boot from scratch (not needed here; the
+    SessionStart hook does its job automatically)
+
+### 2. Runtime mechanics (explain when they ask "how does it know what to do")
+
+- **SessionStart hook** runs \`get_context.py\` and injects identity, git
+  status, current-task pointer, active tasks, and workflow phase into the AI
+  conversation at every session start.
+- **\`<workflow-state>\` tag** is auto-injected with every user message,
+  carrying the current task + phase hint.
+- **\`/trellis:continue\`** loads the Phase Index, reads \`prd.md\` + recent
+  activity, and routes to the right skill (\`trellis-brainstorm\` for planning,
+  \`trellis-implement\` for coding, \`trellis-check\` for verification).
+- **\`trellis-implement\` sub-agent** is spawned when code needs to be written.
+  The platform hook reads \`{TASK_DIR}/implement.jsonl\` and auto-injects those
+  spec files + \`prd.md\` into the sub-agent's prompt so it codes per project
+  conventions.
+- **\`trellis-check\` sub-agent** follows the same pattern with \`check.jsonl\`
+  — reviews changes against specs, auto-fixes issues, runs lint/typecheck.
+
+File layout (mention when they ask "where does what live"):
+- \`.trellis/.current-task\` — session pointer, gitignored, per-checkout
+- \`.trellis/tasks/<task>/{implement,check}.jsonl\` — per-task context manifests
+- \`.trellis/spec/\` — project-wide conventions (source of truth)
+- \`.trellis/workspace/${developer}/journal-*.md\` — their session log,
+  rotated at ~2000 lines
+
+### 3. This project's actual conventions
+
+- Summarize \`.trellis/spec/\` for them — what coding conventions this
+  specific team enforces.
+- Point at the last 5 entries in \`.trellis/tasks/archive/\` as a rhythm
+  example of how people actually work here. **If archive is empty** (the
+  project just started), skip this — don't invent examples.
+- Not your job in this onboarding to teach them the business code itself —
+  the README and their teammates handle that.
+
+### 4. Their assigned work
+
+- Check if \`.trellis/workspace/${developer}/\` already exists — if yes, it's
+  their journal from another machine and worth mentioning.
+- Run \`python3 ./.trellis/scripts/task.py list --assignee ${developer}\` to
+  show tasks assigned to them. (Quote the name if it contains spaces.)
+- Remind them that the "My Tasks" section appears in the SessionStart context
+  on every new session.
+
+---
+
+## Optional: walk through a small task end-to-end
+
+If they want to practice before touching real work, offer to pick a tiny
+P3 task or a typo fix and run the full cycle together: \`/trellis:continue\`
+→ you implement via sub-agents → \`/trellis:finish-work\`.
+
+---
+
+## Completion
+
+When they feel oriented (or after you've covered the four topics with
+reasonable back-and-forth), guide them to run:
+
+\`\`\`bash
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive 00-join-${slug}
+\`\`\`
+
+---
+
+## Suggested opening line
+
+"Welcome! Your \`trellis init\` set me up to onboard you to this project. I
+can walk you through the workflow, show you the runtime mechanics under the
+hood, summarize the team's spec, or jump to what you're already curious about
+— which would you prefer?"
+`;
+}
+/**
+ * Create joiner onboarding task for a new developer on an existing Trellis
+ * project. Task name is slugified to be filesystem-safe for arbitrary
+ * developer names (spaces, Unicode, punctuation).
+ */
+function createJoinerOnboardingTask(cwd, developer) {
+    const slug = slugifyDeveloperName(developer);
+    const taskName = `00-join-${slug}`;
+    const taskJson = getJoinerTaskJson(developer, taskName);
+    const prdContent = getJoinerPrdContent(developer);
+    return writeTaskSkeleton(cwd, taskName, taskJson, prdContent);
 }
 /**
  * Handle re-init when .trellis/ already exists.
@@ -396,6 +595,10 @@ async function handleReinit(cwd, options, developerName) {
                 devName = await askInput("Your name: ");
             }
         }
+        // Capture pre-init state: if .developer did not exist before we ran
+        // init_developer.py, this checkout had no identity → treat as a new
+        // joiner onboarding onto an existing Trellis project.
+        const hadDeveloperFileBefore = fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW, FILE_NAMES.DEVELOPER));
         try {
             const pythonCmd = getPythonCommand();
             const scriptPath = path.join(cwd, PATHS.SCRIPTS, "init_developer.py");
@@ -409,6 +612,18 @@ async function handleReinit(cwd, options, developerName) {
             console.log(chalk.yellow("⚠ Could not initialize developer. Run manually:"));
             console.log(chalk.gray(`  python3 .trellis/scripts/init_developer.py ${devName}`));
         }
+        // Create joiner onboarding task for fresh checkouts (no prior .developer).
+        // Runs outside the init_developer try/catch so failures surface as warnings.
+        if (!hadDeveloperFileBefore) {
+            try {
+                if (!createJoinerOnboardingTask(cwd, devName)) {
+                    console.warn(chalk.yellow("⚠ Failed to create joiner onboarding task"));
+                }
+            }
+            catch (err) {
+                console.warn(chalk.yellow(`⚠ Joiner onboarding setup failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
     }
     return true;
 }
@@ -438,6 +653,9 @@ function writeMonorepoConfig(cwd, packages) {
         if (pkg.isSubmodule) {
             lines.push("    type: submodule");
         }
+        else if (pkg.isGitRepo) {
+            lines.push("    git: true");
+        }
     }
     // Use first non-submodule package as default, fallback to first package
     const defaultPkg = packages.find((p) => !p.isSubmodule)?.name ?? packages[0]?.name;
@@ -449,6 +667,10 @@ function writeMonorepoConfig(cwd, packages) {
 export async function init(options) {
     const cwd = process.cwd();
     const isFirstInit = !fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW));
+    // Captured here (before createWorkflowStructure + init_developer run) so
+    // the three-branch dispatch at the bottom can tell "fresh clone joiner"
+    // (.trellis/ exists, .developer missing) apart from "creator first init".
+    const hadDeveloperFileAtStart = fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW, FILE_NAMES.DEVELOPER));
     // Generate ASCII art banner dynamically using FIGlet "Rebel" font
     const banner = figlet.textSync("Trellis", { font: "Rebel" });
     console.log(chalk.cyan(`\n${banner.trimEnd()}`));
@@ -540,7 +762,26 @@ export async function init(options) {
         // options.monorepo: true = --monorepo, false = --no-monorepo, undefined = auto
         const detected = detectMonorepo(cwd);
         if (options.monorepo === true && !detected) {
-            console.log(chalk.red("Error: --monorepo specified but no monorepo configuration found."));
+            console.log(chalk.red("Error: --monorepo specified but no multi-package layout detected."));
+            console.log("");
+            console.log(chalk.gray("Checked:"));
+            console.log(chalk.gray("  ✗ pnpm-workspace.yaml"));
+            console.log(chalk.gray("  ✗ package.json workspaces"));
+            console.log(chalk.gray("  ✗ Cargo.toml [workspace]"));
+            console.log(chalk.gray("  ✗ go.work"));
+            console.log(chalk.gray("  ✗ pyproject.toml [tool.uv.workspace]"));
+            console.log(chalk.gray("  ✗ .gitmodules"));
+            console.log(chalk.gray("  ✗ sibling .git directories (need ≥ 2)"));
+            console.log("");
+            console.log("To configure manually, add to .trellis/config.yaml:");
+            console.log("");
+            console.log(chalk.cyan("  packages:"));
+            console.log(chalk.cyan("    frontend:"));
+            console.log(chalk.cyan("      path: ./frontend"));
+            console.log(chalk.cyan("      git: true       # if it has its own .git"));
+            console.log(chalk.cyan("    backend:"));
+            console.log(chalk.cyan("      path: ./backend"));
+            console.log(chalk.cyan("      git: true"));
             return;
         }
         if (detected && detected.length > 0) {
@@ -552,11 +793,15 @@ export async function init(options) {
                 // Show detected packages and ask
                 console.log(chalk.blue("\n🔍 Detected monorepo packages:"));
                 for (const pkg of detected) {
-                    const sub = pkg.isSubmodule ? chalk.gray(" (submodule)") : "";
+                    const tag = pkg.isSubmodule
+                        ? chalk.gray(" (submodule)")
+                        : pkg.isGitRepo
+                            ? chalk.gray(" (git repo)")
+                            : "";
                     console.log(chalk.gray(`   - ${pkg.name}`) +
                         chalk.gray(` (${pkg.path})`) +
                         chalk.gray(` [${pkg.type}]`) +
-                        sub);
+                        tag);
                 }
                 console.log("");
                 const { useMonorepo } = await inquirer.prompt([
@@ -1008,14 +1253,33 @@ export async function init(options) {
                 cwd,
                 stdio: "pipe", // Silent
             });
-            // Create bootstrap task only on first init (not re-init for new platforms/devices)
-            if (isFirstInit) {
-                createBootstrapTask(cwd, developerName, projectType, monorepoPackages);
-            }
         }
         catch {
             // Silent failure - user can run init_developer.py manually
         }
+        // Three-branch dispatch using flags captured at init() start (before
+        // createWorkflowStructure/init_developer ran, so they reflect the disk
+        // state of the user's checkout, not the state this init just produced):
+        //   isFirstInit=true                       → creator bootstrap (new project)
+        //   isFirstInit=false + no .developer file → joiner onboarding (fresh clone)
+        //   isFirstInit=false + .developer exists  → same-dev re-init, no task
+        //
+        // Runs OUTSIDE the init_developer try/catch (which uses stdio: "pipe")
+        // so joiner failures surface as warnings instead of being silently
+        // swallowed.
+        if (isFirstInit) {
+            createBootstrapTask(cwd, developerName, projectType, monorepoPackages);
+        }
+        else if (!hadDeveloperFileAtStart) {
+            try {
+                if (!createJoinerOnboardingTask(cwd, developerName)) {
+                    console.warn(chalk.yellow("⚠ Failed to create joiner onboarding task"));
+                }
+            }
+            catch (err) {
+                console.warn(chalk.yellow(`⚠ Joiner onboarding setup failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
     }
     // Print "What We Solve" section
     printWhatWeSolve();