agentleFS
DonaldMurilloDonaldMurillo/gofastr/.claude/skills/app-introspect/SKILL.md

app-introspect

Skill24 starsChanged 2 days agoMITView on GitHub

Inspect a running GoFastr app's shape via MCP introspection tools. Use when the user asks "what routes exist", "is the app ready", "what plugins are loaded", "what's the current config", "what batteries depend on what", "what does this framework doc say", or any "describe the running server" question where the app was built with framework.WithMCPIntrospection() (and framework.WithMCPTools(mcptools.Register) for the docs tools).

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use these to orient before reading code or before issuing requests.

    line 13
  2. Very specific:

    Call app_modules first to see names + current state.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

Inspect a live GoFastr app via the framework's MCP introspection

framework.WithMCPIntrospection() opts the App into a set of read-only tools that describe the running server: routes, plugins, batteries, modules, config, readiness. framework.WithMCPTools(mcptools.Register) (from framework/docs/mcptools) adds the framework's own embedded docs as the framework_docs_* tools; package framework does not import the corpus. Use these to orient before reading code or before issuing requests.

Prerequisites

Any GoFastr app running under gofastr dev has the full surface automatically (mount + introspection + control automatically, plus log_* tools when battery/log is registered; opt-out GOFASTR_DEV_MCP=0). The framework_docs_* tools are never implied: the app adds framework.WithMCPTools(mcptools.Register). Outside the dev loop the app must be built with framework.WithMCPIntrospection() and expose /mcp (via framework.WithMCP()); examples/site, examples/ecommerce and generated apps wire all three. Launch the site with ./scripts/dev-watch.sh (port 8082) or go run ./examples/site (port 8083; plain go-run has no PORT set). The curl examples below use 8082; adjust to how the app was launched.

The tools

ToolUse
app_routesEvery (method, pattern) registered via the router, including from Groups + plugin Init.
app_pluginsList plugin names in registration order.
app_batteriesList batteries with deps and initialized state, in dependency-resolved order.
app_modulesList modules with manifest metadata (version, deps, migration group), enabled state, and owned surface counts.
app_configAppConfig snapshot: name, json_case, debug_endpoints, no_llmmd, request_timeout_ms, disable_request_timeout.
app_readinessRun all registered readiness checks; same set /readyz consults, invokable programmatically.
app_goroutine_leaksCount + stacks of goroutines the runtime has PROVEN leaked (Go's goroutineleak profile, GC-fresh). Zero is healthy; a growing count means a worker/stream is being abandoned.
app_routinesEvery registered stored routine: name, declared dialect, sha256 checksum of the Up body, ledger state (present/drifted/missing/skipped_for_dialect/unknown; skipped_for_dialect means the routine's declared dialect doesn't match the active DB engine), and best-effort liveness in pg_proc/pg_views (Postgres; unknown on SQLite). Use to confirm a routine body change propagated, or spot one the boot skipped.
app_unmountedThe unmounted package copies compiled into the binary ({"unmounted": [...], "count": n}): each copy's source (upstream import path), version (release tag, or dev for a checkout copy) and path (the copy's import path in the app). A copy no longer gets framework fixes on upgrade. Use to confirm which framework packages this build carries its own copy of.
framework_docs_listEvery framework doc topic embedded in the binary (name, title, summary). Needs WithMCPTools(mcptools.Register).
framework_docs_getFull markdown of one topic by name (e.g. entity-declarations). Needs WithMCPTools(mcptools.Register).
framework_docs_searchSubstring search across all topics (min 3 chars, limit caps hits). Needs WithMCPTools(mcptools.Register).
contracts_listEvery rule gofastr verify enforces: ID, slug, capability, default severity, one-line summary. Optional capability filter.
contracts_explainOne rule in full: what it detects, why it matters, how to fix it, a bad/good example pair, and the exact suppression syntax. Takes an ID (GOFASTR1002) or a slug (routing/colon-path-parameter).
contracts_capabilitiesThe rule capabilities with counts and severity breakdown; use to pick the argument for gofastr verify <capability>.
contracts_verifyDev loop only. Runs the analyzers over the app's source tree and returns the findings: rule, file, line, severity, message, whether it is autofixable. Same analysis as gofastr verify. Optional capability filter.
contracts_fixDev loop only. Writes to disk. Applies one rule's autofixes and reports the files changed. Takes an ID or slug; scoped to a single rule so the edits stay reviewable. Rules without an autofix are refused.

contracts_verify and contracts_fix are absent, not merely refused, outside gofastr dev: they read and write local source, so a deployed app never registers them.

The framework_docs_* tools answer "how does the framework work?" questions against the exact framework version the binary was built with. Prefer them over fetching docs from the repo when a live app is available.

The control tools (mutating)

framework.WithMCPControl() adds runtime state control; any app running under gofastr dev has it too, since the whole MCP surface auto-enables there:

ToolUse
app_module_enableEnable a registered module at runtime (persisted; dependency-checked).
app_module_disableDisable a module (fails closed while enabled modules depend on it).

Call app_modules first to see names + current state. These mutate the running app, so confirm with the user before toggling anything they didn't ask about.

How to invoke

Curl the MCP endpoint with a JSON-RPC tools/call payload. Result is wrapped in MCP content format: result.content[0].text is a JSON-encoded string of the actual return value.

What endpoints does this app have?

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"app_routes","arguments":{}}}' \
  | jq -r '.result.content[0].text' | jq '.routes'

What's loaded?

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"app_plugins","arguments":{}}}' \
  | jq -r '.result.content[0].text' | jq .

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"app_batteries","arguments":{}}}' \
  | jq -r '.result.content[0].text' | jq .

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"app_modules","arguments":{}}}' \
  | jq -r '.result.content[0].text' | jq .

Is the app ready?

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"app_readiness","arguments":{}}}' \
  | jq -r '.result.content[0].text' | jq .

ready: false means at least one check failed, with per-check status (ok/error/timeout) and duration_ms in the checks array, OR that zero checks are registered (then reason says "no readiness checks registered" and checks is empty: unconfirmed is not ready). The tool never includes raw error text, even when the App was configured with WithVerboseReadiness(): /readyz and /mcp can sit on different trust boundaries, so verbose applies only to /readyz.

What's the config?

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"app_config","arguments":{}}}' \
  | jq -r '.result.content[0].text' | jq .

request_timeout_ms == 0 with disable_request_timeout: false means the framework default (30s) is in effect. A non-zero value is the explicit override.

What does the framework doc say?

curl -s http://localhost:8082/mcp \
  -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"framework_docs_search","arguments":{"term":"owner_field","limit":10}}}' \
  | jq -r '.result.content[0].text' | jq '.hits'

Then framework_docs_get with the winning topic name for the full markdown.

Anti-patterns

  • Don't curl every tool when only one is needed. Each call is a JSON-RPC round-trip; pick the one that answers the question.
  • Don't trust app_readiness: ready=true as a SLO signal. Readiness checks only cover what someone registered; "ready" can still mean "no real dependencies are wired".
  • Don't read app_config for runtime stats. It's the config the App was constructed with, not live behavior. For counters, pair with log_metrics from the log-debug skill.

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.