install: default jj setup in one-click flow

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

@@ -0,0 +1,188 @@
+# 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
+```