diff --git a/.agents/skills/moxie-docs/SKILL.md b/.agents/skills/moxie-docs/SKILL.md new file mode 100644 index 0000000..557a04b --- /dev/null +++ b/.agents/skills/moxie-docs/SKILL.md @@ -0,0 +1,40 @@ +--- +name: moxie-docs +description: "Use when editing code in Jackalope-Dev/fullstack-app-example before opening a PR — keeps docs in sync by pulling live conventions from the Moxie MCP server and proposing doc updates in the same PR. Triggers on any source edit, new API, or workflow change." +--- + + +# Keeping Jackalope-Dev/fullstack-app-example docs in sync + +The Moxie Docs MCP server holds this repo's live conventions, verified commands, +doc gaps, and existing docs. Always read them from the tools below — never from +memory or this file. They change as the codebase changes. + +## When to use this + +You're about to change code in Jackalope-Dev/fullstack-app-example, or you just finished a change and +haven't opened the PR yet. + +## Workflow + +1. Before editing — `moxie.get_ai_context` (repository: "Jackalope-Dev/fullstack-app-example") for + current status, conventions, verified build/test/lint commands, and open gaps. + Use the commands it returns; don't guess them. +2. Before writing code — `moxie.get_doc_impact` with the file paths you'll + change. It returns the conventions, gaps, and docs whose evidence overlaps + those paths. +3. Make your change, following the conventions `moxie.get_ai_context` returned. +4. In the same PR — for each doc obligation, `moxie.propose_doc_update` with the + title and markdown. Moxie resolves the target path; you write the file into + your branch so docs land with the code. If a path has no doc obligation, say + so — don't fabricate filler. +5. If your change DELETES code — pass those paths as `deletedPaths` to + `moxie.get_doc_impact`. For any doc it flags as orphaned (all its cited code is + gone), call `moxie.propose_doc_removal` and delete the returned path in this PR. +6. Before committing — run the verified commands `moxie.get_ai_context` returned. + +## Don't + +- Don't hardcode commands or conventions from this file — fetch them live. +- Don't add docs that only restate file or component names. +- When you edit an existing doc, fix every stale section in it, not just yours. diff --git a/.claude/skills/moxie-docs/SKILL.md b/.claude/skills/moxie-docs/SKILL.md new file mode 100644 index 0000000..557a04b --- /dev/null +++ b/.claude/skills/moxie-docs/SKILL.md @@ -0,0 +1,40 @@ +--- +name: moxie-docs +description: "Use when editing code in Jackalope-Dev/fullstack-app-example before opening a PR — keeps docs in sync by pulling live conventions from the Moxie MCP server and proposing doc updates in the same PR. Triggers on any source edit, new API, or workflow change." +--- + + +# Keeping Jackalope-Dev/fullstack-app-example docs in sync + +The Moxie Docs MCP server holds this repo's live conventions, verified commands, +doc gaps, and existing docs. Always read them from the tools below — never from +memory or this file. They change as the codebase changes. + +## When to use this + +You're about to change code in Jackalope-Dev/fullstack-app-example, or you just finished a change and +haven't opened the PR yet. + +## Workflow + +1. Before editing — `moxie.get_ai_context` (repository: "Jackalope-Dev/fullstack-app-example") for + current status, conventions, verified build/test/lint commands, and open gaps. + Use the commands it returns; don't guess them. +2. Before writing code — `moxie.get_doc_impact` with the file paths you'll + change. It returns the conventions, gaps, and docs whose evidence overlaps + those paths. +3. Make your change, following the conventions `moxie.get_ai_context` returned. +4. In the same PR — for each doc obligation, `moxie.propose_doc_update` with the + title and markdown. Moxie resolves the target path; you write the file into + your branch so docs land with the code. If a path has no doc obligation, say + so — don't fabricate filler. +5. If your change DELETES code — pass those paths as `deletedPaths` to + `moxie.get_doc_impact`. For any doc it flags as orphaned (all its cited code is + gone), call `moxie.propose_doc_removal` and delete the returned path in this PR. +6. Before committing — run the verified commands `moxie.get_ai_context` returned. + +## Don't + +- Don't hardcode commands or conventions from this file — fetch them live. +- Don't add docs that only restate file or component names. +- When you edit an existing doc, fix every stale section in it, not just yours. diff --git a/AGENTS.md b/AGENTS.md index bb1c91b..f8bf369 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,14 +3,7 @@ ## Moxie Docs Agent Guidance -Use the Moxie Docs MCP server before editing Jackalope-Dev/fullstack-app-example. Load conventions, documentation patterns, documentation gaps, documentation update opportunities, and verified commands before changing code. - -### Documentation expectation - -- Update human-readable docs when a change alters behavior, APIs, workflows, architecture, operational runbooks, or setup paths. -- Follow the repository's detected documentation placement and style. -- Prefer small source-cited docs updates over broad rewrites. -- Avoid filler docs that only restate file names, component names, or code that is already obvious. -- When you edit an existing doc, scan the whole file and correct any other section your change makes stale or wrong — don't leave known-outdated content next to a fresh update. +Before editing Jackalope-Dev/fullstack-app-example, use the Moxie Docs MCP server for live repository conventions, documentation patterns, gaps, and verified commands. The **moxie-docs** skill (`.claude/skills/moxie-docs/`) has the full edit-then-document workflow — follow it when changing code. +When your Moxie Docs token serves more than one repository, pass `repository: "Jackalope-Dev/fullstack-app-example"` in every Moxie tool call from this repo so the context targets Jackalope-Dev/fullstack-app-example.