# Ccc Suggest

> AI-powered 'what should I do next' advisor. Always running in the background (via UserPromptSubmit hook) — observes project state, user intent, and session history,…

- Skill: `kevinzai/ccc-suggest` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kevinzai/ccc-suggest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kevinzai/ccc-suggest/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KevinZai (https://skillmd.com/u/kevinzai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kevinzai/ccc-suggest

---


# /ccc-suggest — The Intelligence Layer

This is CC Commander's headline feature. **The user never has to guess which tool to use.** An Opus-class reasoning pass runs over the current project state + user signals + recent session activity, then surfaces ONE concrete recommendation: the next `/ccc-*` workflow, CCC skill, or third-party plugin to invoke — with named reasoning.

> No more info paralysis. No more "what's the right plugin for this?" No more browsing 500+ skills. You get a ⭐ **Recommended next step** with specific tool names.

## Response shape

Exactly four sections:

### 1. Brand header + context

```
**CC Commander Suggest** · Opus-class routing · Reading your project state…
```

Then a context card showing what was detected.

### 2. Project scan (parallel reads, <2s)

Run all of these in a SINGLE `Bash` invocation (parallelized with `&` + `wait`):

- `git rev-parse --abbrev-ref HEAD` — current branch
- `git log --oneline -5` — recent activity
- `git diff --stat origin/main..HEAD 2>/dev/null | tail -1` — branch ahead?
- `ls CLAUDE.md package.json pyproject.toml Cargo.toml .env 2>/dev/null | wc -l` — project signals
- `cat package.json 2>/dev/null | jq -r '.dependencies // empty | keys[]?' 2>/dev/null | head -20` — JS stack
- `ls tasks/todo.md tasks/plan-*.md 2>/dev/null` — open tasks
- `ls -t ~/.claude/sessions/*.tmp 2>/dev/null | head -1` — last session
- `ls ~/.claude/plugins/cache/*/*/1*/.claude-plugin/plugin.json 2>/dev/null | wc -l` — installed plugins
- `claude mcp list 2>/dev/null | grep -c '^ '` — connected MCPs

### 3. The recommendation

Use **Opus-class reasoning** (this skill runs on Opus when available; Sonnet fallback). Output EXACTLY this structure:

```markdown
## ⭐ Recommended next step

**`/ccc-<workflow>`** — <one-line purpose>

**Why this, now:** <3-5 sentences of concrete reasoning. Reference specific signals from the project scan. Name the alternative options you considered and rejected.>

**Specific tools you'll use:**
- 🛠️ **<primary skill/agent>** — <why it fits>
- 🧩 **<secondary skill/agent/MCP>** — <why it complements>
- 🌐 **<optional third-party plugin>** — <when it becomes relevant>

**Estimated time:** <X minutes>
**Cost:** <rough $ estimate if multi-agent or hosted MCP>
**Confidence:** <HIGH / MEDIUM / LOW, with reasoning>
```

### 4. Runner-up picks (via AskUserQuestion)

If the user wants alternatives, offer them:

```
question: "Prefer something else?"
header: "Alternatives"
multiSelect: false
options:
  - label: "⭐ Go with recommended: /ccc-<workflow>"
    description: "<reasoning abstract>"
  - label: "Runner-up: /ccc-<alt-1>"
    description: "<when this would be better>"
  - label: "Deeper option: /ccc-<alt-2>"
    description: "<more investment, potentially more value>"
  - label: "Show all 12 /ccc-* options"
    description: "Open /ccc-browse for the full picker."
```

Default to the starred first option unless user actively picks an alternative.

## The reasoning heuristics (Opus prompt)

When running the reasoning step, the internal Opus call uses these heuristics, ranked by signal strength:

### Tier 0 — The three PM lenses (frame every pass)

Before ranking tier-1/2/3 signals, evaluate the project through all three PM lenses below. Every pass — explicit invocation AND ambient tick — runs all three and picks the strongest. **The loop is a PM, not a cheerleader:** it must be willing to say "stop building, scope this first." SCOPE outranks IMPROVE when both fire.

1. **IMPROVE** — "What skill or workflow could be implemented right now to make things better?" Missing tests → `/ccc-review` + TDD emphasis. Generic UI → `ccc-design` sub-skills. Slow feedback cycle → propose a new `/loop` recipe. Repeated manual step (same fix/check happening twice) → recommend encoding it as a skill or hook so future iterations don't repeat it — that is the PM's job, not the user's.
2. **SCOPE** — "Is the current work properly defined?" No plan file, vague acceptance criteria, or the task ballooning past its original ask → `/ccc-plan` or `spec-interviewer`. Scope creep detected in the diff vs. the stated goal → flag it explicitly, don't silently let it ride.
3. **AUDIT** — "What is currently unverified?" Branch ahead with no review → `/ccc-review`. Deps unaudited → security scan. Docs drifted from code → doc-sync. Tests green but coverage dropped → qa pass.

### Tier 1 — Strong signals (drive the recommendation)
- **Substantive task (multi-file / research / audit / migration / repo-wide)** → recommend running it workflow-first (the Workflow tool or `/ccc-fleet` / `/ccc-ultracode`); agents return conclusions, not file dumps. See `commander/cowork-plugin/rules/workflow-first.md`.
- **Isolated / parallel work described** (a background job, a separate *unrelated* task, "handle this independently", "while I'm away") → offer to spin it into its **own session** instead of derailing the current thread: a `spawn_task` chip in Cowork Desktop, or `/spawn quick <task>` in the CLI. Detected automatically every turn by the suggest ticker (`hooks/suggest-ticker.js` → `detectIsolationSignal`), deduped so it never nags. **Never spawn without the user's go-ahead.**
- **Branch is ahead of main + tests present** → `/ccc-review diff` (audit before PR)
- **Branch is ahead of main + no tests** → `/ccc-build` with TDD emphasis OR `/ccc-plan` if spec unclear
- **No CLAUDE.md + empty repo or only README** → `/ccc-start` (onboard + plan file)
- **CLAUDE.md exists + active tasks/todo.md** → continue the work; if last task is "plan", route to `/ccc-plan` resume; if "build", `/ccc-build`
- **Recent session crashed or interrupted** → resume via `/ccc-start` → "Import existing project"
- **Tests green + branch ahead + CHANGELOG staged** → `/ccc-ship preflight` (ready to release)
- **CI red / lint failing** → `/ccc-review` with perf+security focus first; fix before adding features
- **Dep audit flagged vulnerabilities** → `/ccc-review security` (critical before shipping)

### Tier 2 — Stack signals (modify the recommendation)
- **Next.js / React / Vite in package.json** → recommend `ccc-design` + Figma MCP in the tool list
- **Postgres / Supabase config** → recommend `ccc-saas` + Supabase MCP
- **GitHub Actions workflow** → recommend `ccc-devops` + GitHub MCP
- **Python ML imports** → recommend `ccc-research` + anthropic-skills via vendor
- **Multi-repo / monorepo** → recommend `ccc-fleet` (parallel agents)

### Tier 3 — User intent (overrides with explicit ask)
- User says "what's next" / "help me decide" / "which tool" → this skill activates directly
- User describes a task → pattern-match to workflow + skill, e.g. "audit security" → `/ccc-review security`
- User asks about a specific domain → route to `ccc-<domain>` domain router + name sub-skills

## Named third-party plugins for context (the "amazing OSS" callouts)

When relevant to the current task, NAME SPECIFIC 3RD-PARTY PLUGINS from the vendor ecosystem. Users should know these exist — discovery is our job, not theirs. The top-20 plugins by star count + active maintenance:

**For design:**
- `impeccable` — the design-language-hardening skill. Use when UI output feels generic.
- `frontend-design` (Anthropic) — anti-slop aesthetic engine.
- `ui-ux-pro-max-skill` — 67K star production design intelligence.

**For memory / context:**
- `claude-mem` — session memory + context injection. ✅ Already in core plugin as MCP.
- `hindsight` — agent memory that learns from past work.
- `beads` — memory upgrade for coding agents.

**For research / browsing:**
- `last30days-skill` — multi-source research (Reddit/X/YT/HN/web).
- `context7` — up-to-date library docs. ✅ Already in core.
- `dev-browser` — real browser for agents.

**For planning:**
- `planning-with-files` — Manus-style persistent markdown planning. Complements `/ccc-plan`.
- `bmad-method` — Breakthrough Method for Agile AI Development.

**For agent orchestration:**
- `wshobson/agents` — 100+ specialized subagents. Complementary to our 17 personas.
- `superpowers` — agentic skills framework.
- `caveman` — 65% token reduction mode. ✅ Already in vendor.

**For code quality:**
- `everything-claude-code` — 159K star full harness optimization.
- `claude-task-master` — task management drop-in.
- `promptfoo` — test prompts + red-teaming.

**For specialized domains:**
- `marketingskills` — CRO, copywriting, growth. ✅ Concept already in ccc-marketing.
- `pm-skills` — 100+ PM skills.
- `andrej-karpathy-skills` — Karpathy's LLM coding observations baked in.

**For live visibility:**
- `claude-hud` — status bar + tool tracking. ✅ Already in vendor.
- `visual-explainer` — rich HTML/slide diagrams. Pairs perfectly with `/ccc-cheatsheet`.

When recommending one, include: name, purpose, install path (`install via /ccc-connect OR vendor submodule OR npm`). Make it one-click from the recommendation to install.

## Always-on mode — ambient intelligence with 4 involvement levels

`/ccc-suggest` is **auto-triggered on every user turn** via the `suggest-ticker.js` UserPromptSubmit hook. It runs a lightweight reasoning pass (Sonnet, not full Opus) and surfaces recommendations based on the current **involvement level**.

The level auto-adjusts based on real-time project analysis. Users can also override via `CCC_SUGGEST_LEVEL=<1|2|3|4>` env var.

### Level 1 — **Passive** (silent analytics)
- Reasoning runs but never displays
- Logs to `~/.claude/commander/suggest-log.jsonl` for telemetry + session learning
- Default when: project is green (tests pass, branch clean, no todos, recent session completed successfully)
- Use case: power users who know what they're doing; data collection for future improvements

### Level 2 — **Gentle nudge** (default)
- Shows a one-line suggestion at the BOTTOM of the response ONLY when confidence ≥ HIGH
- Format: `💡 **Suggested next:** /ccc-ship preflight — tests green, branch ahead, CHANGELOG staged. Ready to release?`
- Dismissible by user (any response that doesn't use the suggestion is fine — no nag)
- Default when: project has signals but no blockers (e.g. branch ahead of main, recent plan file)
- Use case: most users; low intrusion, high value

### Level 3 — **Assertive** (inline recommendation)
- Shows a boxed recommendation card at the TOP of the response
- Always includes confidence + reasoning + runner-up picks
- Format:
  ```
  ┌─ 🎯 CC Commander Suggests ─────────────────────┐
  │ ⭐ /ccc-review diff (HIGH confidence)          │
  │ Why: 18 files changed, 0 test files touched,   │
  │ and you're ahead of main by 3 commits.         │
  │ Alternatives: /ccc-ship preflight · /ccc-plan  │
  └────────────────────────────────────────────────┘
  ```
- Default when: project has BLOCKERS (failed CI, security alerts, lint errors, stale CLAUDE.md drift)
- Use case: beginners or pressure situations; the AI is actively guiding

### Level 4 — **Autopilot** (execute unless objected)
- Skips AskUserQuestion for the top recommendation and just **runs it** after a 5-second countdown (user can say "stop" / "wait" / "no" to cancel)
- Level 4 only kicks in automatically when:
  1. Confidence is HIGH
  2. The recommendation is a READ-ONLY action (analysis, review, preview) — NEVER an action that writes to disk or network
  3. User has explicitly set `CCC_SUGGEST_LEVEL=4` (never auto-activates; opt-in only)
- Use case: heavy solo dev, night mode, autonomous overnight runs

### Auto-adjustment rules (the "brain" decides the level)

The ambient ticker re-evaluates the level at the start of every turn using these signals:

| Signal | Level shift |
|---|---|
| CI failing OR security alert OR open PR with red checks | → Level 3 (assertive) |
| Branch clean + tests green + no todos + recent success | → Level 1 (passive) |
| User said "what next" / "help" / "stuck" | → Level 3 one-turn override |
| User said "autopilot" / "yolo" / "go" | → Level 4 one-turn override |
| `CCC_SUGGEST_LEVEL` env var set | → hard-override to that level for whole session |
| `CCC_SUGGEST_DISABLE=1` | → disables ambient mode entirely (Level 0) |
| Night mode / overnight autonomous session detected | → Level 4 (with the read-only safety constraint) |

## PM Loop mode — the always-on thinking PM

`/ccc-suggest loop` arms a recurring loop: start `/loop /ccc-suggest` (self-paced) or `/loop 30m /ccc-suggest` if the user gives an interval. Per the `/ccc-loop` taxonomy this is a **time-based** loop locally, and graduates to `/schedule /ccc-suggest` for teams who want it to survive laptop-close. See `/ccc-loop` for the full 4-type taxonomy this borrows from.

Each tick runs the existing project scan + the three PM lenses above, then surfaces **at most ONE** recommendation through the existing involvement-level system. A tick with nothing new to say stays silent at Level 1 — logging only, no nag.

**State file — dogfoods the `/ccc-loop` convention:** `.claude/loop-state/ccc-suggest.json`:

```json
{
  "iteration": 4,
  "lastRun": "2026-07-06T14:32:00Z",
  "attempted": ["/ccc-review diff", "/ccc-plan"],
  "dismissed": ["/ccc-ship preflight"],
  "history": []
}
```

**Hard rule:** a suggestion in `dismissed` is never re-surfaced unless its underlying signal materially changed (e.g. CI went from green to red). This is the anti-nag mechanism AND what makes the loop "learn" instead of repeating itself.

**Should-you-loop gate, applied to itself:** recurs constantly (every turn) ✓ · verifier = deterministic project-state signals (git/CI/todos), not self-judged ✓ · budget = cheap Sonnet-tier pass per tick, capped ✓ · real tools = git/gh/fs already wired via the ticker ✓. Passes all 4 — this is why `/ccc-suggest` is the one skill CCC recommends running as a standing loop rather than one-shot.

`/ccc-suggest loop status` reads the state file and prints iteration count + last recommendation + dismissed list. `/ccc-suggest loop stop` stops the loop — same mechanisms as `/ccc-loop` (Cowork Desktop stop button, `Ctrl+C`, or cancel the `/schedule` routine).

### Real-time project analysis signals (refreshed at most every ~30s of turn activity)

The ticker maintains a cached project state **per project** at
`~/.claude/commander/projects/<slug>/project-state.json`, where `<slug>` is
`basename(cwd)` + `-` + the first 8 hex chars of `sha256(cwd)` (the exact
algorithm is `projectSlug()` in `hooks/suggest-ticker.js`). To locate the
current project's file: `ls -d ~/.claude/commander/projects/$(basename "$PWD")-*`.
(The old flat `~/.claude/commander/project-state.json` is pre-v7.3.0 and no
longer written — treat it as stale.) Fields (exactly what `hooks/suggest-ticker.js`
`computeState()` writes):

```json
{
  "timestamp": "2026-07-10T01:15:00Z",
  "branch": "feature/xyz",
  "defaultBranch": "origin/main",
  "aheadMain": 3,
  "behindMain": 0,
  "hasClaudeMd": true,
  "claudeMdAgeDays": 12,
  "openTodos": 1,
  "lastSession": "/Users/you/.claude/sessions/2026-07-09-abc.tmp",
  "stack": ["nextjs", "tailwind", "supabase"],
  "testsStatus": "passing",
  "ciStatus": "passing",
  "lintStatus": "unknown",
  "securityAlerts": 0,
  "lintErrors": 0,
  "recommendedLevel": 2,
  "pmLenses": { "audit": true, "scope": false, "improve": false },
  "lastRecommendation": null
}
```

Signal sources: `ciStatus` from a ≤10-min cached `gh run list --limit 1 --json conclusion` (stale cache refreshes in a detached background process — the hook never blocks); `testsStatus` / `lintStatus` / `securityAlerts` from the PostToolUse cache at `~/.claude/commander/last-test-result.json` (30-min TTL); `defaultBranch` via `git symbolic-ref refs/remotes/origin/HEAD` (fallback `origin/main`). Status values are `passing | failing | unknown`. `hasClaudeMd` + `claudeMdAgeDays` feed the CLAUDE.md drift recommendations (`/ccc-claudemd` at age > 30d, `/ccc-adopt` when missing). `lastRecommendation` is populated by explicit `/ccc-suggest` runs, not by the ticker.

### Marketing positioning (the headline feature)

> **"An Opus-class AI watches your project in real time and always tells you the next best move. You never have to know which of 502+ tools to use — the plugin knows for you."**

This is the headline differentiator. Other plugins ship tools. CC Commander ships **the decision** about which tool to use.

### User overrides

- `CCC_SUGGEST_LEVEL=1..4` — hard-lock the level
- `CCC_SUGGEST_DISABLE=1` — disable ambient mode entirely
- `/ccc-suggest --level=3 --force` — one-turn override
- `/ccc-suggest --history` — show last 10 recommendations + what user actually picked
- `/ccc-suggest --tune` — enter a quick AUQ flow to calibrate what level of involvement the user wants

## Fable escalation rule

When session intent is strongly deep-reasoning (≥2 of: architecture / redesign / migration / threat model / system design / refactor entire / plan the / roadmap; OR prompt >800 chars with planning verbs), surface **once per session** (never nag):

> 🧠 **Deep-reasoning session detected** — consider `/model claude-fable-5[1m]` (Fable deep mode, 1M ctx, adaptive thinking always-on). CCC routes subagents cost-efficiently either way.

- Fire at most ONCE per day (marker file `~/.claude/commander/fable-nudge-<date>`).
- Never trigger on casual or short prompts.
- Never block or delay the response — append as a lightweight suggestion only.
- The `intent-classifier.js` UserPromptSubmit hook handles automatic detection; this skill surfaces it in explicit `/ccc-suggest` runs.

## Anti-patterns

- ❌ Generic "you could try X" recommendations — always cite specific signals
- ❌ More than ONE starred recommendation — we eliminate decision fatigue, so one ⭐ only
- ❌ Recommending without reading project state — the scan is non-negotiable
- ❌ Vague time estimates — say "~15 min" or "~1 hour", not "a while"
- ❌ Recommending third-party plugins without install path — always name the install step
- ❌ Running the full Opus pass on every single message — the background ticker uses Sonnet; Opus only when user explicitly invokes `/ccc-suggest`

## Confidence calibration

- **HIGH** — multiple tier-1 signals agree + stack signals confirm (e.g. "branch ahead + tests green + CHANGELOG staged" → `/ccc-ship` with HIGH confidence)
- **MEDIUM** — one tier-1 signal + user intent compatible (e.g. "empty repo + user said 'build a SaaS'" → `/ccc-build` with MEDIUM)
- **LOW** — no tier-1 signals + user intent ambiguous → show 3 alternatives via AUQ

## Voice

Speak in the PM Consultant voice with the semantic emoji palette from `rules/common/response-style.md` (🎯 focus · 💡 idea · 🟢 approve · 🟡 caution · 🔴 block · ⏭️ next) — every recommendation ends with a decisive **🟢 my call** + one-line rationale, never a hedge.

## Brand positioning (the value prop)

This skill IS the value prop of CC Commander for beginners:
- **No info paralysis** — one recommended next step, always
- **Opus-class reasoning** — not a dumb routing table; full project context
- **Named tools + plugins** — "use `claude-mem` for this" not "use a memory tool"
- **Reasoning shown** — never a black box, always "because X / Y / Z"

The CLI version of the same capability: `ccc --suggest` (headless, JSON output for CI).

## Tips for execution

1. Run the project scan FIRST, in parallel, in ONE Bash call. Don't sequential-read files.
2. The Opus pass is expensive — only on explicit `/ccc-suggest` invocation. The background hook uses Sonnet.
3. If scan reveals no actionable signals: say so, recommend `/ccc-start` for onboarding.
4. Every recommendation has a "what not to do" implicit — by picking ONE, you're hiding 11 others. That's intentional. Commit to the call.

---

> ⚙️ **Fable contract:** plan before build · verifier ≠ worker · prove before alarm · loops need gates · leave durable state — `rules/fable-method.md`