القائمة
How to keep README.md accurate and well-structured when devctl features change — canonical section order, per-section rules, source-of-truth files, style rules, and a pre-save checklist.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | update-readme |
| description | How to keep README.md accurate and well-structured when devctl features change — canonical section order, per-section rules, source-of-truth files, style rules, and a pre-save checklist. |
This skill governs all edits to README.md in the devctl project root. It describes the canonical section order, which source files to verify accuracy against for each section, common drift points, style rules, and a pre-save checklist.
Load this skill any time you are asked to:
The README must always contain a full TOC with anchor links. The sections must appear in this exact order:
php_dd)Do not add, remove, or reorder sections without updating the TOC anchor links to match.
Cross-check these files when updating each section to ensure accuracy.
| Section | Files to verify against |
|---|---|
| Requirements | selfinstall/selfinstall.go (OS checks, root check) |
| Installation | selfinstall/selfinstall.go (--user, --sites-dir, --path, --yes flags; default paths) |
| Uninstall | selfinstall/selfinstall.go (--yes, --purge-services flags; what is removed) |
| Services (table) | config/defaults.go (all service IDs, ports, config file paths); install/*.go (download URLs, binary locations) |
| PHP | install/php.go, php/php.go; config/defaults.go (PHP FPM config path pattern) |
| DNS | dnsserver/ package; api/ DNS settings handlers; selfinstall/selfinstall.go |
| Sites | sites/ package; api/server.go site routes |
| Git Worktrees | api/ worktree handlers; sites/ worktree logic |
| PHP Dumps | dumps/ package; paths/paths.go (PrependPHPPath) |
| SPX Profiler | php/php.go (SPX ini settings); api/ SPX handlers |
config/defaults.go (Mailpit ports and config path); install/mailpit.go | |
| Config Editor | api/ config editor handlers; config/defaults.go (which services have ConfigFile) |
| Browser Notifications | frontend/src/ (notification logic) |
| MCP Server | mcpserver/ package (tools, prompts, resources) |
| Ports | config/defaults.go (all service ports); main.go (dashboard/dump port defaults) |
| Data Paths | paths/paths.go — single source of truth; selfinstall/selfinstall.go (profile.d, systemd unit) |
| Contributing | AGENTS.md, Makefile, api/server.go, go.mod |
The services table has five columns: Service, Port(s), .test vhost, Download source, Config file.
127.0.0.1:port). List all ports for multi-port services..test vhost: write the hostname (e.g. meilisearch.test) or — if the service has no vhost.install/{service}.go.{serverRoot}/... notation. Verify the exact path in config/defaults.go.redis (for Laravel compatibility)MP_* env var config patternapi/ settings handlers and main.go flag defaults.{serverRoot}/... notation — never /etc/devctl/ or any hardcoded absolute path.{serverRoot} explanation must appear above the table: it equals {sitesDir}/server, defaults to ~/sites/server, is stored in the systemd unit as DEVCTL_SERVER_ROOT, and is the single source of truth.paths/paths.go.devctl.db, prepend.php, devctl binary, bin/, logs/, one row per service dir, php/{version}/, systemd unit file, profile.d entry.selfinstall/selfinstall.go (flags are defined there).{sites-dir}/server/devctl/devctl — not /usr/local/bin.make install note must mention that the user must edit HOME, DEVCTL_SITE_USER, and DEVCTL_SERVER_ROOT in the generated unit file.The tools, prompts, and resources tables must match mcpserver/ exactly. When new tools are added, add a row; when tools are removed, remove the row.
Must include: tech stack table, build commands block, package layout table, key conventions list. Verify make targets against Makefile.
{serverRoot} as the placeholder — never ~/sites/server, /etc/devctl/, or any other hardcoded path.{serverRoot} defaults to {sitesDir}/server and is fully configurable via DEVCTL_SERVER_ROOT.{serverRoot}/... paths without re-explaining the variable.---).|.sh for shell commands, php for PHP, json for JSON, env for .env files, ini for INI files.docs/ — do not add [placeholder] comments.These areas are the most likely to become stale after code changes. Always re-check them:
| Area | Why it drifts |
|---|---|
| Services table — download URLs | Installer files change URLs when upstream moves or version pinning changes |
| Services table — config paths | config/defaults.go ConfigFile fields change when paths are reorganised |
| Ports table | New services added to config/defaults.go without corresponding README row |
| MCP tools list | mcpserver/ gains new tools without README update |
| Data Paths table | paths/paths.go adds new path functions without README update |
| PHP CLI symlinks | Logic in php/ changes symlink targets or names |
| Installation flags | selfinstall/selfinstall.go adds/renames flags without README update |
| Valkey service ID note | Easy to omit when rewriting the Services section |
Before finalising any README edit, verify each item:
-)install/*.goconfig/defaults.goconfig/defaults.go/etc/devctl/ anywhere — all paths use {serverRoot}/...paths/paths.gomcpserver/selfinstall/selfinstall.goMakefiledocs/screenshot-*.png names onlyHow to write and run devctl integration tests — where tests live, how to write failing tests first (TDD), and how to run them safely inside an Incus container without touching live host data.
Full workflow for tagging and publishing a devctl release and/or a PHP binaries release — versioning, release note generation from TODO.md, clearing TODO.md completed items, and the exact git/GitHub CLI steps for each release type.
How to add a new CLI command to devctl — writing the Cmd struct, registering it with init(), adding Client methods, using output helpers, and documenting it in README.md
How to add a new dashboard screenshot for a new or existing feature — wiring up scripts/screenshots.js, seeding data into the demo container via scripts/demo.sh, and adding the image reference to the README.
How to create, update, or maintain agent skills for this project — file structure, frontmatter rules, naming constraints, and where OpenCode discovers them
Full workflow for picking up and completing a TODO item from TODO.md — read the backlog, clarify, implement, install, browser-test, update docs, and move the item to Completed.