Viziora x Codex CLI — 10X Expert Course (Advanced)

Run:
cd /code/viziora
git status
git checkout -b course/codex-10x-setup

Run:
mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
profile = "fast"

[profiles.fast]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model_reasoning_effort = "medium"

[profiles.deep_review]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model_reasoning_effort = "high"
EOF

Run:
cat > ~/.codex/AGENTS.md <<'EOF'
- Explain new words the first time you use them.
- Give exact steps using: Run: ...
- After edits: run checks and report results.
- Keep changes small.
EOF

Run:
cd /code/viziora
cat > AGENTS.md <<'EOF'
- Keep changes small and testable.
- Backend: run pytest.
- Web: run pnpm build (or lint).
- For agent/chat: never guess; show SQL; enforce safe query checks.

Reference docs:
- docs/system-overview.md
EOF

git add AGENTS.md || true
git commit -m "chore: add Viziora Codex working agreements" || true

Run:
cd /code/viziora
codex --profile fast

Type in Codex:
/fast

Then ask:
"Summarize what fast mode changes, and when I should NOT use it."

Type in Codex:
/status
/new
/fork

Run:
cd /code/viziora
codex resume
codex fork

Run:
cd /code/viziora
git checkout main

git checkout -b feat/e2e-tests
git -C /code/viziora worktree add /code/viziora-wt-e2e feat/e2e-tests

git checkout main
git checkout -b feat/runlog-ui
git -C /code/viziora worktree add /code/viziora-wt-runlog feat/runlog-ui

Terminal 1:
cd /code/viziora-wt-e2e
codex --profile fast

Terminal 2:
cd /code/viziora-wt-runlog
codex --profile fast

Type in Codex:
/experimental
# enable multi-agents
# restart Codex

Run:
mkdir -p /code/viziora/.codex/agents
cat > /code/viziora/.codex/config.toml <<'EOF'
[features]
multi_agent = true

[agents]
max_threads = 6
max_depth = 1

[agents.reviewer]
description = "Checks correctness, safety, missing tests."
config_file = "agents/reviewer.toml"

[agents.tester]
description = "Writes and improves tests."
config_file = "agents/tester.toml"

[agents.explorer]
description = "Reads code to find execution path. No edits."
config_file = "agents/explorer.toml"
EOF

cat > /code/viziora/.codex/agents/reviewer.toml <<'EOF'
sandbox_mode = "read-only"
model_reasoning_effort = "high"
developer_instructions = "Reviewer: find correctness, safety, missing tests. Return top 3 risks first."
EOF

cat > /code/viziora/.codex/agents/tester.toml <<'EOF'
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"
developer_instructions = "Tester: write tests only. Prefer small reliable tests."
EOF

cat > /code/viziora/.codex/agents/explorer.toml <<'EOF'
sandbox_mode = "read-only"
model_reasoning_effort = "medium"
developer_instructions = "Explorer: cite exact files and symbols. No edits."
EOF

Type in Codex:
Create /tmp/viziora_modules.csv with columns path,owner and one row per important backend module.
Then call spawn_agents_on_csv with:
- csv_path: /tmp/viziora_modules.csv
- id_column: path
- instruction: "Review {path}. Return JSON with keys path, risk, missing_tests, quick_fix via report_agent_job_result."
- output_csv_path: /tmp/viziora_modules_review.csv
- output_schema: required string fields: path, risk, missing_tests, quick_fix
- max_concurrency: 4

Run:
cd /code/viziora
codex cloud exec --env ENV_ID --attempts 2 "Add Playwright e2e tests for Viziora web:
- install Playwright
- add 2 tests: upload dataset; ask chat question and render chart
- add a command to run tests
- update README with how to run e2e tests"

Run:
codex cloud list --env ENV_ID --limit 10
codex apply TASK_ID

Type in Codex:
/ps

Type in Codex:
Write tools/summarize_run_logs.py to summarize a JSONL log file.
Add make summarize-logs LOG=...
Write docs/reports/run-log-summary.md
Add a tiny test for parsing.

Run:
cd /code/viziora
mkdir -p tools
cat > tools/validateVegaSpec.mjs <<'EOF'
export function validateSpec(spec) {
  if (!spec || typeof spec !== "object") return { ok: false, error: "spec is not an object" };
  if (!spec.mark) return { ok: false, error: "missing mark" };
  if (!spec.encoding || typeof spec.encoding !== "object") return { ok: false, error: "missing encoding" };
  return { ok: true };
}
EOF

Use js_repl to import ./tools/validateVegaSpec.mjs and validate:
const spec = { mark: "bar", encoding: { x: {field:"region"}, y: {field:"revenue"} } }

Run:
node -e "import('./tools/validateVegaSpec.mjs').then(m => console.log(m.validateSpec({mark:'bar',encoding:{x:{field:'region'},y:{field:'revenue'}}})))"

Run:
cd /code/viziora
mkdir -p .agents/skills/viziora-e2e-tests
cat > .agents/skills/viziora-e2e-tests/SKILL.md <<'EOF'
---
name: viziora-e2e-tests
description: Use this when adding or updating Playwright end-to-end tests for Viziora web.
---
Workflow:
- Smallest test first
- Avoid fixed sleeps
- Run tests and fix flakiness
EOF

mkdir -p .agents/skills/viziora-chat-evals
cat > .agents/skills/viziora-chat-evals/SKILL.md <<'EOF'
---
name: viziora-chat-evals
description: Use this when adding or improving the evaluation set for Viziora chat behavior.
---
Rules:
- Deterministic checks
- SQL must exist for computed claims
- SQL must be safe
EOF

git add .agents/skills
git commit -m "chore(skills): add Viziora skills" || true

Type in Codex:
Build tools/report_code_health.py to output a markdown and CSV report in docs/reports/.
Add make report-health.
Add a skill to run it.
Keep changes small and testable.

Run:
cd /code/viziora
codex app-server --listen ws://127.0.0.1:8787

Run:
codex debug app-server send-message-v2 "Summarize the Viziora repo and point to key files."

Plan only:
Build mcp/viziora_mcp_server.py with tools:
- list_datasets
- dataset_schema(dataset_id)
- run_safe_query(dataset_id, sql) with safety checks
Add mcp/README.md and show "codex mcp add" steps.
Do not implement yet.

Run:
cd /code/viziora
git checkout -b feat/evals-dashboard

Ship "Viziora chat eval dashboard".

Spawn:
- explorer: locate eval code + where to add endpoint + page.
- reviewer: list risks (leaks, unsafe SQL, flakiness).
- tester: design tests.

Wait for all results.
Then give a step-by-step plan with checks after each step.