CODITECT Standard: Task Specification

Standard ID: CODITECT-STD-003 Version: 1.0.0 Effective Date: January 25, 2026 ADR Reference: ADR-115

1. Purpose

This standard defines the Hybrid Task Specification Format for all tasks in CODITECT project plans (PILOT, PROJECT-PLAN, sprint plans). The format combines:

YAML Frontmatter: Machine-parseable structured data
Markdown Body: Human-readable context and documentation

2. Scope

This standard applies to:

All tasks in PILOT-PARALLEL-EXECUTION-PLAN.md
All tasks in sprint plans
All tasks in project plans
Any task that will be executed by a CODITECT agent

3. Format Specification

3.1 Complete Task Structure

---
# ═══════════════════════════════════════════════════════════════
# CODITECT TASK SPECIFICATION
# Standard: CODITECT-STD-003 v1.0.0
# ═══════════════════════════════════════════════════════════════

# === IDENTIFICATION (Required) ===
task_id: A.9.1.1                      # Track.Section.Task[.Subtask]
title: Create Context API Endpoint    # Concise title (≤100 chars)
status: pending                       # pending|in_progress|complete|blocked|cancelled
track: A                              # Track letter (A-N)

# === ASSIGNMENT (Required) ===
agent:
  name: senior-architect              # CODITECT agent name
  model: sonnet                       # Optional: opus|sonnet|haiku

# === QUALITY (Required) ===
acceptance_criteria:
  - id: ac1
    criterion: POST /api/v1/context/sync returns 200 with sync_cursor
    testable: true
  - id: ac2
    criterion: TenantForeignKey enforces multi-tenant isolation
    testable: true
  - id: ac3
    criterion: Rate limiting applied (100 req/min per user)
    testable: true

# === CLASSIFICATION (Recommended) ===
priority: P1                          # P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
domain: backend                       # backend|frontend|devops|security|testing|docs|research

# === CONTEXT (Recommended) ===
references:
  - type: adr
    id: ADR-053
    path: internal/architecture/adrs/ADR-053-cloud-context-sync.md
  - type: code
    id: context-models
    path: backend/context/models.py

dependencies:
  blocked_by: [A.9.1.0]               # Must complete before this task starts
  blocks: [A.9.1.2, A.9.1.3]          # Cannot start until this task completes

constraints:
  - Must follow ADR-053 sync architecture
  - Must use TenantModel base class
  - Cannot modify existing message endpoints

# === VERIFICATION (Recommended) ===
verification:
  command: |
    curl -X POST https://api.coditect.ai/api/v1/context/sync \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"messages": [{"content": "test"}]}'
  expected: '{"sync_cursor": 12345, "synced": 1}'

# === METADATA (Optional) ===
estimated_hours: 4
tags: [api, context, sync, multi-tenant, rest]
created: 2026-01-25
updated: 2026-01-25
---

## A.9.1.1: Create Context API Endpoint

### Objective

Create POST /api/v1/context/sync endpoint for bidirectional context
synchronization between local SQLite (context.db) and cloud PostgreSQL.

### Context

The context sync system enables Ralph Wiggum checkpoints to persist across
sessions. This endpoint receives batched messages from the local client and
returns a sync_cursor for incremental polling. Part of ADR-053 implementation.

### Implementation Notes

- Location: `backend/context/views.py`
- Extend existing `ContextViewSet` with `sync` action
- Use `@action(detail=False, methods=['post'])` decorator
- Reference `context/models.py` for Message, Decision, Pattern models
- Apply `@ratelimit(key='user', rate='100/m')` decorator

### Agent Invocation

```bash
/agent senior-architect "Implement A.9.1.1: Create POST /api/v1/context/sync
endpoint in coditect-cloud-infra/backend/context/views.py per ADR-053.

Requirements:
- TenantModel isolation via TenantForeignKey
- Rate limiting: 100 requests/minute per user
- Cursor-based pagination for large payloads
- Return sync_cursor for incremental polling

Reference files:
- backend/context/models.py (Message, Decision models)
- backend/context/serializers.py (existing serializers)
- ADR-053-cloud-context-sync.md (architecture)"

### 3.2 Required Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `task_id` | string | Track nomenclature ID per ADR-054 | `A.9.1.1` |
| `title` | string | Concise task title (≤100 chars) | `Create Context API Endpoint` |
| `status` | enum | Current task status | `pending` |
| `track` | enum | Track letter (A-N) | `A` |
| `agent.name` | string | CODITECT agent name | `senior-architect` |
| `acceptance_criteria` | array | At least one testable criterion | See example |

### 3.3 Recommended Fields

| Field | Type | Description | Default |
|-------|------|-------------|---------|
| `priority` | enum | P0/P1/P2/P3 | `P2` |
| `domain` | enum | Task domain | Inferred from track |
| `references` | array | Links to ADRs, specs, code | `[]` |
| `dependencies` | object | blocked_by and blocks | `{}` |
| `constraints` | array | Non-negotiable requirements | `[]` |
| `verification` | object | Test command and expected result | `null` |

### 3.4 Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| `agent.model` | enum | Model override (opus/sonnet/haiku) |
| `estimated_hours` | number | Effort estimate |
| `tags` | array | Keywords for filtering/routing |
| `created` | date | Creation date |
| `updated` | date | Last update date |

## 4. Field Specifications

### 4.1 task_id Format

Per ADR-054 Track Nomenclature:

Format: Track.Section.Task[.Subtask]

Examples: A.9.1.1 = Track A, Section 9, Task 1, Subtask 1 C.14.2 = Track C, Section 14, Task 2 H.8.1.5 = Track H, Section 8, Task 1, Subtask 5

Regex: ^[A-N].[0-9]+.[0-9]+(.[0-9]+)?$

### 4.2 status Values

| Status | Description | Transitions To |
|--------|-------------|----------------|
| `pending` | Not started, ready to work | `in_progress`, `blocked` |
| `in_progress` | Currently being worked | `complete`, `blocked` |
| `complete` | All acceptance criteria met | (terminal) |
| `blocked` | Waiting on dependency | `pending`, `in_progress` |
| `cancelled` | Will not be done | (terminal) |

### 4.3 priority Values

| Priority | Description | Response Time |
|----------|-------------|---------------|
| `P0` | Critical - blocks launch | Immediate |
| `P1` | High - required for milestone | This sprint |
| `P2` | Medium - important but not urgent | Next sprint |
| `P3` | Low - nice to have | Backlog |

### 4.4 track Values

| Track | Domain | Primary Agent |
|-------|--------|---------------|
| `A` | Backend API | `senior-architect` |
| `B` | Frontend UI | `frontend-react-typescript-expert` |
| `C` | DevOps/Infra | `devops-engineer` |
| `D` | Security | `security-specialist` |
| `E` | Testing/QA | `testing-specialist` |
| `F` | Documentation | `codi-documentation-writer` |
| `G` | DMS | `prompt-analyzer-specialist` |
| `H` | Framework Autonomy | `orchestrator` |
| `I` | UI Components | `generative-ui-architect` |
| `J` | Memory Intelligence | `memory-context-agent` |
| `K` | Workflow Automation | `workflow-orchestrator` |
| `L` | Extended Testing | `testing-specialist` |
| `M` | Extended Security | `security-specialist` |
| `N` | GTM & Launch | `content-marketing` |

### 4.5 acceptance_criteria Format

```yaml
acceptance_criteria:
  - id: ac1                           # Unique ID within task
    criterion: Specific testable statement
    testable: true                    # Must be verifiable
  - id: ac2
    criterion: Another criterion
    testable: true

Rules:

At least one criterion required
Each criterion must be testable (binary pass/fail)
Use present tense ("returns" not "should return")
Be specific (include values, formats, behaviors)

Good Examples:

POST endpoint returns 200 with JSON body containing sync_cursor
Rate limiting returns 429 after 100 requests in 60 seconds
TenantForeignKey filters queries to current tenant only

Bad Examples:

Endpoint works correctly (not testable)
Should be fast (not specific)
Handle errors properly (vague)

4.6 references Format

references:
  - type: adr                         # adr|spec|doc|code|url
    id: ADR-053                       # Human-readable identifier
    path: path/to/file.md             # Relative path from repo root
  - type: code
    id: context-models
    path: backend/context/models.py
  - type: url
    id: GitHub Spec Kit
    path: https://github.com/github/spec-kit

4.7 dependencies Format

dependencies:
  blocked_by:                         # Tasks that must complete first
    - A.9.1.0
    - A.8.2.3
  blocks:                             # Tasks waiting on this
    - A.9.1.2
    - A.9.2.1

Rules:

Use task_id format for references
Circular dependencies are invalid
Empty arrays are valid (no dependencies)

4.8 verification Format

verification:
  command: |
    curl -X POST https://api.coditect.ai/api/v1/context/sync \
      -H "Authorization: Bearer $TOKEN" \
      -d '{"messages": [{"content": "test"}]}'
  expected: '{"sync_cursor": 12345, "synced": 1}'

Rules:

Command should be executable in bash
Expected can be exact match or regex pattern
Use | for multiline commands

5. Markdown Body Requirements

5.1 Required Sections

Section	Purpose
Objective	Single declarative statement of WHAT (not HOW)
Agent Invocation	Ready-to-execute `/agent` command

5.2 Recommended Sections

Section	Purpose
Context	Background, rationale, architectural decisions
Implementation Notes	Technical guidance, file locations, patterns

5.3 Objective Guidelines

Do:

Use declarative language (WHAT to achieve)
Be specific about the outcome
Reference the primary deliverable

Don't:

Describe HOW to implement (that's agent's job)
Include implementation details
List multiple unrelated outcomes

Good:

### Objective
Create POST /api/v1/context/sync endpoint for bidirectional context
synchronization between local SQLite and cloud PostgreSQL.

Bad:

### Objective
We need to create an endpoint. First, open views.py, then add a new
function that handles POST requests and saves to the database.

5.4 Agent Invocation Guidelines

The Agent Invocation should be a complete, copy-paste-ready command:

### Agent Invocation

```bash
/agent <agent-name> "<task_id>: <title>

<Objective from above>

Requirements:
- <Acceptance criterion 1>
- <Acceptance criterion 2>

Constraints:
- <Constraint 1>
- <Constraint 2>

Reference files:
- <path/to/file1> (<description>)
- <path/to/file2> (<description>)"

## 6. Validation

### 6.1 Schema Validation

All tasks must pass schema validation:

```bash
python3 scripts/validate-pilot-tasks.py internal/project/plans/PILOT-PARALLEL-EXECUTION-PLAN.md

6.2 Pre-Commit Hook

Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse:Write": [
      {
        "matcher": "PILOT.*\\.md$",
        "command": "python3 ~/.coditect/scripts/validate-pilot-tasks.py $FILE"
      }
    ]
  }
}

6.3 Validation Rules

Rule	Description
`required-fields`	All required fields present
`valid-task-id`	task_id matches regex pattern
`valid-status`	status is valid enum value
`valid-track`	track matches task_id prefix
`testable-criteria`	All acceptance_criteria have testable=true
`no-circular-deps`	No circular dependencies
`agent-exists`	Agent name exists in agents/ directory

7. Migration Guide

7.1 Converting Existing Tasks

Before:

- [ ] A.9.1.1: Create context API endpoint
  - **Agent:** `Task(subagent_type="senior-architect", prompt="Create API")`

After:

---
task_id: A.9.1.1
title: Create Context API Endpoint
status: pending
track: A
agent:
  name: senior-architect
acceptance_criteria:
  - criterion: POST endpoint returns 200
    testable: true
---

## A.9.1.1: Create Context API Endpoint

### Objective
Create POST /api/v1/context/sync endpoint.

### Agent Invocation
/agent senior-architect "Implement A.9.1.1..."

7.2 Migration Phases

Phase	Scope	Timeline
1	New tasks only	Immediate
2	Critical path tasks	Week 1
3	All in-progress tasks	Week 2
4	All pending tasks	Week 3-4

8. Examples

8.1 Minimal Valid Task

---
task_id: C.14.1.1
title: Create pre-git-cleanup.sh hook
status: pending
track: C
agent:
  name: devops-engineer
acceptance_criteria:
  - criterion: Script removes stale index.lock files
    testable: true
---

## C.14.1.1: Create pre-git-cleanup.sh Hook

### Objective
Create shell script to remove stale git lock files.

### Agent Invocation
/agent devops-engineer "Implement C.14.1.1: Create hooks/pre-git-cleanup.sh"

8.2 Complete Task

See Section 3.1 for full example.

Standard	Relationship
ADR-054: Track Nomenclature	Defines task_id format
ADR-183: Governance Hooks	Validation integration
CODITECT-STANDARD-AUTOMATION.md	Principle #12 (Task ID Protocol)

10. Schema

Full JSON Schema: schemas/task-specification.schema.yaml

Standard Version: 1.0.0 Effective Date: January 25, 2026 Review Date: April 25, 2026 Owner: CODITECT Standards Committee

1. Purpose​

2. Scope​

3. Format Specification​

3.1 Complete Task Structure​

4.6 references Format​

4.7 dependencies Format​

4.8 verification Format​

5. Markdown Body Requirements​

5.1 Required Sections​

5.2 Recommended Sections​

5.3 Objective Guidelines​

5.4 Agent Invocation Guidelines​

6.2 Pre-Commit Hook​

6.3 Validation Rules​

7. Migration Guide​

7.1 Converting Existing Tasks​

7.2 Migration Phases​

8. Examples​

8.1 Minimal Valid Task​

8.2 Complete Task​

9. Related Standards​

10. Schema​

1. Purpose

2. Scope

3. Format Specification

3.1 Complete Task Structure

4.6 references Format

4.7 dependencies Format

4.8 verification Format

5. Markdown Body Requirements

5.1 Required Sections

5.2 Recommended Sections

5.3 Objective Guidelines

5.4 Agent Invocation Guidelines

6.2 Pre-Commit Hook

6.3 Validation Rules

7. Migration Guide

7.1 Converting Existing Tasks

7.2 Migration Phases

8. Examples

8.1 Minimal Valid Task

8.2 Complete Task

9. Related Standards

10. Schema