@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/cli/commands/setup.js

@@ -23,8 +23,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline/promises";
 import chalk from "chalk";
-import { getGitRoot, getShadowStatus, repairShadow, SHADOW_BRANCH_NAME, } from "../../parser/shadow.js";
+import { getGitRoot, getShadowStatus, repairShadow, remoteShadowBranchExists, SHADOW_BRANCH_NAME, SHADOW_WORKTREE_DIR, SESSIONS_WORKTREE_DIR, ensureSessionsGitignore, ensureShadowSessionsGitignore, needsSessionsGitignore, needsShadowSessionsGitignore, } from "../../parser/shadow.js";
+import { loadProjectConfig } from "../../parser/config.js";
 import { detectAgentFromEnv, } from "../../parser/agent-detection.js";
+import { getSetupStatus as getSharedSetupStatus, } from "../../parser/setup-status.js";
 import { errors } from "../../strings/index.js";
 import { EXIT_CODES } from "../exit-codes.js";
 import { error, output, success, warn } from "../output.js";
@@ -45,6 +47,7 @@ function debugLog(message, detail) {
 const SETUP_AGENT_OVERRIDES = [
     "claude-code",
     "cline",
+    "droid",
     "cursor",
     "windsurf",
     "unknown",
@@ -65,6 +68,13 @@ function buildDetectedAgent(type) {
             configPath: path.join(os.homedir(), ".claude", "settings.json"),
         };
     }
+    if (type === "droid") {
+        return {
+            type,
+            confidence: "high",
+            configPath: path.join(os.homedir(), ".factory", "settings.json"),
+        };
+    }
     return { type, confidence: "high" };
 }
 /**
@@ -86,6 +96,13 @@ export function detectAgent() {
             configPath: path.join(os.homedir(), ".claude", "settings.json"),
         };
     }
+    if (existsSync(path.join(os.homedir(), ".factory"))) {
+        return {
+            type: "droid",
+            confidence: "low",
+            configPath: path.join(os.homedir(), ".factory", "settings.json"),
+        };
+    }
     return detected;
 }
 /**
@@ -137,8 +154,9 @@ const OLD_GUARD_SCRIPTS = [
 /**
  * Install hooks to project-level Claude Code settings (.claude/settings.json)
  * AC: @enhanced-setup ac-2 - all hook entries present
+ * AC: @project-config ac-hooks-section — respects per-hook enable/disable from config
  */
-async function installClaudeCodeHooks(projectDir, dryRun = false) {
+async function installClaudeCodeHooks(projectDir, dryRun = false, hooksPrefs) {
     const configPath = path.join(projectDir, ".claude", "settings.json");
     const configDir = path.dirname(configPath);
     const hooksDir = path.join(projectDir, ".claude", "hooks");
@@ -165,48 +183,89 @@ async function installClaudeCodeHooks(projectDir, dryRun = false) {
         }
         // Get or create hooks object
         const hooks = config.hooks || {};
-        // Install UserPromptSubmit hook (spec-first reminder)
+        // AC: @project-config ac-hooks-section — prompt-check independently controllable
+        // Default: enabled (lightweight spec-first reminder)
+        const promptCheckEnabled = hooksPrefs?.prompt_check ?? true;
         const promptCheckCommand = "kspec session prompt-check";
         const existingPromptHooks = hooks.UserPromptSubmit;
         const promptAlreadyInstalled = existingPromptHooks?.some((entry) => entry.hooks?.some((hook) => hook.command?.includes("session prompt-check")));
-        if (!promptAlreadyInstalled) {
-            hooks.UserPromptSubmit = [
-                ...(existingPromptHooks || []),
-                {
-                    hooks: [
-                        {
-                            type: "command",
-                            command: promptCheckCommand,
-                        },
-                    ],
-                },
-            ];
-            result.promptCheck = true;
+        if (promptCheckEnabled) {
+            if (!promptAlreadyInstalled) {
+                hooks.UserPromptSubmit = [
+                    ...(existingPromptHooks || []),
+                    {
+                        hooks: [
+                            {
+                                type: "command",
+                                command: promptCheckCommand,
+                            },
+                        ],
+                    },
+                ];
+                result.promptCheck = true;
+            }
+            else {
+                result.promptCheck = true; // Already configured
+            }
         }
         else {
-            result.promptCheck = true; // Already configured
+            // AC: @project-config ac-hooks-section — remove if disabled and previously installed
+            if (promptAlreadyInstalled) {
+                const filtered = (existingPromptHooks || []).map((entry) => ({
+                    ...entry,
+                    hooks: entry.hooks?.filter((hook) => !hook.command?.includes("session prompt-check")),
+                })).filter((entry) => entry.hooks && entry.hooks.length > 0);
+                if (filtered.length > 0) {
+                    hooks.UserPromptSubmit = filtered;
+                }
+                else {
+                    delete hooks.UserPromptSubmit;
+                }
+            }
+            result.promptCheck = false;
         }
-        // Install Stop hook (checkpoint)
+        // AC: @project-config ac-hooks-section — checkpoint independently controllable
+        // Default: disabled (dispatch handles task lifecycle)
+        const checkpointEnabled = hooksPrefs?.checkpoint ?? false;
         const stopHookCommand = "kspec session checkpoint --json";
         const existingStopHooks = hooks.Stop;
         const stopAlreadyInstalled = existingStopHooks?.some((entry) => entry.hooks?.some((hook) => hook.command?.includes("session checkpoint")));
-        if (!stopAlreadyInstalled) {
-            hooks.Stop = [
-                ...(existingStopHooks || []),
-                {
-                    matcher: "",
-                    hooks: [
-                        {
-                            type: "command",
-                            command: stopHookCommand,
-                        },
-                    ],
-                },
-            ];
-            result.stop = true;
+        if (checkpointEnabled) {
+            // AC: @project-config ac-hooks-section — install when enabled
+            if (!stopAlreadyInstalled) {
+                hooks.Stop = [
+                    ...(existingStopHooks || []),
+                    {
+                        matcher: "",
+                        hooks: [
+                            {
+                                type: "command",
+                                command: stopHookCommand,
+                            },
+                        ],
+                    },
+                ];
+                result.stop = true;
+            }
+            else {
+                result.stop = true; // Already configured
+            }
         }
         else {
-            result.stop = true; // Already configured
+            // AC: @project-config ac-hooks-section — remove if disabled and previously installed
+            if (stopAlreadyInstalled) {
+                const filtered = (existingStopHooks || []).map((entry) => ({
+                    ...entry,
+                    hooks: entry.hooks?.filter((hook) => !hook.command?.includes("session checkpoint")),
+                })).filter((entry) => entry.hooks && entry.hooks.length > 0);
+                if (filtered.length > 0) {
+                    hooks.Stop = filtered;
+                }
+                else {
+                    delete hooks.Stop;
+                }
+            }
+            result.stop = false;
         }
         // AC: @enhanced-setup ac-2 - Install PreToolUse hooks with guards
         // AC: @native-guard-commands ac-setup-native - use native kspec guard worktree
@@ -352,6 +411,8 @@ function getDefaultAuthor(agentType) {
             return "@gemini";
         case "codex-cli":
             return "@codex";
+        case "droid":
+            return "@droid";
         case "aider":
             return "@aider";
         case "opencode":
@@ -391,19 +452,30 @@ async function ensureWorktree(autoWorktree) {
         // Not in a git repo, skip worktree check
         return true;
     }
-    const status = await getShadowStatus(projectRoot);
+    const { config } = await loadProjectConfig(projectRoot, projectRoot);
+    const shadowOptions = {
+        branchName: config.shadow.branch,
+        directory: config.shadow.directory,
+        remote: config.shadow.remote?.value,
+        remoteType: config.shadow.remote?.type,
+    };
+    const branchName = shadowOptions.branchName || SHADOW_BRANCH_NAME;
+    const worktreeDir = shadowOptions.directory || SHADOW_WORKTREE_DIR;
+    const status = await getShadowStatus(projectRoot, shadowOptions);
+    const remoteHasShadow = await remoteShadowBranchExists(projectRoot, shadowOptions);
+    const recoverableShadow = status.branchExists || remoteHasShadow;
     // AC: worktree-already-exists - if already valid, skip
     if (status.healthy) {
         return true;
     }
-    // AC: detect-existing-repo - branch exists but worktree doesn't
-    if (status.branchExists && !status.worktreeExists) {
+    // AC: detect-existing-repo - existing shadow state but missing/unhealthy worktree
+    if (recoverableShadow && (!status.worktreeExists || !status.worktreeLinked)) {
         // AC: auto-worktree-flag - auto-create if flag set
         if (autoWorktree) {
-            console.log(`Detected ${SHADOW_BRANCH_NAME} branch without .kspec worktree. Creating...`);
-            const result = await repairShadow(projectRoot);
+            console.log(`Detected ${branchName} shadow state without a healthy ${worktreeDir} worktree. Creating...`);
+            const result = await repairShadow(projectRoot, shadowOptions);
             if (result.success) {
-                success("Created .kspec worktree");
+                success(`Created ${worktreeDir} worktree`);
                 return true;
             }
             else {
@@ -412,12 +484,12 @@ async function ensureWorktree(autoWorktree) {
             }
         }
         // AC: detect-existing-repo - prompt user
-        const shouldCreate = await promptYesNo(`${SHADOW_BRANCH_NAME} branch exists but .kspec worktree is missing. Create it? (y/N)`);
+        const shouldCreate = await promptYesNo(`${branchName} shadow state exists but ${worktreeDir} worktree is missing or unhealthy. Create it? (y/N)`);
         if (shouldCreate) {
-            console.log("Creating .kspec worktree...");
-            const result = await repairShadow(projectRoot);
+            console.log(`Creating ${worktreeDir} worktree...`);
+            const result = await repairShadow(projectRoot, shadowOptions);
             if (result.success) {
-                success("Created .kspec worktree");
+                success(`Created ${worktreeDir} worktree`);
                 return true;
             }
             else {
@@ -474,6 +546,13 @@ function printManualInstructions(agentType) {
             console.log(`set = { KSPEC_AUTHOR = "${author}" }`);
             console.log("```");
             break;
+        case "droid":
+            console.log("Add to .factory/settings.json:");
+            console.log("```json");
+            console.log(JSON.stringify({ env: { KSPEC_AUTHOR: author } }, null, 2));
+            console.log("```");
+            console.log("\nDroid reads project environment variables from the env section of .factory/settings.json.");
+            break;
         case "opencode":
             console.log("Add to ~/.config/opencode/opencode.json:");
             console.log("```json");
@@ -494,210 +573,6 @@ function printManualInstructions(agentType) {
             console.log("\nOr add to your shell profile (~/.bashrc, ~/.zshrc, etc.)");
     }
 }
-/**
- * Check the current setup status
- * AC: @enhanced-setup ac-7, ac-8
- */
-async function getSetupStatus(projectDir, agentOverride) {
-    const detected = agentOverride
-        ? buildDetectedAgent(agentOverride)
-        : detectAgent();
-    const configPath = path.join(projectDir, ".claude", "settings.json");
-    const hooksDir = path.join(projectDir, ".claude", "hooks");
-    const agentsMdPath = path.join(projectDir, "kspec-agents.md");
-    const hashPath = path.join(projectDir, ".kspec", ".kspec-agents-hash");
-    const skillsDir = path.join(projectDir, ".claude", "skills");
-    // Check hooks
-    const hooks = {
-        promptCheck: false,
-        stop: false,
-        preToolUse: false,
-        guardsPresent: [],
-    };
-    try {
-        const configContent = await fs.readFile(configPath, "utf-8");
-        const config = JSON.parse(configContent);
-        const hooksConfig = config.hooks || {};
-        // Check UserPromptSubmit
-        const promptHooks = hooksConfig.UserPromptSubmit;
-        hooks.promptCheck = promptHooks?.some((entry) => entry.hooks?.some((h) => h.command?.includes("prompt-check"))) ?? false;
-        // Check Stop
-        const stopHooks = hooksConfig.Stop;
-        hooks.stop = stopHooks?.some((entry) => entry.hooks?.some((h) => h.command?.includes("checkpoint"))) ?? false;
-        // Check PreToolUse — look for native kspec guard worktree command
-        const preToolUseHooks = hooksConfig.PreToolUse;
-        hooks.preToolUse = preToolUseHooks?.some((entry) => entry.hooks?.some((h) => h.command === NATIVE_GUARD_COMMAND || h.command?.includes(".claude/hooks/"))) ?? false;
-        // Check for native guard command
-        if (preToolUseHooks?.some((entry) => entry.hooks?.some((h) => h.command === NATIVE_GUARD_COMMAND))) {
-            hooks.guardsPresent.push("kspec guard worktree");
-        }
-        // Check for legacy bash scripts still present
-        if (preToolUseHooks?.some((entry) => entry.hooks?.some((h) => OLD_GUARD_SCRIPTS.some((name) => h.command?.includes(name))))) {
-            hooks.guardsPresent.push("legacy:bash-scripts");
-        }
-    }
-    catch (err) {
-        debugLog("Failed to read hooks config for status", err);
-    }
-    // Check for legacy guard script files on disk
-    try {
-        const guardFiles = await fs.readdir(hooksDir);
-        for (const name of OLD_GUARD_SCRIPTS) {
-            if (guardFiles.includes(name)) {
-                hooks.guardsPresent.push(`legacy-file:${name}`);
-            }
-        }
-    }
-    catch (err) {
-        debugLog("Hooks dir doesn't exist", err);
-    }
-    // Check skills
-    const skills = {
-        total: 0,
-        rendered: 0,
-        drifted: 0,
-    };
-    // Helper to scan a directory for skill subdirs with kspec-managed SKILL.md
-    async function scanForSkills(baseDir) {
-        try {
-            const dirs = await fs.readdir(baseDir, { withFileTypes: true });
-            for (const dir of dirs) {
-                if (dir.isDirectory()) {
-                    const skillMdPath = path.join(baseDir, dir.name, "SKILL.md");
-                    try {
-                        const content = await fs.readFile(skillMdPath, "utf-8");
-                        if (content.includes("<!-- kspec-managed -->")) {
-                            skills.total++;
-                            skills.rendered++;
-                        }
-                    }
-                    catch (_noSkillMd) {
-                        // No SKILL.md
-                    }
-                }
-            }
-        }
-        catch (_notReadable) {
-            // Directory doesn't exist
-        }
-    }
-    // Scan .claude/skills/ (project/local skills)
-    await scanForSkills(skillsDir);
-    // Check plugin marketplace health
-    // AC: @enhanced-setup ac-7, ac-8
-    const plugin = {
-        marketplaceRegistered: false,
-        marketplaceHealthy: false,
-        pluginEnabled: false,
-    };
-    try {
-        const { checkMarketplaceHealth } = await import("../../lib/claude-plugin-registry.js");
-        const health = await checkMarketplaceHealth();
-        plugin.marketplaceRegistered = health.status !== "missing";
-        plugin.marketplaceHealthy = health.status === "healthy";
-        plugin.registeredPath = health.registeredPath;
-        plugin.healthMessage = health.message;
-    }
-    catch (err) {
-        debugLog("Could not check marketplace health", err);
-        plugin.healthMessage = "Health check unavailable";
-    }
-    // Check if plugin is enabled in project settings
-    try {
-        const configContent = await fs.readFile(configPath, "utf-8");
-        const config = JSON.parse(configContent);
-        plugin.pluginEnabled = config.enabledPlugins?.["kspec@kspec-plugins"] === true;
-    }
-    catch (err) {
-        debugLog("Could not check plugin enablement", err);
-    }
-    // Check agents.md
-    const agentsMd = {
-        exists: false,
-        status: "missing",
-    };
-    try {
-        await fs.access(agentsMdPath);
-        agentsMd.exists = true;
-        try {
-            const hashContent = await fs.readFile(hashPath, "utf-8");
-            const hashData = JSON.parse(hashContent);
-            agentsMd.generatedAt = hashData.generatedAt;
-            // AC: @cross-platform-and-version-robustness ac-4
-            // Compare stored hash against current meta to detect staleness
-            try {
-                const { initContext, loadMetaContext } = await import("../../parser/index.js");
-                const { computeMetaHash, loadTemplateSections, getPackageRoot } = await import("./agents.js");
-                const ctx = await initContext();
-                if (ctx.manifestPath) {
-                    const metaCtx = await loadMetaContext(ctx);
-                    let templateSections = [];
-                    try {
-                        templateSections = await loadTemplateSections(getPackageRoot());
-                    }
-                    catch (err) {
-                        debugLog("Templates not available for staleness check", err);
-                    }
-                    const currentHash = computeMetaHash(metaCtx.skills, metaCtx.conventions, metaCtx.workflows, templateSections);
-                    agentsMd.status = hashData.metaHash === currentHash ? "current" : "stale";
-                }
-                else {
-                    // AC: @doctor-command ac-staleness-unknown — no manifest means we can't determine staleness
-                    agentsMd.status = "unknown";
-                }
-            }
-            catch (err) {
-                // AC: @doctor-command ac-staleness-unknown — hash computation failed
-                debugLog("Could not compute meta hash for staleness check", err);
-                agentsMd.status = "unknown";
-            }
-        }
-        catch (err) {
-            debugLog("Hash file missing or invalid, marking stale", err);
-            agentsMd.status = "stale";
-        }
-    }
-    catch (err) {
-        debugLog("kspec-agents.md doesn't exist", err);
-    }
-    // Check seeding state
-    const seeding = {
-        permissionsSeeded: false,
-        memorySeeded: false,
-    };
-    try {
-        const configContent = await fs.readFile(path.join(projectDir, ".claude", "settings.json"), "utf-8");
-        const config = JSON.parse(configContent);
-        seeding.permissionsSeeded = !!config.permissions;
-    }
-    catch (err) {
-        debugLog("Could not check permissions seeding state", err);
-    }
-    if (detected.type === "claude-code") {
-        try {
-            const { claudeCodeMemoryWriter } = await import("./setup-seeding.js");
-            const memoryExists = await claudeCodeMemoryWriter.exists(projectDir);
-            seeding.memorySeeded = memoryExists;
-            if (memoryExists) {
-                seeding.memoryPath = claudeCodeMemoryWriter.getMemoryPath(projectDir);
-            }
-        }
-        catch (err) {
-            debugLog("Could not check memory seeding state", err);
-        }
-    }
-    return {
-        agent: {
-            detected: detected.type,
-            confidence: detected.confidence,
-        },
-        hooks,
-        skills,
-        plugin,
-        agentsMd,
-        seeding,
-    };
-}
 /**
  * Render skills using the platform renderer registry
  * AC: @setup-pipeline-unification ac-2 - uses getRenderer/getAllRenderers, not legacy renderClaudeCodeSkill
@@ -761,6 +636,12 @@ async function renderSkillsForSetup(projectDir, dryRun) {
         return { rendered: 0, skipped: 0, pluginProvided: 0, skillIds: [] };
     }
 }
+function getHookInstallSkipMessage(agentType) {
+    if (agentType === "droid") {
+        return "droid hooks are not yet supported; skipping .factory/settings.json hook installation";
+    }
+    return `not applicable for ${agentType}`;
+}
 /**
  * Ensure built-in worker and reviewer agent definitions exist in the project meta.
  *
@@ -1069,8 +950,15 @@ export async function runSetupPipeline(projectDir, options) {
         }
         // Step 3: Install hooks (Claude Code only)
         // AC: @init-setup-integration ac-3 - hooks present
+        // AC: @project-config ac-hooks-section — read config to determine hook preferences
         if (detected.type === "claude-code" && installHooksFlag) {
-            const hooksResult = await installClaudeCodeHooks(projectDir, dryRun);
+            // Load project config to get hooks preferences
+            const { config: projectConfig } = await loadProjectConfig(projectDir, projectDir);
+            const hooksPrefs = {
+                checkpoint: projectConfig.hooks.checkpoint,
+                prompt_check: projectConfig.hooks.prompt_check,
+            };
+            const hooksResult = await installClaudeCodeHooks(projectDir, dryRun, hooksPrefs);
             const installedHooks = [];
             if (hooksResult.promptCheck)
                 installedHooks.push("UserPromptSubmit");
@@ -1100,7 +988,7 @@ export async function runSetupPipeline(projectDir, options) {
             steps.push({
                 name: "Install hooks",
                 status: "skipped",
-                message: `not applicable for ${detected.type}`,
+                message: getHookInstallSkipMessage(detected.type),
             });
         }
         // Step 3a: Ensure artifacts directory exists
@@ -1123,6 +1011,108 @@ export async function runSetupPipeline(projectDir, options) {
                 message: artifactsCreated ? "created .kspec/artifacts/" : "already exists",
             });
         }
+        // Step 3a-ii: Ensure sessions directory and gitignore entries
+        // AC: @session-storage-modes ac-gitignore, ac-sessions-dir-autocreate
+        // AC: @session-legacy-migration ac-shadow-gitignore
+        {
+            const actions = [];
+            // Create .kspec-sessions/ directory
+            const sessionsDirPath = path.join(projectDir, SESSIONS_WORKTREE_DIR);
+            let sessionsCreated = false;
+            try {
+                await fs.access(sessionsDirPath);
+            }
+            catch (_e) {
+                if (!dryRun) {
+                    await fs.mkdir(sessionsDirPath, { recursive: true });
+                }
+                sessionsCreated = true;
+            }
+            if (sessionsCreated) {
+                actions.push(`${dryRun ? "create" : "created"} ${SESSIONS_WORKTREE_DIR}/`);
+            }
+            // Add .kspec-sessions/ to root .gitignore
+            if (dryRun) {
+                const rootNeeded = await needsSessionsGitignore(projectDir);
+                if (rootNeeded) {
+                    actions.push(`add ${SESSIONS_WORKTREE_DIR}/ to .gitignore`);
+                }
+            }
+            else {
+                const rootAdded = await ensureSessionsGitignore(projectDir);
+                if (rootAdded) {
+                    actions.push(`added ${SESSIONS_WORKTREE_DIR}/ to .gitignore`);
+                }
+            }
+            // Add sessions/ to .kspec/.gitignore
+            if (dryRun) {
+                const shadowNeeded = await needsShadowSessionsGitignore(projectDir);
+                if (shadowNeeded) {
+                    actions.push("add sessions/ to .kspec/.gitignore");
+                }
+            }
+            else {
+                const shadowAdded = await ensureShadowSessionsGitignore(projectDir);
+                if (shadowAdded) {
+                    actions.push("added sessions/ to .kspec/.gitignore");
+                }
+            }
+            steps.push({
+                name: "Ensure sessions directory",
+                status: actions.length > 0 ? "done" : "skipped",
+                message: actions.length > 0 ? actions.join(", ") : "already configured",
+            });
+        }
+        // Step 3a-iii: Initialize session branch worktree if sessions.storage is "branch"
+        // AC: @session-branch-worktree ac-init
+        {
+            try {
+                const { initContext } = await import("../../parser/index.js");
+                const ctx = await initContext();
+                const sessionStorage = ctx.manifest?.sessions?.storage;
+                if (sessionStorage === "branch") {
+                    const { initializeSessionBranch, getSessionBranchStatus } = await import("../../parser/session-branch.js");
+                    const sessionBranchName = ctx.manifest?.sessions?.branch || "kspec-sessions";
+                    const sessionStatus = await getSessionBranchStatus(projectDir, sessionBranchName);
+                    if (sessionStatus.healthy) {
+                        steps.push({
+                            name: "Session branch worktree",
+                            status: "skipped",
+                            message: "already initialized",
+                        });
+                    }
+                    else if (dryRun) {
+                        steps.push({
+                            name: "Session branch worktree",
+                            status: "done",
+                            message: `create orphan branch "${sessionBranchName}" with worktree at ${SESSIONS_WORKTREE_DIR}/`,
+                        });
+                    }
+                    else {
+                        const sessionResult = await initializeSessionBranch(projectDir, sessionBranchName);
+                        if (sessionResult.success) {
+                            steps.push({
+                                name: "Session branch worktree",
+                                status: "done",
+                                message: sessionResult.alreadyExists
+                                    ? "already initialized"
+                                    : `created branch "${sessionBranchName}" with worktree at ${SESSIONS_WORKTREE_DIR}/`,
+                            });
+                        }
+                        else {
+                            steps.push({
+                                name: "Session branch worktree",
+                                status: "failed",
+                                message: sessionResult.error || "unknown error",
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                // Session branch init is optional — don't block setup
+            }
+        }
         // Step 3b: Seed permissions (Claude Code only)
         // AC: @new-project-bootstrapping ac-1
         {
@@ -1252,6 +1242,9 @@ export async function runSetupPipeline(projectDir, options) {
                             authorInstalled = true;
                         }
                         break;
+                    case "droid":
+                        authorInstalled = false;
+                        break;
                     case "aider":
                         if (!dryRun) {
                             authorInstalled = await installAiderConfig(author);
@@ -1270,6 +1263,21 @@ export async function runSetupPipeline(projectDir, options) {
                         message: `KSPEC_AUTHOR="${author}"`,
                     });
                 }
+                else if (detected.type === "droid") {
+                    steps.push({
+                        name: "Configure author",
+                        status: "skipped",
+                        message: "add KSPEC_AUTHOR to the .factory/settings.json env section",
+                    });
+                }
+                else if (detected.type === "unknown") {
+                    // AC: @cmd-setup ac-1 - show manual instructions for unknown agents
+                    steps.push({
+                        name: "Configure author",
+                        status: "skipped",
+                        message: `no auto-config for unknown agent — set KSPEC_AUTHOR manually`,
+                    });
+                }
             }
         }
         // Output summary
@@ -1326,7 +1334,7 @@ export function registerSetupCommand(program) {
     program
         .command("setup")
         .description("Configure agent environment for kspec (orchestrated pipeline)")
-        .option("--agent <type>", "Explicit agent type override (claude-code|cline|cursor|windsurf|unknown)")
+        .option("--agent <type>", "Explicit agent type override (claude-code|cline|droid|cursor|windsurf|unknown)")
         .option("--dry-run", "Show what would be done without making changes")
         .option("--author <author>", "Custom author string (default: auto-detected based on agent)")
         .option("--no-hooks", "Skip installing hooks")
@@ -1342,18 +1350,34 @@ export function registerSetupCommand(program) {
                 : undefined;
             // AC: @enhanced-setup ac-7, ac-8 - --status mode
             if (options.status) {
-                const status = await getSetupStatus(projectDir, agentOverride);
+                const status = await getSharedSetupStatus(projectDir, {
+                    agentOverride,
+                });
                 output(status, () => {
                     console.log(chalk.bold("kspec Setup Status\n"));
                     // Agent detection
                     console.log(chalk.gray("Agent:"));
                     console.log(`  Detected: ${status.agent.detected} (${status.agent.confidence} confidence)`);
+                    if (status.agent.configPath) {
+                        console.log(`  Config:   ${status.agent.configPath}`);
+                    }
                     console.log();
                     // Hooks status
                     console.log(chalk.gray("Hooks:"));
-                    console.log(`  UserPromptSubmit: ${status.hooks.promptCheck ? chalk.green("✓") : chalk.red("✗")}`);
-                    console.log(`  Stop:             ${status.hooks.stop ? chalk.green("✓") : chalk.red("✗")}`);
-                    console.log(`  PreToolUse:       ${status.hooks.preToolUse ? chalk.green("✓") : chalk.red("✗")}`);
+                    if (status.hooks.supported) {
+                        console.log(`  UserPromptSubmit: ${status.hooks.promptCheck ? chalk.green("✓") : chalk.red("✗")}`);
+                        console.log(`  Stop:             ${status.hooks.stop ? chalk.green("✓") : chalk.red("✗")}`);
+                        console.log(`  PreToolUse:       ${status.hooks.preToolUse ? chalk.green("✓") : chalk.red("✗")}`);
+                    }
+                    else {
+                        const unsupported = chalk.yellow("unsupported");
+                        console.log(`  UserPromptSubmit: ${unsupported}`);
+                        console.log(`  Stop:             ${unsupported}`);
+                        console.log(`  PreToolUse:       ${unsupported}`);
+                        if (status.agent.detected === "droid") {
+                            console.log("  Note:             droid hooks are not yet supported");
+                        }
+                    }
                     if (status.hooks.guardsPresent.length > 0) {
                         console.log(`  Guards:           ${status.hooks.guardsPresent.join(", ")}`);
                     }
@@ -1419,10 +1443,9 @@ export function registerSetupCommand(program) {
                 ? buildDetectedAgent(agentOverride)
                 : detectAgent();
             const dryRun = options.dryRun || false;
+            // AC: @cmd-setup ac-1 - proceed with setup even when no agent is detected
             if (detected.type === "unknown") {
-                warn("Could not auto-detect agent environment");
-                printManualInstructions("unknown");
-                return;
+                warn("Could not auto-detect agent environment — proceeding with core setup steps");
             }
             // AC: @setup-pipeline-unification ac-3 - delegate to runSetupPipeline()
             // One code path for both 'kspec setup' and 'kspec init --setup'
@@ -1478,6 +1501,13 @@ export function registerSetupCommand(program) {
                     console.log(chalk.green("Setup complete."));
                     console.log(chalk.gray("Restart your agent session for changes to take effect."));
                 }
+                const configureAuthorStep = result.steps.find((step) => step.name === "Configure author");
+                const needsManualInstructions = configureAuthorStep?.status === "skipped" &&
+                    !configureAuthorStep.message?.includes("already set") &&
+                    (detected.type === "unknown" || detected.type === "droid");
+                if (needsManualInstructions) {
+                    printManualInstructions(detected.type);
+                }
             });
         }
         catch (err) {