# Implement Workflow (smaking.v4.implement)

## Purpose
Implement HTML/CSS/JS per site using existing Design.md, with batch locking, concurrency control, validation, and cleanup/retry for failed attempts. LLM coding tools generate the real assets; orchestrators handle locking, retries, and logging only.

## Prereqs
- Interpreter: `python3.12` via `uv run python3.12`
- Paths: `.smbatcher/REGISTRY.md`, `.smbatcher/batches/`, `sites/`
- Virtualenv: managed by `uv`
- Design complete: all sites in batch at status D

## Inputs
- `--batch` (id or `auto`)
- `--concurrency` worker count (default 4)
- `--dry-run` (no writes)

## Status Codes
| Code | Meaning | Set By |
|------|---------|--------|
| O | Open for implementation | Main agent via `lock.sh` |
| i | Implement in-progress | Subagent via `start.sh` |
| I | Implement complete | Subagent via `complete.sh` |
| Q | Done (queued/complete) | Main agent via `finish.sh` |

## Steps

### Main Agent Steps

1. **Select batch**: Check `.smbatcher/batches/Batch_*.md` for sites at status D. Typical: `BATCH=001`.

2. **Lock batch and open for implementation**:
   ```bash
   tools/implement/lock.sh "$BATCH"
   ```
   - Verifies all sites status D
   - Sets D → O atomically
   - Creates implement tracker

3. **Launch subagents**: Launch ~10 subagents in parallel, each owning ONE site to implement.
   - **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)

4. **Mark implement start**:
   ```bash
   tools/implement/start.sh <domain> --root .
   ```
   Sets status O → i.

5. **LLM authoring**:
   - Read `sites/<domain-vX>/DESIGN.md`
   - Write `index.html`, `styles.css`, `script.js`, assets
   - Use `${TMP}` from `.wdmaker/config.toml` for temp artifacts (no `/tmp`)
   - Do NOT manually scan files (no cat/ls/find/wc/globs)
   - Do NOT craft ad-hoc scripts/reports/summaries
   - No placeholders — deliver complete, production-ready files

6. **Validate**:
   ```bash
   # Basic file presence check
   tools/implement/check-outputs.sh sites/<domain-vX>

   # Comprehensive verification
   tools/check/verify-site.sh sites/<domain-vX>

   # Design compliance check
   tools/check/design-compliance.sh sites/<domain-vX>
   ```
   - If fail, fix issues and revalidate
   - Must pass validation before proceeding

7. **Mark implement complete**:
   ```bash
   tools/implement/complete.sh <domain> --root .
   ```
   Sets status i → I (validates outputs before marking).

### Main Agent Finalization

8. **Finalize batch** (after all subagents complete):
   ```bash
   tools/implement/finish.sh --batch "$BATCH" --root .
   ```
   Sets status I → Q for all completed sites in batch.

## Status Flow
```
Main agent: O (lock.sh)
     ↓
Subagent: i (start.sh) → [write code] → I (complete.sh)
     ↓
Main agent: Q (finish.sh)
```

## Outputs
- Updated REGISTRY statuses O/i/I/Q per site
- `.smbatcher/batches/batch-XXX-implement.md`
- `sites/<domain-vX>/{index.html,styles.css,script.js,assets/}`
- Run log in `.smbatcher/runs/`

## Failure Handling
- Missing/stale Design.md → fail fast, reset site to O, do not leave batch locked.
- Lock contention → exit with notice.
- Validation failures → fix issues, revalidate; if unrecoverable, site stays at i.

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

## Commands Summary
| Command | Purpose | Role |
|---------|---------|------|
| `tools/implement/lock.sh <BATCH>` | Lock batch, D → O | Main |
| `tools/implement/start.sh <domain>` | Mark i | Subagent |
| `tools/implement/complete.sh <domain>` | Mark I | Subagent |
| `tools/implement/finish.sh --batch <BATCH>` | Mark Q | Main |
| `tools/implement/check-outputs.sh <site-dir>` | Validate files | Both |
| `tools/check/verify-site.sh <site-dir>` | Full verification | Both |