# CoworkBolt — AI Agent Instructions

> This file provides structured context for LLM agents, AI crawlers, and Claude Cowork sessions.
> Full skill reference: /skill.md (repo root) or see inline sections below.

## What is CoworkBolt?

CoworkBolt is a PWA task bridge between human users and Claude Cowork (Claude Code on the web).
Users create **workflows** and queue **jobs**. You (Claude Cowork) execute the jobs and write results back.

## Application Routes

| Route | Purpose | Auth required |
|---|---|---|
| / | Marketing landing page | No |
| /dashboard | Overview: stats, workflow tiles, create workflow | Yes |
| /workflows/:id | Workflow detail: job timeline, mode toggle, setup instructions | Yes |
| /reports | All job reports across all workflows, grouped by workflow | Yes |
| /account | User profile, sign out | Yes |

## Data Store

Firebase Firestore — all user data lives under:

```
/users/{uid}/tasks/{taskId}              ← workflow document
/users/{uid}/tasks/{taskId}/jobs/{jobId} ← job document
```

## Workflow Document Fields

```
name        string   Display name
mode        string   "queue" (On-Demand) | "collect" (Auto-Collect)
createdAt   Timestamp
```

## Job Document Fields

```
id                     string    Firestore document ID
taskInput              string    Primary instruction — WHAT TO DO
additionalInstructions string    Extra context, constraints, output format
status                 string    "pending" | "running" | "done" | "failed"
report                 string    Your output — HTML, plain text, or JSON
reportedAt             Timestamp When the report was last saved
createdAt              Timestamp When the job was queued
```

## Machine-Readable DOM

When viewing any page in a browser, look for:

- `<div id="cowork-agent-context" hidden>` — JSON blob with full page state
- `data-cowork-entity="workflow"` — workflow elements; also carries `data-cowork-id`, `data-cowork-name`, `data-cowork-mode`
- `data-cowork-entity="job"` — job card elements; also carries `data-cowork-job-id`, `data-cowork-status`, `data-cowork-input`, `data-cowork-has-report`
- `data-cowork-entity="job-report"` — report card elements on /reports
- `data-cowork-stat` — live stat elements; carries `data-cowork-count`

## Workflow Modes

**On-Demand** (`mode: "queue"`)
User queues each job manually. You pick up `status: "pending"` jobs, execute them, write a report, and mark `status: "done"`.

**Auto-Collect** (`mode: "collect"`)
You run autonomously. No job is queued. You create a new job document with `status: "done"` and your findings in `report`.

## Job Lifecycle

```
pending → running → done
                 ↘ failed
```

Always transition to `running` before starting work. The user sees this status in real time.

## Report Format

The `report` field is auto-detected and rendered in the browser:

- Contains HTML tags → rendered as HTML (tables, lists, headings, code blocks all styled)
- No HTML tags → rendered as monospace pre block (use for plain text or JSON)

Prefer HTML for structured output. Example minimal HTML report:

```html
<h2>Result</h2>
<p>Task completed successfully.</p>
<ul><li>Finding 1</li><li>Finding 2</li></ul>
```

## Common Patterns

Read `job.taskInput` (primary instruction) and `job.additionalInstructions` (constraints).
Execute the work. Write result to `report`. Set `status` to `"done"` or `"failed"`.

### Code review
Read referenced files → produce HTML findings table → set status "done"

### Research
Investigate topic → produce HTML comparison table + recommendation → set status "done"

### Code generation
Write code → wrap in HTML with `<pre><code>` block → set status "done"

### Content writing
Draft copy variants → plain text or simple HTML list → set status "done"

## Starting a Session

1. Identify the workflow (name + Firestore ID from the URL `/workflows/{taskId}` or from `cowork-agent-context`)
2. Confirm the mode: `queue` = wait for pending jobs; `collect` = run autonomously now
3. Execute and write reports

## More Documentation

- /skill.md — full skill reference with copy-paste Firebase code examples
- /llms.txt — this file