ogt-docs-create-task

---
name: ogt-docs-create-task
description: Create and manage task documents in the docs/todo/ workflow. Use when creating new tasks, updating task status, or moving tasks between workflow stages. Provides complete task lifecycle management with verification.
---

# 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.

```mermaid
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

```markdown
# 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

```markdown
# 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

```json
{ "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

```markdown
# 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

```markdown
# 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

```markdown
# 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

```markdown
# 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

````markdown
# 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:

```typescript
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

```markdown
# 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

```markdown
# 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

````markdown
# 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

```bash
$ 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

```bash
$ 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
```

---

## Task Lifecycle Operations

### Creating a New Task

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

1. Create folder: `docs/todo/pending/{task_slug}/`
2. Create `task.md` with Summary, Objectives, Acceptance Criteria
3. Optionally add `context.md` for background
4. Create `.priority` with level (critical/high/medium/low)
5. Create `.version` with schema version

### Starting a Task

```bash
# 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

```bash
# 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

```bash
# 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!**

```bash
# 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

```bash
# 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
```

---

## Signal Files Reference

### Status Signals (empty files)

| Signal              | Stage               | Meaning                                |
| ------------------- | ------------------- | -------------------------------------- |
| `.blocked`          | blocked/            | Task cannot proceed                    |
| `.ready_for_review` | review/             | Ready for review                       |
| `.verified`         | done/, implemented/ | **REQUIRED** - Implementation verified |
| `.rejected`         | rejected/           | Task declined                          |

### Assignment Signals (empty files)

| Signal                 | Stage        | Meaning             |
| ---------------------- | ------------ | ------------------- |
| `.assigned_to_{agent}` | in_progress/ | Who's working on it |
| `.verified_by_{agent}` | done/        | Who verified it     |
| `.approved_by_{name}`  | any          | Who approved        |

### Content Signals (contain text)

| Signal             | Content             | Example                               |
| ------------------ | ------------------- | ------------------------------------- |
| `.version`         | JSON schema version | `{"schema": "1.0", "created": "..."}` |
| `.priority`        | Priority level      | `high`                                |
| `.blocked_reason`  | Why blocked         | Free text explanation                 |
| `.rejected_reason` | Why rejected        | Free text explanation                 |
| `.depends_on`      | Dependencies        | List of dependencies                  |
| `.pr_link`         | PR URL              | `https://github.com/...`              |
| `.started_at`      | ISO timestamp       | `2026-02-05T10:00:00Z`                |
| `.completed_at`    | ISO timestamp       | `2026-02-05T14:00:00Z`                |
| `.blocked_at`      | ISO timestamp       | `2026-02-05T12:00:00Z`                |
| `.rejected_at`     | ISO timestamp       | `2026-02-05T09:00:00Z`                |
| `.implemented_at`  | ISO timestamp       | `2026-02-05T16:00:00Z`                |
| `.release_version` | Version string      | `v1.2.0`                              |

---

## Task.md Template

```markdown
# 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

```markdown
## 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

| Mistake                           | Why It's Wrong              | Correct Approach              |
| --------------------------------- | --------------------------- | ----------------------------- |
| Moving to done/ without .verified | No proof of completion      | Verify first, then move       |
| Trusting task.md checkboxes       | Checkboxes can be wrong     | Run actual verification       |
| Skipping implementation.md        | No record of what changed   | Document all changes          |
| Empty verification.md             | No proof of verification    | Record actual test output     |
| Multiple tasks in progress        | Context switching waste     | Finish one, then start next   |
| Editing task.md in done/          | History should be immutable | Create follow-up task instead |