devops-skills/skills/gitea-issue-devops-agent/references/jj-default-usage.md

Jj Default Installation and Usage

This repository installs the gitea-issue-devops-agent skill first, then attempts to install jj by default.

jj is the internal execution layer for agent reliability. Git branches, PRs, CI/CD pipelines, and merge approvals remain the external system of record.

Default Install Strategy

The one-command installers now behave like this:

1. Install the skill into the target Codex directory.
2. Check whether jj is already available.
3. If not, try OS-specific install methods.
4. If all methods fail, keep the skill installed and print manual fallback instructions.

OS-Specific Attempt Order

Linux

• brew install jj
• cargo binstall --strategies crate-meta-data jj-cli
• cargo install --locked --bin jj jj-cli

For prerelease:

• cargo install --git https://github.com/jj-vcs/jj.git --locked --bin jj jj-cli

macOS

• brew install jj
• cargo binstall --strategies crate-meta-data jj-cli
• cargo install --locked --bin jj jj-cli

For prerelease:

• cargo install --git https://github.com/jj-vcs/jj.git --locked --bin jj jj-cli

Windows

• winget install jj-vcs.jj
• scoop install main/jj
• cargo install --locked --bin jj jj-cli

For prerelease:

• cargo install --git https://github.com/jj-vcs/jj.git --locked --bin jj jj-cli

Installer Controls

Bash installers

• INSTALL_JJ=0: skip jj installation
• JJ_INSTALL_METHOD=auto|brew|binstall|cargo
• JJ_CHANNEL=release|prerelease

Example:

INSTALL_JJ=0 curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash

JJ_INSTALL_METHOD=cargo JJ_CHANNEL=prerelease curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash

PowerShell installers

With the one-liner, prefer environment variables:

• $env:INSTALL_JJ='0'
• $env:JJ_INSTALL_METHOD='auto'|'winget'|'scoop'|'cargo'
• $env:JJ_CHANNEL='release'|'prerelease'

Example:

$env:JJ_INSTALL_METHOD='winget'
iwr -useb https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.ps1 | iex

$env:INSTALL_JJ='0'
iwr -useb https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.ps1 | iex

If you save the script locally first, you can also use the -SkipJj, -JjInstallMethod, and -JjChannel parameters directly.

Verification

After installation:

jj --version

Set identity:

jj config set --user user.name "Your Name"
jj config set --user user.email "you@example.com"

Optional shell completion:

source <(jj util completion bash)

PowerShell completion:

jj util completion power-shell | Out-String | Invoke-Expression

Working Model

Use jj as an internal operator tool:

• issue selection, branch naming, PR creation, CI, and merge stay Git/Gitea-native
• jj handles local history rewrites, workspace isolation, and recovery
• each issue branch can map to one jj bookmark

Scenario Examples

1) First-Time Team Setup

1. Run the one-command installer.
2. Verify jj --version.
3. Configure user.name and user.email.
4. Start with one fixed issue in manual or semi-automatic mode.

Recommended when a team is new to AI-assisted delivery and wants controlled adoption.

2) Initial AI PR for a Bug

1. Human selects issue #48.
2. MajorAgent creates the plan.
3. Issue branch and draft PR are created.
4. SubAgent changes only the planned paths.
5. TestAgent validates build, targeted tests, and issue e2e.
6. Engineer reviews and refines before merge approval.

Recommended default flow for day-to-day bug fixing.

3) Semi-Automatic Review Flow

1. AI produces the initial draft PR.
2. Reviewer inspects the plan, diff scope, and evidence.
3. Engineer uses the AI coding tool for follow-up edits if needed.
4. Only after review approval does the branch enter preview-slot testing.

Recommended when engineering review must happen before environment allocation.

4) Human + TestAgent Parallel Verification with Workspaces

1. SubAgent works in the main issue workspace.
2. TestAgent creates a separate jj workspace for validation.
3. Human reviewer can create another workspace for white-box adjustments.
4. All three flows remain tied to the same issue branch and plan.

Recommended for larger issues where testing and code refinement happen in parallel.

5) Recovery After AI Drift

1. AI rewrites the change incorrectly or edits too broadly.
2. Engineer inspects jj op log.
3. Engineer uses jj undo, jj op revert, or jj op restore.
4. The issue branch and PR remain intact while local execution history is repaired.

Recommended when AI behavior is fast but unreliable and quick recovery matters.