install: default jj setup in one-click flow

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

@@ -0,0 +1,170 @@
+# 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:
+
+```bash
+INSTALL_JJ=0 curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash
+```
+
+```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:
+
+```powershell
+$env:JJ_INSTALL_METHOD='winget'
+iwr -useb https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.ps1 | iex
+```
+
+```powershell
+$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:
+
+```bash
+jj --version
+```
+
+Set identity:
+
+```bash
+jj config set --user user.name "Your Name"
+jj config set --user user.email "you@example.com"
+```
+
+Optional shell completion:
+
+```bash
+source <(jj util completion bash)
+```
+
+PowerShell completion:
+
+```powershell
+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.