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

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/_docs/README.md

@@ -0,0 +1,173 @@
+# 𝕱 Flux Workflow System
+
+Read the full story [here](https://github.com/mpfaffenberger/code_puppy/blob/main/docs/FLUX.md)
+
+Here is the TL;DR
+
+A structured, AI-assisted development pipeline organized around **task files** stored in `~/.flux/<flattened-dir>/todo/`.
+Every command guides you through one stage of the lifecycle, with each step proposing the next.
+
+Naming: throughout the docs and command .md files the term 'task' and 'task-file' are used interchangeably.
+They both mean: an .md file in the flux todo directory (`~/.flux/<flattened-dir>/todo`)
+
+---
+
+## First-Time Setup (optional)
+
+```
+/flux/config
+```
+
+This sets up the flux `config.env` file (at `~/.flux/<flattened-dir>/config.env`) with your project's test command.
+
+**NOTE**: config.env is only used by the 'tests' command. If you don't plan to use it, you can skip flux/config and start directly with flux/new
+
+> **Flux root directory:** `~/.flux/<flattened-dir>/`. All task files, review files, and config are stored under the root automatically.
+
+## The Core Pipeline
+
+```
+new -> ask -> split -> aug -> exec -> qa -> tests -> commit -> create-pr
+```
+
+| Step | Command                          | What happens                                                                                                                                                                              |
+| ---- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | /flux/new <prompt\|Jira ticket> | Creates a task `.md` file in the flux todo directory from your description or Jira ticket                                                                                                 |
+| 2    | /flux/ask <task-file\|all>      | Asks clarifying questions (one at a time), researches the codebase, then **augments** the task file                                                                                            |
+| 3    | /flux/split <task-file>         | Splits a large task into multiple focused subtask files. Deletes the original.                                                                                                            |
+| 4    | /flux/aug <task-file\|N\|all>   | Deep research pass - explores source files, finds existing code, enriches task file(s) with citations                                                                                     |
+| 5    | /flux/exec <task-file\|N\|all>  | Faithfully implements exactly what the task says. No scope creep.                                                                                                                         |
+| 6    | /flux/qa <task-file\|N\|all>    | Rates implementation 1-10. If 10/10 -> moves the task file to `done`. If <10 -> refines remaining gaps                                                                                    |
+| 7    | /flux/tests                     | Runs the test suite. Fixes regressions introduced by this branch. Leaves pre-existing failures untouched. If you want those also fixed, you can specify that as 'additional-instructions' |
+| 8    | /flux/commit                    | Diffs vs previous commit, creates a detailed commit message, asks for confirmation, commits (no push)                                                                                     |
+| 9    | /flux/create-pr                 | Creates a GitHub Pull Request from the current branch. Derives title from branch name. Idempotent: shows existing PR if one already exists.                                               |
+
+> **QA loop**: If `qa` doesn't score 10/10, run `exec` again on the updated file, then `qa` again. Repeat until the file is marked 10/10 and is deleted.
+
+---
+
+## Unified Commands
+
+The `aug`, `exec`, and `qa` commands support **both single-task and multi-task** modes through argument detection:
+
+| Argument Type              | Mode        | Behavior                                                                                           |
+| -------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| Filename (e.g., NOTIFS.md) | Single-task | Process one specific task file                                                                     |
+| Number (e.g., 2, 3, 5)     | Multi-task  | Spawn N sub-agents in parallel                                                                     |
+| 'all'                      | Single-task | Process all task files sequentially
+| (empty)                    | Interactive | Prompt user to select task(s) from the list found in the flux todo directory via `ask_user_question` |
+
+**Examples:**
+
+```
+/flux/aug NOTIFS.md      # Augment single task
+/flux/aug 2              # Augment all tasks, 2 agents in parallel
+/flux/aug all            # Augment all tasks sequentially
+/flux/aug                # Show selection prompt
+
+/flux/exec DEV_1.md      # Execute single task
+/flux/exec 3             # Execute all tasks, 3 agents in parallel
+/flux/exec all           # Execute all tasks sequentially
+/flux/exec               # Show selection prompt
+
+/flux/qa FEATURE.md      # QA single task
+/flux/qa 2               # QA all tasks, 2 agents in parallel
+/flux/qa all             # QA all tasks sequentially
+/flux/qa                 # Show selection prompt
+```
+
+---
+
+## Utility Commands
+
+| Command                       | What it does                                                                                                                                                                                                                       |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| /flux/config                 | (optional) Creates or updates the flux `config.env` with project-specific settings (the test command used by /flux/tests). Run once per project before using the Flux suite.                 |
+| /flux/review [PR#]           | Full code review of changes vs parent branch. Optionally accepts PR number for automatic branch detection and PR commenting.                                                                                                       |
+| /flux/address-feedback [zip] | Convert existing review files (present in the flux review folder) into todo tasks. Accepts optional zip file path for reviews received from others.                                                                                |
+| /flux/rebase                 | Rebase the current branch onto latest main, preserving individual commits. Handles clean-tree check, conflict resolution, and force-with-lease push.                                                                               |
+| /flux/squash-commits         | Squash all unmerged commits on the current branch into one. Checks clean tree (with stash option), detects remote out-of-sync, and offers force-with-lease push.                                                                   |
+| /flux/auto-pilot             | Orchestrate the full PIPELINE A end-to-end from a single prompt, spec file, or Jira ticket. Pauses only during `/flux/ask`.                                                                                                       |
+
+---
+
+## Pipelines
+
+### PIPELINE A - New feature / bug fix
+
+```
+1. /flux/new <prompt>
+2. /flux/ask <task-file>
+3. /flux/split <task-file>
+4. /flux/aug 2
+5. /flux/exec 2
+6. /flux/qa 2
+7. /flux/tests
+8. /flux/commit
+9. the agent asks the user to test the changes and proposes next step: /flux/create-pr
+```
+
+### PIPELINE B - Code review (your own changes)
+
+```
+1. /flux/review
+2. /flux/address-feedback
+3. /flux/ask all
+4. /flux/exec 2
+5. /flux/qa 2
+6. /flux/tests
+7. /flux/commit
+```
+
+> **Note:** Depending on the number of changes, you may want to process `critical` tasks one by one.
+
+### PIPELINE C - Code review received on your PR
+
+```
+1. /flux/address-feedback ~/Desktop/review.zip
+2. /flux/ask all
+3. /flux/exec 2
+4. /flux/qa 2
+5. /flux/tests
+6. /flux/commit
+```
+
+---
+
+## Key Design Principles
+
+- **Task files are the source of truth** - never modify them during `exec` or `qa`; only `qa` can edit/delete them
+- **No tests, no benchmarks** - explicitly excluded; they are handled separately (/flux/tests)
+- **No git commands** during `exec`/`qa` - other agents may be working concurrently
+- **Steps always propose the next step** - each command ends by suggesting what to run next with the right arguments
+- **task-file path and extension is inferred** - when passing a task-file as argument, the name with no suffix is sufficient
+  e.g. instead of `/flux/aug <flux-todo-dir>/TASK_1.md` you can just do `/flux/aug TASK_1`
+
+## APPENDIX
+
+- Examples of config.env file:
+
+```
+TEST_CMD=bun run lint && bun run test:quiet
+```
+
+```
+TEST_CMD=uv run ruff check . && uv run pytest -q --no-cov
+```
+
+- Examples of stack.env file:
+
+This is used by `aug`, `exec`, `qa`, `review`. 
+If absent, the agent runs a detection script and writes it (first-run per directory).
+
+```
+pydantic.ai + Python
+```
+
+```
+Ink + Typescript
+```
+
+```
+fastAPI + Python
+```

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/_docs/cheatsheet.md

@@ -0,0 +1,86 @@
+# //flux Cheatsheet
+
+## FIRST-TIME SETUP (run once per project) - optional
+
+```
+/flux/config TEST_CMD=<your-test-command-for-this-project>
+```
+
+Sets up the flux `config.env` (`~/.flux/<flattened-dir>/config.env`) with your test command.
+Required before using the //flux suite on a new repo.
+
+> **Tip:** `TEST_CMD` supports chaining — e.g. `bun run lint && bun run test:quiet`
+
+---
+
+## ON MY BRANCH
+
+### PIPELINE A:
+
+New ticket, feature, bug fix
+
+#### MANUAL
+
+1. /flux/new <task-description | Jira ticket>
+2. /flux/ask <task-file | all>
+3. /flux/split <task-file>
+4. /flux/aug <task-file> or /flux/aug <N> or /flux/aug all
+5. /flux/exec <task-file> or /flux/exec <N> or /flux/exec all
+6. /flux/qa <task-file> or /flux/qa <N> or /flux/exec all
+7. /flux/tests
+8. /flux/commit
+9. test changes (build and run the application)
+10. /flux/create-pr
+
+#### AUTO-PILOT
+
+1. /flux/auto-pilot <task-description | Jira ticket> 
+
+### PIPELINE B:
+
+Review my own changes
+
+1. /flux/review
+2. /flux/address-feedback
+3. /flux/ask all
+4. /flux/exec 2
+5. /flux/qa 2
+6. /flux/commit
+
+### PIPELINE C:
+
+Address review received from a PR reviewer
+
+1. /flux/address-feedback ~/Desktop/review.zip
+2. /flux/ask all
+3. /flux/exec 2
+4. /flux/qa 2
+5. /flux/commit
+
+### PIPELINE D:
+
+Review someone else's PR
+
+1. /flux/review <PR#> OR
+   /flux/review (if you are in the checked out PR branch)
+2. Share the zip file created (e.g. `~/.flux/<flattened-dir>/review.zip`) with PR author (post on the PR, Slack, etc.)
+
+## Quick Reference
+
+| Task                 | Command                                            |
+| -------------------- | -------------------------------------------------- |
+| Project setup        | /flux/config                                       |
+| Create task          | /flux/new <description or JIRA-ID>                 |
+| Clarify requirements | /flux/ask <task-file\|'all'>                       |
+| Break down task      | /flux/split <task-file>                            |
+| Research & augment   | /flux/aug <task-file\|N\|'all'>                    |
+| Execute task(s)      | /flux/exec <task-file\|N\|'all'>                   |
+| QA review            | /flux/qa <task-file\|N\|'all'>                     |
+| Fix test regressions | /flux/tests                                        |
+| Commit changes       | /flux/commit                                       |
+| Create a PR          | /flux/create-pr                                    |
+| Code review          | /flux/review [PR#]                                 |
+| Process feedback     | /flux/address-feedback [zipfile]                   |
+| Rebase onto main     | /flux/rebase                                       |
+| Squash commits       | /flux/squash-commits                               |
+| Full pipeline        | /flux/auto-pilot <prompt \| task-file \| JIRA-ID>  |

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/_docs/pipeline.md

@@ -0,0 +1,167 @@
+# Core Pipeline
+
+## One Time Setup (optional)
+
+**Run once per project or github worktree**
+
+```
+/flux/config TEST_CMD=<your-test-command-for-this-project>
+```
+
+Configures the flux `config.env` (`~/.flux/<flattened-dir>/config.env`) with your test command.
+
+> **Tip:** `TEST_CMD` can chain lint and tests. Example: `bun run lint && bun run test:quiet`
+
+---
+
+## Available Commands
+
+| Command                             | What it does                                                                            |
+| ----------------------------------- | --------------------------------------------------------------------------------------- |
+| /flux/config TEST_CMD=<test-cmd>    | (optional) — configure project settings in the flux `config.env`                        |
+| /flux/new <prompt\|Jira tkt>        | Create a new task file in the flux todo directory                                       |
+| /flux/ask <task-file\|all>          | Clarify requirements via structured questions, then augment the spec                    |
+| /flux/split <task-file\|all>        | Break a large task into focused, single-session subtask files                           |
+| /flux/aug <task-file\|N\|all>       | Research codebase and enrich task file(s) with detail and citations                     |
+| /flux/exec <task-file\|N\|all>      | Execute task(s) exactly as written                                                      |
+| /flux/qa <task-file\|N\|all>        | Code review - rate 1-10, delete if perfect, refine if not                               |
+| /flux/tests                         | Run test suite, fix regressions introduced by this branch, leave pre-existing untouched |
+| /flux/commit                        | Stage and commit with Jira ID from branch name                                          |
+| /flux/create-pr                     | Create a GitHub PR for the current branch, or show existing PR URL and status           |
+| /flux/review [<pr-number>]          | Full code review of changed files with severity ratings                                 |
+| /flux/address-feedback [<zipfile>]  | Convert review files into todo task files                                               |
+| /flux/auto-pilot <prompt\|Jira tkt> | Orchestrate full PIPELINE A end-to-end from a prompt, spec file, or Jira ticket         |
+| /flux/rebase                        | Rebase the current branch onto latest main, preserving individual commits               |
+| /flux/squash-commits                | Squash all commits on the current branch into one                                       |
+
+### Unified Commands
+
+The `aug`, `exec`, and `qa` commands are **unified** - they detect argument type automatically:
+
+| Argument   | Mode        | Behavior                                                    |
+| ---------- | ----------- | ----------------------------------------------------------- |
+| task-file  | Single-task | Process one specific task file, path and extension inferred |
+| N (number) | Multi-task  | Spawn N sub-agents in parallel                              |
+| 'all'      | Single-task | Process all task files sequentially                         |
+| (empty)    | Interactive | Prompt user to select task(s)                               |
+
+**Examples:**
+
+- /flux/exec NOTIFS - Execute single task
+- /flux/exec 3 - Execute all tasks, 3 agents in parallel
+- /flux/exec all - Execute all tasks, sequentially
+- /flux/exec - Show task selection prompt
+
+## PIPELINE A:
+
+---
+
+New ticket, feature, or bug fix
+
+```
+/flux/new
+ -> /flux/ask
+  -> /flux/split
+   -> /flux/aug
+    -> /flux/exec
+     -> /flux/qa
+      -> /flux/tests
+       -> /flux/commit
+        -> run the app, test the changes
+         -> /flux/create-pr
+```
+
+---
+
+**Example**
+
+- /flux/new "Add real-time notifications"
+- /flux/ask NOTIFS
+- /flux/split NOTIFS
+- /flux/aug 2 (augment all tasks, 2 agents)
+- /flux/exec 2 (execute all tasks, 2 agents)
+- /flux/qa all (QA all tasks, sequentially)
+- /flux/tests
+- /flux/commit
+- the agent asks you to test the changes and proposes next step: /flux/create-pr
+
+## PIPELINE B:
+
+---
+
+Review my own changes on the current branch
+
+```
+/flux/review
+ -> /flux/address-feedback
+  -> /flux/ask
+   -> /flux/exec
+    -> /flux/qa
+     -> /flux/tests
+      -> /flux/commit
+```
+
+---
+
+**Example**
+
+- /flux/review
+- /flux/address-feedback
+- /flux/ask all
+- /flux/exec 2
+- /flux/qa 2
+- /flux/tests
+- /flux/commit
+
+## PIPELINE C:
+
+---
+
+Address review feedback
+
+```
+/flux/address-feedback
+ -> /flux/ask
+  -> /flux/exec
+   -> /flux/qa
+    -> /flux/tests
+     -> /flux/commit
+```
+
+---
+
+**Example**
+
+- /flux/address-feedback ~/Desktop/review.zip
+- /flux/ask all
+- /flux/exec 2
+- /flux/qa all
+- /flux/tests
+- /flux/commit
+
+## PIPELINE D:
+
+---
+
+Review someone else's PR
+
+```
+# If the review is done from the PR branch itself (recommended)
+
+/flux/review
+
+# If the review is done from another branch, you need to provide PR number
+
+/flux/review <PR#>
+
+# For both cases, after the review has completed:
+# -> post a comment on the PR, "Code changes suggested", and attach the zip file created
+# (e.g. ~/.flux/<flattened-dir>/review.zip)
+```
+
+---
+
+**Example**
+
+- /flux/review 123 (provide PR number if not on the PR branch)
+- post a comment on the PR, "Code changes suggested", and attach the review.zip from your flux directory (e.g. `~/.flux/<flattened-dir>/review.zip`)