devops-skills/docs/superpowers/plans/2026-03-13-jj-default-installation-plan.md

# Jj Default Installation Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make `jj` a default installation target in this repository's one-command installers without making installer success depend on `jj` success, and expand documentation with clearer usage instructions and scenario-based examples.

**Architecture:** Keep the public installer entrypoints unchanged while adding an internal second phase that attempts platform-appropriate `jj` installation. Preserve deterministic skill installation first, then run best-effort `jj` installation with explicit verification and manual fallback instructions.

**Tech Stack:** Bash, PowerShell, Git, README Markdown, skill reference docs

---

## Chunk 1: Installer Behavior

### Task 1: Add plan-aware installer controls to the Bash installer

**Files:**
- Modify: `install/install.sh`
- Test: `install/install.sh` syntax via `bash -n`

- [ ] **Step 1: Define installer controls**

Add environment-driven controls near the top of `install/install.sh`:
- `INSTALL_JJ` default `1`
- `JJ_INSTALL_METHOD` default `auto`
- `JJ_CHANNEL` default `release`

- [ ] **Step 2: Add `jj` install attempt helpers**

Implement focused functions for:
- logging
- command existence checks
- `brew` install path
- `cargo-binstall` install path
- `cargo install` fallback path
- manual fallback message

- [ ] **Step 3: Add OS-aware default attempt flow**

Implement this order:
- macOS: `brew`, then `cargo-binstall`, then `cargo`
- Linux: `brew` if available, then `cargo-binstall`, then `cargo`

- [ ] **Step 4: Keep skill installation authoritative**

Ensure the script:
- installs the skill first
- attempts `jj` only after the skill copy succeeds
- never exits non-zero only because `jj` failed

- [ ] **Step 5: Verify shell syntax**

Run: `bash -n install/install.sh`
Expected: no output, zero exit code

### Task 2: Add plan-aware installer controls to the PowerShell installer

**Files:**
- Modify: `install/install.ps1`
- Test: `install/install.ps1` parse check via PowerShell

- [ ] **Step 1: Define parameters and defaults**

Add parameters:
- `SkipJj`
- `JjInstallMethod = "auto"`
- `JjChannel = "release"`

- [ ] **Step 2: Add `jj` install attempt helpers**

Implement functions for:
- logging
- command existence checks
- `winget` install path
- `scoop` install path
- `cargo install` fallback path
- manual fallback message

- [ ] **Step 3: Add Windows attempt flow**

Implement this order:
- `winget`
- `scoop`
- `cargo`

- [ ] **Step 4: Keep installer non-blocking for `jj`**

Ensure skill installation still succeeds even if all `jj` attempts fail.

- [ ] **Step 5: Verify script parses**

Run: `powershell -NoProfile -Command "[void][scriptblock]::Create((Get-Content -Raw 'install/install.ps1'))"`
Expected: no output, zero exit code

## Chunk 2: Documentation

### Task 3: Expand README installation and usage guidance

**Files:**
- Modify: `README.md`

- [ ] **Step 1: Update one-command install sections**

Document that installers now:
- install the skill
- attempt `jj` by default
- continue with warnings if `jj` cannot be installed automatically

- [ ] **Step 2: Add installer controls and verification**

Document:
- `INSTALL_JJ=0`
- `JJ_INSTALL_METHOD`
- `JJ_CHANNEL`
- PowerShell equivalents
- `jj --version`
- initial `jj config` commands

- [ ] **Step 3: Add richer scenario examples**

Include examples for:
- first-time team setup
- automatic bug fix flow
- semi-automatic engineering review flow
- manual hotfix flow
- multi-agent flow with `jj` workspaces

### Task 4: Add detailed `jj` usage guide

**Files:**
- Create: `skills/gitea-issue-devops-agent/references/jj-default-usage.md`

- [ ] **Step 1: Explain repository policy**

Document:
- `jj` is default to install
- `jj` is internal execution infrastructure
- Git branches/PRs/CI remain public system of record

- [ ] **Step 2: Explain verification and fallback**

Document:
- how to verify installation
- how to skip or force methods
- what to do when package managers are unavailable

- [ ] **Step 3: Add workflow examples**

Provide concrete examples for:
- issue -> plan -> draft PR
- engineer review after initial AI PR
- `jj workspace` for TestAgent and human reviewer
- rollback with operation log

## Chunk 3: Verification and Delivery

### Task 5: Verify, commit, and push

**Files:**
- Modify: repo index and git history

- [ ] **Step 1: Run syntax checks**

Run:
- `bash -n install/install.sh`
- `powershell -NoProfile -Command "[void][scriptblock]::Create((Get-Content -Raw 'install/install.ps1'))"`

Expected: both succeed

- [ ] **Step 2: Review diff**

Run: `git diff --check`
Expected: no diff formatting errors

- [ ] **Step 3: Commit**

Run:
```bash
git add README.md install/install.sh install/install.ps1 docs/superpowers/plans/2026-03-13-jj-default-installation-plan.md skills/gitea-issue-devops-agent/references/jj-default-usage.md
git commit -m "docs: default jj installation in installers"
```

- [ ] **Step 4: Push**

Run:
```bash
git push origin main
```