ChatGPT Codex Agent.md and environment setup script

*README.md

Getting Started with ChatGPT Codex + Mastra Agents

Step-by-Step Instructions

1. Open the ChatGPT Codex task setup panel. This is where you configure your environment before starting a task.

2. Locate the "Setup Script" field. You’ll see a note that internet access is disabled after the script runs.

3. Copy and paste the full contents of your setup.sh into the setup field. This will install the necessary tools, clone your repository, set up SPARC, and create your Mastra agent.

4. Run the task. The setup script will execute at the beginning. After that, internet access is shut off.

5. Begin coding with your Codex agent. Use the preloaded Mastra agent to help structure, refine, and test your code within the offline environment.

6. Check /workspace for all generated files. Code, tests, logs, and output will be organized per SPARC standards.

Notes

• You don’t need to install anything manually.
• Make sure your script includes everything needed before internet access is disabled.
• The Mastra agent will guide and optimize your code development and testing

agent.md

AGENT.md

Overview

This document outlines the operational standards and directory structure for autonomous ChatGPT Codex agents within an offline, air-gapped SPARC-based development environment. Agents must adhere to the SPARC methodology and operate in a secure, self-contained workspace without internet access post-setup.

---

SPARC Methodology Alignment

1. Specification

• Extract requirements from:

  • /specs/ folder (.md, .yaml, .json)
  • .spec.md files in root or module directories

• Must define:

  • task_id
  • summary
  • input, expected_output
  • constraints, evaluation_criteria

• Output: Test stub in /tests/.

2. Pseudocode

• Store in /pseudo/ using .md, .pseudo.js, or .pseudo.ts.

• Include:

  • Input/output annotations
  • Decision logic
  • Error handling

3. Architecture

• Store in /arch/ as:

  • .md text explanations
  • .uml diagrams (PlantUML/Mermaid)
  • .json component maps

• Document:

  • Module interfaces
  • Data flow
  • Dependencies

4. Refinement

• Code inside /src/, structured per architecture.
• Tests go in /tests/.
• Track refinement cycles in /logs/refinement.log.

5. Completion

• Triggered when:

  • All tests pass
  • Code coverage >90%
  • .completion.json is generated with metadata

• Output goes to /dist/.

---

Required Directory Structure

/workspace/
├── specs/           # Task definitions
├── pseudo/          # Pseudocode modules
├── arch/            # System diagrams and architecture docs
├── src/             # All source code
├── tests/           # All test cases
├── memory/          # Semantic memory and embeddings
├── logs/            # Execution and test logs
├── dist/            # Packaged artifacts
├── .env.template    # Placeholder for secure env vars
├── .completion.json # Completion metadata
├── .roomodes        # Roo mode definitions
└── .roo/            # Mode config and dependency manifest

---

Execution Environment Constraints

• Internet Access: Disabled post-setup.
• Dependencies: Use only local packages declared in .roo/dependencies.json.
• No Remote Fetches: Avoid npm, pip, curl, etc., after setup.
• Graceful Failure: If online behavior is invoked, fail gracefully.

---

Agent Command Modes

Mode	Description	Output Target
spec-mode	Parse .spec.md, generate test stubs	/tests/
pseudo-mode	Generate pseudocode scaffolds	/pseudo/
build-mode	Implement modules based on pseudocode	/src/
test-mode	Run tests offline, no telemetry	/logs/test_runs.log
finalize	Package outputs, generate .completion.json	/dist/, .completion.json

---

Test Strategy

• Use local runners (offline-runner.ts, local pytest).

• Store logs in:

  • /logs/test_runs.log
  • /logs/refinement.log

---

Security & Credential Handling

• Secrets: No plaintext secrets.
• Environment Variables: Use .env.template as reference.
• Access: Refer only via process.env.KEY.
• Logging: Never log secrets to files.

---

Commit and Versioning

• Use Conventional Commits:

  feat(login): add offline auth logic
  fix(utils): correct hashing salt bug
  test(login): add edge case coverage
  

• Append SPARC phase in brackets:

  chore(init): create scaffolding [sparc:spec]
  

• Tag completions:

  git tag -a complete-login-v1 -m "SPARC Completion"
  

---

Memory and State

• /memory/vector_store.json: Local vector memory only.

• Store:

  • Embeddings
  • Completion references
  • Related task links

---

Output Metadata Example

{
  "task_id": "login-flow-001",
  "commit": "d41d8cd9",
  "tests_passed": true,
  "coverage": "91.2%",
  "timestamp": "2025-05-16T23:00:00Z",
  "output_files": [
    "src/login/index.ts",
    "tests/login.test.ts"
  ]
}

---

Final Notes

This specification is mandatory for Codex agents operating offline within SPARC-aligned environments. All output must be self-contained, secure, and verifiable.

Version: SPARC-Agent-Spec v1.2.0 Maintainer: ruvnet/ruv-dev

---

setup.sh

#!/bin/bash

set -e

# 1. Clone the specified repository into /workspace
echo "Cloning repository into /workspace..."
git clone https://gist.github.com/ba1497632143ea9f12062c9c2c1879ad.git /workspace

# 2. Navigate to the workspace directory
cd /workspace

# 3. Initialize a SPARC project
echo "Initializing SPARC project..."
npx create-sparc init --force

# 4. Install Mastra CLI globally
echo "Installing Mastra CLI globally..."
npm install -g mastra

# 5. Install core and dev NPM libraries
echo "Installing NPM packages (Mastra, Jest, TypeScript)..."
npm install \
  @mastra/core \
  @types/jest \
  ts-jest \
  jest \
  typescript \
  sqlite3 \
  @fastify/sqlite \
  dotenv

# 6. Create Mastra directory structure
echo "Setting up Mastra agent structure..."
mkdir -p src/mastra/agents

# 7. Create a basic Mastra agent
cat <<EOL > src/mastra/agents/agent.ts
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new Agent({
  name: "my-agent",
  instructions: "You are a helpful assistant.",
  model: openai("gpt-4o-mini"),
});
EOL

# 8. Create Mastra index file to register the agent
cat <<EOL > src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { myAgent } from "./agents/agent";

export const mastra = new Mastra({
  agents: { myAgent },
});
EOL

# 9. Set up .env.template for environment variables
echo "Setting up .env.template..."
cat <<EOL > .env.template
# Add your environment variables here
OPENAI_API_KEY=your-openai-api-key
DATABASE_URL=sqlite:///./dev.db
EOL

# 10. Set up Python backend: FastAPI, FastMCP, SQLite, Pydantic
echo "Setting up Python backend environment..."
python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install \
  fastapi \
  "uvicorn[standard]" \
  fastmcp \
  pydantic \
  sqlite-utils

deactivate

echo "Setup complete. The environment is now ready for offline use."