# Junior Workflow

This project can use a local junior agent for bounded implementation tasks. The
main agent remains responsible for scope, architecture, review, verification,
commits, and pushes.

## Rules

- Run at most one junior agent process at a time.
- Do not run junior work in the main checkout. Use a dedicated git worktree.
- Give small implementation tasks with an example, exact files, and exact tests.
- Do not delegate architecture, compatibility policy, broad reviews, or release
  decisions.
- Do not let a junior touch external repositories outside the dedicated
  worktree.
- Treat junior output as a patch proposal. Review every diff before merging.
- Prefer `pi` for one-shot tasks because `--no-session` and `--tools` make the
  allowed surface explicit. Use `opencode` only as fallback.

## Worktree Loop

Create a worktree:

```bash
scripts/junior-worktree.sh <task-slug>
```

Run the junior from the printed worktree path:

```bash
cd "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>"
pi --no-session --tools read,edit,bash -p '<prompt from docs/junior-task-template.md>'
```

Review from the main checkout:

```bash
git -C "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>" status --short
git -C "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>" diff
```

If the patch is useful, apply it deliberately from the main checkout using
`git diff`, `git apply`, cherry-pick, or a manual patch. After review:

```bash
git worktree remove "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>"
git branch -D junior/<branch-name>
```

## Good Junior Tasks

- Add one unit test following an existing nearby test.
- Add one small reporter or output-format test after the implementation exists.
- Add support for one comment style in a generic/native tokenizer.
- Add or update a small fixture for one format.
- Port one small function from upstream when the target shape is already clear.
- Run `scripts/check-format.sh <format> <target>` and report exact output.

## Prompt Notes

- Prefer implementation or test tasks over broad read-only scouting. A scout
  prompt that is too procedural may produce a task plan instead of executing the
  checks.
- For read-only fact gathering, explicitly say: "Execute the checks now; do not
  write instructions or a plan."
- Keep fact-gathering prompts to exact files and exact commands. If there are
  many commands, give a shell loop instead of asking the junior to design one.
- Do not use junior output as evidence until the main agent verifies the exact
  commands or diff.

## Bad Junior Tasks

- Review a whole commit or subsystem.
- Decide whether compatibility is acceptable.
- Refactor detector/tokenizer architecture.
- Change generated format registry by hand.
- Touch multiple unrelated files.
- Run broad benchmarks or modify local third-party repositories.

## Review Checklist

- The diff only touches allowed files.
- The implementation follows an existing local pattern.
- Tests are exact enough to catch broken structure, not only `contains` checks.
- Commands in the report match commands actually run.
- `cargo fmt`, `cargo test`, and relevant scripts pass from the main checkout.
- Any accepted patch is committed by the main agent, not by the junior.
