# Competitor Landscape Guide

> **Guide Origin**: Official | **ArcKit Version**: [VERSION]

`/arckit:competitors` discovers competitor landscape intelligence — rival suppliers, awarded-value market share, head-to-head comparison, and concentration — from live UK procurement notices via the UK Tenders MCP.

> **Agent Architecture**: This command uses a three-tier reader/writer subagent split. The **`arckit-tenders-reader`** subagent fetches evidence from the UK Tenders MCP (shared with `/arckit:tenders`, keeping that I/O isolated from your main context window). The orchestrator tier (the slash command) validates the reader's JSON payload against the `tenders-handoff.schema.json` schema and computes deterministic derived fields, including the supplier-rivalry head-to-head. The **`arckit-competitors-writer`** subagent then renders the final artefact. The slash command launches and coordinates both agents.

---

## What is Competitor Landscape Intelligence?

Competitor landscape intelligence is the systematic analysis of real awarded-contract data to understand who else is winning work in a capability space — their share of awarded value, which buyers they serve, and how a focal supplier compares against each rival.

**Key questions answered:**

- Who are the rival suppliers in this capability space, and what is their awarded-value share?
- How does a named supplier compare against each rival (shared buyers, recent wins)?
- How concentrated is the competitive landscape — is one supplier dominant?
- Which government buyers are active in this space?

> **Mandatory caveat.** Awarded value is not actual spend; figures are for market context and benchmarking, not the costed Economic Case. Never use CMPT figures as the cost line in a Green Book / Orange Book Economic Case without independent substantiation.

---

## When to Use

- **Before a vendor evaluation** — understand who has already won similar work and at what scale
- **Before scoping a competition** — know the realistic supplier pool and whether concentration is a risk
- **When building a Company Experience scorecard** — rival award history provides comparative context for `/arckit:score`
- **When assessing a sole-source or incumbent renewal** — evidence the broader competitive landscape
- **As part of a build-vs-buy analysis** — quantify the commercial supply depth alongside `/arckit:research`

---

## Prerequisites and Dependencies

| Artefact | Dependency | Why |
|----------|-----------|-----|
| Requirements (`ARC-*-REQ-*.md`) | OPTIONAL | Capability keywords and CPV codes can be derived from DR/FR/INT requirements |
| Architecture Principles (`ARC-000-PRIN-*.md`) | OPTIONAL | Identifies the organisational context for capability scoping |
| Vendor Profiles (`vendors/{slug}-profile.md`) | ENRICHED | Pre-existing vendor profiles gain an enriched Government Award History section |
| Risk Register (`ARC-*-RISK-*.md`) | DOWNSTREAM | Supplier-concentration findings feed R-xxx concentration/single-supplier-dependency risks |

---

## Inputs

The command accepts three input forms, which can be combined:

| Input | Flag / Form | Example |
|-------|-------------|---------|
| Supplier focus (focal supplier) | `--supplier 'Name'` | `/arckit:competitors --supplier 'Acme Cloud Ltd'` |
| Capability (free text) | bare arguments | `/arckit:competitors cloud hosting` |
| CPV code | `--cpv NNNNNNNN` | `/arckit:competitors --cpv 72200000` |

Use `--supplier 'Name'` to run a **supplier-focus** query: the named supplier becomes the focal point and the command produces a head-to-head comparison against each rival. Without `--supplier`, the command runs in **capability-focus** mode: it returns the full competitive set ranked by awarded-value share, with no focal supplier or head-to-head.

You can combine flags: `/arckit:competitors cloud hosting --cpv 72200000 --supplier 'Acme Cloud Ltd'`.

**CPV code format:** eight digits, optionally followed by a division suffix (`NNNNNNNN-N`). Common codes:

| Code | Category |
|------|----------|
| 72200000 | Software-related services |
| 72300000 | Data services |
| 72600000 | IT support and consultancy |
| 48000000 | Software packages and systems |
| 79000000 | Business services |
| 73000000 | R&D services |

---

## Scenario Matrix

| Scenario | Prompt | Focus |
|---------|--------|-------|
| Capability landscape | `/arckit:competitors digital identity verification` | Rival suppliers ranked by awarded-value share |
| Supplier head-to-head | `/arckit:competitors --supplier 'Acme Cloud Ltd'` | Focal supplier vs each rival |
| Scoped supplier analysis | `/arckit:competitors --cpv 72600000 --supplier 'Acme Cloud Ltd'` | Focal supplier vs rivals in a specific CPV |
| Market concentration check | `/arckit:competitors cloud hosting --cpv 72200000` | Concentration flag and supply-base depth |
| Vendor evaluation context | `/arckit:competitors managed security operations` | Who is winning, at what value, for which buyers |

---

## Command

```bash
/arckit:competitors [project-number-or-name] <--supplier 'Name' | capability | --cpv NNNNNNNN>
```

Outputs: `projects/<id>/research/ARC-<id>-CMPT-<NNN>-v1.0.md`

> **Multi-instance type**: `CMPT` artefacts are sequenced within the project's `research/` directory. Re-running produces a new numbered artefact (`CMPT-001`, `CMPT-002`, …) rather than overwriting the previous run.

---

## Long runs: Remote Control + push notifications

`/arckit:competitors` can take several minutes when the UK Tenders MCP needs to page through large result sets. To avoid babysitting the terminal, pair it with [Claude Code Remote Control](https://code.claude.com/docs/en/remote-control):

```bash
claude remote-control
```

Drive the session from claude.ai/code or the mobile app, then enable `/config → Push when Claude decides` so your phone gets a notification on completion. ArcKit's minimum Claude Code floor (v2.1.121) already covers the v2.1.110 RC requirement.

Caveats: Pro/Max plans only (no API keys, no Bedrock/Vertex/Foundry), push is a single on/off so chatty agents can over-notify, and the local `claude` process must keep running.

---

## Artefact Sections

A completed CMPT artefact contains:

1. **Executive Summary** — 3–5 key findings, concentration flag, focal supplier position (supplier-focus runs only).
2. **Query Scope** — recorded focus, CPV, supplier, keywords, date range so the run is reproducible.
3. **Competitive Set** — rival suppliers ranked by awarded-value share %, with award counts and key buyers.
4. **Focal Supplier** — on supplier-focus runs, the named supplier's awarded value, award count, and share pulled out of the competitive set.
5. **Head-to-Head** — on supplier-focus runs, the focal supplier compared against each rival: shared buyers, rival's most recent win. Renders not-applicable on capability-focus runs.
6. **Per-Rival Buyer Relationships and Recent Wins** — short prose per rival derived from the data.
7. **Concentration** — top-1 / top-3 share and a `HIGH` / `MEDIUM` / `LOW` flag with the rule applied.
8. **Representative Notices** — sample award notices with their `notice_url` (required for OGL attribution).
9. **Data Freshness and Source Health** — `Data current as of <ISO datetime>` or a freshness-unavailable note when the status endpoint was unreachable.
10. **Caveats** — including the mandatory awarded-value caveat.

### Concentration Flag Rules

| Flag | Condition |
|------|-----------|
| `HIGH` | Top-1 supplier share > 50% **or** top-3 supplier share > 80% |
| `MEDIUM` | Top-3 supplier share > 60% (and HIGH conditions not met) |
| `LOW` | All other cases |

A `HIGH` concentration flag should be registered as a supplier-dependency risk in the project Risk Register (`/arckit:risk`).

---

## Vendor Profile Enrichment

When a project already has a vendor profile (`vendors/{slug}-profile.md`) for a rival supplier, the `arckit-competitors-writer` subagent enriches that profile's **Government Award History** section with the award data from the competitive set. This means running `/arckit:competitors` before `/arckit:score` gives the score command richer comparative evidence to work with.

The writer performs a bounded section-merge — it updates only the `## Government Award History` section of pre-existing profiles. It does **not** create new profile files.

---

## Data Source

| Property | Detail |
|----------|--------|
| **MCP server** | `uk-tenders` (keyless, deferred load, shared with `/arckit:tenders`) |
| **Coverage** | ~677,000 UK contracting processes across five national portals |
| **Portals covered** | Find a Tender Service (FTS), Contracts Finder, Public Contracts Scotland, Sell2Wales, eTendersNI |
| **Refresh cadence** | Nightly |
| **Availability** | Best-effort single Cloud Run instance — no formal SLA. A dead endpoint degrades gracefully (the reader returns partial data and the artefact renders with degraded-source notes). |
| **Licence** | Open Government Licence v3.0 (OGL v3.0) |
| **Attribution** | Every notice record carries its official `notice_url`; artefacts must include the OGL v3.0 attribution line |

### OGL Attribution

Every CMPT artefact includes the attribution line:

> Contains public sector information licensed under the Open Government Licence v3.0.

The source data is re-published by the UK Tenders MCP from official UK procurement portals verbatim under the OGL v3.0. Every supplier figure and share percentage in the artefact traces to a `notice_url` citation from the relevant portal.

---

## Evaluation Criteria Explained

The reader returns evidence across five procurement portals, ranked internally by:

| Criterion | Purpose |
|-----------|---------|
| **Awarded value** | Primary ranking signal for rivals and share calculations |
| **Award count** | Proxy for market depth (many small awards vs few large awards) |
| **Share %** | Concentration measurement; feeds the top-1 / top-3 concentration flag |
| **Date range coverage** | Assesses recency and whether the competitive landscape has changed materially |
| **Source health** | Flags which portal feeds were degraded at fetch time |

---

## Integration with Other Commands

| Direction | Command | Integration |
|-----------|---------|-------------|
| **Input** | `/arckit:requirements` | CPV codes and capability keywords derived from DR/FR/INT |
| **Input** | `/arckit:tenders` | TNDR artefact narrows the capability scope and provides market benchmarks |
| **Output** | `/arckit:research` | Feed the competitive set into build-vs-buy analysis and TCO comparison |
| **Output** | `/arckit:score` | Rival award history used as comparative Company Experience evidence |
| **Output** | `/arckit:risk` | Concentration / single-supplier-dependency risk |
| **Output** | `/arckit:adr` | Competitive landscape and route-to-market decisions recorded as ADRs |

---

## Follow-on Actions

- Feed the competitive set into build-vs-buy analysis (`/arckit:research`)
- Use rival award history as Company Experience evidence in a vendor scorecard (`/arckit:score`)
- Register supplier-concentration or single-supplier-dependency risks (`/arckit:risk`)
- Record route-to-market decisions as ADRs (`/arckit:adr`)
- Escalate `HIGH` concentration findings to commercial lead before procurement scoping