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

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/create-pr.md

@@ -0,0 +1,195 @@
+---
+name: create-pr
+description: Create a GitHub PR for the current branch, or show the existing PR URL and status
+---
+
+# CREATE A GITHUB PULL REQUEST
+
+## STEP 1: Validate branch
+
+```bash
+BRANCH=$(git branch --show-current)
+echo "CURRENT_BRANCH: $BRANCH"
+```
+
+If `BRANCH` is `main` or `master`, print and stop:
+
+```
+Error: You are on the default branch ("$BRANCH").
+Switch to a feature branch before opening a PR.
+```
+
+## STEP 2: Check for existing PR
+
+```bash
+EXISTING=$(gh pr view --json number,url,state,title 2>/dev/null)
+echo "$EXISTING"
+```
+
+If output is non-empty JSON, print and stop:
+
+```
+A PR already exists for this branch:
+  Title:  <title>
+  URL:    <url>
+  State:  <state>
+```
+
+## STEP 3: Check for commits ahead of default branch
+
+```bash
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
+echo "DEFAULT_BRANCH: $DEFAULT_BRANCH"
+COMMIT_COUNT=$(git rev-list HEAD ^"origin/${DEFAULT_BRANCH}" --count 2>/dev/null || echo "0")
+echo "COMMIT_COUNT: $COMMIT_COUNT"
+```
+
+If `COMMIT_COUNT` is `0`, print and stop:
+
+```
+Warning: No commits ahead of origin/$DEFAULT_BRANCH.
+Push at least one commit before opening a PR.
+```
+
+## STEP 4: Derive PR title from branch name
+
+```bash
+BRANCH=$(git branch --show-current)
+SLUG=$(echo "$BRANCH" | sed 's|.*/||')
+JIRA_ID=$(echo "$SLUG" | grep -oE '^[A-Z]+-[0-9]+' || true)
+if [ -n "$JIRA_ID" ]; then
+  DESC=$(echo "$SLUG" | sed "s/^${JIRA_ID}-//")
+else
+  DESC="$SLUG"
+fi
+TITLE_DESC=$(echo "$DESC" | tr '-' ' ' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2)); print}')
+if [ -n "$JIRA_ID" ]; then
+  PR_TITLE="${JIRA_ID}: ${TITLE_DESC}"
+else
+  PR_TITLE="${TITLE_DESC}"
+fi
+echo "PR_TITLE: $PR_TITLE"
+```
+
+Examples: `rio/MYPROJ-745-add-create-pr-command` → `MYPROJ-745: Add Create Pr Command` | `feat/dark-mode` → `Dark Mode`
+
+## STEP 5: Detect PR template
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+TEMPLATE_PATH=""
+
+# Check single-file locations in GitHub-documented priority order
+for candidate in \
+  ".github/pull_request_template.md" \
+  ".github/PULL_REQUEST_TEMPLATE.md" \
+  "docs/pull_request_template.md" \
+  "docs/PULL_REQUEST_TEMPLATE.md" \
+  "pull_request_template.md" \
+  "PULL_REQUEST_TEMPLATE.md"; do
+  if [ -f "$REPO_ROOT/$candidate" ]; then
+    TEMPLATE_PATH="$REPO_ROOT/$candidate"
+    break
+  fi
+done
+
+# Check directory locations if no single-file match found
+TEMPLATE_NOTE=""
+TEMPLATE_DIR=""
+if [ -z "$TEMPLATE_PATH" ]; then
+  for dir in \
+    ".github/PULL_REQUEST_TEMPLATE" \
+    "docs/PULL_REQUEST_TEMPLATE" \
+    "PULL_REQUEST_TEMPLATE"; do
+    if [ -d "$REPO_ROOT/$dir" ]; then
+      TEMPLATE_COUNT=$(ls "$REPO_ROOT/$dir/"*.md 2>/dev/null | wc -l | tr -d ' ')
+      if [ "$TEMPLATE_COUNT" -gt 1 ]; then
+        TEMPLATE_NOTE="Multiple templates found in $dir — automatic selection is ambiguous. Falling back to default body."
+        TEMPLATE_DIR="$REPO_ROOT/$dir"
+        break
+      elif [ "$TEMPLATE_COUNT" -eq 1 ]; then
+        TEMPLATE_PATH=$(ls "$REPO_ROOT/$dir/"*.md 2>/dev/null | head -1)
+        break
+      fi
+    fi
+  done
+fi
+
+if [ -n "$TEMPLATE_PATH" ]; then
+  echo "TEMPLATE_FOUND: yes"
+  echo "TEMPLATE_PATH: $TEMPLATE_PATH"
+  echo "---TEMPLATE_BEGIN---"
+  cat "$TEMPLATE_PATH"
+  echo "---TEMPLATE_END---"
+else
+  echo "TEMPLATE_FOUND: no"
+  if [ -n "$TEMPLATE_NOTE" ]; then
+    echo "TEMPLATE_NOTE: $TEMPLATE_NOTE"
+    ls "$TEMPLATE_DIR/"*.md 2>/dev/null | sed 's|.*/||' | while read f; do echo "  - $f"; done
+  fi
+fi
+```
+
+## STEP 6: Generate PR body from diff
+
+```bash
+git log HEAD ^origin/${DEFAULT_BRANCH} --oneline
+git diff origin/${DEFAULT_BRANCH}...HEAD --stat
+```
+
+**If a template was found in STEP 5:**
+
+Parse every section heading from the template file (e.g., `## 📝 Problem`, `## 💡 Solution`, `### 📚 References`, `### CCM:`, `### 🖼️ Screenshots`, `### 📖 Build History`).
+
+Fill in **EVERY section** from the template using context from the current implementation:
+
+- Do not invent your own sections
+- Do not skip any sections
+- Do not reorder sections
+- Match the exact heading text, emoji, and formatting from the template
+- Preserve verbatim any HTML comments, unchecked checkboxes (`- [ ] ...`), and static non-heading text from the template; only replace designated placeholder text (e.g., italic or angle-bracket placeholders like `*describe here*` or `<your text>`)
+
+**If no template was found:**
+
+Write a PR body with:
+
+- `## Summary` — 1–3 bullets: what changed and why (specific to actual commits/files, no placeholders)
+- `## Test plan` — concrete manual verification steps specific to the changes
+
+In both cases, the body is written as literal text inline in the heredoc in STEP 7. Do NOT use a shell variable for the body.
+
+## STEP 7: Create the PR
+
+Do NOT pass `--web`, `--fill`, `--draft`, `--reviewer`, `--label`, `--milestone`, or `--assignee`. Write body inline in the heredoc — do NOT use shell variables for it:
+
+```bash
+PR_URL=$(gh pr create \
+  --title "$PR_TITLE" \
+  --body "$(cat <<'EOF'
+<generated body — either template-filled or fallback Summary+Test plan>
+EOF
+)")
+echo "PR_URL: $PR_URL"
+```
+
+On non-zero exit, surface the raw `gh` error verbatim. Common causes: not authenticated (`gh auth login`), no remote tracking branch (`git push -u origin <branch>`), network/API error.
+
+## STEP 8: Print result
+
+```
+PR created successfully:
+  Title:  <PR_TITLE>
+  URL:    <PR_URL>
+```
+
+Do NOT open a browser window.
+
+## HARD CONSTRAINT
+
+`/flux/create-pr` MUST NOT modify any source files, task files, or config files. The only permitted operations are reading git history, running `gh` commands, and pushing the branch if needed. Write the PR body inline — never via shell variables. Do NOT open a browser window.
+
+## Propose next step
+
+Then propose the next step: `/flux/review`
+
+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.

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

@@ -0,0 +1,221 @@
+---
+name: exec
+argument-hint: todo_file | number_of_agents | additional_instructions
+description: Execute 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: exec, status: done` (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.
+
+# EXECUTE TASK(S)
+
+## 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 (only permitted task file modification — does not alter task content):
+
+> If frontmatter (`---` … `---`) exists, replace `stage`, `status`, `updated`. If absent, prepend before first `#` heading.
+
+```yaml
+---
+stage: exec
+status: in-progress
+updated: <today's date and time, YYYY-MM-DD HH:MM>
+---
+```
+
+## STEP 3: Determine stack
+
+Act as a `$STACK` expert SOFTWARE ARTISAN.
+
+```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: Execute the task
+
+### 4.1 Prepare
+
+CLEAR YOUR TODO list. Focus only on this SINGULAR TASK: `$ARGUMENTS`
+
+Read and fully comprehend the task with sequential thinking and ULTRATHINK. Think "out loud" about exactly what needs to be done.
+
+### 4.2 Implement
+
+Execute the task exactly as written:
+
+- no embellishment — do not improve task scope
+- no scope creep — do not expand scope
+- continue until all requirements and definition of done are met
+- do not fix errors or warnings unrelated to the task
+
+### 4.3 Handle incorrect requirements
+
+If the task is fundamentally incorrect or needs modification:
+
+- stop immediately and return to planning
+- clearly articulate what is faulty
+- do not continue working
+- do not modify the task file until the user reviews and approves changes
+
+### 4.4 Verify completion
+
+- re-review all work
+- verify 100% of requirements are fully implemented
+- ensure ABSOLUTELY NO STUBS or uncompleted work
+
+## STEP 5: Mark as done
+
+```yaml
+---
+stage: exec
+status: done
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+## STEP 6: Output & constraints
+
+**Output:**
+
+- print "I've completed and verified 100% of the requirements are fully implemented in production grade quality"
+- print "I'm ready for a full and detailed QA review of my work with full confidence it will score 10/10 for production readiness based on the task description."
+- print the full path to the task file
+
+**No task file modification:**
+_DO NOT_ under ANY CIRCUMSTANCES modify the original task file content. Your QA reviewer will be reviewing your work with the exact same information as the implementor. Do NOT mark items as DONE or modify the task file in any way shape or form.
+
+**Scope guard — respect the deliverable:**
+Before writing ANY file, verify the task's deliverable:
+
+- If the deliverable is a **markdown/research file** (e.g., `.md` under `$FLUX_BASE/research/`), do NOT modify `./src/`, `./test/`, or `./package.json`. Write only to the output path in the task.
+- If the task says "research", "document", "summarize", "catalog", or "compile a report" — deliverable is markdown, NOT source code.
+- Only modify source files if the task explicitly calls for source code changes in `./src/` or other directories containing source files.
+
+Violation of this rule is treated the same as modifying the task file — immediate termination of the task.
+
+**No git commands:**
+DO NOT USE `git` commands of any type. Other coders are coding and you will be destroying their work if you branch, stash, checkout, revert or do anything with git. 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: exec
+status: in-progress
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+**As each subagent completes**, update that file's frontmatter to `done`. Update each file as it completes, not all at once.
+
+**Task selection:**
+
+- Identify `$ARGUMENTS` tasks to execute in parallel (or fewer if fewer exist)
+- Avoid parallelizing tasks that modify the same file(s)
+- Once easy namespace collision avoidance is exhausted, analyze interdependencies carefully
+- 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 and all constraints (no-git, scope guard, no task file modification).
+
+---
+
+## HARD CONSTRAINTS
+
+- **Path**: All `create_file`/`replace_in_file` file paths 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/exec` MUST NOT use any `git` commands. MUST NOT modify the task file content (frontmatter status updates are the only exception). MUST NOT expand scope beyond what is written in the task. MUST NOT write to paths outside what the task explicitly specifies. If you find yourself about to do any of these things, stop immediately.
+
+## Propose next step
+
+Then propose the next step: `/flux/qa` (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

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

@@ -0,0 +1,151 @@
+---
+name: new
+argument-hint: task_description | JIRA_ticket_id
+description: Create a new task file from a description or Jira ticket
+---
+
+# Create New Task
+
+**Argument:** `$ARGUMENTS`
+
+## STEP 1: Check for leftover task files
+
+```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 "$FLUX_BASE/todo/"*.md 2>/dev/null || true
+```
+
+If files are found, use `ask_user_question`: "Found existing task files in `$FLUX_BASE/todo/`. What would you like to do with them?"
+
+- `Discard them` → `rm "$FLUX_BASE/todo/"*.md`
+- `Back them up` → `mkdir -p "$FLUX_BASE/todo-bkp" && mv "$FLUX_BASE/todo/"*.md "$FLUX_BASE/todo-bkp/"`
+
+## STEP 2: Detect argument type
+
+Pattern for Jira tickets: `^[A-Z]+-[0-9]+$` (e.g. `PROJECT-456`). Lowercase or plain descriptions do NOT match.
+
+## STEP 3: Create task file
+
+### If `$ARGUMENTS` matches Jira pattern
+
+#### 3.1 Check if Jira MCP is available
+
+**If `get_issue_by_key_or_link` is NOT available:**
+
+Inform the user:
+
+> "The Jira MCP server is not configured. To fetch ticket details, please install a Jira MCP server (e.g. `mcp-jira`) via `/mcp`. Then re-run this command."
+
+**Stop. Do not proceed further.**
+
+---
+
+**If `get_issue_by_key_or_link` IS available:**
+
+#### 3.2 Fetch the ticket
+
+```
+get_issue_by_key_or_link(issue_key_or_link: "$ARGUMENTS")
+```
+
+Read the **Summary**, **Description**, and **Acceptance Criteria** fields from the response. Convert any Jira markup to Markdown (see conversion table below).
+
+#### 3.3 Write task file at `$FLUX_BASE/todo/<TICKET-ID>.md`
+
+```markdown
+---
+stage: new
+status: done
+updated: <YYYY-MM-DD HH:MM>
+---
+
+# <TICKET-ID>: <summary>
+
+## Description
+
+<description — converted from Jira markup to Markdown>
+
+## Acceptance Criteria
+
+<omit this section entirely if not present on the ticket>
+
+## Source
+
+- **Jira ticket:** <TICKET-ID>
+- **Status:** <status>
+- **Priority:** <priority>
+```
+
+### If `$ARGUMENTS` does NOT match Jira pattern
+
+#### 3.1 Generate filename
+
+Take 3-4 significant words, UPPER_SNAKE_CASE, append `.md` (e.g. "add dark mode toggle" → `DARK_MODE.md`)
+
+#### 3.2 Clarify if needed
+
+If requirements are unclear, use `ask_user_question` to clarify before writing.
+
+#### 3.3 Write `$FLUX_BASE/todo/<FILENAME>.md`
+
+```markdown
+---
+stage: new
+status: done
+updated: <YYYY-MM-DD HH:MM>
+---
+
+# <Title derived from $ARGUMENTS — Title Case, human-readable (e.g. "Add Dark Mode Toggle")>
+
+## Description
+
+$ARGUMENTS
+
+## Acceptance Criteria
+
+- [ ] <To be clarified>
+```
+
+## HARD CONSTRAINTS
+
+- **Path**: The `create_file` file path 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.
+- **Capture-only**: You MUST NOT read, edit, delete or move any file other than the single task file being created in `$FLUX_BASE/todo/`. No source files, no config files, no other flux files — nothing. If you find yourself about to touch anything else, stop immediately and output the task file instead.
+
+## OUTPUT
+
+```
+Task created: $FLUX_BASE/todo/<FILENAME>.md
+```
+
+After creating the task file, start a new session by writing `$FLUX_BASE/session.env`:
+
+```bash
+SESSION_TS=$(date +%Y-%m-%d-%H-%M)
+echo "SESSION_TS=$SESSION_TS" > "$FLUX_BASE/session.env"
+echo "Session started: $SESSION_TS"
+```
+
+Then propose the next step: `/flux/ask` (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.
+
+## JIRA MARKUP → MARKDOWN
+
+| Jira              | Markdown      |
+| ----------------- | ------------- |
+| `*bold*`          | `**bold**`    |
+| `_italic_`        | `*italic*`    |
+| `{{code}}`        | `` `code` ``  |
+| `{code}...{code}` | ` ```...``` ` |
+| `h1. Title`       | `# Title`     |
+| `h2. Title`       | `## Title`    |
+| `* item`          | `- item`      |
+| `# item`          | `1. item`     |
+| `[text\|url]`     | `[text](url)` |
+
+=================
+$ARGUMENTS