# Workflow & Planning Rules (Tic-Toc)

# Workflow & Planning Rules (Tic-Toc)

<details>
<summary>Relevant source files</summary>

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

- [.devin/rules/always-check-rules-first.md](.devin/rules/always-check-rules-first.md)
- [.devin/rules/data-model-conventions.md](.devin/rules/data-model-conventions.md)
- [.devin/rules/workflow.md](.devin/rules/workflow.md)

</details>



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**
```mermaid
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**
```mermaid
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]()

---