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

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

@@ -0,0 +1,211 @@
+---
+name: ask
+argument-hint: todo_file | all | additional_instructions
+description: Clarify requirements with structured questions, research codebase, and augment todo file
+---
+
+> **⚠️ 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: ask, 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.
+
+# TODO FILE CLARIFICATION & AUGMENTATION WORKFLOW
+
+## STEP 1: Resolve input
+
+**Todo File:** `$ARGUMENTS`
+
+If no argument provided, run:
+
+```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,done,review,research}
+echo "FLUX_BASE=$FLUX_BASE"
+ls -1 "$FLUX_BASE/todo/"*.md 2>/dev/null || true
+```
+
+If `$ARGUMENTS` == `all`: iterate through all files in `$FLUX_BASE/todo/`.
+Else: if no `/`, prepend `$FLUX_BASE/todo/`; if no `.md`, append `.md`.
+(e.g. `NOTIFS` -> `$FLUX_BASE/todo/NOTIFS.md`)
+
+Tell the user: `Please specify a todo file or 'all'` and list the output.
+
+---
+
+## STEP 2: Mark as in-progress
+
+Before any work, update the frontmatter of the target file(s). If a frontmatter block exists, replace `stage`, `status`, `updated`. If none exists, prepend before the first `#` heading.
+
+Single file or `all` (update all files before processing any):
+
+```yaml
+---
+stage: ask
+status: in-progress
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+---
+
+## STEP 3: Read & analyze
+
+Read the complete todo file with sequential thinking. Identify the core USER OBJECTIVE, extract explicit requirements, and categorize gaps/ambiguities:
+
+- **Business Logic** — unclear rules, edge cases, validation
+- **User Experience** — interactions, feedback, error handling
+- **Data & State** — data needed, flow, persistence
+- **Integration Points** — external dependencies, APIs, services
+- **Constraints** — performance, security, compatibility
+
+---
+
+## STEP 4: Ask clarifying questions (one at a time)
+
+Use `ask_user_question` to ask clarifying questions **one at a time**.
+
+- Start with the MOST CRITICAL ambiguity
+- Each question: 2–4 concrete options with brief implication descriptions
+- Wait for answer before asking the next
+- Continue until all critical ambiguities are resolved (typically 3–8 questions)
+- Priority order: Core Behavior → Edge Cases → User Expectations → Scope Boundaries → Success Criteria
+- If user selects "Other", record their response verbatim
+
+Example format:
+
+```
+Question: "How should the system handle invalid input?"
+Header: "Error handling"
+Options:
+  - Label: "Silent rejection"
+    Description: "Quietly ignore invalid input, no user feedback"
+  - Label: "Inline validation"
+    Description: "Show error message next to the field immediately"
+  - Label: "Toast notification"
+    Description: "Display temporary notification with error details"
+  - Label: "Modal dialog"
+    Description: "Block user with detailed error explanation and retry option"
+```
+
+---
+
+## STEP 5: Codebase research
+
+```bash
+lsd --tree ./src/ 2>/dev/null || find ./src -type f | sort
+lsd --tree ./packages/ 2>/dev/null || find ./packages -type f | sort
+```
+
+- Search for files related to the feature
+- Find EXISTING implementations to reuse or adapt
+- Identify established patterns and integration points
+- **CRITICAL:** Much of the code is often ALREADY WRITTEN — USE IT. DO NOT call for duplication.
+
+---
+
+## STEP 6: Augment the todo file
+
+Replace the original todo file with the augmented version containing all gathered information.
+
+**Add these sections:**
+
+```markdown
+## Business Requirements (Clarified)
+
+### Core Behavior
+
+- [Requirement from Q1 answer]
+
+### Edge Cases & Error Handling
+
+- [Requirement from relevant answers]
+
+### User Experience
+
+- [Requirement from relevant answers]
+
+### Constraints & Boundaries
+
+- [What is OUT of scope]
+- [Performance/security requirements]
+
+## Implementation Research
+
+### Existing Code to Leverage
+
+- `./src/path/to/file.ts` - [what can be reused]
+- `./src/other/module.ts` - [pattern to follow]
+
+### Files That Need Changes
+
+| File        | Change Required  |
+| ----------- | ---------------- |
+| `./src/...` | Add/modify X     |
+| `./src/...` | Integrate with Y |
+
+### Code Patterns to Follow
+
+[Links to existing patterns with relative paths]
+
+## Implementation Plan
+
+### Step 1: [Action]
+
+- Specific file: `./src/...`
+- Exact change: [describe precisely]
+
+### Step 2: [Action]
+
+...
+
+### Definition of Done
+
+- [ ] [Concrete, verifiable criterion]
+- [ ] [Concrete, verifiable criterion]
+```
+
+**Exclude:** unit/functional/integration tests, benchmarks, extensive documentation, multiple options.
+**Include:** precise `./src` change instructions, citation links, inline code patterns, single prescriptive implementation path, definition of done.
+
+---
+
+## STEP 7: Mark as done
+
+After finishing each todo file, update its frontmatter:
+
+```yaml
+---
+stage: ask
+status: done
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+For `all`: update each file to `done` as it completes, not all at once.
+
+---
+
+## 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/ask` is a **clarify-and-augment-only** command. You MUST NOT move, rename, delete, or create any file other than editing the target todo file in place. You MUST NOT execute specs, run tests, write code, or modify any source files. No shell commands beyond the codebase research in STEP 5. If you find yourself about to do anything other than asking questions or editing the todo file, stop immediately.
+
+---
+
+## OUTPUT
+
+Print the full absolute filepath as the **VERY LAST LINE** of output. Then await next instruction.
+
+## Propose next step
+
+Then propose the next step: `/flux/split` (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/aug.md

@@ -0,0 +1,181 @@
+---
+name: aug
+argument-hint: todo_file | number_of_agents | additional_instructions
+description: Augment task(s) with research - 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: aug, 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.
+
+# AUGMENT 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,done,review,research}
+echo "FLUX_BASE=$FLUX_BASE"
+ls -1 "$FLUX_BASE/todo/"*.md 2>/dev/null || true
+```
+
+**Detection logic:**
+
+```
+IF $ARGUMENTS is empty:
+  -> List: `ls -1 "$FLUX_BASE/todo/"*.md`
+  -> Use ask_user_question to let user select task(s)
+  -> Single selection -> Single-task mode
+  -> 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 in single-task mode yourself (no subagents), one after another
+  -> Do not proceed to next task until 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 in single-task mode yourself (no subagents), one after another
+    -> Do not proceed to next task until 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 no `/`, prepend `$FLUX_BASE/todo/`; if no `.md`, append `.md`.
+(e.g. `NOTIFS` -> `$FLUX_BASE/todo/NOTIFS.md`)
+
+---
+
+## SINGLE-TASK MODE
+
+## STEP 2: Mark as in-progress
+
+Update the task file's frontmatter before starting. If frontmatter exists, replace `stage`, `status`, `updated`. If none, prepend before the first `#` heading.
+
+```yaml
+---
+stage: aug
+status: in-progress
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+## STEP 3: Research & augment
+
+### 3.1 Determine stack
+
+```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"
+```
+
+Act as a `$STACK` expert SOFTWARE ARTISAN. 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)"
+```
+
+### 3.2 Read the task file
+
+Read the full task file with sequential thinking. Think "out loud" about the core user OBJECTIVE.
+
+### 3.3 Explore the codebase
+
+```bash
+lsd --tree ./src 2>/dev/null || find ./src -type f | sort
+```
+
+- Examine module hierarchy; search for files related to the feature
+- Much of the code needed is ALREADY WRITTEN — USE IT. DO NOT call for duplication.
+
+Think deeply with step-by-step reasoning:
+
+- What is the core objective?
+- What needs to change in `./src` to accomplish this task?
+- What questions remain? What needs research?
+
+### 3.4 Augment the task file in place
+
+- Clone any needed third-party libraries into `./tmp`
+- Augment the task file with rich research detail
+- Link to citation sources in `./tmp` and `./src` with relative markdown hyperlinks
+- Plan required source code with ULTRATHINK; demonstrate core patterns inline in the task file
+- Remove any language calling for tests, benchmarks, or documentation
+- Provide precise instructions on what to change in `./src` and how
+- Provide a clear definition of done (not requiring extensive testing)
+- Be prescriptive — always select the most feature-rich, code-correct option as the single required implementation path. Do not take the path of least resistance.
+
+REPLACE THE ORIGINAL FILE in place. Do not write augmentations to a new file.
+
+Print the full absolute filepath as the **VERY LAST LINE** of output. Then return to planning.
+
+## STEP 4: Mark as done
+
+```yaml
+---
+stage: aug
+status: done
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+---
+
+## MULTI-TASK MODE
+
+Use the `invoke_agent` tool to execute tasks IN PARALLEL. _NEVER_ run agents in the background — always foreground.
+
+- Spawn `$ARGUMENTS` subagents at a time (or fewer if fewer tasks exist)
+- As each completes, spawn a new one until all `$FLUX_BASE/todo/*.md` tasks are done
+
+### Subagent prompt template
+
+Use the single-task mode steps above as the subagent prompt, substituting `{{absolute_file_path}}` for `$ARGUMENTS`.
+
+---
+
+## 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/aug` is a **research-and-augment-only** command. You MUST NOT modify any source files, run any tests, or create new files outside of `./tmp`. The only file operation allowed on the project is editing the target task file in place. If you find yourself about to touch any source file, stop immediately.
+
+## Propose next step
+
+Then propose the next step: `/flux/exec` (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/auto-pilot.md

@@ -0,0 +1,71 @@
+---
+name: auto-pilot
+argument-hint: task_description | spec.md | spec.txt | TICKET-123 | additional_instructions
+description: 'Orchestrates the complete //flux pipeline end-to-end. Accepts: a prompt, a .md/.txt spec file, or a Jira ticket (e.g. PROJ-123).'
+---
+
+# auto-pilot
+
+Fully autonomous development pipeline orchestrator. Executes the full **//flux pipeline** start to finish — pausing only during `/flux/ask` for clarifying questions.
+
+## STEP 1: Resolve input
+
+Resolve `$ARGUMENTS` before starting:
+
+- **Jira key** (`PROJ-123` pattern): fetch via `get_issue_by_key_or_link`, extract summary/description/acceptance criteria. Display: `📋 Loaded task from Jira: <KEY> — <summary>`
+- **File path** (`.md`/`.txt`): read with `read_file` tool, use full content. Display: `📄 Loaded task from file: <path>`
+- **Natural language**: use directly. Display: `💬 Task: <description>`
+
+## STEP 2: Execute pipeline
+
+Execute each step in sequence. For each step: announce `▶ Step: /flux/<command>`, execute all its instructions with correct arguments, announce `✓ Step: /flux/<command> complete`, carry output artifacts forward.
+
+### 2.1 — `/flux/new`
+
+Pass resolved task description. Output: task file name (e.g. `NOTIFS`) — carry forward.
+
+### 2.2 — `/flux/ask`
+
+Pass task file name from 2.1. **Only step where you pause** — ask all clarifying questions, wait for user responses, then continue automatically.
+
+### 2.3 — `/flux/split`
+
+Pass task file name from 2.1. Output: subtask count — carry forward.
+
+### 2.4 — `/flux/aug`
+
+Pass `2` (augment all subtasks with 2 parallel agents). Wait for completion.
+
+### 2.5 — `/flux/exec`
+
+Pass `2` (execute all subtasks with 2 parallel agents). Wait for completion.
+
+### 2.6 — `/flux/qa`
+
+Pass `2`. If QA produces refined tasks, re-run `/flux/exec 2` and `/flux/qa 2` until all tasks clear (max 3 cycles).
+
+### 2.7 — `/flux/tests`
+
+No arguments. Run the test suite, fix regressions introduced by this branch. If unresolved failures remain after 3 fix cycles, report and continue to commit (do not block the pipeline).
+
+### 2.8 — `/flux/commit`
+
+No additional arguments. User will be asked for commit confirmation — expected and allowed.
+
+## STEP 3: Error recovery
+
+On step failure: identify root cause, apply fix, re-run the failed step. After 3 failed attempts on the same step, stop and report: which step failed, what was attempted, what the user should do next.
+
+## HARD CONSTRAINT
+
+`/flux/auto-pilot` orchestrates other `//flux` commands — it does not implement logic of its own beyond sequencing. Each step's own HARD CONSTRAINTs apply in full. Do not skip steps, do not merge steps, do not take shortcuts.
+
+## Output style
+
+- Concise and scannable
+- Use `▶`/`✓` step headers
+- Actionable errors — no raw stack traces
+- Do not produce summary files unless a step requires it
+
+=================
+$ARGUMENTS

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

@@ -0,0 +1,16 @@
+---
+name: cheatsheet
+description: Show the //flux pipeline cheatsheet (all stages, colorized)
+exec: {python} {script:flux_cheatsheet.py} --docs {command:flux/_docs}
+---
+
+# /flux/cheatsheet
+
+Renders the //flux pipeline cheatsheet -- a colorized view of every pipeline
+stage (A/B/C/D) sourced from the canonical `pipeline.md` doc.
+
+> **Note:** code-puppy executes this command via the `exec:` frontmatter hook,
+> which runs the bundled `flux_cheatsheet.py` (resolved under code-puppy's
+> config dir) and streams its ANSI output back through the message bus. The
+> body below is reference docs only -- it is not sent to the AI when the script
+> is wired up.

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

@@ -0,0 +1,103 @@
+---
+name: commit
+description: Create a detailed commit message from branch changes
+argument-hint: amend
+---
+
+# CREATE A DETAILED COMMIT MESSAGE
+
+## STEP 1: Detect mode
+
+If argument (case-insensitive) equals `amend`, enter **amend mode**:
+
+- Run `git log -1 --format=%B` and display: `"Previous commit message: <message>"`
+- Use it as context in STEP 4; newly generated message is authoritative
+- Use `git commit --amend -m "..."` in STEP 5 instead of `git commit -m "..."`
+
+## STEP 2: Detect commit prefix
+
+```bash
+BRANCH=$(git branch --show-current)
+TICKET=$(echo "$BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1 || echo "")
+echo "BRANCH: $BRANCH"
+echo "TICKET: $TICKET"
+```
+
+- `$TICKET` non-empty → prefix: `$TICKET:` (e.g. `PROJ-123: description`)
+- `$TICKET` empty → `ask_user_question`:
+  - Question: "No Jira ticket found in branch name. What type of commit is this?"
+  - Header: "Commit type"
+  - Options: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`
+  - Prefix: `<type>: description`
+
+## STEP 3: Identify changed files
+
+List all files changed vs main branch (both modified and new).
+
+## STEP 4: Generate commit message
+
+Generate an informative commit message for the changes. In amend mode, use the previous message as context to incorporate any new staged changes.
+
+## STEP 5: Confirm and apply
+
+```bash
+git status
+git diff --stat HEAD
+```
+
+If no changes, tell the user and stop.
+
+**Amend mode:** if no staged changes, print `"Nothing is staged. Stage your changes with \`git add\` before amending."` and stop.
+
+**Amend mode only** — show before confirmation:
+
+> ⚠️ `--amend` rewrites history. If this branch has already been pushed, a force-push will be required.
+
+Present the message from STEP 4, then `ask_user_question`:
+
+- Normal: "Ready to commit with the message above?" → `["Yes, commit now", "No, let me review first"]`
+- Amend: "Ready to amend the previous commit with the message above?" → `["Yes, amend now", "No, let me review first"]`
+
+If "No, let me review first" → stop.
+
+**Normal mode:**
+
+```bash
+git add .
+git commit -m "$(cat <<'EOF'
+$COMMIT_PREFIX Your generated message here
+EOF
+)"
+```
+
+**Amend mode:**
+
+```bash
+git add .
+git commit --amend -m "$(cat <<'EOF'
+$COMMIT_PREFIX Your refined message here
+
+EOF
+)"
+```
+
+IMPORTANT: Never use `$DETAILED_MSG` or any shell variable for the commit message. Write the actual generated message inline in the heredoc.
+
+IMPORTANT: DO NOT push unless the user specifically asks!
+
+## STEP 6: Summarize
+
+Summarize completion. In amend mode, note "Amended previous commit" instead of "Created new commit".
+
+## HARD CONSTRAINT
+
+`/flux/commit` MUST NOT push to any remote unless the user explicitly asks. MUST NOT modify any source files or task files. The only permitted operations are reading git history, staging files, and creating/amending a commit. Write the commit message inline — never via shell variables.
+
+## 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

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

@@ -0,0 +1,108 @@
+---
+name: config
+description: Create or update the flux config.env with settings used by the flux command suite
+---
+
+# Configure Flux Settings
+
+## STEP 1: Check for existing config
+
+```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"
+```
+
+```bash
+cat "$FLUX_BASE/config.env" 2>/dev/null && echo "__EXISTS__" || echo "__MISSING__"
+```
+
+**File exists** — check the mandatory key (`TEST_CMD`):
+
+- **Present** → display summary:
+
+  ```
+  TEST_CMD = <value>
+  ```
+
+  `ask_user_question` — question: "Config looks good. Do you want to update any values?" / header: "Update config" / options: `Yes, update values` | `No, looks good`
+
+  - No → stop. Yes → STEP 2 (update flow).
+
+- **Missing** → proceed to STEP 2 (update flow).
+
+**File missing** → proceed to STEP 2 (new file flow).
+
+---
+
+## STEP 2: Collect values
+
+### 2a. New file flow
+
+If the config file did not exist, do NOT ask questions. Write the file immediately with a blank value and an inline comment:
+
+```bash
+cat > "$FLUX_BASE/config.env" << 'CONFIG_EOF'
+# Command that runs your test suite (e.g. bun run test:quiet, npm test, pytest -q, cargo test -- --quiet)
+# Tip: chain lint + tests together, e.g. bun run lint && bun run test:quiet
+TEST_CMD=
+CONFIG_EOF
+```
+
+```bash
+echo "=== $FLUX_BASE/config.env ==="
+cat "$FLUX_BASE/config.env"
+```
+
+`ask_user_question` — question: "Config file created at `$FLUX_BASE/config.env`. Please open it, fill in your value, then re-run `/flux/config` to verify. Ready to continue?" / header: "Edit config" / options:
+
+- `Done, verify now` — re-read `$FLUX_BASE/config.env`, jump to STEP 4
+- `Exit` — stop
+
+### 2b. Update flow
+
+Runs only when the user chose "Yes, update values" from STEP 1, or when the key is missing. Ask via `ask_user_question` with options `Keep current` (pre-filled) and `New value - use Other below` (free-text via Other input).
+
+**TEST_CMD**: "What command runs your test suite?" / header: "TEST_CMD"
+
+- `Keep current` → description: `Current value: <TEST_CMD>`
+- `New value - use Other below` → description: `e.g. bun run test:quiet, npm test, pytest -q — or chain with lint: bun run lint && bun run test:quiet`
+- Store result as `TEST_CMD_VALUE`.
+
+---
+
+## STEP 3: Write config (update flow only)
+
+```bash
+cat > "$FLUX_BASE/config.env" << 'CONFIG_EOF'
+TEST_CMD=<TEST_CMD_VALUE>
+CONFIG_EOF
+```
+
+Rules: use the actual collected value (not the placeholder name), overwrite completely.
+
+```bash
+echo "=== $FLUX_BASE/config.env ==="
+cat "$FLUX_BASE/config.env"
+```
+
+---
+
+## STEP 4: Confirm
+
+Parse `$FLUX_BASE/config.env` (strip comments and blank lines) and print:
+
+```
+ $FLUX_BASE/config.env ready:
+
+  TEST_CMD = <value or "(not set)">
+
+All //flux commands will read this file automatically via:
+  source "$FLUX_BASE/config.env" 2>/dev/null
+```
+
+## HARD CONSTRAINT
+
+`/flux/config` MUST NOT modify any source files, task files, or any file outside of `$FLUX_BASE/config.env`. The only permitted file operation is writing/overwriting `$FLUX_BASE/config.env`. No git commands. No task creation.