mk-help
Workflow navigator: scans project state (plans, reviews, tests, git) and recommends the next pipeline step. Use for 'what next?' or 'where am I?'. NOT for complexity routing (mk:scale-routing).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 16
- Forks
- 3
01 前言 Front Matter
- name
- mk-help
- description
- Workflow navigator: scans project state (plans, reviews, tests, git) and recommends the next pipeline step. Use for 'what next?' or 'where am I?'. NOT for complexity routing (mk:scale-routing).
03 SKILL.md 正文
Navigation Help
Answers "What should I do next?" by scanning project state and mapping to the 7-phase pipeline.
How It Works
mk:help is the FORWARD-looking navigator (what to do next). Backward-looking delivery
analysis stays with the status skill (project-manager) — this skill never reproduces it.
Collect candidates from ALL scan sources below, then RANK them and emit the top 3 — do NOT stop at the first hit. The rank-1 candidate equals what the old "stop at first actionable hit" behavior would have returned (back-compat); ranks 2–3 are alternates with one-line rationale. This skill is read-only: it reads state, never writes it.
1. Paused Step-File Workflows
Check .meowkit/state/*-progress.json for any in-progress step-file workflow.
- Found → "Resume [skill] at step [N]. Run
/mk:[skill]to continue."
2. In-Progress Plans
Check tasks/plans/ for plan files without matching review verdicts.
- Plan exists, no tests → "Plan approved. Next: run tester agent (Phase 2 — RED)"
- Plan exists, tests failing → "Tests failing. Next: run developer agent (Phase 3 — GREEN)"
- Plan exists, tests passing, no review → "Tests green. Next: run reviewer agent (Phase 4 — Review)"
3. Pending Reviews
Check tasks/reviews/ for verdict files with WARN or action items.
- WARN verdict → "Review has warnings. Acknowledge and approve for Gate 2, or fix findings."
- FAIL verdict → "Review failed. Fix required changes, then re-run reviewer."
4. Uncommitted Changes
Check git status for staged/unstaged changes.
- Changes exist + review approved → "Ready to ship. Run
the ship skill(Phase 5)" - Changes exist, no review → "Changes detected but no review. Run reviewer first."
5. Clean State
No plans, no reviews, no changes.
- "Everything clean. Options: start a new task with planner, run
the retro skill, or ask me anything."
Additional Scan Sources (read after sources 1–5)
ALL four may be absent at rest (e.g. .meowkit/state/checkpoints/ does not exist until
runtime). Absent file → skip silently; note the skip only under --verbose. Never error
on a missing source.
| # | Source | Fields to read | Absent-case |
|---|---|---|---|
| 6 | .meowkit/state/checkpoints/checkpoint-latest.json |
state.model_tier, progress.plan_path, environment.{git_branch,working_dir_clean,uncommitted_changes}, budget.{estimated_spent_usd,turn_count}, created_at |
skip; no checkpoint context |
| 7 | .meowkit/state/budget-state.json |
estimated_cost_usd, turn_count, warnings_emitted (advisory only) |
skip; no budget caution |
| 8 | .meowkit/state/detected-model.json |
tier (authoritative current-session tier) |
skip; tier unknown |
| 9 | tasks/reviews/<slug>-verdict.json |
decision, dimensions[].verdict, created_at; .md is prose fallback |
use git/plan scan only |
| 10 | docs/development-roadmap.md (when present; Type-1 allowlisted) |
current phase / milestone progress | skip; tag (CF-C5) if relied on |
Model tier: source the current tier from .meowkit/state/detected-model.json (written
fresh at SessionStart). Do NOT source model_tier from budget-state.json — it has no
created_at/session marker and may carry a prior session's tier. Treat budget figures as
advisory unless a current-session signal corroborates them.
Staleness: if checkpoint-latest.json created_at is older than 24h, demote its
evidence and note the staleness in the rationale.
Ranking Heuristic (deterministic, evidence-cited — no vibes ranking)
Collect candidates from all sources, then rank:
- Blocked phase or BLOCKED verdict → rank-1 unblock/fix action. A review verdict is
blocked when
decision === "BLOCKED"— the verdict enum isPASS | PASS_WITH_RISK | BLOCKED; there is NO top-level"FAIL"value.FAILexists only per-dimension indimensions[].verdict. Cite the failing dimension(s) in the rationale. - In-progress phase (plan phase
status: in-progress, or GFM- [ ]checkboxes remaining) → continue action, rationale cites checkbox % (count- [x]vs- [ ]). - Approved plan, nothing built → cook action.
- Budget caution: if
warnings_emitted > 0OR spent ≥ $30, fold a budget caution into the rank-1 rationale (does not by itself create a rank). - Clean state → the existing fallback table (start a task / retro / ask).
Each candidate's rationale MUST cite the source file(s) it came from.
For skill suggestions based on task type, see mk:agent-detector (its ../agent-detector/references/lifecycle-routing.md maps task patterns to skills).
State-to-Recommendation Map
mk:plan-creatoris the planning entrypoint, and itsred-team,validateandarchivesubcommands are handled by that same skill — there is no separate dispatcher to route through.
| State | Pipeline Phase | Recommendation |
|---|---|---|
| No plan | Phase 0 → 1 | "Start with the plan skill or describe your task" |
| Existing plan — stress-test | Standalone subcommand | "the plan skill red-team {path} — adversarial review of existing plan" |
| Existing plan — interview | Standalone subcommand | "the plan skill validate {path} — critical question interview on existing plan" |
| Completed/cancelled plans | Housekeeping | "the plan skill archive — archive completed or cancelled plans" |
| Plan approved, no tests | Phase 2 (TDD mode only) | "In TDD mode (--tdd / MEOWKIT_TDD=1): run tester agent — write failing tests (RED phase). In default mode: skip Phase 2; run developer directly" |
| Tests written, failing | Phase 3 | "Run developer agent — implement to pass tests (GREEN)" |
| Tests passing, no review | Phase 4 | "Run the review skill — adversarial code review" |
| Review PASS/WARN | Phase 5 | "Run the ship skill — commit, PR, deploy" |
| Shipped | Phase 6 | "Run documenter — update docs, then the retro skill" |
| Paused workflow | Resume | "Resume [skill] at step [N]" |
| Mixed state | Clarify | "Multiple items in progress. Which to focus on?" |
Specialist Skills (surface when domain matches)
| Situation | Skill | When to suggest |
|---|---|---|
| Operations, triage, case management, escalation protocols, billing workflows | the decision-framework skill |
User asks "how should we handle X cases" or is designing any case-routing system |
| "Is everything green?", pre-review check, post-implementation validation | the verify skill |
After implementation completes, before review, or when user wants a quick health check |
| API contract design or review — interface shape, error semantics, compatibility, pagination | the api-design-principles skill |
User is authoring or reviewing what an API promises, not how it runs |
| Backend change end to end — handler, service, integration, webhook, job | the backend-development skill |
User is changing backend behavior and needs contract, data, and auth owners coordinated |
| Schema, migration, query, index, or ORM data-access boundary | the database skill |
User is modelling, evolving, or querying data |
| Infrastructure, containers, CI/CD, deployment safety, rollback | the devops skill |
User is changing how the system is built, configured, or delivered |
Fast Paths (surface these prominently)
Not every task needs the full 7-phase pipeline. Mention these when relevant:
| Situation | Fast Path | What it bypasses |
|---|---|---|
| Simple bug fix, typo, rename, config tweak | the fix skill |
Gate 1 (plan approval) — scope is the plan |
Task flagged as one-shot by scale-routing |
Auto Gate 1 bypass | Gate 1 — zero blast radius confirmed |
| Rapid iteration / spike work | MEOWKIT_HOOK_PROFILE=fast |
post-write scan, pre-ship, pre-task-check, TDD check |
Quick fix? Use the fix skill — bypasses Gate 1 for simple changes.
Small config change? Scale-routing may auto-bypass Gate 1 when blast radius is zero.
Hook profiles: Set MEOWKIT_HOOK_PROFILE=fast for rapid iteration (skips non-critical hooks).
Set MEOWKIT_HOOK_PROFILE=strict to enable ALL hooks including post-session capture.
Gotchas
- Multiple in-progress plans create ambiguity — ask user which to focus on, don't guess
.meowkit/state/files from previous sessions may be stale — check timestamps, warn if >24h old- Git status can be noisy (untracked IDE files) — focus on files in
src/,lib/,app/,tests/ - Don't recommend skipping phases — even if the user seems impatient, show the full path
- Fast paths are not loopholes — Gate 2 (review) is NEVER bypassed; security hooks are NEVER skipped
.meowkit/state/checkpoints/does not exist until runtime — its absence is normal, not an error; skip silentlybudget-state.jsonis missing at session start — treat budget figures as advisory; never source model tier from it (usedetected-model.json)- Prefer the machine-readable
*-verdict.jsonover the.mdprose verdict; a verdict is blocked whendecision === "BLOCKED"(never a top-level"FAIL") - This is the forward-looking navigator — backward-looking delivery status stays with
the status skill; do not duplicate it here
Output Format
The ranked next-steps are a JSON-compatible shape (documented here for downstream tooling), rendered as a concise human summary. This skill does NOT emit machine JSON itself — there is no scanner script; the shape documents what the ranking reasons about.
{
"next_steps": [
{
"rank": 1,
"action": "the cook skill tasks/plans/260610-x/plan.md",
"priority": "high",
"rationale": "Plan approved (Gate 1), phase-02 in-progress at 3/7 checkboxes; budget $4.20 of $30",
"source": ["tasks/plans/260610-x/phase-02-*.md", ".meowkit/state/budget-state.json"]
}
],
"progress": { "plan": "260610-x", "phases_done": 1, "phases_total": 6, "checkbox_pct": 43 }
}
Human rendering (same headings as before — rank-1 is "Recommended Next Step"):
## Status
**Current phase:** [Phase N — Name]
**State:** [brief description]
### Recommended Next Step
[rank-1 action] — [rationale]
### Other Options
- [rank-2 action] — [one-line rationale]
- [rank-3 action] — [one-line rationale]
If --verbose flag: also show full state scan results (plan files, review files, test
status, git status) AND which additional sources (6–10) were present vs skipped.
04 同仓库更多 Skills
mk-worktree
Manages git worktrees for parallel agent isolation: creates parallel/{name}-{timestamp} branches, merges with conflict detection. NOT for user feature branches (use git worktree directly).
mk-workflow-orchestrator
Auto-invoked 7-phase workflow for complex-feature intent; fasttrack mode for pre-approved specs. NOT for explicit single tasks (mk:cook), green-field builds (mk:autobuild), or simple fixes (mk:fix).
mk-web-to-markdown
Fetch a URL and return clean markdown, for arbitrary external pages (blog, RFC, GitHub issue, vendor doc) not covered by mk:docs-finder. Static-only by default; opt-in JS rendering available.
mk-vulnerability-scanner
Vulnerability analysis: OWASP Top 10, current threat landscape, supply chain security, attack surface mapping, risk prioritization. Use for security audits. NOT for STRIDE/CSO infra audits (mk:cso).
mk-vue
Vue 3 authoring/review: components, composables, reactivity, Pinia, Pinia Colada, file routing, forms. Composition API + script setup. Auto-activates on .vue files. Deep review: mk:vue-best-practices.
mk-vue-testing-best-practices
Vue 3 testing best-practices review: Vitest + Vue Test Utils for components, composables, Pinia, Router, async/Suspense, forms, a11y, plus Playwright E2E strategy. Advisory only.