agilab-runbook
Runbook for working in the AGILab repo (uv, Streamlit, run configs, packaging, troubleshooting).
When & Why to Use This Skill
The AGILab Runbook is a specialized Claude skill designed to streamline development and operational workflows within the AGILab repository. It provides instant access to repo-specific protocols, including environment management with 'uv', Streamlit application deployment, run configuration synchronization, and standardized troubleshooting procedures. By codifying repository policies and common commands, it ensures consistency and reduces onboarding friction for developers.
Use Cases
- Environment Management: Quickly generating the correct 'uv' commands to run Python or Streamlit scripts with specific preview features and dependency resolutions.
- Development Workflow Automation: Synchronizing IDE run configurations by automatically providing the commands to regenerate wrappers after editing XML configuration files.
- Release and Testing Orchestration: Guiding users through complex smoke tests for application pages and performing dry-run or production releases to PyPI.
- Technical Troubleshooting: Resolving common repository issues such as import errors in multi-scoped pyproject.toml files or fixing virtual environment installer conflicts.
- Policy Enforcement: Ensuring all developers follow the 'no silent fallbacks' and 'fail fast' rules by providing compliant code patterns and execution steps.
| name | agilab-runbook |
|---|---|
| description | Runbook for working in the AGILab repo (uv, Streamlit, run configs, packaging, troubleshooting). |
| license | BSD-3-Clause (see repo LICENSE) |
| short-description | AGILab repo runbook |
| updated | 2026-01-08 |
AGILab runbook (Agent Skill)
Use this skill when you need repo-specific “how we do things” guidance in agilab/: launching Streamlit, regenerating run-config wrappers, debugging installs, or preparing releases.
Background: Agent Skills (status update 2026-01-08)
- Codex now supports Agent Skills using the open Agent Skills standard (
SKILL.md+ folder layout). - Skills support progressive disclosure: only name/description load initially; full instructions load when invoked.
- Skill scopes: repo (
.codex/skills/…), user (~/.codex/skills/…), and admin/system (/etc/codex/skills/…). - Security note: skills are executable/context-bearing packages; treat third-party skills as supply-chain inputs (audit, pin versions, prefer sandboxes/approvals).
AGILab working rules (repo policy)
- Use
uvfor all runs so dependencies resolve in managed envs:uv --preview-features extra-build-dependencies run python …uv --preview-features extra-build-dependencies run streamlit …
- No repo
uvx: do not runuvx agilabfrom this checkout (it will run the published wheel and ignore local changes). - Run config parity: after editing
.idea/runConfigurations/*.xml, regenerate wrappers:uv --preview-features extra-build-dependencies run python tools/generate_runconfig_scripts.py
- Streamlit API: do not add
st.experimental_rerun(); usest.rerun. - No silent fallbacks: avoid runtime “auto-fallbacks” between API clients or parameter rewrites; fail fast with actionable errors.
Common commands (from the runbook matrix)
- Dev UI:
cd "$PROJECT_DIR" && uv --preview-features extra-build-dependencies run streamlit run src/agilab/AGILAB.py -- --openai-api-key "…" --apps-dir src/agilab/apps - Apps-pages smoke:
cd "$PROJECT_DIR" && uv --preview-features extra-build-dependencies run python tools/smoke_preinit.py --active-app src/agilab/apps/builtin/flight_project --timeout 20 - Publish dry-run (TestPyPI):
cd "$PROJECT_DIR" && uv --preview-features extra-build-dependencies run python tools/pypi_publish.py --repo testpypi --dry-run --leave-most-recent --verbose
Troubleshooting reminders
- Missing import: check both manager and worker
pyproject.tomlscopes (src/agilab/apps/<app>/pyproject.tomlandsrc/agilab/apps/<app>/src/<app>_worker/pyproject.toml). - Installer pip issue: run
uv --preview-features extra-build-dependencies run python -m ensurepip --upgradeonce in the target venv.