Comfac SOP: Agentic AI Reverse-Engineering and Development Workflow

Target Audience: Comfac Staff, Interns, and Development Teams
Objective: Safely and systematically reverse-engineer, validate, and build upon third-party open-source GitHub repositories using agentic AI tools (OpenCode, ClaudeCode) while building internal institutional knowledge.

Introduction: The Power and the Peril

Agentic AI tools are incredibly powerful for accelerating development. However, they introduce two massive risks:

Prompt Injections: Unverified, third-party codebases can contain hidden prompt injections designed to hijack the AI agent and execute malicious commands on your local machine or steal API keys.
Hallucinations: AI agents will confidently invent APIs, libraries, and code structures if they lack grounded, up-to-date documentation.

To harness their power safely, Comfac has developed this mandatory 6-phase Standard Operating Procedure (SOP). This workflow balances AI speed with strict human validation.

Our ultimate goal is to build our own validated SDKs and architectural patterns for systems like Frappe, FreeCAD Workbenches, LibreOffice/OnlyOffice Addons, and Firefox/Thunderbird packages.

Phase 1: Security First – Isolation and Burner Accounts

NEVER unleash an autonomous coding agent directly on your primary development machine or use your primary GitHub account for initial exploration.

Action Items for Staff/Interns:

Before executing any agentic commands, you must establish an isolated sandbox and use a burner GitHub account. This contains the "blast radius" if an agent encounters a prompt injection.

You MUST follow the isolation techniques documented in our internal wikis exactly as written:

OpenCode Isolation Workflow: Opencode isolation and burner workflow 260216
Claude Code Isolation Workflow: Claude Code Isolation and Burner Workflow 260211

Phase 2: Structural Breakdown and Diagramming

Once your isolated environment and burner accounts are active, clone the target Git repository.

DO NOT ask the AI to write code yet.

Action Items for Staff/Interns:

Instruct the AI agent to crawl the downloaded directory and break down the architecture. Your prompt should look something like this:

"Crawl this repository. Do not write or modify any code. Generate a detailed markdown report breaking down the directory structure, core modules, and how they interact. Create a text-based architectural dependency diagram."

This step forces the AI to map the territory, giving the human team an immediate understanding of the system's baseline structure.

Phase 3: The Human Element – Mirroring SDKs (Intern Task)

AI agents often fail at scraping official documentation due to aggressive bot-protection on modern web hosts. This is a mandatory human task. You must print pages to PDF, copy-paste content into documents, or do whatever is necessary to extensively download all this knowledge. Once acquired, use your AI tools to rebuild and format the documentation, and then give it to Comfac to host.

Action Items for Interns:

Locate System Reference Designs, Developer Guides, or Software Development Kits (SDKs) for the target software.
Manually mirror (copy/paste/format) these documents into our internal Comfac Wikis. We will host and maintain these to absorb bot traffic.

Example: LibreOffice 25.8 Addons

If we are building LibreOffice extensions, interns must extract information from the LibreOffice Developer's Guide and SDK Overview. You must mirror:

Core Concepts: The Universal Network Objects (UNO) component technology.
SDK Structure: Definitions of the libraries, binaries, header, and IDL files.
Specific Examples: Mirror the exact code and descriptions for examples like the Python Tool Panel Poc (creates a ToolPanel in Calc) or the Java BookmarkInsertion tool.

By doing this, you create clean, bot-friendly, hallucination-free context links for our AI agents to ingest later.

Phase 4: Forking and Discrepancy Analysis

Never work on the main branch of an unknown repository.

Action Items for Staff/Interns:

Fork the target repository into your burner organization.
Instruct the AI to compare the actual codebase against the mirrored SDK documentation you just placed in the Comfac Wiki.

SDKs frequently fall out of date compared to the working codebase. The AI's job here is to flag discrepancies.

Example AI Prompt: "Compare the UNO component initialization in the actual Counter C++ demo in this repo against the LibreOffice SDK documentation provided at Comfac Wiki Link. List all discrepancies, deprecated API calls, and missing structural patterns."

Phase 5: Incremental Validation and Distributing POCs (Critical!)

This is the most critical phase: The Proof and Validation Process. Do not ask the AI to build the entire final product. Break the AI's structural understanding into bite-sized Proofs of Concept (POCs).

Action Items for the Team:

Distribute these micro-tasks across the development team.

User A: Have your agent recreate and run the C++ Counter UNO component independently.
User B: Have your agent test the LibreOffice Basic macro for Replacing Text to ensure it successfully enforces American English spelling.

Validation Rule: Multiple users must be able to independently recreate these proofs on their own isolated systems using the generated steps. If an AI generates a solution that only works on one specific machine, it is a failure. We require a validated, universally replicable architecture.

Phase 6: Scaling and Architectural Blueprinting

This rigorous process will cost tens of dollars in API tokens and take days of human effort. That is the expected cost of doing it right.

The output is immensely valuable: a set of validated, working SDKs, exact architectural blueprints, and proven workflows.

Action Items for Staff/Interns:

Take the successful, validated POCs and update the Comfac Wikis. These Wiki pages now become the primary context links we feed the AI for all future development.

Because we have done the hard work of validating the baseline, entry-level coders, non-coders, and students can now safely architect new modifications. We can eventually leave more powerful agentic tools to build components unsupervised, knowing they are strictly grounded in our meticulously curated, highly accurate Comfac Wiki knowledge base.