Peec Agent

---
name: peec-agent
description: Orchestrator for the 5 Peec AI growth skills (peec-setup, peec-content-intel, peec-cluster, peec-outreach, peec-report). Reads project state and last learnings, detects the single highest-leverage gap, and returns exactly one next-move decision with a measurable 4-week metric — then hands off to the skill that executes it. Use when multiple priorities compete and you need one call, not a dashboard.
user-invocable: true
---

# AI Growth Agent

## Role
Pick the single next move for a Peec AI project. One decision, one skill handoff, one measurable 4-week target. Nothing else.

## Input
- `project_id` — resolve via `mcp__peec-ai__list_projects` if unknown
- optional `focus` — force a specific gap type (`taxonomy|cluster|content|citation|learning`)

## Output
One markdown document matching the schema in §5, plus one appended entry in `<project>/growth_loop/decisions_log.md`. Nothing else is produced.

## When to use
- Weekly 30-min ritual: "what is the one thing this week?"
- When multiple priorities compete and clarity is missing
- Quarterly strategy refresh

Do not use when:
- The answer is already known — call the target skill directly
- Peec project has <7 days of data — run `peec-setup` first

---

## The loop

```
     ┌─────────────────────────────────────────────────┐
     │                                                 │
     │  1. UNDERSTAND                                  │
     │     peec-setup  (prompts + taxonomy)   │
     │     peec-content-intel   (demand signals)       │
     │                  ↓                              │
     │  2. ANALYZE                                     │
     │     peec-cluster (zones)             │
     │     peec-content-intel      (source intel)      │
     │                  ↓                              │
     │  3. DECIDE                                      │
     │     → THIS SKILL: one zone + one action         │
     │                  ↓                              │
     │  4. EXECUTE                                     │
     │     content-write     (new content)             │
     │     peec-outreach (external citations)      │
     │                  ↓                              │
     │  5. LEARN                                       │
     │     peec-report                        │
     │                  ↓                              │
     └───────→ feedback into step 1 ────────────────────┘
```

One full cycle: **1 week** for active projects, **4 weeks** for maintenance.

---

## Pipeline

### 0. Pre-flight — setup state required

Per [`_shared/SETUP_STATE.md`](../_shared/SETUP_STATE.md), this skill refuses to run without a completed setup. Before anything else:

```
Read <project>/growth_loop/setup_state.json
If file missing OR completed_at missing OR phases_completed lacks
   {competitors, prompts, topics, tags}:
     STOP. Output exactly:
       "No Peec setup state found at <project>/growth_loop/setup_state.json.
        Run /peec-setup first."
     Do not bootstrap setup yourself — that is peec-setup's job.
If completed_at older than 90 days: WARN once, continue.
Use peec_project_id from state — do not call list_projects again.
```

### 1. Read state — ALWAYS run /peec-checkup first

The orchestrator does not duplicate diagnostic logic. It **always** invokes `/peec-checkup` as its first substantive step and uses the resulting report as the input for gap detection in §2. This guarantees:
- Setup health (red flags) is considered before any content/citation move is recommended
- Inventory counts (brands / prompts per stage / topics / tags / chats) are explicit, not guessed
- Brand-performance snapshot is the same one the user would see if they ran the checkup themselves — no drift between agent and dashboard

```
# Step 1a — orchestrate the read-only diagnostic
Invoke /peec-checkup
  inputs:
    project_id    = setup_state.peec_project_id
    date_range    = last 28 days (auto-shrink if project younger)
    top_n         = 8
  output: <project>/checkups/YYYY-MM-DD_checkup.md  (skill writes this)

# Step 1b — read auxiliary history that checkup doesn't cover
Read: <project>/growth_loop/*_learnings.json      (may not exist)
Read: <project>/growth_loop/decisions_log.md      (may not exist)
Read: <project>/outreach/*_outreach_log.md        (may not exist)

# Step 1c — cross-project priors (optional, if SkillMind MCP is available)
mcp__skillmind__recall(query="<likely gap type>", k=5, filter_tags=["peec"])
```

If `/peec-checkup` reports `days_with_data < 7`: STOP at Tier 1 below — do not force action.
If no history exists: say so plainly ("first run — deciding from checkup + structural data only, next cycle will be sharper") and continue. If SkillMind is not installed, skip the recall step — patterns are a bonus prior, not a requirement.

### 2. Detect gap (priority ladder — higher tier always wins)

Inputs come from the §1 checkup report — read its sections in this order:

1. **Inventory + Setup health** (checkup §0 + §1) → tiers 1 + 2
2. **Brand performance** (checkup §2) → tiers 3 + 4 + 5
3. **Top improvements ranked** (checkup §3) → confirms or overrides tier choice with concrete actions

| Tier | Gap | Signal (from checkup) | Handoff |
|---|---|---|---|
| 1 | Data | `days_with_data < 7` in checkup §0 | STOP. Wait, do not force action. |
| 2 | Setup quality | checkup §1 Setup Health < 80% OR any P0 finding | `peec-setup` (audit or partial:<phase>) |
| 3 | Taxonomy mass | <20 active prompts OR any funnel stage <2 prompts (checkup §0) | `peec-setup partial:prompts` |
| 4 | Cluster | 20+ prompts, no strategic `zone:*` tags (checkup §0 tags list) | `peec-cluster` |
| 5 | Content | Zones exist, but a losing hero prompt (checkup §2) has no own asset | `content-write` (external) or `peec-content-intel` for the brief |
| 6 | Citation | Hero content exists, source diversity < 5 (checkup §2) OR `editorial`/`ugc` actions queued | `peec-outreach` |
| 7 | Learning | Loop has been running 4+ weeks, no `growth_loop/*_report.md` files | `peec-report` |

**Rule:** Exactly one tier per cycle. If two tiers look tied, pick the lower number. Parallel work across tiers means the tiers weren't ranked properly — fix the ranking.

**Override rule:** if checkup §3 ranks a #1 improvement that maps to a higher-tier handoff than the gap detection picked, prefer the checkup's #1 — its leverage scoring (impact × actionability × strategic_fit) already accounts for the same axes. Log the override in §6.

### 3. Produce decision (see §5 schema)

The decision names **one** skill, **one** scope, **one** 4-week metric with a concrete number. No "and also", no "optionally". If the measurable change wouldn't happen in 4 weeks, the metric is wrong — rewrite it.

### 4. Hand off

Invoke the target skill with parameters pre-filled. Do not recommend — execute. The user can override at any point, but default is execution.

### 5. Log

Append to `<project>/growth_loop/decisions_log.md` using the schema in §6. Every next run reads this file first — the log IS the memory.

---

## Decision output schema

```markdown
# Growth Agent — <project name> (<YYYY-MM-DD>)

## Decision
<One sentence. One verb. One object. One deadline.>

## Why this, now
<3–5 sentences. Causal chain: signal → implication → therefore this action.>

## How
Run <skill-name> with:
  <param>: <value>
  <param>: <value>

## Measurable in 4 weeks
<Specific metric + number. "Visibility on prompt pr_xxx: 0% → ≥15%."
 If this doesn't move, the decision was wrong.>

## Not doing now (explicit skip)
- <option>: skipped because <reason>
- <option>: skipped because <reason>

## Next checkpoint
<YYYY-MM-DD> — re-run agent, measure the metric above.
```

## Decision log schema

```markdown
## <YYYY-MM-DD> — <skill-name>

Checkup ref: <path to YYYY-MM-DD_checkup.md>   # always present from this version on
Signal: <what in the checkup triggered this>
Tier picked: <1–7>  · Override of detected tier? <no | yes: detected=N, override=M>
Decision: <one sentence>
Params: <key=value, key=value>
Executed: ✓ | ✗ <reason>
Output: <one line on what came out>
Checkpoint: <YYYY-MM-DD> — metric: <name + target>
```

---

## Handoff matrix

| Intent | Skill |
|---|---|
| Setup / taxonomy / competitors | `@peec-setup` |
| Strategic zones from flat prompt set | `@peec-cluster` |
| Source / demand research for a prompt | `@peec-content-intel` |
| New article (handled outside this repo) | `@content-write` |
| External citations & outreach | `@peec-outreach` |
| Weekly / monthly loop close | `@peec-report` |

---

## Example (real output, Antonio Blago project, 2026-04-19)

```markdown
# Growth Agent — Antonio Blago (2026-04-19)

## Decision
Build the content zone "KI-SEO Retainer Decision" by 2026-04-26 with one hero article.

## Why this, now
47 Peec prompts are active, but the Decision stage is covered by only 3 weak prompts,
2 of which sit at 0% visibility. The Retainer is the main revenue product — Decision
must be the strongest zone, is currently the weakest. No other tier resolves this gap.

## How
Run content-write with:
  project_id: or_bf5b4228-7344-4f71-b231-c4396a7775f6
  focus_keyword: "KI-SEO Retainer"
  page_type: blog
  language: de            # from setup_state.prompt_language
  target_country: DE      # from setup_state.target_country

## Measurable in 4 weeks
Visibility on pr_a38381d4: 0% → ≥15%. Aggregate visibility of zone
"KI-SEO Retainer Decision": → >10%.

## Not doing now (explicit skip)
- New Awareness cluster ("Was ist GEO?") — 4 prompts already cover it, smaller gap.
- Citation outreach — no substance to pitch until hero content is live.

## Next checkpoint
2026-05-17 — measure visibility trend for pr_a38381d4 + zone tag.
```

---

## Guardrails (do not do these)

- Do not list options — pick one
- Do not say "it depends" without saying on what
- Do not delegate analysis back to the user — the analysis is the job
- Do not say "everything is fine, keep going" — a critical read is the core value
- Do not ask for more input, except at Tier 1 (genuine data gap)
- Do not work on two tiers in parallel