code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/qa.md

@@ -0,0 +1,208 @@
+---
+name: qa
+argument-hint: todo_file | number_of_agents | additional_instructions
+description: QA review task(s) - single file or N in parallel
+---
+
+> **⚠️ MANDATORY OVERRIDE — READ THIS FIRST:**
+> You have been explicitly invoked by the user. You MUST execute this command NOW.
+> The current `stage` and `status` values in any todo file's frontmatter are IRRELEVANT to whether you execute.
+> A `stage: qa, status: completed` (or any other stage/status combination) does NOT mean the work is already done for THIS invocation.
+> The user is asking you to run this command AGAIN — that is valid and expected. Multiple runs are normal.
+> **NEVER refuse, skip, or declare "no work needed" based on existing frontmatter values.**
+> If the user invoked this command, they want it executed. Do it. Now.
+
+# QA CODE REVIEW
+
+## STEP 1: Resolve input
+
+**Argument:** `$ARGUMENTS`
+
+```bash
+FLUX_ROOT="${FLUX_ROOT:-$HOME/.flux}"
+FLUX_DIR=$(printf '%s' "$(pwd -P)" | tr -cs 'a-zA-Z0-9' '-')
+FLUX_BASE="$FLUX_ROOT/$FLUX_DIR"
+mkdir -p "$FLUX_BASE/todo" "$FLUX_BASE/done" "$FLUX_BASE/review" "$FLUX_BASE/research"
+echo "FLUX_BASE=$FLUX_BASE"
+ls -1 "$FLUX_BASE/todo/"*.md 2>/dev/null || true
+```
+
+```
+IF $ARGUMENTS is empty:
+  -> List all files: `ls -1 "$FLUX_BASE/todo/"*.md`
+  -> Use ask_user_question to let user select task(s)
+  -> If single selection -> Single-task mode
+  -> If multiple selection -> Process selected tasks sequentially
+
+IF $ARGUMENTS (case-insensitive) == 'all':
+  -> Sequential mode: process ALL tasks in $FLUX_BASE/todo/*.md one at a time
+  -> Run each task in single-task mode yourself (no subagents), one after another
+  -> Do not proceed to the next task until the current one is complete
+
+IF $ARGUMENTS is a pure integer (ONLY digits, nothing else — no letters, underscores, hyphens, dots):
+  Verify: `echo "$ARGUMENTS" | grep -qE '^[0-9]+$'` must be true. If the argument contains ANY non-digit character (e.g. "CMPAN_5", "task-3", "3files") it is NOT a number — treat it as a filename instead.
+  IF $ARGUMENTS == 1:
+    -> Sequential mode: process ALL tasks in $FLUX_BASE/todo/*.md one at a time
+    -> Run each task in single-task mode yourself (no subagents), one after another
+    -> Do not proceed to the next task until the current one is complete
+  ELSE:
+    -> Multi-task mode with $ARGUMENTS parallel sub-agents
+
+OTHERWISE (argument is a filename — including any argument that contains letters, underscores, hyphens, or dots):
+  -> Single-task mode for that file
+```
+
+**Path and suffix inference:**
+If `$ARGUMENTS` doesn't contain a `/`, prepend `$FLUX_BASE/todo/`
+If `$ARGUMENTS` doesn't contain `.md`, append `.md`
+Example: `NOTIFS` -> `$FLUX_BASE/todo/NOTIFS.md`
+
+---
+
+## SINGLE-TASK MODE
+
+## STEP 2: Mark as in-progress
+
+Update the task file's frontmatter:
+
+> If frontmatter (`---` … `---`) exists, replace `stage`, `status`, `updated`. If absent, prepend before first `#` heading.
+
+```yaml
+---
+stage: qa
+status: in-progress
+updated: <today's date and time, YYYY-MM-DD HH:MM>
+---
+```
+
+## STEP 3: Determine stack
+
+Act as an objective `$STACK` expert QA code reviewer.
+
+```bash
+FLUX_ROOT="${FLUX_ROOT:-$HOME/.flux}"
+FLUX_DIR=$(printf '%s' "$(pwd -P)" | tr -cs 'a-zA-Z0-9' '-')
+FLUX_BASE="$FLUX_ROOT/$FLUX_DIR"
+echo "FLUX_BASE=$FLUX_BASE"
+```
+
+If a file called `stack.env` exists at `$FLUX_BASE/stack.env`, read it and set `$STACK` from its contents. Otherwise, run the following detection script to determine `$STACK` and save it (this only ever runs the first time for this directory):
+
+```bash
+STACK="software"
+if [ -f "package.json" ]; then
+  STACK=$(bun -e "
+    const d=JSON.parse(require('fs').readFileSync('./package.json','utf8'));
+    const deps=Object.assign({}, d.dependencies, d.devDependencies, d.peerDependencies);
+    const frameworks=['ink','react','vue','angular','next','express'];
+    const fw=frameworks.find(f=>deps[f]);
+    const ts=deps['typescript']?'TypeScript':'JavaScript';
+    console.log(fw?fw+' + '+ts:ts);
+  " 2>/dev/null || echo "JavaScript/TypeScript")
+elif [ -f "Cargo.toml" ]; then STACK="Rust"
+elif [ -f "go.mod" ]; then STACK="Go"
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then STACK="Python"
+elif [ -f "pom.xml" ] || [ -f "build.gradle" ]; then STACK="Java/Kotlin"
+fi
+mkdir -p "$FLUX_BASE"
+echo "$STACK" > "$FLUX_BASE/stack.env"
+echo "Detected stack: $STACK (saved)"
+```
+
+## STEP 4: Review & verdict
+
+### 4.1 Rate the implementation
+
+Rate the implementation of `$ARGUMENTS` on a scale of 1–10. Cite full reasoning for your objective rating.
+
+- Allow for deviations that improve the code or correct imperfections in task requirements — if the implementation is BETTER than spec, that's a pass.
+- Do not literally interpret the task if the developer exceeded requirements.
+
+### 4.2 If 10/10 — mark complete and move to done
+
+> **⚠️ CRITICAL: `stage` MUST be the literal string `qa` — NEVER `done`.**
+
+1. Update frontmatter:
+   ```yaml
+   ---
+   stage: qa
+   status: completed
+   updated: <today's date and time, YYYY-MM-DD HH:MM>
+   ---
+   ```
+2. Read session timestamp and move to session subdirectory:
+   ```bash
+   SESSION_TS=$(grep '^SESSION_TS=' "$FLUX_BASE/session.env" 2>/dev/null | cut -d= -f2)
+   SESSION_TS="${SESSION_TS:-$(date +%Y-%m-%d-%H-%M)}"
+   mkdir -p "$FLUX_BASE/done/$SESSION_TS"
+   mv <task_file_path> "$FLUX_BASE/done/$SESSION_TS/"
+   ```
+
+### 4.3 If lacking IN ANY WAY NO MATTER HOW SMALL — mark needs-rework
+
+> **⚠️ CRITICAL: `stage` MUST be the literal string `qa` — NEVER `done`.**
+
+1. Update frontmatter:
+   ```yaml
+   ---
+   stage: qa
+   status: needs-rework
+   updated: <today's date and time, YYYY-MM-DD HH:MM>
+   ---
+   ```
+2. Update task file body: remove every item that is complete in production quality; focus on outstanding items with specific guidance on what needs to be resolved.
+3. Print the full filepath as the last line of output.
+
+**No git commands:**
+DO NOT USE `git` commands of any type. Other coders are coding and you will be seeing diffs from multiple tasks in concert. DO NOT `git stash`, `git diff`, or other methods. JUST READ THE FILES AS THEY EXIST. YOU WILL BE IMMEDIATELY FIRED if you use any `git` commands whatsoever.
+
+---
+
+## MULTI-TASK MODE
+
+Use the `invoke_agent` tool (subagents) to execute IN PARALLEL each task in `$FLUX_BASE/todo/*.md`.
+_NEVER_ run agents in the background. Always run them in the foreground.
+
+**Before spawning any subagents**, update all target task files' frontmatter:
+
+```yaml
+---
+stage: qa
+status: in-progress
+updated: <today's date and time, YYYY-MM-DD HH:MM>
+---
+```
+
+Each subagent updates its own file's frontmatter to `completed` or `needs-rework` upon completion.
+
+**Task selection:**
+
+- Identify `$ARGUMENTS` task files to delegate in parallel (or fewer if fewer exist)
+- Manage `$ARGUMENTS` sub-agents at a time; spawn new subagents as initial ones complete; continue until all tasks in `$FLUX_BASE/todo/*.md` are reported complete
+
+### Subagent prompt template
+
+Prompt each subagent with the single-task mode steps above, substituting `{{absolute_file_path}}` for `$ARGUMENTS`. Include the stack detection snippet, `$FLUX_BASE` setup, and all constraints (no-git, review criteria).
+
+---
+
+## HARD CONSTRAINTS
+
+- **Path**: All file operations MUST use the exact `FLUX_BASE` value printed by the STEP 1 bash output (e.g. `FLUX_BASE=/Users/...`). Copy it character-for-character — never reconstruct it from `cwd` or memory.
+- `/flux/qa` is a **review-only** command. You MUST NOT write or modify any source files. The only permitted file operations are: updating the task file's frontmatter, updating the task file body to remove completed items, and moving the task file to `$FLUX_BASE/done/`. No git commands under any circumstances.
+
+## Propose next steps
+
+After QA completes, present the user with two options:
+
+**Option A — Continue PIPELINE A (fix regressions):**
+`/flux/tests` — run the test suite and fix regressions introduced by this branch before committing.
+
+**Option B — Start PIPELINE B (self-review your changes):**
+`/flux/review` → `/flux/address-feedback` → `/flux/ask all` → `/flux/exec` → `/flux/qa` → `/flux/commit`
+Start here to review your own changes before creating a PR.
+
+Valid `//flux` commands: `/flux/config`, `/flux/new`, `/flux/ask`, `/flux/split`, `/flux/aug`, `/flux/exec`, `/flux/qa`, `/flux/tests`, `/flux/commit`, `/flux/create-pr`, `/flux/review`, `/flux/address-feedback`, `/flux/status`, `/flux/auto-pilot`, `/flux/rebase`. Do NOT suggest any command not on this list.
+
+=================
+$ARGUMENTS

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/rebase.md

@@ -0,0 +1,180 @@
+---
+name: rebase
+description: Rebase branch onto latest default branch, preserving individual commits
+---
+
+# REBASE ONTO LATEST DEFAULT BRANCH
+
+Replays your branch commits on top of the latest default branch, preserving each commit individually.
+
+**Example:** 3 commits on `luc/new-feature` + 10 new commits on `main` (or `master`/`develop`) → your 3 commits replayed on top of those 10.
+
+## STEP 1: Capture current state
+
+```bash
+BRANCH=$(git branch --show-current)
+TICKET=$(echo "$BRANCH" | grep -oE ‘[A-Z]+-[0-9]+’ | head -1 || echo "")
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq ‘.defaultBranchRef.name’ 2>/dev/null || echo "main")
+echo "BRANCH: $BRANCH"
+echo "TICKET: $TICKET"
+echo "DEFAULT_BRANCH: $DEFAULT_BRANCH"
+
+# Commits on our branch (will be replayed)
+git log "$DEFAULT_BRANCH"..HEAD --oneline
+
+# Files we touch
+git diff "$DEFAULT_BRANCH" --stat
+```
+
+Record: the commit list and changed files. Used for verification after the rebase.
+
+**Gotcha:** If `BRANCH` is empty or `HEAD` (detached HEAD), stop and tell the user to checkout a real feature branch before rebasing.
+
+## STEP 2: Working tree must be clean
+
+```bash
+git status --porcelain
+```
+
+If there is **any** output (staged or unstaged changes, untracked files you care about):
+
+`ask_user_question` — question: "Your working tree is not clean. Rebase requires a clean tree (or stashed work). How do you want to proceed?" / header: "Unclean working tree" / options:
+
+- `Stash changes and continue` → run `git stash push -u -m "myproj-flux-rebase-wip"`. Set an internal flag that a stash was created — STEP 9 will offer to pop it.
+- `Abort` → stop. Do not rebase.
+
+If the tree is already clean, continue to STEP 3.
+
+## STEP 3: Sync local default branch with origin
+
+```bash
+git fetch origin "$DEFAULT_BRANCH":"$DEFAULT_BRANCH"
+```
+
+> If this fails because the local branch has diverged from origin, use `git fetch origin "$DEFAULT_BRANCH":"$DEFAULT_BRANCH" --force`.
+> ⚠️ `--force` overwrites your local branch — only safe if you never commit directly to `$DEFAULT_BRANCH`.
+
+**Gotcha:** If `$DEFAULT_BRANCH` does not exist locally yet, use `git fetch origin "$DEFAULT_BRANCH"` and ensure you have a local branch tracking `origin/$DEFAULT_BRANCH` (e.g. `git branch -u "origin/$DEFAULT_BRANCH" "$DEFAULT_BRANCH"` once) before relying on the `branch:branch` refspec.
+
+## STEP 4: Identify potential conflicts (high-risk files)
+
+Overlap of “files changed on `$DEFAULT_BRANCH` since the merge base” and “files changed on your branch” flags **likely** conflict hotspots — not a guarantee (conflicts can appear elsewhere; some overlaps merge cleanly).
+
+```bash
+# Files changed on default branch since our branch diverged
+git diff --name-only HEAD...”$DEFAULT_BRANCH”
+
+# Files changed on our branch
+git diff --name-only “$DEFAULT_BRANCH”..HEAD
+```
+
+For any file appearing in **both** lists: read both sides to understand intent before rebasing.
+
+## STEP 5: Rebase onto default branch
+
+```bash
+git rebase "$DEFAULT_BRANCH"
+```
+
+Git will replay each of your commits one at a time onto the tip of `$DEFAULT_BRANCH`. If there are no conflicts, this completes automatically and you can skip to STEP 7.
+
+## STEP 6: Resolve conflicts (if any — repeat per commit)
+
+During rebase, Git pauses at each commit that conflicts. For each pause:
+
+```bash
+git status
+git diff --name-only --diff-filter=U
+```
+
+Use `git status` as the source of truth (including renames and unmerged paths that are not plain “both modified”).
+
+### Resolution principles
+
+- Aim for a result that matches the **intent of the commit being replayed** and is **consistent with current `$DEFAULT_BRANCH`**. Do not drop the other side’s changes without a clear reason (e.g. `$DEFAULT_BRANCH` removed deprecated code — follow that removal if correct).
+- Every unmerged path must reach a resolved state and be **staged** (`git add` / `git rm` as appropriate) before `git rebase --continue`.
+
+### By scenario (add a line or two of reasoning in your summary when non-trivial)
+
+| Scenario                                                            | What to do                                                                                                                                                     |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Text / conflict markers**                                         | Edit the file, remove `<<<<<<<`, `=======`, `>>>>>>>`, then `git add <file>`.                                                                                  |
+| **Modify/delete** — one side changed the file, the other deleted it | Decide keep file (possibly with merged content) vs delete. Keeping: fix content then `git add <file>`. Deleting: `git rm <file>`.                              |
+| **Binary or generated files** (no usable markers)                   | Choose one side or regenerate: e.g. `git checkout --ours -- <file>` or `git checkout --theirs -- <file>`, or replace the file manually, then `git add <file>`. |
+| **Rename / complex unmerged states**                                | Follow `git status` paths; use `git add` on the correct final path after resolving.                                                                            |
+| **Submodules**                                                      | Do not guess: use submodule workflow (`git submodule status`, update pointer as intended, `git add` submodule path) or stop and ask the user.                  |
+
+### If `git rebase --continue` fails
+
+- Grep or search for leftover `<<<<<<<` / conflict markers.
+- Run `git diff --check` for whitespace or conflict artifacts.
+- Ensure **all** previously unmerged files are staged; unstaged resolutions block continue.
+
+### Empty commits after resolution
+
+If Git says the commit is now empty: **`git rebase --skip`** only when you are sure the replayed change is fully redundant (e.g. identical patch already on `$DEFAULT_BRANCH`). Skipping drops a commit — default to investigating rather than skipping blindly.
+
+> Abort at any time: `git rebase --abort` (restores pre-rebase state; does not restore an unstashed stash — your stash from STEP 2 remains).
+
+## STEP 7: Verify — history and files
+
+```bash
+# Commits on top of default branch (see note below on count)
+git log "$DEFAULT_BRANCH"..HEAD --oneline
+
+# Changed files vs default branch — should reflect your work (paths may shift if trees moved)
+git diff "$DEFAULT_BRANCH" --stat
+```
+
+**Commit count:** Expect the **same number of commits** as in STEP 1 only if your branch was **linear** (no merge commits you introduced). If you had merge commits from `$DEFAULT_BRANCH` into the branch, the replayed count can differ — compare **content** (`git diff "$DEFAULT_BRANCH" --stat`, behavior) rather than count alone.
+
+Confirm history and diffs match expectations (no dropped features). If changes are missing — investigate before pushing.
+
+## STEP 8: Confirm push (ask_user_question)
+
+After a rebase, commit hashes differ from any previous push of the same branch. Choose the right push: first-time upstream vs `--force-with-lease` when the branch already exists on the remote.
+
+```bash
+git rev-parse @{u} >/dev/null 2>&1 && echo HAS_UPSTREAM || echo NO_UPSTREAM
+```
+
+- **`NO_UPSTREAM`** (first push of this branch): `ask_user_question` — question: "Rebase is complete and verified. Push this branch and set upstream with `git push -u origin \"$BRANCH\"`? (No force needed.)" / header: "Push branch" / options: `Yes, push now` | `No, I'll push manually later`
+
+  - Yes → `git push -u origin "$BRANCH"`
+  - No → skip push; say so in STEP 9.
+
+- **`HAS_UPSTREAM`**: `ask_user_question` — question: "Rebase rewrote history. Push with `git push --force-with-lease origin \"$BRANCH\"`? Refuses if someone else pushed in the meantime. Only do this for your own feature branch — never `$DEFAULT_BRANCH`." / header: "Push rebased branch" / options: `Yes, force-with-lease now` | `No, I'll push manually later`
+  - Yes → `git push --force-with-lease origin "$BRANCH"`
+  - No → skip push; say so in STEP 9.
+
+If `--force-with-lease` fails because the remote moved, run `git fetch origin`, re-evaluate (and re-ask if appropriate), then retry.
+
+**Gotcha:** `--force-with-lease` can still fail if the remote branch was deleted/recreated or the ref lease is stale — fetch and understand remote state before forcing.
+
+> ⚠️ Never `git push --force` without lease, and never force-push `$DEFAULT_BRANCH` (see HARD CONSTRAINT).
+
+## STEP 9: Summarize
+
+Report:
+
+- `$TICKET` (if any) and `$BRANCH`
+- Original commits from STEP 1 vs final `git log "$DEFAULT_BRANCH"..HEAD --oneline` (note if merge commits made counts differ)
+- How many commits from `$DEFAULT_BRANCH` were incorporated under you
+- Conflicts: how many stops, which files, any modify/delete/binary/submodule cases
+- Push: done vs deferred by user choice
+- If STEP 2 stashed: use `ask_user_question` — question: "You stashed changes before the rebase. Do you want to pop the stash now?" / header: "Restore stash" / options: `Yes, pop stash now` | `No, I'll pop it manually later`
+  - Yes → run `git stash pop`. If it produces conflicts, list the conflicted files and instruct the user to resolve them manually (`git add <file>` after editing, then `git stash drop` once done — do NOT run `git stash pop` again).
+  - No → remind the user to run `git stash pop` manually when ready.
+
+## HARD CONSTRAINT
+
+`/flux/rebase` MUST NOT squash or modify commit content except as required for conflict resolution during `git rebase --continue`. MUST NOT commit to `$DEFAULT_BRANCH`. MUST NOT use `git push --force` (use `--force-with-lease` when updating an existing remote branch). The only permitted history edits are the rebase itself and conflict resolutions in STEP 6.
+
+## Propose next step
+
+Then propose the next step: `/flux/create-pr` (include arguments if needed).
+
+Valid `//flux` commands: `/flux/config`, `/flux/new`, `/flux/ask`, `/flux/split`, `/flux/aug`, `/flux/exec`, `/flux/qa`, `/flux/tests`, `/flux/commit`, `/flux/create-pr`, `/flux/review`, `/flux/address-feedback`, `/flux/status`, `/flux/auto-pilot`, `/flux/rebase`. Do NOT suggest any command not on this list.
+
+=================
+$ARGUMENTS