# BobNet OS Chat Orchestrator Harness

## Core Principle

The chat must not be a deterministic keyword toy. The owner should be able to type a new, complex workflow in plain English and have the local model decompose it into a board and cards.

The safe architecture is:

```text
User message
  -> host builds context prompt
  -> local model returns structured plan JSON
  -> host parses JSON
  -> host validates every action
  -> host shows preview
  -> owner confirms
  -> host executes through board services
  -> host logs chat proposal and action events
```

Free-form prose is allowed for answers, but only validated JSON can become board mutations.

## Planner Output Envelope

The local model must return a JSON object matching this shape:

```json
{
  "kind": "propose_actions",
  "answer": "I can create a board and a staged set of cards for this workflow.",
  "confidence": 0.82,
  "needs_clarification": false,
  "clarifying_questions": [],
  "actions": [
    {
      "type": "create_board_with_cards",
      "board": {
        "name": "Daily Research Newspaper",
        "goal": "Run daily multi-agent research and publish a local newspaper-style website."
      },
      "cards": [
        {
          "temp_id": "research_na",
          "title": "Research topic from North American sources",
          "body": "Gather source-linked facts and images for the daily edition.",
          "assignee": "Researcher",
          "status": "Ready",
          "workspace_mode": "Scratch",
          "acceptance_criteria": [
            "At least 5 source links captured.",
            "Every image includes source URL.",
            "Summary is neutral and dated."
          ]
        }
      ],
      "links": []
    }
  ]
}
```

Allowed `kind` values:

```text
answer
clarify
propose_actions
refuse
```

Allowed V1 action types:

```text
create_board
create_card
create_card_batch
create_board_with_cards
```

Future actions such as delete/archive/run-dispatch may be added only behind stronger confirmation.

## Card Draft Fields

Each model-generated card should support:

```json
{
  "temp_id": "string used by links before persistence",
  "title": "short imperative title",
  "body": "detailed task instructions",
  "assignee": "profile name or suggested role",
  "status": "Backlog or Ready",
  "workspace_mode": "Direct, Scratch, or Worktree",
  "acceptance_criteria": ["testable result"],
  "suggested_skills": ["optional"],
  "notes": "optional"
}
```

Host validation rules:

- Title required.
- Body required for generated work cards.
- Status must be Backlog or Ready for new planned cards.
- Workspace mode must be valid.
- Assignee can be blank only if the preview clearly marks it as unassigned.
- Unknown assignee should be a warning, not a crash.
- Dependency links must refer to known `temp_id` values.
- A plan with destructive actions must be refused in V1.

## Prompt Builder Requirements

The host should send the local model:

- Product identity: BobNet OS.
- Current board summary.
- Selected card summary if any.
- Available profile names.
- Allowed action grammar.
- Safety rules.
- User message.

System prompt sketch:

```text
You are the BobNet OS planning router.
BobNet OS is a local Windows desktop kanban and agent command surface.
Your job is to answer ordinary questions or propose structured BobNet OS actions.
Do not claim you executed actions. You only propose.
When the user asks to create boards, cards, workflows, daily automations, or agent pipelines, return propose_actions JSON.
When details are missing but a useful draft can be made, make the draft and mark assumptions.
Never propose destructive delete/archive actions in V1.
Return only valid JSON.
```

Context block sketch:

```text
Current board:
- id: board_123
- name: Test board
- goal: Verify BobNet OS
- card counts: Backlog 0, Ready 2, Blocked 1

Available agents:
- Coder
- Planner
- Researcher
- Reviewer

Selected card: none
```

## Parser Strategy

The parser should handle:

- Pure JSON response.
- JSON fenced in markdown.
- Extra text before/after JSON only if a single object can be extracted safely.

If parsing fails:

- Show a friendly error in chat.
- Save raw model output for debugging if safe.
- Do not mutate the board.

## Validator Strategy

Validator returns:

```csharp
public sealed record PlanValidationResult(
    bool IsValid,
    IReadOnlyList<string> Errors,
    IReadOnlyList<string> Warnings,
    ValidatedPlan? Plan);
```

Do not silently coerce dangerous fields. For example, if status is `Delete`, reject.

## Preview UI

A proposal preview should show:

- Board to be created or current board target.
- Cards to be added.
- Assignees and unknown-assignee warnings.
- Dependencies.
- Acceptance criteria.
- Buttons: `Approve and Create`, `Revise`, `Cancel`.

Nothing changes until approval.

## Complex Daily Research Newspaper Test

The following prompt must produce a structured board/card plan, not a refusal:

```text
I want to create a kanban board that I can run once a day that will send a series of researchers with different personalities out to research X task every day. Then I want that built into a locally hosted website I can see every morning when I wake up. We will also need a visual agent to format and make sure the website looks proper. I want it to look like an old time newspaper, like the New York Times, and have all images and pages link back to their source information.
```

Expected cards:

- Define daily topic and source policy.
- Researcher A: factual/background research.
- Researcher B: skeptical/source validation.
- Researcher C: visual/image source research.
- Synthesis/editor card.
- Local website generator card.
- Visual design QA card.
- Link/source attribution audit card.
- Daily automation schedule card.
- Final review card.

Expected dependencies:

- Synthesis depends on researchers.
- Website depends on synthesis and visual assets.
- Attribution audit depends on website.
- Final review depends on audit.

## Test Matrix

Unit tests:

- Parses valid JSON envelope.
- Extracts fenced JSON.
- Rejects invalid JSON.
- Validates `create_board_with_cards`.
- Warns on unknown assignee.
- Rejects destructive action.
- Converts temp dependency IDs to persisted card IDs.

Integration tests:

- Fake model returns complex newspaper plan.
- Host creates one board and multiple cards after confirmation.
- Host creates dependency links.
- Chat transcript shows activity and result.

Manual UI smoke:

1. Open Chat tab.
2. Paste complex newspaper prompt.
3. Confirm activity indicator appears.
4. Confirm proposal preview appears.
5. Approve.
6. Switch to Board tab.
7. Confirm board/cards/dependencies exist.