diff --git a/docs/workpad/goals/uv_detection.md b/docs/workpad/goals/uv_detection.md index 8136f75..551707f 100644 --- a/docs/workpad/goals/uv_detection.md +++ b/docs/workpad/goals/uv_detection.md @@ -1,16 +1,27 @@ -- detect tainted .venv folders: custom files and folders inside .venv, using .venv as multi-python base dir, etc. should lead to a warning, as it shows that `uv` is not fully embraced in that project. -- detect default packages for skills in main uv: - - requests or httpx - - python-dotenv - - pydantic v2+ - - pytest - - pyyaml - - tomllib or tomli - - mcp -- support `SCRIPTS_DIR` (default: `'scripts/'`), `SCRIPTS_STORE` (default: `'/tmp/'`) and `SCRIPTS_UV` (default: `''`) env vars? +- support `SCRIPTS_DIR` (default: `'scripts/'`, these are usually project shipped scripts), `SCRIPTS_STORE` (default: `'/tmp/'`, this is space to store temporary files and scripts) and `SCRIPTS_UV` (default: `''`, this is the executable to run uv) env vars in the skills boot sequence. Only react if that is successful. +- otherwise agent has to figure it out by running check_uv.py +- detect justfiles, makefiles, misefiles, check for uv or python recipes, specificly to run scripts. - detect if project itself is a python project, or uv is there to be used by the agent. -- detect uv pins (uv.toml, pyproject.toml, pip requirements) -- detect justfiles, makefiles, misefiles -- \ No newline at end of file +- check_uv then should: + - detect uv pins (uv.toml, pyproject.toml, pip requirements) + - detect tainted .venv folders: custom files and folders inside .venv, using .venv as multi-python base dir, etc. should lead to a warning, as it shows that `uv` is not fully embraced in that project. + - detect default packages for skills in main check_uv: + - requests or httpx + - python-dotenv + - pydantic v2+ + - pytest + - pyyaml + - tomllib or tomli + - mcp + - reiterate env vars, and doing most detections it can do deterministically + +- running check_uv should confirm if the agent found the same conclusion. it is a chicken and egg problem, that can result in the fact, that the check_uv will tell the agent, that it detected a different running pattern, than the agent used. +- the agent finally has to decide, which method it keeps. once this is settled, and this can settle fast if everything is preconfigured, the agent is ready to use python, and both conclusions agree. +- the main task in this performative ritual is to ground on how to use scripts in the project. + +- this skills' existence is proof, that the user wants to use helper scripts in the project, and wants to utilize a uv installation locally in the project by the agent, and wants the agent to figure out, which one to use, and then not switch around later on, while the task is to actually focus on executing scripts and skills. +- it should also therefore get the idea of where a local scratch pad (SCRIPTS_STORE), project scripts folder (SCRIPTS_DIR), etc. might exist, and can therefore substitute this also as knowledge if it has to work with other tools, that want files or scripts written, but do not define where a certain folder is. These directories build good fallbacks for such concerns, and python therefore a solid tool to support the developer in tasks. +- for full python projects, it is very likely, that the configured uv is also capable of running actual project code, so namespaces should be respected. +- for rust projects, the uv configuration is almost certainly the local python environment for the agent. diff --git a/plugins/g4b_ai/skills/workpad/SKILL.md b/plugins/g4b_ai/skills/workpad/SKILL.md index b6d57ed..40055db 100644 --- a/plugins/g4b_ai/skills/workpad/SKILL.md +++ b/plugins/g4b_ai/skills/workpad/SKILL.md @@ -1,6 +1,6 @@ --- name: workpad -description: Decides WHERE and WHEN to put working documents — reports, plans, goals, brainstorms, designs, journals, research, specs, tickets, bug notes. Use this skill whenever the user asks you to write a "report", "plan", "goal", "brainstorm", "design", "journal", "research note", "spec", or anything "in the workpad" — and also when another skill is about to drop a markdown file somewhere ad-hoc (e.g. a `superpowers/` subdirectory, the repo root, `/tmp`, or alongside source code). If a workpad exists, the workpad wins. This skill steers other skills toward a single, predictable place for thinking-in-markdown so the user can always find what was written and when. +description: Decides WHERE and WHEN to put working documents — reports, plans, goals, brainstorms, designs, journals, research, specs, tickets, bug notes. Use this skill whenever the user asks you to write a "report", "plan", "goal", "brainstorm", "design", "journal", "research note", "spec", or anything "in the workpad" — and also when another skill is about to drop a markdown file somewhere ad-hoc (e.g. a `superpowers/` subdirectory, the repo root, `/tmp`, or alongside source code). If a workpad exists, the workpad wins. This skill steers other skills toward a single, predictable place for markdown documents. Can be used together with any superpowers. --- # Workpad @@ -14,14 +14,14 @@ Treat this skill as authoritative for placement. If another skill suggests writi Resolve the workpad base directory in this order — stop at the first hit: 1. **Explicit user instruction in the current conversation.** If they said "put it in `~/notes/foo`", that wins. -2. **`WORKPAD_FOLDER` environment variable.** Reading it reliably is fiddly because Claude Code runs commands in subshells that may not inherit the user's interactive env, and the value may live in a project-local `.env` file rather than the actual environment. Try, in order: - - `uv run --quiet --with python-dotenv python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.environ.get('WORKPAD_FOLDER',''))"` if `uv` is available. This loads `.env` from the current working directory before reading the variable, which catches the common case where `WORKPAD_FOLDER` is set per-project in a `.env`. - - `just workpad-folder` (or any equivalent recipe) if a `.justfile` / `justfile` is present and defines one — `just` loads `.env` automatically. - - `printenv WORKPAD_FOLDER` as a last resort. This will only see values exported into the actual process environment, not values in `.env` files. +2. **`WORKPAD_FOLDER` environment variable.** Reading it reliably is fiddly because Agents run commands in subshells that may not inherit the user's interactive env, and the value may be injected on purpose not available to the agent: + - `just workpad-folder` (or any equivalent recipe) if a `.justfile` / `Justfile` is present and defines one — `just` loads `.env` automatically. + - `printenv WORKPAD_FOLDER` as a last resort. This will only see values exported into the actual process environment. If any of these prints a non-empty path, treat it as the workpad base. 3. **Project-local ticket folder.** Some projects keep a sibling folder *outside* the main repo for per-ticket scratch (e.g. `../-tickets/` or a path the user has mentioned before). If such a folder is configured for this project, prefer placing the workpad inside it (e.g. `/workpad/`). When in doubt whether one exists, ask. 4. **`/docs/workpad`** at the project root, if a `/docs` folder already exists. -5. **Otherwise: ask.** If there is no `/docs` folder and no other signal, do not silently create `/docs/workpad/`. Ask the user where the workpad should live, and confirm before creating any folders. +5. **`/.workpad`** at the project root. +6. **Otherwise: ask.** If there is no `/docs` folder and no other signal, do not silently create `/docs/workpad/`. Ask the user where the workpad should live, and confirm before creating any folders. ## Folder structure @@ -42,7 +42,7 @@ It may also contain any of these, created on demand: - `specs/` — frozen, unchanging specifications - `tickets/` — per-ticket scratch space -If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively. +If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively. Treat unknown folders as owned by the user and ignore them. ## File naming