agentleFS
lalulalilalulali/vespyr/.agents/skills/help-me/SKILL.md

help-me

Skill11 starsChanged 11 days agoMITView on GitHub

Dynamic next-step navigator — evaluates project state, checks skill catalog, codebase/doc graphs, and provides a tailored navigation report with recommended slash commands.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 6 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After a long pause between sessions — fast re-orientation

    line 21
  2. Distinctive:

    Before running any skill — check if prerequisites are met

    line 22
  3. Distinctive:

    Check whether BOTH files exist:

    line 30
  4. Very specific:

    If either is missing, the project is uninitialized.

    line 34
  5. Very specific:

    Read .agents/skills/help-me/skills-catalog.json for the skill index

    line 38
  6. Very specific:

    Read .agents/AGENTS.md if you need framework context (phases, agents, guardrails)

    line 39
  7. Very specific:

    If Vespyr generated the prototype earlier in this project → run /design.

    line 43
  8. Very specific:

    If the question implies starting a project, close with /unpack-problem (for pain points), /validate-idea (for concepts), /shape-up (for …

    line 45
  9. Distinctive:

    Keep the response tight — they asked one thing, not a tour

    line 46
  10. Distinctive:

    Stop here. Do not enumerate skills, do not call any other agent.

    line 62
  11. Very specific:

    Read artifacts/memory/project-context.md, artifacts/output/pipeline-state.json, and artifacts/output/sprint-status.yaml (its human-readable …

    line 71
  12. Very specific:

    Read .agents/skills/help-me/skills-catalog.json — the compiled index of all available skills with their names, descriptions, prerequisites, …

    line 84
  13. Very specific:

    Answer the question asked first: If the user typed a specific query, address it before anything else.

    line 113
  14. Distinctive:

    Reach for structure only when it earns its keep: Prefer prose. Use a list or table when there are 3+ parallel things that genuinely need …

    line 119

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Help Me — Next-Step Navigator

What this skill does

Acts as your intelligent co-pilot. When you feel stuck, uncertain about the next step, or need to check project health, help-me performs a full diagnostic and tells you exactly what to do next.

It answers: "What should I do right now?"

When to use

  • "help me" or /help-me — when unsure of the next step
  • "/help-me [query]" — targeted question about a specific phase or skill
  • After a long pause between sessions — fast re-orientation
  • Before running any skill — check if prerequisites are met

Workflow

Step 0: Empty-Project Fast Path

Run this check first — before any agent or script call.

Check whether BOTH files exist:

  • artifacts/output/pipeline-state.json
  • artifacts/memory/project-context.md

If either is missing, the project is uninitialized. Do not call @memory-controller, do not run orchestrator_state.js, do not run any graph generator. Two paths from here:

Path A — User asked a specific question (e.g., "what skills are available?", "how does vespyr work?", "what's the difference between /design and /develop?"):

  • Read .agents/skills/help-me/skills-catalog.json for the skill index
  • Read .agents/AGENTS.md if you need framework context (phases, agents, guardrails)
  • Answer their question directly, citing the relevant skills/agents by name
  • Prototype-first intent (e.g., "I have a prototype, help me create the document", "I built this in Figma/Stitch — turn it into a PRD", "I have an HTML mock, generate requirements"): this is /design reverse mode, not a from-scratch start. Route it:
    • If they built the prototype outside Vespyr (Figma export, Google Stitch, hand-coded HTML) → tell them to place it in artifacts/input/prototype/ and run /design. This is the imported sub-track: it reverse-derives the SPEC.md kernel from the prototype (no prior PRD or product-manager flow needed), then synthesizes requirements.md + user-stories.md through the Evidence Ledger and parity gate. Every requirement traces back to something observable in their prototype.
    • If Vespyr generated the prototype earlier in this project → run /design; it takes the generated sub-track (uses the existing SPEC.md kernel).
    • Say the literal command: "Drop your prototype in artifacts/input/prototype/, then run /design — it'll reverse-engineer the PRD from it."
  • If the question implies starting a project, close with /unpack-problem (for pain points), /validate-idea (for concepts), /shape-up (for shaping pitches/notes) as the natural next step
  • Keep the response tight — they asked one thing, not a tour

Path B — User typed bare /help-me with no question (or a generic "what should I do?"):

Respond with this exact short message:

This looks like a fresh project — no pipeline state yet.

  • To start a project:
    • Run /unpack-problem if you have a pain point or symptom (problem-first)
    • Run /validate-idea if you have an unvalidated concept (pressure-test with @founder)
    • Run /shape-up if you have a raw pitch, doc, or notes (shaping engine with zero prerequisites)
    • Have a prototype already? Drop it in artifacts/input/prototype/ and run /design — reverse mode turns your own Figma/Stitch/hand-coded prototype into a PRD (no prior PRD needed)
  • To learn the framework: ask "what skills are available", "how does vespyr work", or "what's the difference between /design and /develop" — I'll walk you through it
  • To load existing state: run /status if you have specs or a codebase already

Stop here. Do not enumerate skills, do not call any other agent.

Step 1: Load Project State

Load memory context:

@memory-controller load help-me [next step navigation]

Read artifacts/memory/project-context.md, artifacts/output/pipeline-state.json, and artifacts/output/sprint-status.yaml (its human-readable mirror) to determine:

  • Project Name, Type, and Active Phase
  • Current Phase (Validation / Discovery / Research / Strategy / Architecture / Planning / Execution / Launch / Iteration / Documentation / Retro)
  • Operation Mode (autonomous or semi-autonomous)
  • Active Blockers & Open Change Requests (CRs)

Also read these freshness signals in project-context.md:

  • ## Session Activity — the last 5 agent sessions with timestamps (- {YYYY-MM-DD HH:MM} @{agent} — {domain}: {goal}). Use this to re-orient the user after a pause: who worked last, on what, and when. It is auto-populated by session-start / session-write / complete and by the git post-push hook (sync-context).
  • ## [CORE] header — the machine-readable fields (Stack, Phase, Sprint, Blockers). Stack and Repository are auto-detected on every session.
  • artifacts/memory/session-summaries/latest.md — the most recent session's worked-on/decisions/next-step. Read it if you need to resume where the last agent left off.

Step 2: Load Skill Catalog

Read .agents/skills/help-me/skills-catalog.json — the compiled index of all available skills with their names, descriptions, prerequisites, outputs, and key agents.

This file is auto-generated by node .agents/scripts/compile_skills.js. Re-run if you suspect it is stale (e.g., after a skill's SKILL.md is edited or a new skill is added).

Step 3: Check Artifact Readiness & Determine Next Action

Query the pipeline state engine via the CLI to find the exact next task and status:

  1. Run:
    node .agents/scripts/orchestrator_state.js status
    node .agents/scripts/orchestrator_state.js next
    status gives the full pipeline snapshot (phases, blockers, CRs); next tells you the single most logical next action. Run both — they are cheap.
  2. Parse the state engine's returning JSON next action to direct the user:
    • resolve-cr: Point out the specific open Change Request (CR) ID, sender, receiver, and target file. Suggest resolving this CR before moving forward.
    • resolve-blocker: List the active blockers and the assigned owners.
    • generate-artifacts: Identify precisely which required artifacts are missing for the current phase, cross-referencing against the skill catalog's prerequisites, and recommend the exact skill to run.
    • advance-phase: Suggest the exact command to transition the pipeline to the next phase.
    • continue-phase: The current phase is in progress but not complete — identify what remains (missing artifacts, open CRs, blockers) and recommend the next action within the current phase.

Other pipeline commands you may surface, depending on the situation:

  • session-start — node .agents/scripts/orchestrator_state.js session-start --agent {agent} --domain {domain} --goal "..." refreshes project-context.md (Phase/Blockers/Repository/Stack + Session Activity). Suggest it when the user is starting fresh work or invoking an agent directly.
  • sync-context — node .agents/scripts/orchestrator_state.js sync-context refreshes project-context.md without an agent (used by the git post-push hook). Mention it if the user just pushed to git and the Repository line looks stale.

Step 4: Respond

Answer based on what you actually found — not a branching script. A few rules to follow:

  • Answer the question asked first. If the user typed a specific query, address it before anything else. Source from the skill catalog, skills.md, or workflow.md as needed.
  • Be the person who checked, not the person who asks. You just read the state. Reflect it back — don't interrogate the user about what you could have looked up yourself.
  • Point to one next step, not a menu. Recommend the single most logical next action/command returned by orchestrator_state.js next. Only surface alternatives when the choice genuinely depends on the user's intent.
  • Resume context when re-orienting. If the user is returning after a pause, lead with what the ## Session Activity and session-summaries/latest.md show (last agent, what it did, its stated next step), then bridge to the recommended next action. If a new session is starting, suggest session-start first so project-context.md stays fresh.
  • Always surface the exact command. When recommending a next step, end with the literal command to run it — e.g. "Run /explore-idea to start research", "Say @architect to begin architecture design", or "Run /phase to switch to design". Don't leave the user to guess how to invoke it.
  • Match the length to the situation. A blank-slate response is short — there's little to say. A mid-project response may need more context. A targeted question gets a direct answer.
  • Reach for structure only when it earns its keep. Prefer prose. Use a list or table when there are 3+ parallel things that genuinely need comparison — not as a default.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.