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, 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:)
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

# 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

## <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)

# 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