Copy page

Microservices

Workflow & Planning Rules (Tic-Toc)

Workflow & Planning Rules (Tic-Toc)

Relevant source files

The following files were used as context for generating this wiki page:

• .devin/rules/always-check-rules-first.md
• .devin/rules/data-model-conventions.md
• .devin/rules/workflow.md

The Tic-Toc Planning cycle is a mandatory governance framework for AI agents and developers operating within the Primebrick v3 microservices repository. It ensures that every modification—whether a feature, bugfix, or refactor—is preceded by a rigorous analysis and a formal approval gate. This process is coupled with strict data-model conventions to maintain high portability and system-wide consistency.

1. The Tic-Toc Planning Cycle

The Tic-Toc cycle is designed to prevent "drift" and uncoordinated changes by forcing a separation between the Analysis Phase and the Execution Phase.

1.1 Phase 1: Analysis & Plan Generation

Upon receiving a request (feature, refactor, or bugfix), the agent must first perform a read-only analysis of the codebase. During this phase, any modification to source files is strictly forbidden .devin/rules/workflow.md:11-11.

The agent then generates a structured Markdown plan file. These files are stored in a dedicated directory to maintain a history of architectural decisions:

• Location: ai-plans/ .devin/rules/workflow.md:12-12
• Format: Markdown (.md) .devin/rules/workflow.md:12-12
• Content: Must include objectives, impacted files, architectural changes, and precise acceptance criteria with code examples .devin/rules/workflow.md:13-13.

1.2 Phase 2: The PROCEED Gate

Once the plan is generated, the system enters a MANDATORY BLOCKER state. The agent is required to output a specific status message and halt all execution .devin/rules/workflow.md:14-15.

The PROCEED Workflow:

1. Agent creates ai-plans/feature-name-plan.md.
2. Agent outputs: "Planning complete. I have created the plan file inside your ai-plans folder. Awaiting approval." .devin/rules/workflow.md:14-14
3. Halt: No terminal commands, sub-agents, or file writes are permitted .devin/rules/workflow.md:15-15.
4. User Action: The user reviews the plan.
5. Resume: Execution only continues after the user explicitly sends the keyword: "PROCEED" .devin/rules/workflow.md:15-15.

Tic-Toc Execution Flow

The following diagram illustrates the transition from natural language requirements to the formal planning state.

Diagram: Requirement to Plan Transition

Code
graph TD
    subgraph "Natural Language Space"
        REQ["User Requirement (Feature/Bug)"]
    end

    subgraph "Analysis Phase (Read-Only)"
        CHECK["Check .devin/rules/"]
        SCAN["Scan Codebase"]
    end

    subgraph "Code Entity Space (Planning)"
        PLAN_GEN["Create ai-plans/*.md"]
        BLOCKER["MANDATORY BLOCKER"]
    end

    REQ --> CHECK
    CHECK --> SCAN
    SCAN --> PLAN_GEN
    PLAN_GEN --> BLOCKER
    BLOCKER -- "Awaiting 'PROCEED'" --> EXEC["Execution Phase"]

    style BLOCKER stroke-width:4px

Sources: .devin/rules/workflow.md:7-15, .devin/rules/always-check-rules-first.md:11-17

---

2. Data Model Conventions

The repository enforces a "Zero-Rename" policy and strict snake_case naming to ensure maximum portability across the database, TypeScript services, and JSON API responses.

2.1 Snake_case Everywhere

All identifiers—Database columns, TypeScript interfaces, and JSON keys—must use snake_case .devin/rules/data-model-conventions.md:12-13.

Layer	Convention	Example
Database	snake_case	oidc_issuer_url
TS Interface	snake_case	interface Config { oidc_issuer_url: string; }
JSON API	snake_case	{ "oidc_issuer_url": "..." }

The Zero-Rename Policy: Field names must be identical across all internal layers. Renaming oidc_issuer_url to oidcIssuerUrl (camelCase) is strictly forbidden, except at the boundary of an External API adapter .devin/rules/data-model-conventions.md:14-16.

2.2 Read/Write Path Fidelity

To ensure data integrity, the codebase distinguishes between the "Read Path" (fetching data) and the "Write Path" (upserting data).

• Read Path (Forbidden Transformations): No lowercasing, trimming, or data-quality normalization is allowed during a read. The system must return exactly what is in the database .devin/rules/data-model-conventions.md:26-26.
• Write Path (Enforcement): All data quality enforcement (validation, normalization) must occur at the API upsert/write stage .devin/rules/data-model-conventions.md:26-26.
• No Fake Defaults: For configuration data (Auth, Gateway, etc.), the system must never use fallback defaults like || "http://localhost". If a value is missing, the system must throw an error or return undefined .devin/rules/data-model-conventions.md:35-38.

2.3 Implementation: No DTO Transformation

Intermediate Data Transfer Objects (DTOs) that rename fields are prohibited. The database row result should be treated as the TypeScript model .devin/rules/data-model-conventions.md:18-20.

Preferred Pattern: Instead of field-by-field rebuilding, developers must use the spread operator to pass raw results through the system .devin/rules/data-model-conventions.md:21-21.

Diagram: Data Flow Fidelity

Code
flowchart LR
    subgraph "Database (PostgreSQL)"
        DB_COL["column: user_email_address"]
    end

    subgraph "Data Access Layer (TypeScript)"
        ENTITY["interface UserEntity { user_email_address: string }"]
    end

    subgraph "API Layer (Express/HTTP)"
        JSON_RES["{ 'user_email_address': '...' }"]
    end

    DB_COL -- "Raw Fetch (No Rename)" --> ENTITY
    ENTITY -- "res.json({...entity})" --> JSON_RES

    style DB_COL stroke-dasharray: 5 5
    style JSON_RES stroke-dasharray: 5 5

Sources: .devin/rules/data-model-conventions.md:12-21, .devin/rules/data-model-conventions.md:29-33

---

3. Mandatory Pre-Action Checklist

Before any action is taken (file creation, terminal command, or planning), the agent must verify compliance with the governance rules .devin/rules/always-check-rules-first.md:7-8.

3.1 Verification Steps

1. Read .devin/rules/: List and read all governance files .devin/rules/always-check-rules-first.md:13-13.
2. Identify Scope: Determine which rules (Workflow, Data Model, etc.) apply to the current task .devin/rules/always-check-rules-first.md:15-15.
3. Verify Paths: Ensure file operations follow the paths defined in the rules (e.g., placing plans in ai-plans/), regardless of existing project patterns .devin/rules/always-check-rules-first.md:16-16.

3.2 Forbidden Behaviors

• Copying existing file patterns without checking rules first .devin/rules/always-check-rules-first.md:20-20.
• Assuming "typical" file locations .devin/rules/always-check-rules-first.md:21-21.
• Skipping rule-checking for tasks deemed "obvious" .devin/rules/always-check-rules-first.md:22-22.

Sources: .devin/rules/always-check-rules-first.md:10-23

---