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:

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:

git push origin main