<div align="center">
  <img src="assets/readme-hero.png" alt="The Touchline pixel-art reconstruction squad gathered around its stadium command board." width="100%" />
  <p><strong>A browser-first squad that audits a website, stops for your decision, rebuilds from evidence, and verifies every state.</strong></p>
  <p><a href="#install">Install</a> · <a href="docs/architecture.md">Architecture</a> · <a href="docs/security.md">Security</a> · <a href="CONTRIBUTING.md">Contribute</a></p>
</div>

> [!IMPORTANT]
> Touchline is an unofficial independent open-source project. It is unrelated to and not endorsed by any named footballer, team, league, governing body, or the unrelated AI coaching product named Touchline. Player names are configurable role aliases; artwork is original and uses generic kits without official marks.

## What ships

- Fourteen portable Agent Skills for Codex, Claude/Claude Code, Cursor, Grok, Antigravity, ChatGPT, Lovable, and compatible hosts.
- A Node.js 22 TypeScript daemon, `touchline` CLI, MCP server, and signed localhost dashboard.
- A resumable append-only state machine: `DISCOVER → RECON → CONSULTATION_REQUIRED → SPEC → BUILD → VERIFY → COMPLETE`.
- Chrome-extension-first browser routing, safe direct Playwright fallback, Dembrandt token extraction, prompt exports, approval gates, and provenance records.
- Installed-skill capability routing, mandatory component-sourcing records, executable specification gates, and four-viewport pixel verification.

The dashboard is a real control surface, not a simulated team view: assignments, process events, artifacts, approvals, and run state come from the same persisted store used by the CLI and MCP server.

## Why the whistle matters

Touchline cannot build before Phase 3. Reconnaissance freezes what the site actually does, then asks you to choose:

1. 1:1 reconstruction or adaptation for a new product.
2. Preserve observed behavior or repair the original UX/console defects.
3. Target stack, deployment, and data constraints.

Missing evidence remains an explicit unknown. It never becomes an invented color, breakpoint, animation, or API payload.

## Install

Requirements: Node.js 22+, pnpm 10+, and at least one supported host CLI. A Chrome control extension or browser MCP is preferred; direct Playwright is the fallback.

```bash
pnpm install
pnpm build
npm install -g .
touchline setup
touchline doctor
touchline dashboard
```

Host installation:

| Host | Native path | Portable fallback |
|---|---|---|
| Codex | `codex plugin add touchline@mcpmarket-my-toolkit` | `npx skills add edenbuilds/touchline --all -g` |
| Claude Code | `/plugin marketplace add edenbuilds/touchline`, then `/plugin install touchline@touchline` | Copy `skills/` to `~/.claude/skills` |
| Cursor | Agent Skills discovery | Copy `skills/` to `~/.cursor/skills` |
| Grok / Antigravity | Host skill directory or custom CLI adapter | Use the exported host prompt |
| ChatGPT / Lovable | Exported prompt pack | Upload approved evidence with the matching prompt |

If npm is unavailable, download the identical package tarball and skills archive from GitHub Releases.

## First run

```bash
touchline audit https://example.com --workspace /absolute/path/to/project
# Read docs/research/reconnaissance.md, then record the consultation decision.
touchline approve <approval-id>
# Create design tokens, routing-map.md, component-sources.json, and bounded specs.
touchline gates <run-id>
touchline run <run-id>
# Start the implementation locally; BUILD cannot self-certify.
touchline verify <run-id> --candidate http://127.0.0.1:3000
touchline run <run-id> # completes only after verification passes
# Re-run verify against the deployed URL; a regression reopens BUILD.
touchline export-prompts <run-id> --targets all
```

The browser audit writes responsive screenshots and metadata to `docs/design-references/<run-id>/`, plus reconnaissance, HAR metadata, console JSONL, token, DOM, and asset manifests beneath `docs/research/`.

## Squad

| Role alias | Assignment |
|---|---|
| Pep Guardiola | Manager: policy, assignments, approvals |
| Lionel Messi | Captain: intent, synthesis, creative direction |
| Cristiano Ronaldo | Delivery and release finishing |
| Kevin De Bruyne / Xavi / Iniesta | Architecture, design systems, interaction fidelity |
| Neymar / Mbappé / Salah | Motion, performance, compatibility |
| Busquets / Van Dijk / Neuer | Data, security, QA and recovery |
| Modrić / Haaland / Roberto Carlos | Context, focused implementation, visual correction |

Every role is configuration. Map any installed model or CLI to any player, replace the roster, or add more than eleven specialists.

## Public surfaces

```text
touchline setup                         touchline_create_run
touchline doctor                        touchline_get_run
touchline dashboard                     touchline_list_agents
touchline audit <url> --workspace PATH  touchline_assign_task
touchline gates <run-id>                touchline_submit_evidence
touchline run <run-id>                  touchline_check_gates
touchline verify <run-id> --candidate   touchline_advance
touchline approve <approval-id>         touchline_request_approval
touchline export-prompts <run-id>       touchline_record_decision
touchline sources inspect <repo>        touchline_export_prompt_pack
touchline agents list                   touchline_verify
```

The HTTP API lives at `http://127.0.0.1:4317/api/v1`, is guarded by a random session token, and exposes SSE run events. See [architecture](docs/architecture.md) and [security](docs/security.md).

## Quality bar

CI runs type checks, unit/contract tests, dashboard/runtime builds, plugin and skill validation, package inspection, license audit, and secret scanning on Linux, macOS, and Windows. The included reference fixture covers lazy loading, tabs, modal, form, hover/focus, Canvas, animation, API calls, console failures, and four responsive widths.

Visual acceptance uses frozen references and a default ≤0.5% mismatch threshold at 1920, 1440, 768, and 390 pixels. The verifier emits actuals and pixel diffs, checks page height and heading order, and blocks on console errors or failed images. Baselines are never rewritten merely to pass.

## Project documents

[Architecture](docs/architecture.md) · [Security and approvals](docs/security.md) · [Host adapters](docs/host-adapters.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) · [Third-party notices](THIRD_PARTY_NOTICES.md)

MIT © edenbuilds