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

---

Content truncated.