Interactive Setup Wizard with Project-Type-Aware Recommendations

[github-actions]

Strategic Improvement

Setup takes ~30 min (target <5 min) and lacks guidance on best practices for user's project type. Build interactive wizard that detects project characteristics (language, framework, test runner, CI config) and recommends optimized templates, stage gates, and daemon settings with explanations. Improves time-to-value and reduces misconfiguration.

Acceptance Criteria

• Detects project type: language (via file extensions), framework (package.json/go.mod/requirements.txt), test command (npm/pytest/go test)
• Recommends pipeline template based on project type + user goals (speed vs safety vs cost)
• Suggests daemon-config.json settings: effort levels, model routing, iteration counts
• Interactive prompts with defaults, explanations, and "why this matters"
• Generates .claude/ directory structure with recommended config
• Measures setup time from start to first successful pipeline run, validates <5 min on test projects

Context

• Priority: P1
• Complexity: standard
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P1: Developer Experience

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Strategic DX improvement aligned with Shipwright mission; enhances existing setup.sh/prep.sh to auto-detect project type and recommend optimized templates/config, reducing setup friction and time-to-value for new users.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	24294834926

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (16 lines)

The plan is ready for review. Here's a summary of the approach:

What: Replace the basic Phase 2+3 of sw-setup.sh with an interactive wizard that detects project type using the existing project-detect.sh library, asks about user goals (speed/safety/cost/automation), recommends a pipeline template, and generates a tuned daemon-config.json.

Key files:

• New: scripts/lib/setup-wizard.sh — wizard functions (prompts, config generation)
• New: scripts/sw-setup-wizard-test.sh — dedicated test suite
• Modify: scripts/sw-setup.sh — wire in wizard, add --auto/--interactive flags
• Modify: scripts/sw-setup-test.sh — test new flags
• Modify: package.json — register new test

Design highlights:

• Reuses existing project-detect.sh (8 languages, 15+ frameworks) — no duplicate detection
• Goal-to-config mapping table drives template + effort levels + model routing
• TTY detection for auto mode (CI/daemon compatibility)
• Atomic file writes, Bash 3.2 compatible, set -euo pipefail

---

Generated by shipwright pipeline at 2026-04-12T00:31:36Z

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (232 lines)

Now I have a thorough understanding of the codebase. Let me write the ADR.

---

Design: Interactive Setup Wizard with Project-Type-Aware Recommendations

Context

sw-setup.sh Phase 2 duplicates language/framework detection that scripts/lib/project-detect.sh already handles more thoroughly (8 languages, 15+ frameworks vs. 4 languages, 5 frameworks). Phase 3 delegates to sw-init.sh with zero user input — it generates a one-size-fits-all daemon-config.json regardless of whether the user prioritizes speed, safety, cost, or full automation. There is no way for a user to influence template selection, effort levels, or model routing during setup.

Constraints:

• Bash 3.2 compatibility (no associative arrays, no readarray, no ${var,,})
• set -euo pipefail required
• Must work in non-TTY environments (CI, daemon-spawned pipelines)
• Atomic file writes (tmp + mv)
• Must not break existing --skip-daemon-prompt flag behavior
• project-detect.sh already caches to .claude/project-detection.json with 3600s TTL — reuse, don't duplicate

Decision

Component Diagram

┌─────────────────────────────────────────────────────────┐
│                   sw-setup.sh (orchestrator)            │
│  Phase 1: prerequisites  (unchanged)                    │
│  Phase 2: detection      (delegates to wizard)          │
│  Phase 3: config gen     (delegates to wizard)          │
│  Phase 4: validation     (unchanged)                    │
└───────┬──────────────────────┬──────────────────────────┘
        │                      │
        ▼                      ▼
┌───────────────────┐  ┌──────────────────────────────────┐
│ project-detect.sh │  │ lib/setup-wizard.sh              │
│ (existing, reused)│  │                                  │
│                   │  │  wizard_run(root, auto)           │
│ project_detect_   │◄─│    ├─ wizard_detect(root)        │
│   all(root)→JSON  │  │    ├─ wizard_prompt_goal()       │
│                   │  │    ├─ wizard_recommend(det, goal) │
│ project_recommend_│  │    └─ wizard_generate_config(...) │
│   template(root)  │  │                                  │
└───────────────────┘  └──────────────────────────────────┘

Three components:

1. sw-setup.sh (modified) — Orchestrator. Adds --auto/--interactive flags. In Phase 2+3, calls wizard_run() instead of inline detection + bare sw-init.sh. Falls back to auto mode when no TTY.

2. scripts/lib/setup-wizard.sh (new) — Pure library of functions. No top-level execution. Sources project-detect.sh for detection. Contains goal→config mapping table, prompt helpers, and config generation.

3. scripts/lib/project-detect.sh (existing, unmodified) — Detection engine. Called via project_detect_all() which returns cached JSON.

Interface Contracts

// wizard_run(repo_root: string, auto_mode: "true"|"false") → exit 0|1
// Orchestrates the full wizard flow. Prints to stdout/stderr.
// Side effect: writes daemon-config.json atomically.

// wizard_detect(repo_root: string) → stdout: JSON

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-04-12T00:35:30Z_

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: opus

[github-actions]

[github-actions]