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: - 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 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**