ffc-dev
Skill16 starsChanged 37 days agoMITView on GitHub
Entry point for changing the ffc (Foxmayn Frappe CLI) Go codebase in the foxmayn_frappe_cli repository - build, lint and test commands, the rules that bite most often, release and versioning, and which focused ffc-dev-* skill to load next. Use it for any code change, bug fix, refactor or review inside this repo (internal/cmd, internal/client, internal/config, internal/mcpinstall, desktop/, Makefile, CI), even a small one. For using ffc against a site, use ffc-core instead.
- Commits and pushes
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-commandSkill
- ffc-dev-desktopSkill
- ffc-dev-mcp-toolSkill
- 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
6 rules. About 0 are common, 1 is distinctive, and 5 are 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.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Every config write goes through config.Edit / config.Overwrite (lock, re-read, atomic 0600).
- Very specific: line 37
No prompts without a terminal: prompts go through runForm/confirm.
- Distinctive: line 39
Only GET is retried or follows redirects.
- Very specific: line 43
Never print secrets: use redactedURL and the redaction helpers in client/debug.go for anything that logs requests.
- Very specific: line 44
Keep syscall/x/sys/windows code in the build-tagged files (mcp_detach_unix.go, mcp_detach_windows.go).
- Very specific: line 49
Commit messages follow conventional commits, as in git log (feat(desktop): ..., fix(release): ..., refactor(sitecache): ...).
≈ “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
Developing ffc
CLAUDE.md at the repository root is the authoritative guide (architecture map, conventions, every pitfall with Frappe source references). Read the parts that touch your change. This skill is the short path through it.
Load the focused skill
| Change | Skill |
| New or changed CLI command, flag, output, prompt | ffc-dev-command |
New or changed MCP tool, policy, MCP surface, mcp install | ffc-dev-mcp-tool |
| HTTP client, auth, OAuth, retries, redirects, config writes, site setup | ffc-dev-client |
| Tests: fake Frappe, CLI harness, MCP tests, contract tests | ffc-dev-testing |
The desktop app in desktop/ | ffc-dev-desktop |
Build and verify
make fmt && make lint && make test && make build # before every commit
make vuln # govulncheck (pinned, go run)
make contract SITE=<config site> # real, disposable site only: it writes test data
go build -o /tmp/ffc ./cmd/ffc && /tmp/ffc <cmd> --help # check help text after flag changesmake lint = gofmt check + go vet + staticcheck (pinned, via go run). make test = go test -race ./.... CI also runs vet and tests on Windows (no -race), a tidy check and a cross-build. The root go test ./... skips the nested desktop/ module.
Rules that bite (details in CLAUDE.md "Common Pitfalls")
- A command or MCP tool gets its client only through
callSite/newClient(site_client.go), neverclient.New: that is where OAuth refresh and session logout happen. - Every config write goes through
config.Edit/config.Overwrite(lock, re-read, atomic 0600). Neveros.WriteFileor marshal the struct. - Data on stdout, diagnostics on stderr. Output through
render/printResult, neveroutput.PrintJSONdirectly, so--outputand--jqwork. - Return typed errors where the exit code matters (
usageErrorf,client.APIError,client.StateError,partialError); exit codes are a contract (exit.go). - No prompts without a terminal: prompts go through
runForm/confirm; writes get--dry-runviaaddDryRunand skip their confirmation underdryRunOn(cmd). - MCP handlers never write to stdout (it is the JSON-RPC channel) and every tool is registered in
toolActionsandtoolSurface. - Only GET is retried or follows redirects. Never add retries to writes.
rootCmd.PersistentPreRunEbelongs to update_check.go; add pre-run logic inside it, never reassign it.-ois a local shorthand only (list-docs --order-by,--output-file); never make it persistent.- Numbers are
json.Number(decoded with UseNumber); handle that when inspecting values. - Never print secrets: use
redactedURLand the redaction helpers in client/debug.go for anything that logs requests. - Keep
syscall/x/sys/windowscode in the build-tagged files (mcp_detach_unix.go,mcp_detach_windows.go).
Conventions
- Errors:
fmt.Errorf("context: %w", err); never log and return. - Commit messages follow conventional commits, as in
git log(feat(desktop): ...,fix(release): ...,refactor(sitecache): ...). - User-facing change: update the command's
Longhelp, the matching page under docs/ (README.md only for essentials), CLAUDE.md (architecture line or pitfall) and the matching user skill inskills/(ffc-core, ffc-bulk-lifecycle, ffc-reports-api, ffc-files-collab, ffc-setup, ffc-mcp).
Shared code to reuse, not duplicate
CLI and MCP share one function per feature; extend it instead of writing a second path.
- Schema:
fetchSchema(get_schema.go) merges Custom Fields (mergeCustomFields, byinsert_after) and applies Property Setters (applyPropertySetters);compactSchemais the default--jsonview (a JSON contract). Problems become warnings, not failures. - Self-update:
internal/releasefinds (Latest,v<digit>tags only), downloads and verifies (relsig signature, then SHA-256) a release;update.goonly confirms and swaps the binary. The desktop installer uses the same package. - Others:
checkPermission(can),buildWhoami,fetchDocContext/compactDocContext(doc-info),buildAggregateQuery/runAggregate,runSearch, the collab functions in collab.go. CLAUDE.md "Architecture" lists them by file.
Release and versions
- CLI:
git tag vX.Y.Z && git push origin vX.Y.Z; GoReleaser cross-compiles, signschecksums.txt(Ed25519,tools/relsign) and attests.ffc updaterefuses a release without a valid signature; install.sh checks it when OpenSSL 3 is available; install.ps1 checks SHA-256 only. Public keys live ininternal/relsig/keys.goandRELEASE_KEYSin install.sh (kept in sync by a test). Key rotation steps: CLAUDE.md "Release". - Version info comes from ldflags into
internal/version. go.mod:goline one release behind thetoolchainline; bump the toolchain with each Go patch release and runmake vuln.- Desktop releases use
desktop-v*tags and must never be GitHub's "latest" (see ffc-dev-desktop).
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.

