### Task Status Management Examples (Markdown)

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

Illustrates the valid task statuses used within the system and provides examples of how AI agents update task statuses, including claiming, blocking, and completing tasks. These statuses are crucial for coordination.

```markdown
# Valid Task Statuses

| Status                        | Meaning                              |
|-------------------------------|--------------------------------------|
| `Todo`                        | Ready to be claimed                  |
| `InProgress_By_[AgentName]`   | Claimed and actively being worked    |
| `Blocked_By_[Reason]`         | Cannot proceed; must include reason  |
| `NeedsReview`                 | Work complete; awaiting review       |
| `Done`                        | Reviewed and approved                |
| `Cancelled`                   | Intentionally stopped (with reason)  |

# Example Status Updates

## Claiming a Task
**Status:** InProgress_By_Backend_Agent_01
**Last Updated:** 2025-06-05

## AI Agent Log:
* 2025-06-05 14:00: Started processing task. Checked dependencies - all Done.

## Blocking a Task
**Status:** Blocked_By_Merge_Conflict_in_src/routes/auth

## AI Agent Log:
* 2025-06-05 15:30: Encountered merge conflict. Unable to resolve safely. Notified user.

## Completing a Task
**Status:** NeedsReview

## AI Agent Log:
* 2025-06-05 16:00: All sub-tasks completed. Quality gates passed. Ready for review.

```

--------------------------------

### Task File Structure Example (Markdown)

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

Demonstrates the structure of a task file, including metadata, detailed description, implementation steps, completion criteria, and an AI agent log. This format serves as the primary communication and tracking mechanism for AI agents.

```markdown
# Task: User Registration Endpoint

**Task ID:** `V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md`
**Version:** V1_MVP
**Phase:** 02_Backend_Core_Features
**Module:** 02.01_Authentication
**Priority:** High
**Status:** Todo
**Assignee:** Backend_Agent_01
**Created Date:** 2025-06-05
**Last Updated:** 2025-06-05
**Dependencies:**
- `V1_MVP/01_Database/task_01.01_users_table.md`

## 1. Detailed Description
Create API endpoint that allows new users to register an account.

## 2. Implementation Steps (Specific Sub-tasks)
- [ ] 1. Define Request and Response structs
- [ ] 2. Write validation logic
- [ ] 3. Integrate password hashing library
- [ ] 4. Write handler function
- [ ] 5. Register route in Router
- [ ] 6. Write Unit/Integration Tests

## 3. Completion Criteria
- [ ] Endpoint is accessible
- [ ] Valid registration returns 201 + Token
- [ ] Unit tests pass

## AI Agent Log:
* 2025-06-05 10:30: Started processing task. Reviewed schema.

```

--------------------------------

### Project Directory Structure Example (Text)

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

Outlines the hierarchical directory structure for organizing project tasks, following a Version/Phase/Task pattern. This structure facilitates parallel development and clear task isolation.

```text
/project_root
├── docs/
│   ├── Task_over_view.md              # High-level overview file
│   │
│   ├── V1_MVP/                        # Version 1: Minimum Viable Product
│   │   ├── 00_Project_Setup_And_Environment/
│   │   │   ├── task_00.01_rust_axum_backend_setup.md
│   │   │   ├── task_00.02_sveltekit_frontend_setup.md
│   │   │   └── task_00.03_surrealdb_local_setup.md
│   │   │
│   │   ├── 01_Database_Schema_And_Seed_Data/
│   │   │   ├── task_01.01_define_core_schemas.md
│   │   │   └── task_01.02_create_seed_data_files.md
│   │   │
│   │   ├── 02_Backend_Core_Features/
│   │   │   ├── 02.01_Authentication/
│   │   │   │   ├── task_02.01.01_user_registration_endpoint.md
│   │   │   │   └── task_02.01.02_user_login_endpoint.md
│   │   │   └── 02.02_User_Profile_Management/
│   │   │       └── task_02.02.01_create_update_profile_endpoints.md
│   │   │
│   │   └── 03_Frontend_Core_UI/
│   │       └── 03.01_Authentication_Pages/
│   │           ├── task_03.01.01_login_page.md
│   │           └── task_03.01.02_registration_page.md
│   │
│   └── V1.1_Post_Launch_Enhancements/  # Version 1.1
│       └── 01_Bug_Fixes_From_V1.0/
│           └── task_01.01_fix_login_issue_xyz.md
│
└── src/                               # Project source code

```

--------------------------------

### Example JSON Response Body for Successful User Registration

Source: https://github.com/tymon3568/folder-tasks/blob/master/task_XX.YY.ZZ_taskName.md

Defines the JSON structure returned upon successful user registration. It includes the newly created user's details and an authentication token.

```json
{
  "user": {
    "id": "users:ulid_string",
    "email": "user@example.com",
    "full_name": "John Doe",
    "created_at": "2025-06-05T10:00:00Z"
  },
  "token": "eyJhbGciOiJIUzI1Ni..."
}
```

--------------------------------

### Local Quality Gates using Bun

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

These bash commands outline the local quality gates that agents must run before marking a task as NeedsReview. They include installing dependencies, running type checks, linting, and executing tests using Bun.

```bash
# Local Quality Gates (run before NeedsReview)

# Install dependencies
bun install

# Run typecheck
bun run check

# Run linter
bun run lint

# Run tests
bun run test

# All must pass before setting Status: NeedsReview
```

--------------------------------

### Svelte 5 Login Page Component

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

An example Svelte 5 component for a login page, demonstrating the use of Svelte 5 runes like $props, $state, $derived, and $effect for reactive UI and state management. It includes client-side form validation and submission handling.

```svelte
<script lang="ts">
  import type { PageProps } from './$types';

  // Svelte 5: Use $props() instead of export let
  let { data, form }: PageProps = $props();

  // Svelte 5: Use $state for local reactive state
  let isSubmitting = $state(false);
  let email = $state('');
  let password = $state('');

  // Svelte 5: Use $derived for computed values
  let isFormValid = $derived(email.length > 0 && password.length >= 8);

  // Svelte 5: Use $effect for side effects only
  $effect(() => {
    if (form?.error) {
      console.error('Login failed:', form.error);
    }
  });
</script>

<form method="POST" use:enhance={() => {
  isSubmitting = true;
  return async ({ update }) => {
    await update();
    isSubmitting = false;
  };
}}>
  <label for="email">Email</label>
  <input id="email" name="email" type="email" bind:value={email} required />

  <label for="password">Password</label>
  <input id="password" name="password" type="password" bind:value={password} required />

  {#if form?.error}
    <p class="error" role="alert">{form.error}</p>
  {/if}

  <button type="submit" disabled={!isFormValid || isSubmitting}>
    {isSubmitting ? 'Logging in...' : 'Login'}
  </button>
</form>
```

--------------------------------

### Git Workflow: Pull Before Work

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This command ensures the local repository is up-to-date with the remote 'main' branch before starting any new task, following the pull-before-work pattern.

```bash
# Before Starting a Code Task
git pull origin main
```

--------------------------------

### Example JSON Request Body for User Registration

Source: https://github.com/tymon3568/folder-tasks/blob/master/task_XX.YY.ZZ_taskName.md

Specifies the JSON payload structure expected by the user registration API endpoint. It includes the necessary fields: email, password, and full name.

```json
{
  "email": "user@example.com",
  "password": "SecretPassword123!",
  "full_name": "John Doe"
}
```

--------------------------------

### Define AI Agent Task Management Workflow Rules (XML)

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This XML snippet defines a custom rule for AI agents to manage task workflows. It specifies guidelines for receiving tasks, checking dependencies, updating statuses, executing sub-tasks, managing code commits, handling blockers, and completing tasks. This configuration is loaded into the agent's context to guide its behavior.

```xml
<!-- user_rule.md - Custom Rules for AI Agents -->
<rule name="task_management_workflow">
    <description>Rules for AI agents when working with the Markdown task system.</description>
    <guideline>1. **Receive Task:** Only work on tasks that are directly assigned or 'Todo' tasks that match the USER's search request. Always check and respect the 'Assignee' field.</guideline>
    <guideline>2. **Check Dependencies:** Before starting, verify that all tasks in the 'Dependencies' section of the task file are in 'Done' status.</guideline>
    <guideline>3. **Update Status:** As soon as starting a task, suggest updating the task file status to 'InProgress_By_[AI_Agent_Name]' and log in 'AI Agent Log'.</guideline>
    <guideline>4. **Execute Sub-tasks:** Handle sub-tasks sequentially. After each sub-task is completed, suggest marking the checkbox and logging details.</guideline>
    <guideline>5. **Code Management:** Always `git pull` before starting code. Suggest `git commit` frequently with clear messages (including TaskID).</guideline>
    <guideline>6. **Handle Blockers:** If encountering issues, suggest updating task status to 'Blocked_By_[Reason]', log details and immediately notify the USER.</guideline>
    <guideline>7. **Complete Task:** When all sub-tasks and completion criteria are met, suggest updating task status to 'NeedsReview' and notify the USER.</guideline>
</rule>
```

--------------------------------

### Check Task Dependencies using cat and grep

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This command sequence first displays the content of a task file and then filters for the 'Status:' line to check if dependencies are met.

```bash
# Check dependencies before claiming
cat ./V1_MVP/01_Database/task_01.01_users_table.md | grep "Status:"
```

--------------------------------

### Git Workflow: Staging and Committing Changes

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This sequence demonstrates staging specific files and committing them with a message that includes a task ID, essential for tracking code changes related to specific tasks.

```bash
# Working on a Task
git add src/routes/auth/register.ts
git commit -m "task_02.01.01: Implement request validation for user registration"
```

--------------------------------

### SvelteKit Server-Side Login Form Handling

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

A SvelteKit server-side module (+page.server.ts) for handling login form submissions. It includes server-side validation, user authentication, session cookie management, and redirection logic. This code ensures security by never trusting client-side input.

```typescript
import type { Actions, PageServerLoad } from './$types';
import { fail, redirect } from '@sveltejs/kit';
import { validateEmail, validatePassword } from '$lib/server/validators/auth';
import { authenticateUser } from '$lib/server/auth';

export const load: PageServerLoad = async ({ locals }) => {
  // Redirect if already authenticated
  if (locals.user) {
    redirect(303, '/dashboard');
  }
  return {};
};

export const actions = {
  default: async ({ request, cookies }) => {
    const formData = await request.formData();
    const email = formData.get('email')?.toString() ?? '';
    const password = formData.get('password')?.toString() ?? '';

    // Server-side validation (never trust client input)
    if (!validateEmail(email)) {
      return fail(400, { error: 'Invalid email format', email });
    }

    if (!validatePassword(password)) {
      return fail(400, { error: 'Password must be at least 8 characters', email });
    }

    try {
      const { user, token } = await authenticateUser(email, password);

      cookies.set('session', token, {
        path: '/',
        httpOnly: true,
        secure: true,
        sameSite: 'strict',
        maxAge: 60 * 60 * 24 * 7 // 1 week
      });

      redirect(303, '/dashboard');
    } catch (error) {
      return fail(401, { error: 'Invalid credentials', email });
    }
  }
} satisfies Actions;
```

--------------------------------

### Git Workflow: Creating a Pull Request

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This command uses the GitHub CLI to create a pull request, including a title referencing the task ID and a descriptive body explaining the changes.

```bash
# Create Pull Request
gh pr create --title "task_02.01.01: User Registration Endpoint" \
  --body "Implements user registration with email validation and password hashing."
```

--------------------------------

### Define User and Auth Response Structs in Rust

Source: https://github.com/tymon3568/folder-tasks/blob/master/task_XX.YY.ZZ_taskName.md

Defines the structures for user data and authentication responses. The `UserResponse` contains basic user information, while `AuthResponse` includes the user data and an authentication token.

```rust
use chrono::{DateTime, Utc};

#[derive(Debug)]
pub struct UserResponse {
    pub id: String,
    pub email: String,
    pub full_name: String,
    pub created_at: DateTime<Utc>,
}

#[derive(Debug)]
pub struct AuthResponse {
    pub user: UserResponse,
    pub token: String,
}
```

--------------------------------

### GitHub Actions CI Configuration

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This YAML configuration defines a GitHub Actions workflow named 'CI' that runs on pull requests and pushes to main/master branches. It includes jobs for frontend tasks like typechecking, linting, and testing using Bun.

```yaml
# .github/workflows/ci.yml
name: CI

on:
  pull_request:
  push:
    branches:
      - main
      - master

jobs:
  frontend:
    name: Frontend (bun): typecheck, lint, test
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Typecheck
        run: bun run check

      - name: Lint
        run: bun run lint

      - name: Tests
        run: bun run test
```

--------------------------------

### Search for Unclaimed Tasks using grep

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This command searches recursively for files containing 'Status: Todo' within the specified directory, helping to identify unclaimed tasks.

```bash
# Search for unclaimed tasks
grep -r "Status: Todo" ./V1_MVP/02_Backend_Core_Features/
```

--------------------------------

### Axum Handler for User Registration

Source: https://github.com/tymon3568/folder-tasks/blob/master/task_XX.YY.ZZ_taskName.md

Illustrates a basic Axum handler function for the user registration endpoint. It outlines the steps for receiving, validating, processing (hashing password, database insertion), and responding to registration requests.

```rust
use axum::extract::State;
use axum::http::StatusCode;
use axum::response::IntoResponse;
use axum::Json;
use crate::errors::AppError;
use crate::models::auth_model::RegisterUserRequest;
use crate::models::user_model::AuthResponse;
use crate::services::auth_service::AuthService;

pub async fn register_handler(
    State(auth_service): State<AuthService>,
    Json(payload): Json<RegisterUserRequest>,
) -> Result<impl IntoResponse, AppError> {
    // 1. Validation (handled by validator crate)
    payload.validate()?;

    // 2. Check if email exists (example)
    if auth_service.user_exists(&payload.email).await? {
        return Err(AppError::new(StatusCode::CONFLICT, "AUTH_EMAIL_EXISTS"));
    }

    // 3. Hash password (using Argon2, not shown here)
    let hashed_password = "hashed_password_placeholder"; // Replace with actual hashing

    // 4. Create user in database (example)
    let user = auth_service.create_user(&payload.email, hashed_password, &payload.full_name).await?;

    // 5. Generate JWT Token (not shown here)
    let token = "jwt_token_placeholder"; // Replace with actual token generation

    // 6. Prepare and return response
    let response = AuthResponse {
        user: UserResponse {
            id: user.id,
            email: user.email,
            full_name: user.full_name,
            created_at: user.created_at,
        },
        token: token.to_string(),
    };

    Ok((StatusCode::CREATED, Json(response)))
}
```

--------------------------------

### POST /api/v1/auth/register

Source: https://github.com/tymon3568/folder-tasks/blob/master/task_XX.YY.ZZ_taskName.md

Allows new users to register an account by providing their email, password, and full name. The endpoint validates input, hashes the password, and saves the user information to the database, returning a JWT token upon successful registration.

```APIDOC
## POST /api/v1/auth/register

### Description
Creates a new user account. Requires email, password, and full name. Validates input, hashes password, and returns user details along with an authentication token.

### Method
POST

### Endpoint
`/api/v1/auth/register`

### Parameters
#### Request Body
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password (minimum 8 characters).
- **full_name** (string) - Required - User's full name.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "SecretPassword123!",
  "full_name": "John Doe"
}
```

### Response
#### Success Response (201 Created)
- **user** (object) - Contains user details.
  - **id** (string) - Unique user identifier.
  - **email** (string) - User's email address.
  - **full_name** (string) - User's full name.
  - **created_at** (string) - Timestamp of user creation.
- **token** (string) - JWT token for authentication.

#### Response Example (Success)
```json
{
  "user": {
    "id": "users:ulid_string",
    "email": "user@example.com",
    "full_name": "John Doe",
    "created_at": "2025-06-05T10:00:00Z"
  },
  "token": "eyJhbGciOiJIUzI1Ni..."
}
```

#### Error Responses
- **400 Bad Request**
  - `VAL_INVALID_EMAIL`: Invalid email format.
  - `VAL_WEAK_PASSWORD`: Password is too short (less than 8 characters).
- **409 Conflict**
  - `AUTH_EMAIL_EXISTS`: Email address is already in use.
- **500 Internal Server Error**
  - `SYS_INTERNAL_ERROR`: An unexpected server error occurred.
```

--------------------------------

### Blocker Handling: Update Task Status

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This markdown snippet illustrates the first step in handling a blocker: updating the task's status to 'Blocked_By_[Reason]', clearly indicating the issue.

```markdown
# Blocker Handling Protocol

## Step 1: Update Task Status
**Status:** Blocked_By_Merge_Conflict_in_src/routes/(app)/auth
```

--------------------------------

### Define User Registration Request Struct in Rust

Source: https://github.com/tymon3568/folder-tasks/blob/master/task_XX.YY.ZZ_taskName.md

Defines the structure for the incoming user registration request payload. It includes fields for email, password, and full name, with validation annotations from the 'validator' crate.

```rust
use validator::Validate;

#[derive(Debug, Validate)]
pub struct RegisterUserRequest {
    #[validate(email)]
    pub email: String,
    #[validate(length(min = 8))]
    pub password: String,
    pub full_name: String,
}
```

--------------------------------

### Git Workflow: Pushing Code Changes

Source: https://context7.com/tymon3568/folder-tasks/llms.txt

This command pushes the completed code changes for a task to a feature branch on the remote repository, preparing for a pull request.

```bash
# Push When Code Portion Complete
git push origin feature/user-registration
```