Skip to content

Core Architecture & Operational Invariants

gosec adheres to strict architectural patterns engineered specifically for high-efficiency Go development and AI pair programming with Antigravity.

1. Zero-CGo Static Go Architecture

Every package and binary in gosec compiles cleanly with CGO_ENABLED=0. - The SQLite database engine uses modernc.org/sqlite—a 100% pure-Go transpilation of SQLite that requires no C compiler, headers, or dynamic linkers. - Binaries are compiled with -ldflags="-s -w" for minimal footprint and instant startup.

2. Antigravity-First AI Tooling & Progressive Disclosure

gosec is designed ground-up for Google Antigravity (IDE, CLI agy, skills runtime, and hierarchical rules): - Root Policy Files: AGENTS.md and GEMINI.md establish authoritative project invariants discovered automatically by AI agents. - Hierarchical Invariants (.agents/rules/): - single-task-discipline.md: Enforces exactly ONE active task at any moment. - local-llm-tiering.md: Tier 0/1 local Ollama with seamless cloud fallback. - session-continuity.md: Cross-turn state persistence in local/SESSION_MEMORY.md. - local-binaries.md: Mandatory recompilation to bin/ upon code modifications. - pre-implementation-research.md: Zero training-cutoff assumptions via live research. - Skills (.agents/skills/): Progressive disclosure instruction manuals loaded on-demand by Antigravity agents.

3. The 6-Phase Engineering Lifecycle

Every capability implemented in gosec follows an immutable lifecycle tracked inside the SQLite backlog:

flowchart LR
    Backlog["1. Backlog"] --> Research["2. Research"]
    Research --> TDD["3. TDD"]
    TDD --> Verification["4. Verification"]
    Verification --> Documentation["5. Documentation"]
    Documentation --> Release["6. Release"]
Hold "Alt" / "Option" to enable pan & zoom
  1. Backlog: Registered in local/backlog.sqlite with explicit acceptance criteria.
  2. Research: Live documentation review and signature verification.
  3. TDD: Unit and integration tests written first (go test -v -race).
  4. Verification: Static analysis, linting, and binary compilation.
  5. Documentation: User documentation and memory dump update.
  6. Release: Version tagging, release packaging, and push.

4. Rule 14: Mandatory AI MCP Coverage

Every major capability must be delivered across three surfaces: 1. Go Package (pkg/<name>): Reusable Go API. 2. CLI Command (cmd/gosec): Human-friendly terminal command. 3. MCP Tool (cmd/mcp-server): Strongly typed JSON-RPC tool for Antigravity agents.