advanced-calc-engine: Instructions file for Codex

AdvancedCalc Engine

Project Purpose

AdvancedCalc Engine is an agentic Excel analysis and calculation platform.

The system uses OpenCode agents, MCP tools and Python to:

1. Understand Excel workbook structure.
2. Analyze user requests.
3. Create an execution plan.
4. Execute calculations.
5. Modify Excel workbooks safely.
6. Validate results.
7. Run automated tests.
8. Maintain an audit trail.

Architecture

The system contains:

• Architect Agent
• Engineer Agent
• Validation Agent
• Security Auditor Agent
• Excel Metadata Tool
• Calculation Engine
• Formula Writer
• Workbook Validator
• MCP Server
• Pytest validation
• Audit logging

Core Rules

1. Analyze before modifying.
2. Never blindly modify a workbook.
3. Never overwrite source data unless explicitly requested.
4. Create backups before destructive operations.
5. Validate workbook structure before calculations.
6. Validate results after modification.
7. Never silently ignore errors.
8. Log important operations.
9. Never expose secrets.
10. Never execute unrestricted arbitrary Python code.

Agent Responsibilities

Architect:

• Analyze
• Plan
• Do not modify

Engineer:

• Execute
• Calculate
• Modify approved workbook areas

Validator:

• Independently verify results
• Do not modify the workbook

Security Auditor:

• Identify security risks
• Do not modify application code

Python Standards

Use:

• Type hints
• Pydantic models
• Clear function boundaries
• Exception handling
• Logging
• Pytest
• Small testable functions

Excel Safety

Before modifying Excel:

1. Verify file exists.
2. Verify worksheet exists.
3. Verify expected columns exist.
4. Verify target range.
5. Create backup.
6. Apply changes.
7. Reopen workbook.
8. Validate changes.

Security

Never:

• Execute arbitrary user Python.
• Read .env secrets through tools.
• Expose API keys.
• Delete files without approval.
• Modify unrelated workbooks.