Imported from rokuroku-066/business-agent-loop (AGENTS.md). Install upstream with npx skills add rokuroku-066/business-agent-loop. Copyright stays with the author.

AGENTS.md

Guidance for OpenAI Codex and other coding agents working on this repository.

The system design and business context for this project are documented separately (see docs/DESIGN.md). This file focuses on how to develop and maintain the codebase: environment setup, coding style, tests, and safety rules.

Setup commands

Standard setup (Linux / WSL, GPU environment)

From the repository root:

• Create and activate a Python virtual environment:

  • python3 -m venv .venv
  • source .venv/bin/activate

• Install core dependencies (gpt-oss-20b via vLLM, Harmony, OpenAI SDK):

  • uv pip install --upgrade pip
  • uv pip install --pre 'vllm==0.10.1+gptoss' \ --extra-index-url https://wheels.vllm.ai/gpt-oss/ \ --extra-index-url https://download.pytorch.org/whl/nightly/cu128 \ --index-strategy unsafe-best-match
  • uv pip install openai-harmony openai gpt-oss

• Start local inference server (if available):

  • ./scripts/run_vllm_server.sh

If scripts/setup_gpt_oss_env.sh exists:

• Prefer ./scripts/setup_gpt_oss_env.sh over manual steps above.
• Codex should reuse the existing .venv instead of creating new environments.

Platform notes

• Primary target is Linux / WSL with an NVIDIA GPU (16 GB VRAM+ recommended) running gpt-oss-20b via vLLM.
• On non-GPU or non-Linux systems, Codex should:
  • Still keep the same project structure and interfaces.
  • Stub / mock the local model server in tests rather than removing it.

Dev environment conventions

• Main language: Python (3.10+ recommended).

• Runtime: local gpt-oss-20b served via vLLM, using the Harmony response format.

• Expected layout:

  • config/ – IP profile and project configuration JSON.
  • scripts/ – setup and server scripts (e.g. setup_gpt_oss_env.sh, run_vllm_server.sh).
  • src/ – agent orchestrator, task loop, and supporting modules.
  • docs/ – DESIGN.md (detailed system design) and additional architecture notes.
  • tests/ – unit and integration tests.
  • state/, ideas/, iterations/, snapshots/ – runtime data generated by the agent.

Before making non-trivial changes, Codex should:

1. Read docs/DESIGN.md to understand the architecture and agent behavior.
2. Inspect config/ to see how IP profiles and project themes are configured.
3. Skim scripts/ to reuse existing entrypoints and conventions.
4. Confirm which modules under src/ already exist before adding new top-level packages.

Code style

Python style rules for this repository:

• Formatting

  • Use black with default settings.
  • If pyproject.toml contains black configuration, respect it.

• Linting

  • Use ruff as the primary linter.
  • Fix high-signal warnings (unused imports, dead code, obvious bugs).
  • It is acceptable to leave low-value style warnings if fixing them would create noisy diffs.

• Typing

  • Add type hints to public functions, dataclasses, and core models.
  • Use typing / typing_extensions (e.g. TypedDict, Protocol) where it improves clarity.
  • Prefer explicit return types on functions that hit external systems (model calls, filesystem).

• Structure

  • Keep model runtime + Harmony integration in a dedicated namespace, e.g. src/runtime/.
  • Keep agent orchestration logic (task queues, loops, stagnation detection) in src/agent/.
  • Put CLI / entrypoints in src/cli/ and keep them thin.
  • Avoid mixing business logic with I/O, logging, or CLI parsing.

• Error handling & logging

  • Avoid silent failures; prefer raising explicit exceptions or logging at appropriate levels.
  • Long-running loops should centralize error handling and retries rather than duplicating try/except blocks everywhere.

When Codex introduces new modules or dependencies, it should update existing config files (e.g. pyproject.toml, requirements.txt, ruff.toml) instead of inventing ad-hoc local rules.

Testing instructions

• Test framework: pytest.

• Default commands (from repo root):

  • Run all tests:
    • pytest
  • Run unit tests only (if split):
    • pytest tests/unit
  • Run integration tests (model + agent loop):
    • pytest tests/integration

Expectations for Codex:

• Whenever non-trivial behavior is added or changed, add or update tests under tests/.
• After each change set, run pytest and fix failures before treating the task as complete.
• For setup scripts and orchestration code, prefer smoke tests that at least:
  • Import key modules.
  • Instantiate primary classes / call main functions.
  • Validate configuration loading and basic wiring.

If there are no tests in an area yet, Codex should:

• Propose a minimal test layout for that area.
• Implement focused tests that cover the new behavior instead of building a heavy test framework.

Using web search and external references

This project expects Codex to consult up-to-date public documentation via web search when network access is enabled in the Codex environment:

• For gpt-oss: use the official GitHub repo and OpenAI docs to confirm:
  • Recommended vLLM versions.
  • Installation flags.
  • Supported runtimes and constraints.
• For vLLM: follow the latest guidance for gpt-oss integration (server flags, CUDA support, performance tips).
• For Harmony: refer to openai-harmony documentation for the exact response format and parsing helpers.
• For Codex and AGENTS.md: use the latest OpenAI docs and the AGENTS.md reference site to keep instructions aligned with current best practices.

When using internet access:

• Prefer official or highly reputable sources (OpenAI docs, official GitHub repositories, well-known libraries) over random blogs.
• Do not paste large blocks of third-party code with incompatible licenses into this repository.
• Summarize external guidance in comments or documentation instead of copying full articles.

If network access is disabled in the current Codex profile, Codex should:

• Rely on the local design docs (docs/) and existing code.
• Avoid assuming that HTTP requests or external tools are available.
• Clearly mark any behavior that would require internet access as a TODO with rationale.

Working with Codex

When Codex works on this repository, it should:

• Treat this AGENTS.md as the primary source of project-specific rules.
• Read docs/DESIGN.md before large refactors or when adding new agent behaviors.
• Keep changes scoped:
  • Prefer working within one module or feature per task.
  • Avoid cross-cutting refactors across the entire project unless explicitly requested.

Behavioral guidelines:

• Ask for human approval (via commit messages or comments) before:

  • Introducing new top-level dependencies.
  • Changing the way the main agent loop persists state.
  • Modifying setup scripts that may affect other environments.

• After code edits that touch Python modules:

  • Run the relevant tests (pytest, or narrower subset when appropriate).
  • Run formatters / linters if configuration is present:
    • black .
    • ruff check .

• Do not:

  • Commit secrets, tokens, API keys, or credentials.
  • Change AGENTS.md itself unless explicitly asked to update project rules.
  • Disable tests or safety checks just to “make CI green” without explanation.

Notes on long-running agent behavior

This project hosts an AI agent that runs long-lived planning and iteration loops for business idea generation and refinement.

Implementation expectations:

• Keep configuration for IP and project themes in config/ and treat those files as the single source of truth.
• Persist agent state (task queues, idea metadata, iteration logs) under state/, ideas/, iterations/, and snapshots/ using simple, inspectable formats (e.g., JSON, JSONL, Markdown).
• Do not introduce external databases, message queues, or vector stores unless the design doc is updated accordingly.

When modifying the agent loop, Codex should:

• Clearly document:
  • How stagnation / loop detection works.
  • How exploration vs. deepening modes are chosen.
  • Any resource-related assumptions (token limits per iteration, backoff strategy, schedule).
• Keep the loop logic testable by:
  • Isolating side effects (file I/O, model calls) behind interfaces that can be mocked.
  • Adding tests that simulate multiple iterations without actually running the real model.