domains / devops / conductor-rails-workspace-setup / conductor-setup

conductor-setup

Skill card

combined

The two copies use the same skill name but describe different procedures. The first copy is a generic, interactive project onboarding flow that creates a conductor/ directory, setup_state.json, and product/tech/workflow/style documents. The second copy is a Rails-specific setup that creates conductor.json, bin/conductor-setup, script/server, and updates Redis-related Rails configuration. Neither copy is a shortened or wrapped version of the other; each contains material steps and constraints the other lacks, so crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

---
name: conductor-setup
description: Initialize a project for Conductor, either as a generic documentation setup or as a Rails workspace setup.
---

# Conductor Setup

Initialize or resume Conductor project setup. Choose the appropriate path based on the project type.

## When to Use
- You need to initialize a project with Conductor artifacts.
- For generic projects: create foundational documentation through interactive Q&A.
- For Rails projects: configure the project to run inside Conductor workspaces with isolated ports, Redis settings, and shared secrets.

## Pre-flight Checks
1. Check if `conductor/` directory already exists in the project root:
   - If `conductor/product.md` exists: Ask user whether to resume setup or reinitialize.
   - If `conductor/setup_state.json` exists with incomplete status: Offer to resume from last step.
2. Detect project type:
   - **Greenfield**: No .git, no package.json, no requirements.txt, no go.mod, no src/ directory.
   - **Brownfield**: Any of the above exist.
   - **Rails**: Check for Gemfile, config/, and Rails-specific indicators.
3. Load or create `conductor/setup_state.json` for generic setup, or check for existing `conductor.json` for Rails setup.

## Path A: Generic Documentation Setup

### Interactive Q&A Protocol
- Ask ONE question per turn.
- Wait for user response before proceeding.
- Offer 2-3 suggested answers plus "Type your own" option.
- Maximum 5 questions per section.
- Update `setup_state.json` after each successful step.
- Validate file writes succeeded before continuing.

### Section 1: Product Definition (max 5 questions)
- Q1: Project Name
- Q2: Project Description
- Q3: Problem Statement
- Q4: Target Users
- Q5: Key Goals (optional)

### Section 2: Product Guidelines (max 3 questions)
- Q1: Voice and Tone
- Q2: Design Principles

### Section 3: Tech Stack (max 5 questions)
- For brownfield projects, analyze existing code to pre-populate tech stack.
- Q1: Primary Language(s)
- Q2: Frontend Framework (if applicable)
- Q3: Backend Framework (if applicable)
- Q4: Database (if applicable)
- Q5: Infrastructure

### Section 4: Workflow Preferences (max 4 questions)
- Q1: TDD Strictness
- Q2: Commit Strategy
- Q3: Code Review Requirements
- Q4: Verification Checkpoints

### Section 5: Code Style Guides (max 2 questions)
- Q1: Languages to Include
- Q2: Existing Conventions

## Path B: Rails Workspace Setup

### 1. conductor.json (project root)
Create `conductor.json` in the project root if it doesn't already exist:
```json
{
  "scripts": {
    "setup": "bin/conductor-setup",
    "run": "script/server"
  }
}
```

### 2. bin/conductor-setup (executable)
Create `bin/conductor-setup` if it doesn't already exist:
```bash
#!/usr/bin/env bash
set -euo pipefail
: "${CONDUCTOR_ROOT_PATH:?Set the reviewed repository root first}"

link_if_absent() {
  local source_path="$1" destination="$2"
  if [[ -f "$source_path" && ! -e "$destination" && ! -L "$destination" ]]; then
    ln -s -- "$source_path" "$destination"
  fi
}
link_if_absent "$CONDUCTOR_ROOT_PATH/.env" .env
mkdir -p config
link_if_absent "$CONDUCTOR_ROOT_PATH/config/master.key" config/master.key

bundle install
if [[ -f package-lock.json ]]; then
  npm ci --ignore-scripts
elif [[ -f package.json ]]; then
  printf '%s\n' 'A reviewed npm lockfile is required; no silent npm install.' >&2
  exit 1
fi
```
Make it executable with `chmod +x bin/conductor-setup`.

### 3. script/server (executable)
Create the `script` directory if needed, then create `script/server` if it doesn't already exist:
```bash
#!/usr/bin/env bash
set -euo pipefail

PORT="${CONDUCTOR_PORT:-3000}"
[[ "$PORT" =~ ^[0-9]{1,5}$ ]] || { printf '%s\n' 'Invalid port' >&2; exit 1; }
PORT=$((10#$PORT))
(( PORT >= 1024 && PORT <= 64535 )) || { printf '%s\n' 'Port outside safe range' >&2; exit 1; }
export PORT
export VITE_RUBY_PORT=$((PORT + 1000))

: "${REDIS_URL:?Set an approved workspace-specific development Redis URL}"
export REDIS_URL
exec bin/dev
```
Make it executable with `chmod +x script/server`.

### 4. Update Rails Config Files
For each of the following files, if they exist and contain Redis configuration, update them to use `ENV.fetch('REDIS_URL', ...)` or `ENV['REDIS_URL']` with a fallback:
- config/initializers/sidekiq.rb
- config/cable.yml
- config/environments/development.rb
- config/initializers/rack_attack.rb

## Verification
1. Confirm all Conductor files exist and scripts are executable.
2. Validate script syntax first, then start the owned development server with a bounded observation window and a defined shutdown method; verify actual port/Redis separation across workspaces.
3. Check that Rails configs properly reference `ENV['REDIS_URL']` or `ENV.fetch('REDIS_URL', ...)`.

## Limitations
- Secret symlinks share the same sensitive values across workspaces; use only approved development credentials, preserve owner-only source permissions, exclude secrets from Git and do not imply worktrees are a secret sandbox.
- Sharing one Redis URL across Sidekiq, Cable and cache may still need service namespaces; dedicated instances or explicitly assigned namespaces are safer than modulo hashes. Never flush shared Redis as cleanup.
- npm/Gem installation and bin/dev execute project dependencies/scripts. Review them first; explicitly required lifecycle steps should be run individually after approval, not re-enabled silently.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.