specrails-core 3.7.0 → 3.8.1

package/README.md

@@ -47,17 +47,18 @@ Updates automatically: `claude plugin update sr`
 ### Scaffold method (alternative)
 
 ```bash
-npx specrails-core@latest init --root-dir .   # TUI agent selection + install files
-/specrails:enrich --from-config               # run AI analysis using your config
+npx specrails-core@latest init --root-dir .   # TUI: select agents, choose tier
 ```
 
+**Quick tier** (default) — agents installed directly, ready to use immediately. No AI interaction.
+**Full tier** — run `/specrails:enrich` after install for deep codebase analysis, VPC personas, and competitive research.
+
 ### Start building
 
 ```bash
 > /specrails:implement "add user authentication"
 > /specrails:implement #1, #2                 # from local tickets (default)
 > /specrails:implement #42, #43               # from GitHub Issues (if configured)
-> /specrails:auto-propose-backlog-specs    # discover new features with AI
 ```
 
 That's it. The pipeline takes over.

package/docs/getting-started.md

@@ -37,15 +37,29 @@ npx specrails-core@latest init --root-dir <your-project>
 
 See [installation.md](installation.md) for full details on both methods and when to use each.
 
-## Run the Enrich Wizard
+## Installation Tiers
 
-Open Claude Code in your project and run:
+### Quick Install (default via TUI)
+
+When you run `npx specrails-core@latest init`, the TUI installer lets you choose **Quick** tier. This places agents, commands, rules, and settings directly — no AI interaction required:
+
+1. Select agents to install
+2. Choose a model preset
+3. Provide a brief product description
+
+Agents are ready to use immediately after install. Open Claude Code and start working.
+
+> Quick install excludes VPC personas and persona-dependent agents/commands (sr-product-manager, sr-product-analyst). These require the full enrichment process.
+
+### Full Install (via `/specrails:enrich`)
+
+For deeper customization, choose **Full** tier or run `/specrails:enrich` after a Quick install:
 
 ```
 /specrails:enrich
 ```
 
-By default, `/specrails:enrich` runs the **full 5-phase wizard** — deep stack analysis, researched user personas, and fully adapted agents.
+The full 5-phase wizard provides deep stack analysis, researched user personas, and fully adapted agents:
 
 | Phase | What happens |
 |-------|-------------|
@@ -55,17 +69,9 @@ By default, `/specrails:enrich` runs the **full 5-phase wizard** — deep stack
 | **4. Generate** | Generates your project data files (`.specrails/`) with project-specific context |
 | **5. Cleanup** | Removes the wizard scaffolding, leaving only your tailored workflow files |
 
-**In a hurry?** Run `/specrails:enrich --quick` for the quick version: three questions, sensible defaults, done in under a minute.
-
-| Question | What it configures |
-|----------|-------------------|
-| What is this project? | Agent context and CLAUDE.md |
-| Who are the target users? | Persona stubs for product discovery |
-| Git access — read-only or read-write? | Whether agents can commit |
-
-Quick mode installs the four core agents (architect, developer, reviewer, product manager), all workflow commands, and local ticket storage. You can run the full wizard later to deepen the configuration.
+Full install adds VPC personas, sr-product-manager, sr-product-analyst, and persona-dependent commands.
 
-After either mode, your project data files are ready to use and your `/specrails:*` commands are live.
+After either tier, your `/specrails:*` commands are live.
 
 ## Your first feature
 

package/docs/installation.md

@@ -226,24 +226,36 @@ After this phase, `/specrails:enrich` is no longer available until re-run — yo
 
 ---
 
-### Quick Mode (`/specrails:enrich --quick`)
+### Quick Install (TUI → `tier: quick`)
 
-The quick path — three questions, sensible defaults, done in under a minute.
+The quick path — select agents in the TUI, answer two context questions, done in seconds. No AI interaction required.
 
-1. What is this project? (one sentence)
-2. Who are the target users?
-3. Git access for agents — read-only or read-write?
+1. Select which agents to install (from 14 available)
+2. Choose a model preset (balanced, budget, or max)
+3. Provide a short product description and target users
 
 **What gets installed:**
 
 | Item | Detail |
 |------|--------|
-| Core agents | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
-| All workflow commands | `/specrails:implement`, `/specrails:get-backlog-specs`, and 14 more |
-| Backlog storage | Local tickets (`.specrails/local-tickets.json`) — no GitHub or JIRA required |
-| CLAUDE.md | Project-level context for agents |
+| Selected agents | Placed directly in `.claude/agents/` with template defaults |
+| Workflow commands | `/specrails:implement`, `/specrails:doctor`, and more (18 commands) |
+| Rules & settings | Layer conventions, settings.json, security exemptions |
+| Agent memory | `.claude/agent-memory/<agent>/` directories |
+| Skills | OpenSpec skills in `.claude/skills/` |
 
-You can run the full wizard later to deepen configuration: personas, stack analysis, layer-specific conventions.
+**What is NOT installed (requires full enrichment):**
+
+| Item | Reason |
+|------|--------|
+| VPC personas | Require competitive research and AI analysis |
+| sr-product-manager | Drives VPC persona creation — needs enrichment |
+| sr-product-analyst | Analyzes personas — needs enrichment |
+| `/specrails:auto-propose-backlog-specs` | Depends on personas |
+| `/specrails:vpc-drift` | Depends on personas |
+| `/specrails:get-backlog-specs` | References personas for prioritization |
+
+Agents work immediately with template defaults. Run `/specrails:enrich` later to add personas, competitive analysis, and codebase-specific customization.
 
 ---
 
@@ -256,7 +268,7 @@ Runs a fully automated installation using `.specrails/install-config.yaml`. No i
 ```yaml
 version: 1
 provider: claude        # claude | codex | auto
-tier: full              # full | quick
+tier: full              # full (requires /specrails:enrich) | quick (agents placed directly)
 agents:
   selected:             # list of agent names to install
     - sr-architect

package/install.sh

@@ -857,6 +857,170 @@ if [ -d "$SCRIPT_DIR/prompts" ] && [ "$(ls -A "$SCRIPT_DIR/prompts" 2>/dev/null)
     ok "Installed prompts"
 fi
 
+# ─────────────────────────────────────────────
+# Phase 3c: Quick-tier direct placement
+# ─────────────────────────────────────────────
+# For Quick tier, copy agents/commands/rules/personas/settings from
+# setup-templates directly to their final locations under $SPECRAILS_DIR.
+# Placeholders are stripped (enrich not required).
+
+if [[ "$TIER" == "quick" ]]; then
+    step "Phase 3c: Placing agents and commands (quick install)"
+
+    _templates="${REPO_ROOT}/.specrails/setup-templates"
+    _project_name="$(basename "$REPO_ROOT")"
+    _quick_product_desc=""
+    _quick_target_users=""
+
+    # Read quick_context from install-config.yaml if available
+    _qc_file="${CONFIG_PATH:-${REPO_ROOT}/.specrails/install-config.yaml}"
+    if [[ -f "$_qc_file" ]]; then
+        _quick_product_desc=$(grep '^\s*product_description:' "$_qc_file" 2>/dev/null | head -1 | sed 's/.*product_description:[[:space:]]*//' | sed 's/^"//;s/"$//' || true)
+        _quick_target_users=$(grep '^\s*target_users:' "$_qc_file" 2>/dev/null | head -1 | sed 's/.*target_users:[[:space:]]*//' | sed 's/^"//;s/"$//' || true)
+    fi
+
+    # VPC/persona-dependent agents are excluded from Quick tier (require enrichment)
+    _quick_excluded_agents="sr-product-manager sr-product-analyst"
+
+    # --- Agents ---
+    if [[ -d "$_templates/agents" ]] && ls "$_templates/agents/"*.md &>/dev/null; then
+        mkdir -p "${REPO_ROOT}/${SPECRAILS_DIR}/agents"
+        _agent_count=0
+        _agent_skipped=0
+        for _src in "$_templates/agents/"*.md; do
+            [[ -f "$_src" ]] || continue
+            _name="$(basename "$_src" .md)"
+
+            # Skip VPC-dependent agents in Quick tier
+            if echo " $_quick_excluded_agents " | grep -q " ${_name} "; then
+                (( _agent_skipped++ )) || true
+                continue
+            fi
+
+            _dest="${REPO_ROOT}/${SPECRAILS_DIR}/agents/${_name}.md"
+            cp "$_src" "$_dest"
+
+            # Substitute known placeholders
+            sed -i.bak \
+                -e "s|{{PROJECT_NAME}}|${_project_name}|g" \
+                -e "s|{{PROJECT_DESCRIPTION}}|${_quick_product_desc}|g" \
+                -e "s|{{TARGET_USERS}}|${_quick_target_users}|g" \
+                -e "s|{{MEMORY_PATH}}|.claude/agent-memory/${_name}/|g" \
+                -e "s|{{SECURITY_EXEMPTIONS_PATH}}|${SPECRAILS_DIR}/security-exemptions.yaml|g" \
+                -e "s|{{PERSONA_DIR}}|${SPECRAILS_DIR}/agents/personas/|g" \
+                "$_dest" && rm -f "${_dest}.bak"
+
+            # Strip remaining {{PLACEHOLDER}} lines (leave blank line)
+            sed -i.bak 's/{{[A-Z_]*}}//g' "$_dest" && rm -f "${_dest}.bak"
+
+            # Create agent memory directory
+            mkdir -p "${REPO_ROOT}/.claude/agent-memory/${_name}"
+
+            (( _agent_count++ )) || true
+        done
+        if (( _agent_skipped > 0 )); then
+            ok "Installed ${_agent_count} agent(s) to ${SPECRAILS_DIR}/agents/ (skipped ${_agent_skipped} VPC-dependent)"
+        else
+            ok "Installed ${_agent_count} agent(s) to ${SPECRAILS_DIR}/agents/"
+        fi
+    fi
+
+    # Persona-dependent commands excluded from Quick tier
+    _quick_excluded_cmds="auto-propose-backlog-specs vpc-drift get-backlog-specs"
+
+    # --- Commands ---
+    if [[ -d "$_templates/commands/specrails" ]]; then
+        mkdir -p "${REPO_ROOT}/${SPECRAILS_DIR}/commands/specrails"
+        _cmd_count=0
+        for _src in "$_templates/commands/specrails/"*.md; do
+            [[ -f "$_src" ]] || continue
+            _cmd_name="$(basename "$_src" .md)"
+
+            # Skip persona-dependent commands in Quick tier
+            if echo " $_quick_excluded_cmds " | grep -q " ${_cmd_name} "; then
+                continue
+            fi
+
+            _dest="${REPO_ROOT}/${SPECRAILS_DIR}/commands/specrails/${_cmd_name}.md"
+            cp "$_src" "$_dest"
+            sed -i.bak \
+                -e "s|{{PROJECT_NAME}}|${_project_name}|g" \
+                -e "s|{{PROJECT_DESCRIPTION}}|${_quick_product_desc}|g" \
+                -e "s|{{TARGET_USERS}}|${_quick_target_users}|g" \
+                -e "s|{{MEMORY_PATH}}|.claude/agent-memory/|g" \
+                -e "s|{{PERSONA_DIR}}|${SPECRAILS_DIR}/agents/personas/|g" \
+                -e "s|{{SECURITY_EXEMPTIONS_PATH}}|${SPECRAILS_DIR}/security-exemptions.yaml|g" \
+                "$_dest" && rm -f "${_dest}.bak"
+            sed -i.bak 's/{{[A-Z_]*}}//g' "$_dest" && rm -f "${_dest}.bak"
+            (( _cmd_count++ )) || true
+        done
+        ok "Installed ${_cmd_count} command(s) to ${SPECRAILS_DIR}/commands/specrails/"
+    fi
+
+    # --- Rules ---
+    if [[ -d "$_templates/rules" ]]; then
+        mkdir -p "${REPO_ROOT}/${SPECRAILS_DIR}/rules"
+        for _src in "$_templates/rules/"*.md; do
+            [[ -f "$_src" ]] || continue
+            cp "$_src" "${REPO_ROOT}/${SPECRAILS_DIR}/rules/$(basename "$_src")"
+        done
+        ok "Installed rules to ${SPECRAILS_DIR}/rules/"
+    fi
+
+    # Personas are NOT installed in Quick tier (require VPC enrichment)
+
+    # --- Settings ---
+    if [[ -f "$_templates/settings/settings.json" && ! -f "${REPO_ROOT}/${SPECRAILS_DIR}/settings.json" ]]; then
+        cp "$_templates/settings/settings.json" "${REPO_ROOT}/${SPECRAILS_DIR}/settings.json"
+        ok "Installed settings.json"
+    fi
+    if [[ -f "$_templates/settings/integration-contract.json" ]]; then
+        cp "$_templates/settings/integration-contract.json" "${REPO_ROOT}/.specrails/integration-contract.json"
+        ok "Installed integration-contract.json"
+    fi
+
+    # --- Backlog config (default: local provider) ---
+    _backlog_cfg="${REPO_ROOT}/.specrails/backlog-config.json"
+    if [[ ! -f "$_backlog_cfg" ]]; then
+        mkdir -p "${REPO_ROOT}/.specrails"
+        cat > "$_backlog_cfg" <<'BCEOF'
+{
+  "provider": "local",
+  "write_access": true,
+  "git_auto": true
+}
+BCEOF
+        ok "Created .specrails/backlog-config.json (provider: local, git_auto: true)"
+    fi
+
+    # --- Local tickets store ---
+    _tickets_file="${REPO_ROOT}/.specrails/local-tickets.json"
+    if [[ ! -f "$_tickets_file" ]]; then
+        _now="$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")"
+        cat > "$_tickets_file" <<LTEOF
+{
+  "schema_version": "1.0",
+  "revision": 0,
+  "last_updated": "${_now}",
+  "next_id": 1,
+  "tickets": {}
+}
+LTEOF
+        ok "Created .specrails/local-tickets.json"
+    fi
+
+    # --- Skills (OpenSpec) ---
+    if [[ -d "$_templates/skills" ]]; then
+        mkdir -p "${REPO_ROOT}/${SPECRAILS_DIR}/skills"
+        cp -r "$_templates/skills/"* "${REPO_ROOT}/${SPECRAILS_DIR}/skills/" 2>/dev/null || true
+        ok "Installed skills to ${SPECRAILS_DIR}/skills/"
+    fi
+
+    if [[ "$HUB_JSON" == true ]]; then
+        echo "CHECKPOINT:quick_placement:done:Agents and commands placed"
+    fi
+fi
+
 # Initialize OpenSpec if available and not already initialized
 if [ "$HAS_OPENSPEC" = true ] && [ ! -d "$REPO_ROOT/openspec" ]; then
     info "Initializing OpenSpec..."
@@ -891,46 +1055,81 @@ if [[ "$AGENT_TEAMS" == "true" ]]; then
     echo "  Agent Teams: installed (/specrails:team-review, /specrails:team-debug)"
     echo "  Feature flag: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (required)"
 fi
-echo ""
-echo "  Files installed:"
-if [[ "$CLI_PROVIDER" == "codex" ]]; then
-    echo "    .agents/skills/enrich/SKILL.md       ← The \$enrich skill"
-    echo "    .agents/skills/doctor/SKILL.md       ← The \$doctor skill"
-else
-    echo "    $SPECRAILS_DIR/commands/specrails/enrich.md  ← The /specrails:enrich command"
-fi
-echo "    .specrails/setup-templates/              ← Templates: commands + skills (temporary, removed after enrich)"
-echo "    .specrails/specrails-version             ← Installed specrails version"
-echo "    .specrails/specrails-manifest.json       ← Artifact checksums for update detection"
-echo ""
+if [[ "$TIER" == "quick" ]]; then
+    # Quick tier: agents placed directly
+    _installed_agents=$(ls "${REPO_ROOT}/${SPECRAILS_DIR}/agents/"*.md 2>/dev/null | wc -l | tr -d ' ')
+    _installed_commands=$(ls "${REPO_ROOT}/${SPECRAILS_DIR}/commands/specrails/"*.md 2>/dev/null | wc -l | tr -d ' ')
+    echo ""
+    echo "  Installed:"
+    echo "    ${_installed_agents} agent(s)    → ${SPECRAILS_DIR}/agents/"
+    echo "    ${_installed_commands} command(s)  → ${SPECRAILS_DIR}/commands/specrails/"
+    echo "    .specrails/backlog-config.json   (provider: local)"
+    echo "    .specrails/local-tickets.json"
+    echo "    .specrails/specrails-version"
+    echo "    .specrails/specrails-manifest.json"
+    echo ""
 
-echo -e "${BOLD}Prerequisites:${NC}"
-echo ""
-[ "$HAS_NPM" = true ]      && ok "npm"        || warn "npm (optional)"
-[ "$HAS_OPENSPEC" = true ]  && ok "OpenSpec"    || warn "OpenSpec (optional)"
-[ "$HAS_GH" = true ]        && ok "GitHub CLI"  || warn "GitHub CLI (optional, for GitHub Issues backlog)"
-[ "$HAS_JIRA" = true ]      && ok "JIRA CLI"    || info "JIRA CLI not found (optional, for JIRA backlog)"
-echo ""
+    echo -e "${BOLD}Prerequisites:${NC}"
+    echo ""
+    [ "$HAS_NPM" = true ]      && ok "npm"        || warn "npm (optional)"
+    [ "$HAS_OPENSPEC" = true ]  && ok "OpenSpec"    || warn "OpenSpec (optional)"
+    [ "$HAS_GH" = true ]        && ok "GitHub CLI"  || warn "GitHub CLI (optional, for GitHub Issues backlog)"
+    [ "$HAS_JIRA" = true ]      && ok "JIRA CLI"    || info "JIRA CLI not found (optional, for JIRA backlog)"
+    echo ""
 
-echo -e "${BOLD}${CYAN}Next steps:${NC}"
-echo ""
-echo "  1. Open $CLI_PROVIDER in this repo:"
-echo ""
-echo -e "     ${BOLD}cd $REPO_ROOT && $CLI_PROVIDER${NC}"
-echo ""
-echo "  2. Run the enrich wizard:"
-echo ""
-if [[ "$CLI_PROVIDER" == "codex" ]]; then
-    echo -e "     ${BOLD}\$enrich${NC}"
-else
-    echo -e "     ${BOLD}/specrails:enrich${NC}"
-fi
-echo ""
-if [[ "$CLI_PROVIDER" == "codex" ]]; then
-    echo "  Codex will analyze your codebase, ask about your users,"
+    echo -e "${BOLD}${CYAN}Next steps:${NC}"
+    echo ""
+    echo "  1. Open $CLI_PROVIDER in this repo:"
+    echo ""
+    echo -e "     ${BOLD}cd $REPO_ROOT && $CLI_PROVIDER${NC}"
+    echo ""
+    echo "  2. Your agents are ready to use! Start working:"
+    echo ""
+    echo "     Agents, commands, and rules are pre-configured."
+    echo "     No additional setup required."
+    echo ""
 else
-    echo "  Claude will analyze your codebase, ask about your users,"
+    echo ""
+    echo "  Files installed:"
+    if [[ "$CLI_PROVIDER" == "codex" ]]; then
+        echo "    .agents/skills/enrich/SKILL.md       ← The \$enrich skill"
+        echo "    .agents/skills/doctor/SKILL.md       ← The \$doctor skill"
+    else
+        echo "    $SPECRAILS_DIR/commands/specrails/enrich.md  ← The /specrails:enrich command"
+    fi
+    echo "    .specrails/setup-templates/              ← Templates: commands + skills (temporary, removed after enrich)"
+    echo "    .specrails/specrails-version             ← Installed specrails version"
+    echo "    .specrails/specrails-manifest.json       ← Artifact checksums for update detection"
+    echo ""
+
+    echo -e "${BOLD}Prerequisites:${NC}"
+    echo ""
+    [ "$HAS_NPM" = true ]      && ok "npm"        || warn "npm (optional)"
+    [ "$HAS_OPENSPEC" = true ]  && ok "OpenSpec"    || warn "OpenSpec (optional)"
+    [ "$HAS_GH" = true ]        && ok "GitHub CLI"  || warn "GitHub CLI (optional, for GitHub Issues backlog)"
+    [ "$HAS_JIRA" = true ]      && ok "JIRA CLI"    || info "JIRA CLI not found (optional, for JIRA backlog)"
+    echo ""
+
+    echo -e "${BOLD}${CYAN}Next steps:${NC}"
+    echo ""
+    echo "  1. Open $CLI_PROVIDER in this repo:"
+    echo ""
+    echo -e "     ${BOLD}cd $REPO_ROOT && $CLI_PROVIDER${NC}"
+    echo ""
+    echo "  2. Run the enrich wizard:"
+    echo ""
+    if [[ "$CLI_PROVIDER" == "codex" ]]; then
+        echo -e "     ${BOLD}\$enrich${NC}"
+    else
+        echo -e "     ${BOLD}/specrails:enrich${NC}"
+    fi
+    echo ""
+    if [[ "$CLI_PROVIDER" == "codex" ]]; then
+        echo "  Codex will analyze your codebase, ask about your users,"
+    else
+        echo "  Claude will analyze your codebase, ask about your users,"
+    fi
+    echo "  research the competitive landscape, and generate all agents,"
+    echo "  commands, rules, and personas adapted to your project."
+    echo ""
 fi
-echo "  research the competitive landscape, and generate all agents,"
-echo "  commands, rules, and personas adapted to your project."
-echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"

package/templates/commands/specrails/propose-spec.md

@@ -49,6 +49,8 @@ Output ONLY the following structured markdown. Do not add any preamble or explan
 
 After generating the proposal, read `.specrails/backlog-config.json` to determine `BACKLOG_PROVIDER` and `BACKLOG_WRITE`.
 
+If `.specrails/backlog-config.json` does not exist, default to `provider=local` and `write_access=true`. Initialize `.specrails/local-tickets.json` if it does not exist (empty store with `schema_version: "1.0"`, `revision: 0`, `next_id: 1`, `tickets: {}`).
+
 ### If provider=local — Create Local Ticket
 
 Create a local ticket from the proposal output: