From 98cb570e9666ba434bef80e7275116c1a960ea02 Mon Sep 17 00:00:00 2001 From: root Date: Tue, 14 Apr 2026 12:03:46 -0300 Subject: [PATCH] Portable setup: venv, Claude Code + Codex project config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Makes the skill work on any laptop regardless of installed Python version or LLM harness, without per-command approval prompts or missing deps. - Makefile: auto-detect Python (venv > 3.12 > 3.11 > 3.10 > python3) and new `make venv` target that picks the best Python at creation time - .claude/settings.json: project-level Claude Code permissions (Write to examples/ and output/, common bash commands pre-authorized) - .codex/config.toml: Codex sandbox config with network_access=true, approval_policy=never, sandbox_mode=workspace-write — fixes `make venv` failing with "No matching distribution" in Codex - CLAUDE.md / AGENTS.md: document the `make venv` flow, drop all hardcoded python3.12 references in favor of make targets - CLAUDE.md: add Karpathy-style coding guidelines (think before coding, simplicity first, surgical changes, goal-driven execution) - .gitignore: add .venv/ Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/settings.json | 20 ++++++++++ .codex/config.toml | 21 +++++++++++ .gitignore | 1 + AGENTS.md | 45 ++++++++++++---------- CLAUDE.md | 88 +++++++++++++++++++++++++++++-------------- Makefile | 20 +++++++++- codex/README.md | 17 ++++++++- 7 files changed, 161 insertions(+), 51 deletions(-) create mode 100644 .claude/settings.json create mode 100644 .codex/config.toml diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..eb98507 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,20 @@ +{ + "permissions": { + "allow": [ + "Read(**)", + "Write(examples/**)", + "Write(output/**)", + "Bash(python3.12:*)", + "Bash(python3:*)", + "Bash(.venv/bin/python:*)", + "Bash(make:*)", + "Bash(git:*)", + "Bash(pip:*)", + "Bash(pip3:*)", + "Bash(pip3.12:*)", + "Bash(ls:*)", + "Bash(which:*)", + "Bash(find:*)" + ] + } +} diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..28d0c68 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,21 @@ +# Codex project configuration for OCI Deal Accelerator +# Applies to every user who opens this project with Codex CLI. + +# Allow the agent to run commands without per-command approval prompts. +approval_policy = "never" + +# Workspace-write: agent can write inside the project root but not system-wide. +sandbox_mode = "workspace-write" + +[sandbox_workspace_write] +# Allow network access so `pip install -r requirements.txt` and `make venv` +# can actually download dependencies. Without this, Codex blocks PyPI. +network_access = true +writable_roots = [] +exclude_tmpdir_env_var = false +exclude_slash_tmp = false + +[shell_environment_policy] +# Inherit the user's shell env so python3.12 / python3 resolution works +# the same way as the Makefile expects. +inherit = "all" diff --git a/.gitignore b/.gitignore index c5c1e77..7005c50 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.venv/ __pycache__/ *.pyc *.pyo diff --git a/AGENTS.md b/AGENTS.md index 583f268..f2c7ff4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,32 +85,39 @@ DEFINE (Ideate → Validate → Plan) → DESIGN (Current → Future → Confi Phase details in `docs/` — skill references them via progressive disclosure. +## Environment Setup (MANDATORY before running tools) + +```bash +make venv && source .venv/bin/activate +``` + +The Makefile auto-detects the best available Python (3.12 > 3.11 > 3.10 > python3). +**Always use `make ` to run tools.** For custom specs, activate the venv first. + +### Codex sandbox note + +This project ships `.codex/config.toml` which enables `network_access = true` +for the workspace-write sandbox. This is required so `make venv` can reach +PyPI. If you see `No matching distribution found for pyyaml`, the config file +is missing or Codex is ignoring it — re-open the project from its root so +Codex loads `.codex/config.toml`. + ## Running Tools ```bash -# Generate slide deck (default output) +# Standard targets (recommended) +make deck # slide deck with sample spec +make diagram # architecture diagram +make full # all outputs (pptx + drawio + docx + xlsx + pdf) +make validate # WA validation +make lint # check YAML syntax +make venv # create/update virtual environment + +# Custom specs (activate venv first) python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx - -# Generate customer-facing PDF (branded, no internal KB refs) python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf - -# Generate diagram python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio - -# Run WA validation -python scripts/validate-architecture.py \ - --profile examples/sample-workload-profile.yaml \ - --architecture examples/sample-architecture.yaml \ - --output scorecard.yaml - -# Output orchestrator (multiple formats at once) python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/ - -# Build automation -make help # show all commands -make full # generate all outputs -make validate # run WA validation -make lint # check YAML syntax ``` ## Output Formats diff --git a/CLAUDE.md b/CLAUDE.md index 9161942..92d7fae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,47 +110,44 @@ doc only ← technical doc without slides deliver ← handover + go-live checklist + success criteria ``` -## Running Tools +## Environment Setup + +Before running ANY Python tool, ensure dependencies are installed: ```bash -# Generate slide deck (default output) +make venv && source .venv/bin/activate +``` + +The Makefile auto-detects the best available Python (3.12 > 3.11 > 3.10 > python3). +**Always use `make ` to run tools** — this guarantees the correct Python with all dependencies. + +## Running Tools + +Prefer `make` targets. For custom specs, activate the venv first (`source .venv/bin/activate`), then use `python`: + +```bash +# Standard targets (recommended) +make deck # slide deck with sample spec +make diagram # architecture diagram +make full # all outputs (pptx + drawio + docx + xlsx + pdf) +make validate # WA validation +make lint # check YAML syntax +make venv # create/update virtual environment +make freshness # check KB freshness + +# Custom specs (activate venv first) python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx - -# Generate customer-facing PDF (branded, no internal KB refs) python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf -python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf --diagram arch.png - -# Generate BOM (.xlsx Bill of Materials) python tools/oci_bom_gen.py --spec examples/bom-spec.yaml --output customer-bom.xlsx - -# Generate diagram python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio - -# Run WA validation -python scripts/validate-architecture.py \ - --profile examples/sample-workload-profile.yaml \ - --architecture examples/sample-architecture.yaml \ - --output scorecard.yaml - -# Output orchestrator (multiple formats at once) python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/ -# Refresh SKU catalog from Oracle pricing API +# KB maintenance (activate venv first) python tools/refresh_sku_catalog.py --refresh # update all prices python tools/refresh_sku_catalog.py --refresh --diff # update + show changes python tools/refresh_sku_catalog.py --validate # check for stale prices -python tools/refresh_sku_catalog.py --sku B110627 # inspect single SKU - -# Refresh Architecture Center catalog -python tools/refresh_arch_catalog.py --whats-new # crawl What's New pages -python tools/refresh_arch_catalog.py --url # add single entry +python tools/refresh_arch_catalog.py --whats-new # crawl What's New pages python tools/refresh_arch_catalog.py --validate # validate catalog - -# Build automation -make help # show all commands -make full # generate all outputs -make validate # run WA validation -make lint # check YAML syntax ``` ## Key Principles @@ -162,6 +159,39 @@ make lint # check YAML syntax - **KB is the moat** — field experience, not documentation regurgitation - **ECAL-aligned** — Define → Design → Deliver with iterative checkpoints +## Coding Guidelines + +### 1. Think Before Coding +Don't assume. Don't hide confusion. Surface tradeoffs. +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them — don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +### 2. Simplicity First +Minimum code that solves the problem. Nothing speculative. +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +### 3. Surgical Changes +Touch only what you must. Clean up only your own mess. +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it — don't delete it. +- Remove imports/variables/functions that YOUR changes made unused. +- Every changed line should trace directly to the user's request. + +### 4. Goal-Driven Execution +Define success criteria. Loop until verified. +- "Add validation" → write tests for invalid inputs, then make them pass. +- "Fix the bug" → write a test that reproduces it, then make it pass. +- "Refactor X" → ensure tests pass before and after. +- For multi-step tasks, state a brief plan with verification steps. + ## Welcome Flow When the user starts a conversation without providing discovery notes or a specific request (e.g., a greeting like "hola", "hey", or empty context): diff --git a/Makefile b/Makefile index 89adec1..fc60532 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,14 @@ .PHONY: help install test validate example diagram deck full clean lint codex-package update-icons freshness freshness-refresh sync-skill -PYTHON ?= python3.12 +# Use venv if present, otherwise find best available python3 +ifneq (,$(wildcard .venv/bin/python)) + PYTHON ?= .venv/bin/python +else ifneq (,$(shell command -v python3.12 2>/dev/null)) + PYTHON ?= python3.12 +else + PYTHON ?= python3 +endif SPEC_DIR = examples OUTPUT_DIR = examples/sample-output @@ -10,7 +17,16 @@ help: ## Show this help @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \ awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' -install: ## Install Python dependencies +VENV_PYTHON := $(shell command -v python3.12 2>/dev/null || command -v python3.11 2>/dev/null || command -v python3.10 2>/dev/null || echo python3) + +venv: ## Create virtual environment and install dependencies + @echo "Using $(VENV_PYTHON) to create venv..." + $(VENV_PYTHON) -m venv .venv + .venv/bin/pip install --upgrade pip + .venv/bin/pip install -r requirements.txt + @echo "Virtual environment ready. Run: source .venv/bin/activate" + +install: ## Install Python dependencies (system-wide) pip install -r requirements.txt validate: ## Validate imports and configs diff --git a/codex/README.md b/codex/README.md index 0f21535..9cf8c83 100644 --- a/codex/README.md +++ b/codex/README.md @@ -8,7 +8,10 @@ # Navigate to the project root cd oci-deal-accelerator -# Run Codex — it auto-discovers AGENTS.md and .agents/skills/ +# One-time: create virtual environment with all dependencies +make venv + +# Run Codex — it auto-discovers AGENTS.md, .agents/skills/, and .codex/config.toml codex # Or explicitly load the skill @@ -18,6 +21,18 @@ codex --skill oci-deal-accelerator Codex automatically reads: - `AGENTS.md` at project root (project-level instructions) - `.agents/skills/oci-deal-accelerator/SKILL.md` (the skill definition) +- `.codex/config.toml` (project sandbox + approval config — **enables network for pip**) + +### Why `.codex/config.toml` matters + +By default Codex CLI blocks network access and prompts before every command. +The committed `.codex/config.toml` pre-configures this project with: + +- `approval_policy = "never"` — no per-command prompts +- `sandbox_mode = "workspace-write"` — agent can write in the repo +- `network_access = true` — `pip install` and `make venv` actually work + +Without this file, `make venv` fails with `No matching distribution found for pyyaml` because PyPI is unreachable from the sandbox. ### Option 2: Using Codex App