OGT Docs Create Task

OGT Docs - Create Task

Complete guide for creating and managing tasks in the docs-first workflow.

Overview

Tasks are the unit of work in the docs-first system. Each task is a folder that moves through workflow stages, accumulating documentation and signals as it progresses. flowchart LR subgraph stages ["Task Lifecycle"] P[pending] --> IP[in_progress] IP --> R[review] R --> D[done] IP --> B[blocked] B --> IP R --> REJ[rejected] REJ --> P D --> IMP[implemented] end style P fill:#fef3c7 style IP fill:#dbeafe style R fill:#e0e7ff style B fill:#fee2e2 style REJ fill:#fecaca style D fill:#d1fae5 style IMP fill:#a7f3d0

Folder Structure

docs/todo/ ├── pending/ # Tasks not yet started │ └── {task_slug}/ │ ├── task.md # Primary task definition │ ├── context.md # Background information (optional) │ ├── .version # Schema version │ └── .priority # Priority level (content: critical|high|medium|low) │ ├── in_progress/ # Tasks being actively worked on │ └── {task_slug}/ │ ├── task.md │ ├── progress.md # Work log and updates │ ├── .version │ ├── .priority │ ├── .assigned_to_{agent} # Who's working on it │ └── .started_at # Timestamp when started │ ├── review/ # Tasks awaiting review │ └── {task_slug}/ │ ├── task.md │ ├── progress.md │ ├── implementation.md # What was done │ ├── .version │ ├── .ready_for_review # Empty signal │ ├── .pr_link # PR URL if applicable │ └── .review_requested_at │ ├── blocked/ # Tasks that cannot proceed │ └── {task_slug}/ │ ├── task.md │ ├── progress.md │ ├── .version │ ├── .blocked # Empty signal │ ├── .blocked_reason # Why blocked (content) │ ├── .blocked_at # When blocked │ └── .depends_on # What it's waiting for │ ├── done/ # Completed and verified tasks │ └── {task_slug}/ │ ├── task.md │ ├── progress.md │ ├── implementation.md │ ├── verification.md # How it was verified │ ├── .version │ ├── .verified # Empty signal - REQUIRED │ ├── .completed_at # Completion timestamp │ └── .verified_by_{agent} # Who verified │ ├── rejected/ # Tasks that were declined │ └── {task_slug}/ │ ├── task.md │ ├── .version │ ├── .rejected # Empty signal │ ├── .rejected_reason # Why rejected (content) │ └── .rejected_at # When rejected │ └── implemented/ # Done tasks that are deployed/released └── {task_slug}/ ├── task.md ├── implementation.md ├── verification.md ├── .version ├── .verified ├── .completed_at ├── .implemented_at # When deployed └── .release_version # Which release included it

Stage: pending/

Tasks that are defined but not yet started.

Example: pending/fuzzy_search/

• pending/
• └── fuzzy_search/
• ├── task.md
• ├── context.md
• ├── .version
• └── .priority
• task.md
• # Task: Fuzzy Search Implementation
• ## Summary
• Replace substring search with fuzzy indexed search using MiniSearch.
• ## Objectives
• Install MiniSearch library
• Create SearchIndexService
• Refactor GlobalSearch component
• Add debounce to search input
• ## Acceptance Criteria
• [ ] Typing "fir" returns "Fireball", "Fire Elemental", etc.
• [ ] Results ranked by relevance
• [ ] Search responds within 16ms
• [ ] TypeScript compiles clean
• ## Dependencies
• None
• ## Estimated Effort
• Medium (2-4 hours)
• ## References
• MiniSearch docs: https://lucaong.github.io/minisearch/
• Current search: front/components/features/GlobalSearch.tsx
• context.md
• # Context: Fuzzy Search
• ## Current State
• GlobalSearch.tsx uses `String.toLowerCase().includes()` for matching.
• No ranking, no debounce, no fuzzy matching.
• ## User Request
• "Global search with ctrl+k, should be instant, indexed, fuzzy.
• If I search fire just by typing fir I should get instantly a list."
• ## Technical Decision
• MiniSearch chosen over:
• Fuse.js (heavier, slower on large datasets)
• Lunr (no fuzzy matching)
• MiniSearch is 6KB gzipped, used by VitePress.
• .version
• { "schema": "1.0", "created": "2026-02-05T10:00:00Z" }
• .priority
• high

Stage: in_progress/

Tasks actively being worked on.

Example: in_progress/card_variants/

• in_progress/
• └── card_variants/
• ├── task.md
• ├── progress.md
• ├── .version
• ├── .priority
• ├── .assigned_to_claude
• └── .started_at
• task.md
• # Task: Card Variant System Expansion
• ## Summary
• Add Condensed, ListItemCondensed, and stub Quaternary/Penta card variants.
• ## Objectives
• Update UICardFrameType enum
• Create \*Condensed.tsx components
• Create \*ListItemCondensed.tsx components
• Stub Quaternary and Penta variants
• Update all \*CardMain.tsx orchestrators
• ## Acceptance Criteria
• [ ] Condensed renders 48-64px tile with art, border, icon badge
• [ ] ListItemCondensed renders 32px single-line row
• [ ] Quaternary/Penta exist as stubs
• [ ] All orchestrators route to new variants
• [ ] TypeScript compiles clean
• ## Dependencies
• None
• ## Estimated Effort
• Large (4-8 hours)
• progress.md
• # Progress: Card Variants
• ## 2026-02-05 10:30 - Started
• Read existing card components
• Identified 8 entity types needing variants
• Created implementation plan
• ## 2026-02-05 11:00 - UICardFrameType Updated
• Added Condensed, Penta, ListItem, ListItemCondensed to type
• File: front/data/app-generics.ts:82
• ## 2026-02-05 11:30 - CreatureCardCondensed Created
• Created front/components/compendium/CreatureCardCondensed.tsx
• 64x64 portrait, rarity border, type icon badge
• Tooltip on hover shows name
• ## Current Status
• [x] Type definition updated
• [x] CreatureCardCondensed
• [ ] ItemCardCondensed
• [ ] AbilityCardCondensed
• [ ] Remaining entity types
• [ ] ListItemCondensed variants
• [ ] Quaternary/Penta stubs
• [ ] Orchestrator updates
• .assigned_to_claude
• (empty file - presence indicates assignment)
• .started_at
• 2026-02-05T10:30:00Z

Stage: review/

Tasks completed and awaiting review.

Example: review/spell_routes/

• review/
• └── spell_routes/
• ├── task.md
• ├── progress.md
• ├── implementation.md
• ├── .version
• ├── .ready_for_review
• ├── .pr_link
• └── .review_requested_at
• task.md
• # Task: Wire SpellDetailView into Router
• ## Summary
• SpellDetailView.tsx exists but is not routed. Wire it into the app router.
• ## Objectives
• Add route to APP_ROUTES
• Add Route element in App.tsx
• Verify component loads correctly
• ## Acceptance Criteria
• [ ] /spells/:slug route works
• [ ] SpellDetailView renders with spell data
• [ ] Navigation from spell cards works
• [ ] TypeScript compiles clean
• progress.md
• # Progress: Spell Routes
• ## 2026-02-05 09:00 - Started
• Located SpellDetailView at front/app/(main)/compendium/SpellDetailView.tsx
• Reviewed existing route patterns
• ## 2026-02-05 09:15 - Implementation Complete
• Added spell_detail to APP_ROUTES in app-configs.ts
• Added Route element in App.tsx
• Tested with /spells/fireball - works
• TypeScript compiles clean
• implementation.md
• # Implementation: Spell Routes
• ## Files Changed
• ### front/data/app-configs.ts
• Added route configuration:
• ```typescript
• spell_detail: {
• path: '/spells/:slug',
• label: 'Spell Detail',
• }
• ```

front/app/App.tsx

Added import and route: import SpellDetailView from './(main)/compendium/SpellDetailView'; // ... <Route path="/spells/:slug" element={<SpellDetailView />} />

Testing

• Manual test: /spells/fireball loads correctly
• Manual test: /spells/magic-missile loads correctly
• TypeScript: No errors
• #### .ready_for_review
• (empty file)
• #### .pr_link
• https://github.com/org/repo/pull/123
• #### .review_requested_at
• 2026-02-05T09:30:00Z
• ---
• ## Stage: blocked/
• Tasks that cannot proceed due to dependencies or blockers.
• ### Example: blocked/auth_refactor/
• blocked/
• └── auth_refactor/
• ├── task.md
• ├── progress.md
• ├── .version
• ├── .blocked
• ├── .blocked_reason
• ├── .blocked_at
• └── .depends_on
• #### task.md
• ```markdown
• # Task: Auth Service Refactor
• ## Summary
• Refactor AuthService to support multiple OAuth providers.
• ## Objectives
• Abstract provider-specific logic
• Add Steam OAuth support
• Implement token refresh flow
• Update all auth consumers
• ## Acceptance Criteria
• [ ] Google OAuth still works
• [ ] Discord OAuth still works
• [ ] Steam OAuth works
• [ ] Token refresh is automatic
• [ ] No breaking changes to API
• progress.md
• # Progress: Auth Refactor
• ## 2026-02-03 14:00 - Started
• Analyzed current AuthService implementation
• Identified 3 provider-specific code paths
• ## 2026-02-03 15:00 - BLOCKED
• Steam OAuth requires server-side changes
• Backend team needs to add Steam provider to Strapi
• Cannot proceed until backend work is complete
• ## Waiting For
• Backend task: "Add Steam OAuth Provider to Strapi"
• ETA: Unknown
• .blocked
• (empty file)
• .blocked_reason
• Requires backend changes: Steam OAuth provider must be added to Strapi before frontend can implement Steam login flow. Backend task not yet created.
• .blocked_at
• 2026-02-03T15:00:00Z
• .depends_on
• backend/steam_oauth_provider (not yet created)
• Strapi plugin configuration

Stage: done/

Completed tasks that have been verified.

Example: done/ogt_cli_commands/

• done/
• └── ogt_cli_commands/
• ├── task.md
• ├── progress.md
• ├── implementation.md
• ├── verification.md
• ├── .version
• ├── .verified
• ├── .completed_at
• └── .verified_by_claude
• task.md
• # Task: OGT CLI Check Commands
• ## Summary
• Create generic file/data validation CLI tools under `ogt check`.
• ## Objectives
• ogt check assets - Check for missing files
• ogt check slugs - Verify slug conventions
• ogt check indexed - Verify index.ts exports
• ogt check data - Validate against schema
• ## Acceptance Criteria
• [x] All commands have --help
• [x] Commands return proper exit codes
• [x] JSON output option available
• [x] TypeScript compiles clean
• verification.md
• # Verification: OGT CLI Commands
• ## Verification Date
• 2026-01-30
• ## Tests Performed
• ### Command Existence
• ```bash
• $ ogt check --help
• # ✅ Shows subcommands: assets, slugs, indexed, data, from-list
• $ ogt check assets --help
• # ✅ Shows usage and flags
• $ ogt check slugs --help
• # ✅ Shows usage and flags
• $ ogt check indexed --help
• # ✅ Shows usage and flags
• $ ogt check data --help
• # ✅ Shows usage and flags
• ```

Functional Tests

$ ogt check indexed creatures # ✅ Returns JSON with 197 total, 197 passed $ ogt check slugs front/data/app-creatures -r # ✅ Returns JSON with slug validation results $ ogt check assets static/public/creatures portrait.png -r # ✅ Returns JSON listing missing portraits

Exit Codes

$ ogt check indexed creatures && echo "pass" # ✅ Exits 0, prints "pass" $ ogt check indexed nonexistent || echo "fail" # ✅ Exits 1, prints "fail"

Verification Result

• PASS - All acceptance criteria met
• #### .verified
• (empty file - REQUIRED for done/ status)
• #### .completed_at
• 2026-01-30T14:00:00Z
• #### .verified_by_claude
• (empty file)
• ---
• ## Stage: rejected/
• Tasks that were declined and will not be implemented.
• ### Example: rejected/legacy_api_compat/
• rejected/
• └── legacy_api_compat/
• ├── task.md
• ├── .version
• ├── .rejected
• ├── .rejected_reason
• └── .rejected_at
• #### task.md
• ```markdown
• # Task: Legacy API Compatibility Layer
• ## Summary
• Create compatibility layer for v0 API endpoints.
• ## Objectives
• Map v0 endpoints to v1 services
• Maintain backward compatibility for 6 months
• Log deprecation warnings
• ## Acceptance Criteria
• [ ] All v0 endpoints work
• [ ] Deprecation headers sent
• [ ] Usage logging enabled
• .rejected
• (empty file)
• .rejected_reason
• Decision: Clean break over compatibility layer.
• Rationale:
• 1. No external consumers of v0 API
• 2. Maintenance burden outweighs benefits
• 3. v0 endpoints have security issues
• 4. Better to document migration path
• Alternative: Create migration guide instead.
• See: docs/guides/v0_to_v1_migration/
• .rejected_at
• 2026-02-01T09:00:00Z

Stage: implemented/

Tasks that are done AND deployed/released to production.

Example: implemented/creatures_index/

implemented/ └── creatures_index/ ├── task.md ├── implementation.md ├── verification.md ├── .version ├── .verified ├── .completed_at ├── .implemented_at └── .release_version .implemented_at 2026-02-02T10:00:00Z .release_version v1.2.0

Creating a New Task

flowchart TD A[User Request] --> B{Task Defined?} B -->|No| C[Create task.md] C --> D[Add context.md if needed] D --> E[Set .priority] E --> F[Add .version] F --> G[Place in pending/] B -->|Yes| H[Update existing task] Steps: Create folder: docs/todo/pending/{task_slug}/ Create task.md with Summary, Objectives, Acceptance Criteria Optionally add context.md for background Create .priority with level (critical/high/medium/low) Create .version with schema version

Starting a Task

# Move from pending to in_progress mv docs/todo/pending/{task_slug} docs/todo/in_progress/ # Add assignment signal touch docs/todo/in_progress/{task_slug}/.assigned_to_{agent} # Add start timestamp echo "$(date -Iseconds)" > docs/todo/in_progress/{task_slug}/.started_at # Create progress log touch docs/todo/in_progress/{task_slug}/progress.md

Blocking a Task

# Move to blocked mv docs/todo/in_progress/{task_slug} docs/todo/blocked/ # Add blocked signals touch docs/todo/blocked/{task_slug}/.blocked echo "Reason here" > docs/todo/blocked/{task_slug}/.blocked_reason echo "$(date -Iseconds)" > docs/todo/blocked/{task_slug}/.blocked_at

Submitting for Review

# Move to review mv docs/todo/in_progress/{task_slug} docs/todo/review/ # Add review signals touch docs/todo/review/{task_slug}/.ready_for_review echo "$(date -Iseconds)" > docs/todo/review/{task_slug}/.review_requested_at # Add implementation docs # Create implementation.md documenting what was done

Completing a Task

CRITICAL: Must verify before marking done! # 1. Run ALL acceptance criteria checks # 2. Document in verification.md # 3. ONLY if all pass: # Move to done mv docs/todo/review/{task_slug} docs/todo/done/ # Add completion signals touch docs/todo/done/{task_slug}/.verified # REQUIRED echo "$(date -Iseconds)" > docs/todo/done/{task_slug}/.completed_at touch docs/todo/done/{task_slug}/.verified_by_{agent}

Rejecting a Task

# Move to rejected mv docs/todo/review/{task_slug} docs/todo/rejected/ # Add rejection signals touch docs/todo/rejected/{task_slug}/.rejected echo "Reason here" > docs/todo/rejected/{task_slug}/.rejected_reason echo "$(date -Iseconds)" > docs/todo/rejected/{task_slug}/.rejected_at

Status Signals (empty files)

SignalStageMeaning.blockedblocked/Task cannot proceed.ready_for_reviewreview/Ready for review.verifieddone/, implemented/REQUIRED - Implementation verified.rejectedrejected/Task declined

Assignment Signals (empty files)

SignalStageMeaning.assigned_to_{agent}in_progress/Who's working on it.verified_by_{agent}done/Who verified it.approved_by_{name}anyWho approved

Content Signals (contain text)

SignalContentExample.versionJSON schema version{"schema": "1.0", "created": "..."}.priorityPriority levelhigh.blocked_reasonWhy blockedFree text explanation.rejected_reasonWhy rejectedFree text explanation.depends_onDependenciesList of dependencies.pr_linkPR URLhttps://github.com/....started_atISO timestamp2026-02-05T10:00:00Z.completed_atISO timestamp2026-02-05T14:00:00Z.blocked_atISO timestamp2026-02-05T12:00:00Z.rejected_atISO timestamp2026-02-05T09:00:00Z.implemented_atISO timestamp2026-02-05T16:00:00Z.release_versionVersion stringv1.2.0

Task.md Template

• # Task: {Title}
• ## Summary
• One paragraph describing what needs to be done and why.
• ## Objectives
• Specific objective 1
• Specific objective 2
• Specific objective 3
• ## Acceptance Criteria
• [ ] Verifiable criterion 1
• [ ] Verifiable criterion 2
• [ ] Verifiable criterion 3
• [ ] TypeScript compiles clean (if applicable)
• ## Dependencies
• {dependency} or "None"
• ## Estimated Effort
• {Tiny|Small|Medium|Large|XLarge} ({time estimate})
• ## References
• Relevant link 1
• Relevant file path
• Related task

Verification Rules

NEVER mark a task as done without verification.

Verification Checklist

• ## For each acceptance criterion:
• 1. IDENTIFY: What command/action proves this criterion?
• 2. RUN: Execute the verification
• 3. CAPTURE: Record the output
• 4. ASSESS: Does it pass?
• ## Required Verifications by Type:
• ### File Creation
• [ ] File exists: `test -f {path} && echo "EXISTS"`
• [ ] File is exported (if module): `grep "export" {index_file}`
• ### Dependency Installation
• [ ] In package.json: `grep "{package}" package.json`
• [ ] Can import: Create test file with import
• ### Route Addition
• [ ] In router: `grep "{route}" {router_file}`
• [ ] Navigable: Test in browser
• ### Pattern Removal
• [ ] Zero matches: `grep -r "{pattern}" {path} | wc -l` = 0
• ### Type Addition
• [ ] Type exists: `grep "type {Name}" {types_file}`
• [ ] Compiles: `tsc --noEmit` or equivalent
• ### General
• [ ] TypeScript compiles: Run type checker
• [ ] Tests pass: Run test suite
• [ ] No console errors: Check browser/runtime

Common Mistakes

MistakeWhy It's WrongCorrect ApproachMoving to done/ without .verifiedNo proof of completionVerify first, then moveTrusting task.md checkboxesCheckboxes can be wrongRun actual verificationSkipping implementation.mdNo record of what changedDocument all changesEmpty verification.mdNo proof of verificationRecord actual test outputMultiple tasks in progressContext switching wasteFinish one, then start nextEditing task.md in done/History should be immutableCreate follow-up task instead