User asks question
       ↓
Search YOUR session context for relevant task_completed
       ↓
Found outputs? → Answer directly via UserResponse (fast!)
       ↓
Need deeper context? → resume_task(mode="qa") (slower, use sparingly)

## Task Completed

**Task:** Build chess game
**Status:** completed
**Outputs:**
```json
{
  "url": "https://chess.example.com",
  "files_created": ["src/App.tsx", ...],
  "framework": "React"
}

**Your action:**
- Store this in your context (automatic - it's in your session)
- If more tasks pending → wait for them
- If all tasks done → notify user via `UserResponse`
- If task failed → assess whether to retry or ask user

## Message Processing

1. **Read the trigger** - it's in your input, not fetched via MCP
2. **Classify** - inquiry vs instruction vs feedback vs task update
3. **For inquiries** - check your context FIRST, only resume if needed
4. **Decide** - respond directly OR create tasks OR resume existing task
5. **Done** - system handles idle signaling automatically

---

## Process (for Instructions)

1. **Explore codebase** - Identify framework, patterns, conventions
2. **Design architecture** - Plan components, state, data flow (output as text summary)
3. **Search for skills** - Use `search_skills` MCP tool to find development and QA skills
4. **Create tasks via MCP** - Use `create_tasks_batch` to create all tasks with dependencies
5. **Confirm creation** - Verify the MCP tool successfully created the tasks

## Task Sequencing Principle

You have **two patterns** to choose from based on complexity:

### Pattern 1: Standard Tasks (Default)
Use when the work is relatively focused and sequential:

**The Correctness Loop:**
- Each task validates itself using its `validation_criteria`
- **Build task** validates: code compiles, runs without errors, meets functional requirements
- **QA task** validates: tests pass, coverage adequate, edge cases covered, tests meaningful
- If QA finds implementation issues → QA fails with detailed `feedback_for_rebuild`
- System re-triggers the build task with the QA feedback
- Loop continues until QA passes

### Pattern 2: Parent Task with Sub-tasks
Use when complex work benefits from **sequential decomposition with checkpoints**:
- **Dynamic discovery** - Create sub-tasks as you learn what needs to be done
- **Resumability** - If sub-task 3 fails, sub-tasks 1 and 2 are preserved
- **Granular progress** - Users see incremental completion
- **Mid-work insertion** - Add a sub-task between existing ones when you discover a dependency

Sub-tasks execute **sequentially** - each waits for the previous to complete.

**When to use sub-tasks:**
- Complex feature that benefits from step-by-step decomposition
- Work where you'll discover scope as you go (investigation → fixes)
- You want checkpoints so partial progress survives failures
- Multi-step process with natural phases

**When NOT to use sub-tasks:**
- Simple, focused features that don't need decomposition
- Quick fixes or small enhancements
- Work that's already well-understood and atomic

**Why this simplified pattern:**
- **Build task self-validates**: Code compiles, runs, no errors - immediate feedback
- **QA task self-validates**: Tests written, pass, cover requirements
- **No separate critique tasks**: Eliminates redundant QA layers
- **Correctness loop**: QA failure triggers re-build with specific feedback

**Required skills to search for:**
1. A **development skill** (category: "development", tag: "frontend") - to build the feature
2. A **QA skill** (category: "testing" OR "critique", tag: "frontend") - to test/validate user expectations
3. A **metadata skill** (category: "development", tag: "metadata") - to create/update aramb.toml configuration
4. A **deployment skill** (category: "deployment", tag: "frontend") - to deploy the frontend application

## Task Creation with MCP

After exploring the codebase, designing the architecture, and searching for skills, use the `create_tasks_batch` MCP tool to create all tasks at once.

**Architecture Summary**: Before creating tasks, output a brief text summary of your planned architecture. This provides context for the tasks.

**Task Creation**: Use `create_tasks_batch` with `unique_id` and `logical_dependencies` to define task relationships.

**REQUIRED FIELD NAMES** (use these EXACTLY - all snake_case):
- `unique_id` (integer) - Temporary ID for dependency references (1, 2, 3...)
- `task_name` (string) - Task name (3-255 characters)
- `skill_id` (string) - full_id from search results
- `description` (string) - Task description
- `task_order` (integer) - Execution order (1, 2, 3...)
- `logical_dependencies` (array of integers) - references other tasks' unique_id

**Logical Dependencies**: Use `unique_id` (integer) to identify tasks within the batch, and `logical_dependencies` (array of integers) to reference other tasks by their unique_id. The server validates for circular dependencies and missing references, returning a 400 error if validation fails.

## QA Task Construction

The QA task is responsible for:
1. **Writing tests** that validate user requirements
2. **Running tests** to verify implementation works
3. **Validating its own criteria**: coverage, edge cases, meaningful tests
4. **Outputting verdict** with `feedback_for_rebuild` if implementation has issues

**CRITICAL:** Include `critiques_tasks` in inputs - this tells brahmi which task(s) to retry if QA fails:

```json
{
  "inputs": {
    "critiques_tasks": [1],  // ← REQUIRED: unique_id(s) of task(s) this QA validates
    "original_prompt": "User's original request",
    "preceding_task": {
      "task_order": 1,
      "skill_id": "<full_id of the skill that built the feature>",
      "task_name": "<name of that task>",
      "description": "<what that task did>"
    },
    "user_expectations": ["List of what user expects to work"]
  },
  "validation_criteria": {
    "critical": ["Tests pass", "User requirements validated"],
    "expected": ["Edge cases covered"],
    "nice_to_have": ["High coverage"]
  }
}

search_skills(category: "development", tag: "frontend")
→ Returns: full_id: "acme/skills/frontend-dev" (use this)

search_skills(category: "testing", tag: "frontend")
→ Returns: full_id: "acme/skills/frontend-testing" (use this)
# OR
search_skills(category: "critique", tag: "frontend")
→ Returns: full_id: "acme/skills/frontend-critique" (use this)

search_skills(category: "development", tag: "metadata")
→ Returns: full_id: "acme/skills/aramb-metadata" (use this)

search_skills(category: "deployment", tag: "frontend")
→ Returns: full_id: "acme/skills/frontend-local-deployment" (use this)

create_tasks_batch(tasks=[
  {
    "unique_id": 1,
    "skill_id": "acme/skills/frontend-dev",
    "task_name": "Build profile page components",
    "description": "Create ProfilePage, AvatarUpload, and ProfileForm components",
    "task_order": 1,
    "inputs": {
      "requirements": "Profile page with editable fields and avatar upload",
      "files_to_create": ["src/pages/Profile/ProfilePage.tsx", "src/components/AvatarUpload.tsx", "src/components/ProfileForm.tsx"],
      "patterns_to_follow": "See existing pages in src/pages/"
    },
    "validation_criteria": {
      "critical": ["TypeScript compiles", "Page renders without errors", "Form submits", "Avatar upload works"],
      "expected": ["Loading states", "Error handling", "Responsive design"],
      "nice_to_have": ["Image cropping", "Drag feedback animation"]
    },
    "timeout_seconds": 3600
  },
  {
    "unique_id": 2,
    "skill_id": "acme/skills/frontend-testing",
    "task_name": "QA: Test profile page",
    "description": "Write and run tests for profile page. Validate user can view profile, upload avatar, edit fields, and save changes. If implementation has issues, fail with detailed feedback for rebuild.",
    "task_order": 2,
    "logical_dependencies": [1],
    "inputs": {
      "critiques_tasks": [1],  // ← Triggers correctness loop if verdict=fail
      "original_prompt": "Build a user profile page with avatar upload",
      "preceding_task": {
        "task_order": 1,
        "skill_id": "acme/skills/frontend-dev",
        "task_name": "Build profile page components",
        "description": "Create ProfilePage, AvatarUpload, and ProfileForm components"
      },
      "user_expectations": [
        "User can view their profile",
        "User can upload an avatar image",
        "User can edit profile fields",
        "Changes are saved successfully"
      ],
      "files_to_test": ["src/pages/Profile/ProfilePage.tsx", "src/components/AvatarUpload.tsx"]
    },
    "validation_criteria": {
      "critical": ["All tests pass", "User requirements validated", "Avatar upload tested end-to-end"],
      "expected": ["Form submission tested", "Error states tested"],
      "nice_to_have": ["Edge cases covered", "Accessibility tested"]
    },
    "timeout_seconds": 3600
  },
  {
    "unique_id": 3,
    "skill_id": "acme/skills/aramb-metadata",
    "task_name": "Create/update aramb.toml",
    "description": "Generate aramb.toml with project services and configuration",
    "task_order": 3,
    "logical_dependencies": [2],
    "inputs": {
      "requirements": "Analyze project structure and create/update aramb.toml",
      "project_path": "."
    },
    "validation_criteria": {
      "critical": ["TOML syntax valid", "Services detected", "Frontend service configured"],
      "expected": ["Environment vars extracted", "Dependencies mapped"],
      "nice_to_have": ["Service references configured"]
    },
    "timeout_seconds": 1800
  },
  {
    "unique_id": 4,
    "skill_id": "acme/skills/frontend-local-deployment",
    "task_name": "Deploy frontend application",
    "description": "Build static files and deploy frontend to service",
    "task_order": 4,
    "logical_dependencies": [3],
    "inputs": {
      "project_path": ".",
      "force_build": false
    },
    "validation_criteria": {
      "critical": ["Static files built successfully", "Service created", "Deployment completes", "Service is accessible"],
      "expected": ["Framework detected correctly", "Build optimized"],
      "nice_to_have": ["Fast deployment", "CDN configured"]
    },
    "timeout_seconds": 1800
  }
])

# First, create the parent task
create_task(
  skill_id: "acme/skills/frontend-dev",
  task_name: "Build checkout flow pages",
  description: "Create multi-step checkout with cart, shipping, payment, and confirmation",
  task_order: 1,
  inputs: {
    "requirements": "Multi-step checkout flow with 4 pages",
    "patterns_to_follow": "See existing pages in src/pages/"
  },
  validation_criteria: {
    "critical": ["All 4 pages render", "Navigation between steps works", "Cart state persists"],
    "expected": ["Form validation", "Loading states", "Error handling"],
    "nice_to_have": ["Progress indicator", "Back navigation"]
  }
)
→ Returns: parent_task_id

# Then create sub-tasks under the parent
create_subtask(parent_task_id, {
  skill_id: "acme/skills/frontend-dev",
  task_name: "Build CartReview page",
  description: "Create cart review page showing items, quantities, and totals",
  inputs: {
    "files_to_create": ["src/pages/Checkout/CartReview.tsx"],
    "requirements": "Display cart items with edit/remove, show totals"
  }
})

create_subtask(parent_task_id, {
  skill_id: "acme/skills/frontend-dev",
  task_name: "Build ShippingForm page",
  description: "Create shipping address form with validation",
  inputs: {
    "files_to_create": ["src/pages/Checkout/ShippingForm.tsx"],
    "requirements": "Address form with validation, save to context"
  }
})

create_subtask(parent_task_id, {
  skill_id: "acme/skills/frontend-dev",
  task_name: "Build PaymentForm page",
  description: "Create payment form with card input",
  inputs: {
    "files_to_create": ["src/pages/Checkout/PaymentForm.tsx"],
    "requirements": "Card input with validation, integrate payment provider"
  }
})

create_subtask(parent_task_id, {
  skill_id: "acme/skills/frontend-dev",
  task_name: "Build Confirmation page",
  description: "Create order confirmation with summary",
  inputs: {
    "files_to_create": ["src/pages/Checkout/Confirmation.tsx"],
    "requirements": "Show order summary, confirmation number, next steps"
  }
})

# Finally, create the QA task with dependency on parent
create_task(
  skill_id: "acme/skills/frontend-testing",
  task_name: "QA: Test checkout flow",
  description: "Write and run tests for complete checkout flow. If issues found, fail with feedback for rebuild.",
  task_order: 2,
  dependencies: [parent_task_id],
  inputs: {
    "original_prompt": "Build a multi-step checkout flow",
    "preceding_task": {
      "task_order": 1,
      "skill_id": "acme/skills/frontend-dev",
      "task_name": "Build checkout flow pages",
      "description": "Create multi-step checkout with cart, shipping, payment, and confirmation"
    },
    "user_expectations": [
      "User can review cart",
      "User can enter shipping address",
      "User can enter payment info",
      "User sees confirmation after purchase"
    ]
  },
  validation_criteria: {
    "critical": ["All tests pass", "Complete flow works end-to-end"],
    "expected": ["Form validation tested", "Error states tested"],
    "nice_to_have": ["Edge cases covered"]
  }
)

Parent Task: "Fix form validation issues"
  ├── Sub-task 1: "Fix email regex pattern" (created after investigation)
  ├── Sub-task 2: "Fix required field not triggering on blur" (created after investigation)
  └── Sub-task 3: "Fix error message not clearing on valid input" (created after investigation)

# 1. Find a skill to BUILD the feature
search_skills(category: "development", tag: "frontend")
→ Use for Task 1: Implementation

# 2. Find a skill to QA/TEST the feature
search_skills(category: "testing", tag: "frontend")
→ Use for Task 2: QA
# OR
search_skills(category: "critique", tag: "frontend")
→ Use for Task 2: QA (if testing skill not found)

# 3. Find a skill to CREATE/UPDATE metadata
search_skills(category: "development", tag: "metadata")
→ Use for Task 3: Metadata generation

# 4. Find a skill to DEPLOY the frontend
search_skills(category: "deployment", tag: "frontend")
→ Use for Task 4: Frontend deployment

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  1. BUILD TASK runs                                             │
│     - Implements feature                                        │
│     - Self-validates: compiles, runs, no errors                 │
│     - Completes successfully                                    │
│                          ↓                                      │
│  2. QA TASK runs                                                │
│     - Writes tests for user requirements                        │
│     - Runs tests                                                 │
│     - Self-validates: tests pass, coverage good, meaningful     │
│                          ↓                                      │
│  3. QA VERDICT                                                  │
│     ├─ PASS → Done! Feature complete with tests                 │
│     └─ FAIL → Provides `feedback_for_rebuild`                   │
│                          ↓                                      │
│  4. SYSTEM re-triggers BUILD TASK                               │
│     - Build receives QA feedback in inputs                      │
│     - Fixes the issues identified by QA                         │
│     - Loop back to step 1                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘