ffc-dev-command
Skill16 starsChanged 37 days agoMITView on GitHub
Add or change a CLI command, subcommand or flag in the ffc Go codebase (internal/cmd) the way the repo expects - cobra file layout and flag-variable prefixes, callSite for site access, render/printResult for --output and --jq, JSON flags with @FILE, lists with --all, writes with --dry-run and --yes, prompts through runForm, exit-code errors, shell completion, doctor checks, help text and the docs to update. Use it whenever you create a new file in internal/cmd, add a flag, change command output, or wire a new Frappe call into a command. Load ffc-dev first for build and test commands.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- desktop/CLAUDE.mdCLAUDE.md
- ffc-bulk-lifecycleSkill
- ffc-coreSkill
- ffc-dev-clientSkill
- ffc-dev-desktopSkill
- ffc-dev-mcp-toolSkill
- ffc-devSkill
- ffc-dev-testingSkill
- ffc-files-collabSkill
- ffc-mcpSkill
- ffc-reports-apiSkill
- ffc-setupSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
New Frappe call: add a method on client.FrappeClient that goes through c.do(...) with a hints map (see ffc-dev-client).
- Very specific: line 29
No prompt without a terminal: forms go through runForm(groups...) (auth_wizard.go), which returns errNoInput (usage error) under --no-input …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Add or change an ffc command
Ground truth is the code next to yours: copy the closest existing command (get_doc.go for a read, create_doc.go for a write, delete_doc.go for a confirmed write, list_docs.go for a list). CLAUDE.md "Conventions" has the full rules.
Checklist
- File:
internal/cmd/<snake_name>.go, packagecmd;Useis kebab-case. Flag variables are package-level with a unique two-letter prefix (gdget-doc,ldlist-docs,cdcreate-doc...); grep before picking one. - Command:
Args: cobra.NoArgsfor flag-only data commands (positional args only where the UX needs them, e.g.search TEXT...,upload FILE).RunE, neverRun.Longends with anExamples:block; that text is the user documentation agents read. - Validate first: parse and check every flag before any network call. Bad values return
usageErrorf(...)(exit 2); cobra's own flag errors are already usage errors. - Site access:
callSite(cmd, "Doing X…", func(ctx, c) (T, error) {...}), orcallSiteCfgwhen you need the site config, ornewClient/newClientCfgfor several calls (thendefer c.CloseQuietly(), which logs a password session out). Neverclient.Newin a command. - New Frappe call: add a method on
client.FrappeClientthat goes throughc.do(...)with a hints map (see ffc-dev-client). - Output:
if machineOutput() { return printResult(v, fields...) }, then the table (output.PrintTable,output.PrintDocTable,output.PrintSuccess), orrender(v, fields, tableFn). Never calloutput.PrintJSONdirectly, or--output/--jqbreak. Lists uselistDocs(cmd, pages, title, doctype, opts, fields, tableFn)with apageFlagsregistered viapages.register(cmd, "limit", "start"), which adds--all/--page-size. - JSON flags:
parseObject("--data", raw)for objects,filtersFlag(raw)for filters,jsonFlagfor anything else, so@FILEand@-work and an empty file is an error. Field lists:parseFields. Limits:listLimit(0 = no limit, negatives refused). - Writes:
addDryRun(cmd, false)ininit()(trueonly when every request must be held back, as in call-method and api). A confirmed write:--yesflag, thenif !yes && !dryRunOn(cmd) { if err := confirm("…"); err != nil { return err } }. Under a dry run, still do the reads that prove the write would work. - Single DocTypes: a command taking
-d/-nfor one document defaults the name withdocNameOrSingle(name, doctype)(not for delete). - Register:
rootCmd.AddCommand(cmd)(orparentCmd.AddCommand) ininit();_ = cmd.MarkFlagRequired(...). - Tests against the fake site through
runFFC(ffc-dev-testing): success, machine output, a usage error, the server error classes that matter, and--dry-runsending no write. - Docs: the matching page under docs/cli/ (README.md only for essentials), CLAUDE.md (architecture line, new pitfall) and the matching user skill under
skills/.
Template and the read/list variants: references/templates.md.
Prompts and confirmation
- No prompt without a terminal: forms go through
runForm(groups...)(auth_wizard.go), which returnserrNoInput(usage error) under--no-inputor a non-TTY stdin and maps Esc/Ctrl+C toerrAborted. Simple yes/no:confirm(prompt)(helpers.go), which turnserrNoInputinto "pass --yes". - huh v1.0.0 binds only Ctrl+C to quit. A hand-built form must use
.WithKeyMap(escQuitKeyMap())(config_cmd.go) so Esc aborts. - A declined prompt is
errAborted(non-zero exit). Only the config TUI's explicit "Cancel" exits 0.
Errors and exit codes
Wrap with fmt.Errorf("context: %w", err); never log and return. classify (exit.go) maps: usageError 2, client.AuthError / 401 3, 404 or missing DocType 4, 403 or deniedError 5, client.StateError / 400/409/417/422/413 / TimestampMismatchError 6, client.TransportError / 5xx / 429 7, partialError 8 (bulk: bulkReport.err()), codeError{code} for a fixed code (doctor uses 1). Exit codes are a documented contract: never repurpose one.
Things that come for free, or must not be broken
- Completion: registered by flag name in
registerCompletions(completion.go): anydoctypeflag and afieldsflag next to it complete automatically. A new enum flag adds onereg(cmd, "flag", fixedValues(...))line. Completion reads only config and cache: never a request. - Env vars
FFC_SITE,FFC_CONFIG,FFC_TIMEOUT,FFC_OUTPUT,FFC_DEBUGare applied inapplyEnv; do not read them yourself. - Pre-run:
rootCmd.PersistentPreRunEis owned by update_check.go. The update check skipsupdate,mcp,completion,__complete,help; a command whose stdout is a protocol must be added to that skip list. -ostays local (--order-by,--output-file). The output flag is--outputwith no shorthand.- Caches: site versions through
serverInfo(ctx, c, cfg, refresh)(24 h; version-dependent code uses.FrappeMajor()); DocType/report lists and schemas throughmeta_cache.go(fill only from complete, unfiltered results; never cache documents). Cache paths come frominternal/sitecache(sitecache.Dir,sitecache.DirName), never from a raw site name. - doctor checks: a method on
doctorcallingd.add(id, checkPass|checkWarn|checkFail, message, hint). Ids are a JSON contract (never rename); a check changes nothing (no refresh, no cache, no cleanup) and prints no secret. - Sanitising: the
outputpackage sanitises server strings; sanitise yourself (text.Sanitize) anything you print another way.
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
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.

