# Design Workflow (smaking.v4.design)

## Purpose
Create unique Design.md files per site from a themed list, register batches, and enforce portfolio-wide uniqueness before implementation.

## Prereqs
- Interpreter: `python3.12` via `uv run python3.12`
- Paths: `.smbatcher/REGISTRY.md`, `.smbatcher/batches/`, `sites/`
- Virtualenv: managed by `uv`

## Inputs
- `--sites` comma list: `domain:title:desc[:theme]` (theme tag optional, not used in path)
- `--batch-size` (default 20)
- `--dry-run` (no writes)

## Status Codes
| Code | Meaning | Set By |
|------|---------|--------|
| B | Batched (ready for design) | Main agent via `batch.sh` |
| d | Design in-progress | Subagent via `start.py` |
| D | Design complete | Subagent via `complete.py` |

## Steps

### Main Agent Steps

1. **Register (prepare phase)**: `tools/prepare/register.sh --input-file sites.csv` (locked).

2. **Create batch (prepare phase)**: `tools/prepare/batch.sh --version v1 --batch-size N --input-file sites.csv`
   (locked). Sets `B`, writes `Batch_<ID>.md`, scaffolds `sites/<domain-vX>/`.

3. **Get uniqueness signals**:
   - `tools/design/frequency.sh --root .` — check overused/underused terms
   - `tools/design/list-designed.sh --root .` → `${TMP}/DESIGNED.md`
   - `tools/design/analyze-seeds.sh --batch-id <ID>` — annotate batch with unused seed/style combos

4. **Verify directories**: `tools/design/check-dirs.sh --batch-id <ID> --root .`
   - If missing, STOP and rerun prepare/batch step
   - Do NOT create directories manually (no `mkdir -p`)

5. **Launch subagents**: Launch ~10 subagents in parallel, each owning ONE site to design.
   - **CRITICAL**: Send a SINGLE message with MULTIPLE Task tool calls
   - DO NOT launch sequentially (one at a time)
   - DO include all Task calls in the same response

### Subagent Steps (Per Site)

6. **Mark design start**:
   ```bash
   tools/design/start.sh <domain> --root .
   ```
   Sets status B → d.

7. **Generate Design.md**:
   - Build prompts using site metadata + similarity findings
   - Use `${TMP}` from `.wdmaker/config.toml` for all temporary artifacts (no `/tmp`)
   - Use the Frontend-design plugin/skill to ideate bold layout/typography/motion
   - Write `DESIGN.md` with required headings/notes (no placeholders)
   - Do NOT manually scan files (no cat/ls/find/wc/globs)
   - Do NOT craft ad-hoc scripts/reports/summaries

8. **Validate**:
   ```bash
   tools/design/check-design.sh sites/<domain-vX>/DESIGN.md
   ```
   - If similarity ≥ threshold (50%) → redesign; keep status in `d` until resolved
   - Must pass validation before proceeding

9. **Stamp**:
   ```bash
   tools/design/write-design.sh sites/<domain-vX>/DESIGN.md --auto
   ```

10. **Mark design complete**:
    ```bash
    tools/design/complete.sh <domain> --root .
    ```
    Sets status d → D (validates DESIGN.md before marking).

## Status Flow
```
Main agent: B (batch.sh)
     ↓
Subagent: d (start.sh) → [write DESIGN.md] → D (complete.sh)
```

## Outputs
- Updated REGISTRY with statuses and batch id
- `sites/<domain-vX>/DESIGN.md`
- `.smbatcher/batches/batch-XXX-design.md`
- Run log in `.smbatcher/runs/`

## Failure Handling
- Missing sites input → fail fast.
- Similarity above threshold → redesign loop (keep d).
- Registry/paths missing → fail fast with message.
- Validation failure → keep d, fix issues, revalidate.

## Locking
- All status updates use `REGISTRY.lock` via `fcntl.flock`
- `start.sh` and `complete.sh` acquire lock before updating REGISTRY
- Do not bypass locking mechanism