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:

Understand the docs/ folder structure
Find the right sub-skill for a specific task
Initialize a new docs-first project
Navigate between definition types

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:

Move entire folder between workflow stages
Attach unlimited supporting files
Signal status via dot-files
Version and track changes atomically

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

mermaid

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

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

ogt-docs

NPX Install

Tags

SKILL.md Content

OGT Docs - Documentation as Source of Truth

Philosophy

When to Use This Skill

Documentation Structure Overview

The Folder-as-Entity Pattern

Sub-Skills Reference

Definitions (WHAT things ARE)

Rules (HOW to IMPLEMENT)

Tasks (WHAT to DO)

Other

Workflow Overview

Quick Start

"I need to define something new"

"I need to create a task"

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

"I need to add coding rules"

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

Naming Conventions

Signal Files Reference

The Golden Rules