OGT Docs

OGT Docs - Documentation as Source of Truth

Philosophy

Documentation is the database of decisions. Code is merely its implementation.

┌─────────────────────────────────────────────────────────────────┐
│                    THE DOC-FIRST PRINCIPLE                      │
├─────────────────────────────────────────────────────────────────┤
│  1. Documentation DEFINES what something IS                     │
│  2. Code IMPLEMENTS what documentation specifies                │
│  3. Conflicts RESOLVE in favor of documentation                 │
│                                                                 │
│  If docs say X and code does Y → CODE IS WRONG                  │
└─────────────────────────────────────────────────────────────────┘

When to Use This Skill

Use ogt-docs when you need to:

For specific tasks, use the specialized sub-skills listed below.

Documentation Structure Overview

docs/
├── definitions/              # WHAT things ARE
│   ├── business/             # Business model, pricing, users
│   ├── features/             # Product features and specs
│   ├── technical/            # Architecture, services, data
│   └── domain/               # Domain-specific concepts
│
├── rules/                    # HOW to IMPLEMENT
│   ├── code/                 # Coding standards
│   │   ├── frontend/
│   │   ├── backend/
│   │   └── infra/
│   ├── git/                  # Version control rules
│   └── domain/               # Domain-specific rules
│
├── todo/                     # TASK management
│   ├── pending/              # Not started
│   ├── in_progress/          # Being worked on
│   ├── review/               # Awaiting review
│   ├── blocked/              # Cannot proceed
│   ├── done/                 # Completed & verified
│   └── rejected/             # Declined tasks
│
├── guides/                   # HOW-TO documents
│   └── {topic}/
│
└── social/                   # Marketing & communications
    ├── campaigns/
    ├── content/
    └── branding/

The Folder-as-Entity Pattern

Every documentable item is a folder containing:

{item_slug}/
├── {type}.md                 # Primary document (task.md, feature.md, etc.)
├── {supporting_files}.md     # Additional documentation
└── .{signal_files}           # Status markers and metadata

Benefits:

Sub-Skills Reference

Definitions (WHAT things ARE)

| Sub-Skill | Purpose | Use When | | --------------------------- | ------------------------------ | --------------------------------- | | ogt-docs-define | General definition guidance | Need overview of definition types | | ogt-docs-define-business | Business model, pricing, users | Defining business concepts | | ogt-docs-define-feature | Product features and specs | Specifying a new feature | | ogt-docs-define-code | Technical architecture | Defining services, data models | | ogt-docs-define-marketing | Brand, messaging, audience | Marketing definitions | | ogt-docs-define-branding | Visual identity, tone | Brand guidelines | | ogt-docs-define-tools | Tooling and CLI specs | Defining developer tools |

Rules (HOW to IMPLEMENT)

| Sub-Skill | Purpose | Use When | | --------------------------- | ------------------------- | --------------------------- | | ogt-docs-rules | General rules guidance | Need overview of rule types | | ogt-docs-rules-code | Coding standards overview | General code rules | | ogt-docs-rules-code-front | Frontend-specific rules | React, CSS, components | | ogt-docs-rules-code-back | Backend-specific rules | API, database, services | | ogt-docs-rules-code-infra | Infrastructure rules | Docker, CI/CD, deployment | | ogt-docs-rules-git | Version control rules | Commits, branches, PRs |

Tasks (WHAT to DO)

| Sub-Skill | Purpose | Use When | | ---------------------- | ----------------------- | ------------------------------ | | ogt-docs-create-task | Create and manage tasks | Need to create/update a task | | ogt-docs-audit-task | Verify task completion | Checking if task is truly done |

Other

| Sub-Skill | Purpose | Use When | | ------------------------ | ------------------------- | --------------------------------- | | ogt-docs-create | General creation guidance | Need to create any doc type | | ogt-docs-create-social | Marketing content | Creating social/marketing content | | ogt-docs-audit | General audit guidance | Auditing documentation | | ogt-docs-init | Initialize docs structure | Setting up new project | | ogt-docs-config | Configuration options | Customizing docs workflow |

Workflow Overview

flowchart TB
    subgraph define ["1. DEFINE"]
        D1[Create Definition]
        D2[Get Approval]
    end
    subgraph regulate ["2. REGULATE"]
        R1[Create Rules]
        R2[Add Examples]
    end
    subgraph implement ["3. IMPLEMENT"]
        I1[Create Task]
        I2[Write Code]
        I3[Review]
    end
    subgraph verify ["4. VERIFY"]
        V1[Run Checks]
        V2[Confirm Match]
    end
    define --> regulate --> implement --> verify
    verify -->|Mismatch| implement
    verify -->|Docs Wrong| define

Quick Start

"I need to define something new"

→ Use ogt-docs-define to understand types, then the specific sub-skill

"I need to create a task"

→ Use ogt-docs-create-task

"I need to check if a task is really done"

→ Use ogt-docs-audit-task

"I need to add coding rules"

→ Use ogt-docs-rules-code or the specific frontend/backend/infra variant

"I need to set up docs for a new project"

→ Use ogt-docs-init

Naming Conventions

| Element | Format | Example | | ---------------- | --------------------- | --------------------------------------- | | Folder slugs | snake_case | global_search, user_auth | | Primary files | lowercase type | task.md, feature.md, rule.md | | Supporting files | lowercase descriptive | phase_0.md, notes.md, progress.md | | Signal files | dot + snake_case | .blocked_reason, .approved_by_human |

Signal Files Reference

Signal files are dot-files that indicate status or metadata.

| Signal | Type | Meaning | | ---------------------- | ------- | --------------------------- | | .version | Content | Schema/doc version (JSON) | | .blocked | Empty | Item is blocked | | .blocked_reason | Content | Why it's blocked | | .approved | Empty | Approved for implementation | | .approved_by_{name} | Empty | Who approved | | .rejected | Empty | Rejected | | .rejected_reason | Content | Why rejected | | .verified | Empty | Implementation verified | | .completed_at | Content | Completion timestamp | | .assigned_to_{agent} | Empty | Who's working on it | | .pr_link | Content | Associated PR URL | | .depends_on | Content | Dependencies list |

The Golden Rules

1. If it's not documented, it doesn't exist 2. If code contradicts docs, code is wrong 3. Never trust "done" status without verification 4. Move folders, don't copy files 5. Signal with dot-files, don't edit status fields

"I need to define something new"

→ Use ogt-docs-define to understand types, then the specific sub-skill

"I need to create a task"

→ Use ogt-docs-create-task

"I need to check if a task is really done"

→ Use ogt-docs-audit-task

"I need to add coding rules"

→ Use ogt-docs-rules-code or the specific frontend/backend/infra variant

"I need to set up docs for a new project"

→ Use ogt-docs-init