diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000000..ebf0cdcea7 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,13 @@ +{ + "name": "strapi-documentation", + "owner": { + "name": "Strapi Documentation" + }, + "plugins": [ + { + "name": "inki", + "description": "Inki — discover, write, review, submit your docs. A Claude Code plugin encapsulating the Strapi documentation toolkit.", + "source": "./claude-plugins/inki" + } + ] +} diff --git a/.cursor/rules/strapi-docs-drafter.mdc b/.cursor/rules/strapi-docs-drafter.mdc index 1c5a339fe9..50afcef827 100644 --- a/.cursor/rules/strapi-docs-drafter.mdc +++ b/.cursor/rules/strapi-docs-drafter.mdc @@ -56,7 +56,7 @@ The Drafter operates in one of 3 modes, determined by the target's `priority` an **Mode selection rule:** If an outline is provided → Compose. If a `micro_instruction` is provided → Micro-edit. Otherwise (existing page + edits needed) → Patch. -See the interface specification (`agents/prompts/shared/drafter-interface.md`) for the full mode selection logic. +See the interface specification (`claude-plugins/inki/references/prompts/shared/drafter-interface.md`) for the full mode selection logic. --- @@ -66,8 +66,8 @@ See the interface specification (`agents/prompts/shared/drafter-interface.md`) f ```yaml doc_type: feature | plugin | configuration | guide | api | ... -template: agents/templates/feature-template.md # or null -guide: agents/authoring/AGENTS.cms.features.md # or null +template: claude-plugins/inki/references/templates/feature-template.md # or null +guide: claude-plugins/inki/references/authoring/AGENTS.cms.features.md # or null key_topics: [topic1, topic2] target: @@ -88,7 +88,7 @@ The outline contains: - `sections` — the heading tree with `intent`, `content_hints`, `source_refs`, and `components` per node - `drafter_notes` — free-text notes about gaps, ambiguities, and cross-links -See the interface specification (`agents/prompts/shared/drafter-interface.md`) for the full outline schema. +See the interface specification (`claude-plugins/inki/references/prompts/shared/drafter-interface.md`) for the full outline schema. #### Source material diff --git a/.cursor/rules/strapi-docs-orchestrator.mdc b/.cursor/rules/strapi-docs-orchestrator.mdc index 5f80681c73..35ade1ee2e 100644 --- a/.cursor/rules/strapi-docs-orchestrator.mdc +++ b/.cursor/rules/strapi-docs-orchestrator.mdc @@ -293,10 +293,10 @@ When a prompt needs to run, search project knowledge for the file name (e.g., se ### Claude Code -The prompt files live in the repository at `agents/prompts/`. Claude Code can read them directly from disk: +The prompt files live in the repository at `claude-plugins/inki/references/prompts/`. Claude Code can read them directly from disk: ``` -cat agents/prompts/router.md +cat claude-plugins/inki/references/prompts/router.md ``` The `AGENTS.md` file at the repo root can serve as an alternative entry point, but this system prompt provides more detailed orchestration logic. @@ -305,7 +305,7 @@ The `AGENTS.md` file at the repo root can serve as an alternative entry point, b Add the prompt files to the workspace context. Depending on the IDE: -- **Cursor**: Reference prompt files with `@file` (e.g., `@agents/prompts/router.md`) or add them to `.cursor/rules/`. See [Cursor Rules Setup](#cursor-rules-setup) below. +- **Cursor**: Reference prompt files with `@file` (e.g., `@claude-plugins/inki/references/prompts/router.md`) or add them to `.cursor/rules/`. See [Cursor Rules Setup](#cursor-rules-setup) below. - **Windsurf**: Add to `.windsurfrules` or reference in workspace context. - **Other IDE agents**: Add the prompt files to whatever context/knowledge mechanism the IDE provides. @@ -501,8 +501,8 @@ The `shared/` folder contains guides used by multiple prompts: ## References - **12 Rules of Technical Writing:** https://github.com/strapi/documentation/blob/main/12-rules-of-technical-writing.md -- **Templates:** [`agents/templates/` in the repository](https://github.com/strapi/documentation/tree/main/agents/templates) -- **Authoring guides:** [`agents/authoring/AGENTS.*.md` in the repository](https://github.com/strapi/documentation/tree/main/agents/authoring) +- **Templates:** [`claude-plugins/inki/references/templates/` in the repository](https://github.com/strapi/documentation/tree/main/claude-plugins/inki/references/templates) +- **Authoring guides:** [`claude-plugins/inki/references/authoring/AGENTS.*.md` in the repository](https://github.com/strapi/documentation/tree/main/claude-plugins/inki/references/authoring) - **Root agent guide:** [`AGENTS.md` in the repository](https://github.com/strapi/documentation/blob/main/AGENTS.md) --- @@ -656,12 +656,12 @@ Detected: **[Type]** (from path `[path]`) | Path pattern | Type | Template | |-------------|------|----------| -| `cms/features/*` | Feature | `agents/templates/feature-template.md` | -| `cms/plugins/*` | Plugin | `agents/templates/plugin-template.md` | -| `cms/configurations/*` | Configuration | `agents/templates/configuration-template.md` | -| `cms/api/*` | API | `agents/templates/api-template.md` | -| `cms/migration/**/breaking-changes/*` | Breaking Change | `agents/templates/breaking-change-template.md` | -| `**/guides/*` or "How to..." | Guide | `agents/templates/guide-template.md` | +| `cms/features/*` | Feature | `claude-plugins/inki/references/templates/feature-template.md` | +| `cms/plugins/*` | Plugin | `claude-plugins/inki/references/templates/plugin-template.md` | +| `cms/configurations/*` | Configuration | `claude-plugins/inki/references/templates/configuration-template.md` | +| `cms/api/*` | API | `claude-plugins/inki/references/templates/api-template.md` | +| `cms/migration/**/breaking-changes/*` | Breaking Change | `claude-plugins/inki/references/templates/breaking-change-template.md` | +| `**/guides/*` or "How to..." | Guide | `claude-plugins/inki/references/templates/guide-template.md` | --- diff --git a/.cursor/rules/strapi-docs-outline-checker.mdc b/.cursor/rules/strapi-docs-outline-checker.mdc index 0605b006f9..afd156e095 100644 --- a/.cursor/rules/strapi-docs-outline-checker.mdc +++ b/.cursor/rules/strapi-docs-outline-checker.mdc @@ -166,12 +166,12 @@ Each page should primarily serve ONE Diataxis type: | Path pattern | Type | Template | |-------------|------|----------| -| `cms/features/*` | Feature | `agents/templates/feature-template.md` | -| `cms/plugins/*` | Plugin | `agents/templates/plugin-template.md` | -| `cms/configurations/*` | Configuration | `agents/templates/configuration-template.md` | -| `cms/api/*` | API | `agents/templates/api-template.md` | -| `cms/migration/**/breaking-changes/*` | Breaking Change | `agents/templates/breaking-change-template.md` | -| `**/guides/*` or title starts with "How to" | Guide | `agents/templates/guide-template.md` | +| `cms/features/*` | Feature | `claude-plugins/inki/references/templates/feature-template.md` | +| `cms/plugins/*` | Plugin | `claude-plugins/inki/references/templates/plugin-template.md` | +| `cms/configurations/*` | Configuration | `claude-plugins/inki/references/templates/configuration-template.md` | +| `cms/api/*` | API | `claude-plugins/inki/references/templates/api-template.md` | +| `cms/migration/**/breaking-changes/*` | Breaking Change | `claude-plugins/inki/references/templates/breaking-change-template.md` | +| `**/guides/*` or title starts with "How to" | Guide | `claude-plugins/inki/references/templates/guide-template.md` | ### Override diff --git a/.cursor/rules/strapi-docs-outline-generator.mdc b/.cursor/rules/strapi-docs-outline-generator.mdc index 4d8aba67b0..505fa558ae 100644 --- a/.cursor/rules/strapi-docs-outline-generator.mdc +++ b/.cursor/rules/strapi-docs-outline-generator.mdc @@ -48,8 +48,8 @@ The machine-readable YAML from the Router, containing: ```yaml doc_type: feature | plugin | configuration | guide | api | breaking-change -template: agents/templates/feature-template.md # or null -guide: agents/authoring/AGENTS.cms.features.md # or null +template: claude-plugins/inki/references/templates/feature-template.md # or null +guide: claude-plugins/inki/references/authoring/AGENTS.cms.features.md # or null key_topics: [topic1, topic2, topic3] targets: @@ -75,7 +75,7 @@ The raw input that describes what needs to be documented: **Not required when:** `action: create_page` — the page doesn't exist yet. -**How to obtain it:** Use GitHub MCP tools to fetch the file from the repository (see `agents/prompts/shared/github-mcp-usage.md`). +**How to obtain it:** Use GitHub MCP tools to fetch the file from the repository (see `claude-plugins/inki/references/prompts/shared/github-mcp-usage.md`). --- @@ -95,8 +95,8 @@ If the Router output contains multiple `primary` targets (rare), generate a sepa **Before analyzing source material**, read the template and authoring guide specified in the Router output: -1. **Read the template file** (e.g., `agents/templates/feature-template.md`). This is the Single Source of Truth (SSOT) for required sections, components, and structure. -2. **Read the authoring guide** (e.g., `agents/authoring/AGENTS.cms.features.md`). This provides additional conventions, heading rules, and quality expectations. +1. **Read the template file** (e.g., `claude-plugins/inki/references/templates/feature-template.md`). This is the Single Source of Truth (SSOT) for required sections, components, and structure. +2. **Read the authoring guide** (e.g., `claude-plugins/inki/references/authoring/AGENTS.cms.features.md`). This provides additional conventions, heading rules, and quality expectations. If both `template` and `guide` are null (rare), fall back to the type-specific heuristics in the "Document type handling" section below plus the 12 Rules of Technical Writing. @@ -151,8 +151,8 @@ Generate the structured YAML outline following the output format defined below. ### Feature (`doc_type: feature`) -**Template:** `agents/templates/feature-template.md` -**Guide:** `agents/authoring/AGENTS.cms.features.md` +**Template:** `claude-plugins/inki/references/templates/feature-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.features.md` **Skeleton:** H1 → `` → Intro → `` → `## Configuration` → `## Usage` @@ -164,8 +164,8 @@ Generate the structured YAML outline following the output format defined below. ### Plugin (`doc_type: plugin`) -**Template:** `agents/templates/plugin-template.md` -**Guide:** `agents/authoring/AGENTS.cms.plugins.md` +**Template:** `claude-plugins/inki/references/templates/plugin-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md` **Skeleton:** H1 → `` → `` → `## Installation` → `## Configuration` → `## Usage` @@ -182,8 +182,8 @@ Generate the structured YAML outline following the output format defined below. ### Configuration (`doc_type: configuration`) -**Template:** `agents/templates/configuration-template.md` -**Guide:** `agents/authoring/AGENTS.cms.configurations.md` +**Template:** `claude-plugins/inki/references/templates/configuration-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md` **Common core:** H1 → `` → `:::caution` (if applicable) → Intro paragraph (names file paths) @@ -198,8 +198,8 @@ Generate the structured YAML outline following the output format defined below. ### Guide (`doc_type: guide`) -**Template:** `agents/templates/guide-template.md` -**Guide:** `agents/authoring/AGENTS.cms.guides.md` +**Template:** `claude-plugins/inki/references/templates/guide-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.guides.md` **Skeleton:** H1 → `` → Intro → `:::prerequisites` → Steps → `## Troubleshooting` (optional) @@ -212,8 +212,8 @@ Generate the structured YAML outline following the output format defined below. ### API (`doc_type: api`) -**Template:** `agents/templates/api-template.md` -**Guide:** `agents/authoring/AGENTS.cms.api.md` +**Template:** `claude-plugins/inki/references/templates/api-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.api.md` API pages have **3 sub-types**. Determine from source material: @@ -244,8 +244,8 @@ Each endpoint H2 has H3s: Path/query parameters, Request body, Responses, Exampl ### Breaking Change (`doc_type: breaking-change`) -**Template:** `agents/templates/breaking-change-template.md` -**Guide:** `agents/authoring/AGENTS.cms.breaking-changes.md` +**Template:** `claude-plugins/inki/references/templates/breaking-change-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.breaking-changes.md` **Skeleton:** imports → H1 → Summary → `` → `` → `## Breaking change description` → `## Migration` diff --git a/.cursor/rules/strapi-docs-router.mdc b/.cursor/rules/strapi-docs-router.mdc index aa67df614f..f7fb700868 100644 --- a/.cursor/rules/strapi-docs-router.mdc +++ b/.cursor/rules/strapi-docs-router.mdc @@ -36,7 +36,7 @@ The Router cannot make reliable placement decisions without these files. If neit When the user provides a GitHub PR as source material, use the GitHub MCP tools to fetch the PR content directly. -👉 **See [GitHub MCP Usage Guide](agents/prompts/shared/github-mcp-usage.md)** for the full workflow. +👉 **See [GitHub MCP Usage Guide](claude-plugins/inki/references/prompts/shared/github-mcp-usage.md)** for the full workflow. **Quick reference:** 1. `github:get_pull_request(owner, repo, pull_number)` → PR title, description @@ -74,7 +74,7 @@ A structured Markdown report containing: | Page | What to do | |------|------------| -| `path/to/new-page.md` | **Create** new page — follow [Feature template](https://github.com/strapi/documentation/blob/main/agents/templates/feature-template.md) + [Features authoring guide](https://github.com/strapi/documentation/blob/main/agents/authoring/AGENTS.cms.features.md) | +| `path/to/new-page.md` | **Create** new page — follow [Feature template](https://github.com/strapi/documentation/blob/main/claude-plugins/inki/references/templates/feature-template.md) + [Features authoring guide](https://github.com/strapi/documentation/blob/main/claude-plugins/inki/references/authoring/AGENTS.cms.features.md) | | `path/to/existing.md` | **Update** — add [description] to "[Section name]" section | | `path/to/other.md` | **Update** — add row to "[Table name]" table | | `path/to/conditional.md` | **Later** — [condition, e.g., "when X feature ships"] | @@ -306,12 +306,12 @@ Set `ask_user` (as a top-level YAML field or as the placement decision) when: | Type | Path patterns | Template | Authoring guide | |------|--------------|----------|-----------------| -| **Feature** | `cms/features/*` | `agents/templates/feature-template.md` | `agents/cms/features/AGENTS.md` | -| **Plugin** | `cms/plugins/*` (not `plugins-development`) | `agents/templates/plugin-template.md` | `agents/cms/plugins/AGENTS.md` | -| **Configuration** | `cms/configurations/*` | `agents/templates/configuration-template.md` | `agents/cms/configurations/AGENTS.md` | -| **Guide** | `**/guides/*` or task-oriented "How to…" | `agents/templates/guide-template.md` | `agents/cms/AGENTS.guides.md` | -| **API** | `cms/api/*` | `agents/templates/api-template.md` | `agents/cms/api/AGENTS.md` | -| **Breaking Change** | `cms/migration/**/breaking-changes/*.md` | `agents/templates/breaking-change-template.md` | `agents/cms/migration/AGENTS.md` | +| **Feature** | `cms/features/*` | `claude-plugins/inki/references/templates/feature-template.md` | `agents/cms/features/AGENTS.md` | +| **Plugin** | `cms/plugins/*` (not `plugins-development`) | `claude-plugins/inki/references/templates/plugin-template.md` | `agents/cms/plugins/AGENTS.md` | +| **Configuration** | `cms/configurations/*` | `claude-plugins/inki/references/templates/configuration-template.md` | `agents/cms/configurations/AGENTS.md` | +| **Guide** | `**/guides/*` or task-oriented "How to…" | `claude-plugins/inki/references/templates/guide-template.md` | `agents/cms/AGENTS.guides.md` | +| **API** | `cms/api/*` | `claude-plugins/inki/references/templates/api-template.md` | `agents/cms/api/AGENTS.md` | +| **Breaking Change** | `cms/migration/**/breaking-changes/*.md` | `claude-plugins/inki/references/templates/breaking-change-template.md` | `agents/cms/migration/AGENTS.md` | | **Concept** | Introductions, overviews, conceptual pages | None | `agents/cms/AGENTS.concepts.md` | | **Cloud** | `cloud/*` | None | `agents/cloud/AGENTS.md` | | **Snippet** | `snippets/*` | None | `agents/snippets/AGENTS.md` | @@ -404,7 +404,7 @@ For **each target** in the routing: 1. **Determine document type** from the target's path (see Document Types table) 2. **Locate the template** (if one exists for this type) 3. **Locate the authoring guide** (if one exists for this type) -4. If no template or guide exists for a target, note that the [12 Rules of Technical Writing](https://strapi.notion.site/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04) and the [Style Checker](https://github.com/strapi/documentation/blob/main/agents/prompts/style-checker.md) are the minimum standards. +4. If no template or guide exists for a target, note that the [12 Rules of Technical Writing](https://strapi.notion.site/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04) and the [Style Checker](https://github.com/strapi/documentation/blob/main/claude-plugins/inki/references/prompts/style-checker.md) are the minimum standards. **Important:** Each target may have a different document type. For example, a routing with both `cms/features/mcp-server.md` and `cms/configurations/server.md` requires: - Feature template + Features authoring guide for the feature page @@ -432,7 +432,7 @@ The "Existing pages found" table must show the correct template and authoring gu 8. **Respect existing architecture.** Prefer fitting content into the existing structure over creating new categories. `create_category` should be rare and always confirmed with the user. -9. **Use GitHub MCP when available.** When the source is a GitHub PR, use the GitHub MCP tools to fetch the PR content directly rather than asking the user to paste it. See [GitHub MCP Usage Guide](agents/prompts/shared/github-mcp-usage.md). +9. **Use GitHub MCP when available.** When the source is a GitHub PR, use the GitHub MCP tools to fetch the PR content directly rather than asking the user to paste it. See [GitHub MCP Usage Guide](claude-plugins/inki/references/prompts/shared/github-mcp-usage.md). 10. **Stay in scope.** The Router decides *where* content goes. It does NOT: - Extract detailed specifications from the source material (→ Outline Generator) @@ -639,7 +639,7 @@ targets: **Source:** User says "Route PR #1542 from strapi/documentation" -**Expected workflow:** See [GitHub MCP Usage Guide](agents/prompts/shared/github-mcp-usage.md) +**Expected workflow:** See [GitHub MCP Usage Guide](claude-plugins/inki/references/prompts/shared/github-mcp-usage.md) 1. Fetch PR metadata → Title: "Add MCP Server documentation" 2. Fetch changed files → `docs/cms/features/mcp-server.md` (added), `docs/cms/configurations/server.md` (modified) diff --git a/.github/prompts/docs-self-healing-drafter.md b/.github/prompts/docs-self-healing-drafter.md index 9b289c20c4..2114d26856 100644 --- a/.github/prompts/docs-self-healing-drafter.md +++ b/.github/prompts/docs-self-healing-drafter.md @@ -22,11 +22,11 @@ containing `targets`, `doc_type`, `template`, `guide`, and `confidence`. ## Step 2 — Run the documentation pipeline (per PR with targets) **Load these agent prompts now:** -- Orchestrator: `$DOC_REPO/agents/prompts/orchestrator.md` -- Outline Generator: `$DOC_REPO/agents/prompts/outline-generator.md` -- Drafter: `$DOC_REPO/agents/prompts/drafter.md` -- Style Checker: `$DOC_REPO/agents/prompts/style-checker.md` -- Integrity Checker: `$DOC_REPO/agents/prompts/integrity-checker.md` +- Orchestrator: `$DOC_REPO/claude-plugins/inki/references/prompts/orchestrator.md` +- Outline Generator: `$DOC_REPO/claude-plugins/inki/references/prompts/outline-generator.md` +- Drafter: `$DOC_REPO/claude-plugins/inki/references/prompts/drafter.md` +- Style Checker: `$DOC_REPO/claude-plugins/inki/references/prompts/style-checker.md` +- Integrity Checker: `$DOC_REPO/claude-plugins/inki/references/prompts/integrity-checker.md` For each PR, read the pre-fetched body and diff from `/tmp/pr--body.txt` and `/tmp/pr-.diff`. @@ -34,7 +34,7 @@ Follow the auto-chain execution from the Orchestrator: 1. **For `create_page` targets:** - Run Outline Generator with Router YAML + source material - - Also load: `$DOC_REPO/agents/prompts/outline-checker.md` + - Also load: `$DOC_REPO/claude-plugins/inki/references/prompts/outline-checker.md` - Run Drafter in Compose mode with the outline - Self-review: run Style Checker and Outline Checker on output - If errors: re-run Drafter once with corrections (max 1 retry) @@ -52,10 +52,10 @@ Follow the auto-chain execution from the Orchestrator: - Run Integrity Checker on the final output (links, paths, anchors, code block syntax) - Log any issues but do not block PR creation — Pierre will verify during review -**Authoring guides:** For each target, load the relevant authoring guide from `$DOC_REPO/agents/authoring/` +**Authoring guides:** For each target, load the relevant authoring guide from `$DOC_REPO/claude-plugins/inki/references/authoring/` based on the Router's `doc_type` and target path. Read per target, not upfront. -**Templates:** For `create_page` targets, load the relevant template from `$DOC_REPO/agents/templates/` +**Templates:** For `create_page` targets, load the relevant template from `$DOC_REPO/claude-plugins/inki/references/templates/` based on the Router's `doc_type`. ## Step 3 — Create branch and draft PR (per PR) diff --git a/.github/prompts/docs-self-healing-router.md b/.github/prompts/docs-self-healing-router.md index 663fd9659d..912f6300bf 100644 --- a/.github/prompts/docs-self-healing-router.md +++ b/.github/prompts/docs-self-healing-router.md @@ -14,7 +14,7 @@ You run on Haiku for cost efficiency. Do NOT draft content or create PRs. ## Instructions 1. **Read these files once:** - - Router prompt: `$DOC_REPO/agents/prompts/router.md` + - Router prompt: `$DOC_REPO/claude-plugins/inki/references/prompts/router.md` - Sidebars: `$DOC_REPO/docusaurus/sidebars.js` - Page index: `$DOC_REPO/docusaurus/static/llms.txt` @@ -36,7 +36,7 @@ You run on Haiku for cost efficiency. Do NOT draft content or create PRs. "decision": "has_targets", "complexity": "full", "reason": "", - "targets_yaml": "targets:\n - path: cms/features/x.md\n action: update_section\n priority: primary\n existing_section: \"Configuration\"\n description: \"Add feature X config options\"\n\ndoc_type: feature\ntemplate: null\nguide: agents/authoring/AGENTS.cms.features.md\nconfidence: high" + "targets_yaml": "targets:\n - path: cms/features/x.md\n action: update_section\n priority: primary\n existing_section: \"Configuration\"\n description: \"Add feature X config options\"\n\ndoc_type: feature\ntemplate: null\nguide: claude-plugins/inki/references/authoring/AGENTS.cms.features.md\nconfidence: high" }, { "number": 12350, diff --git a/.github/workflows/inki-sync-root-refs.yml b/.github/workflows/inki-sync-root-refs.yml new file mode 100644 index 0000000000..f3a428aec0 --- /dev/null +++ b/.github/workflows/inki-sync-root-refs.yml @@ -0,0 +1,56 @@ +name: Sync root refs to inki plugin + +on: + pull_request: + paths: + - 'git-rules.md' + - '12-rules-of-technical-writing.md' + - 'style-guide.md' + - 'claude-plugins/inki/references/git-rules.md' + - 'claude-plugins/inki/references/12-rules-of-technical-writing.md' + - 'claude-plugins/inki/references/style-guide.md' + +permissions: + contents: write + pull-requests: write + +jobs: + sync-or-fail: + runs-on: ubuntu-latest + steps: + - name: Checkout PR head + uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + fetch-depth: 0 + + - name: Detect plugin-side-only edits (forbidden) + run: | + set -e + CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD) + echo "Changed files:" + echo "$CHANGED" + for f in git-rules.md 12-rules-of-technical-writing.md style-guide.md; do + if echo "$CHANGED" | grep -q "^claude-plugins/inki/references/$f$"; then + if ! echo "$CHANGED" | grep -q "^$f$"; then + echo "::error::You modified claude-plugins/inki/references/$f but not $f at the repo root." + echo "::error::The repo root is canonical. Edit $f at the root; the plugin copy is auto-synced." + exit 1 + fi + fi + done + + - name: Run sync script + run: ./claude-plugins/inki/scripts/sync-root-refs.sh + + - name: Commit and push if changed + run: | + git config user.email "github-actions@github.com" + git config user.name "GitHub Actions (inki sync)" + git add claude-plugins/inki/references/ + if ! git diff --staged --quiet; then + git commit -m "Auto-sync root refs to inki plugin" + git push + else + echo "No changes to commit." + fi diff --git a/AGENTS.md b/AGENTS.md index deb5c4e956..133f428eac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ ## Scope and precedence - This file applies to the entire repository. -- Area‑specific AGENTS files (in `agents/`) may add or override rules for their scope. +- Area‑specific AGENTS files (in `claude-plugins/inki/references/authoring/`) may add or override rules for their scope. ## Project overview @@ -66,19 +66,20 @@ Path‑based policy (applies to folders and all subfolders): │ ├── scripts/ # Build and utility scripts │ ├── sidebars.js # Sidebar configuration │ └── docusaurus.config.js # Main configuration -├── agents/ # Documentation review and generation agents -│ ├── prompts/ # AI agent specifications -│ ├── templates/ # Content templates -│ └── authoring/ # Authoring guides +├── claude-plugins/inki/ # Inki Claude Code plugin +│ └── references/ # Agent prompts, templates, authoring guides +│ ├── prompts/ # AI agent specifications +│ ├── templates/ # Content templates +│ └── authoring/ # Authoring guides └── .cursor/rules/ # Cursor IDE rules for documentation agents ``` ### Key files - AI toolbar: `docusaurus/src/components/AiToolbar/openLLM.js`, `.../config/aiToolsConfig.js`, `.../config/aiPromptTemplates.js` - Generators/validators: `docusaurus/scripts/generate-llms-code.js`, `docusaurus/scripts/generate-llms.js`, `docusaurus/scripts/validate-prompts.js` -- Authoring templates: `agents/templates/*.md` (see `agents/templates/INDEX.md`) -- Agent prompts: `agents/prompts/` (see table in Documentation Review System section) -- Components guidance: `agents/templates/components/tabs.md` (Tabs/TabItem rules) +- Authoring templates: `claude-plugins/inki/references/templates/*.md` (see `claude-plugins/inki/references/templates/INDEX.md`) +- Agent prompts: `claude-plugins/inki/references/prompts/` (see table in Documentation Review System section) +- Components guidance: `claude-plugins/inki/references/templates/components/tabs.md` (Tabs/TabItem rules) - Configuration: `docusaurus.config.js`, `sidebars.js`, `package.json` ## Writing guidelines and content validation @@ -105,34 +106,34 @@ Path‑based policy (applies to folders and all subfolders): ### Directory of AGENTS guides -- CMS (canonical): `agents/authoring/AGENTS.cms.md` -- CMS – How‑to Guides: `agents/authoring/AGENTS.cms.guides.md` -- CMS – API docs: `agents/authoring/AGENTS.cms.api.md` -- CMS – Configurations: `agents/authoring/AGENTS.cms.configurations.md` -- CMS – Features: `agents/authoring/AGENTS.cms.features.md` -- CMS – Plugins: `agents/authoring/AGENTS.cms.plugins.md` -- Cloud docs: `agents/authoring/AGENTS.cloud.md` -- Snippets: `agents/authoring/AGENTS.snippets.md` +- CMS (canonical): `claude-plugins/inki/references/authoring/AGENTS.cms.md` +- CMS – How‑to Guides: `claude-plugins/inki/references/authoring/AGENTS.cms.guides.md` +- CMS – API docs: `claude-plugins/inki/references/authoring/AGENTS.cms.api.md` +- CMS – Configurations: `claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md` +- CMS – Features: `claude-plugins/inki/references/authoring/AGENTS.cms.features.md` +- CMS – Plugins: `claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md` +- Cloud docs: `claude-plugins/inki/references/authoring/AGENTS.cloud.md` +- Snippets: `claude-plugins/inki/references/authoring/AGENTS.snippets.md` -The `agents/templates/README.md` explains the purpose of the templates directory (authoring skeletons) and lists all templates with links. +The `claude-plugins/inki/references/templates/README.md` explains the purpose of the templates directory (authoring skeletons) and lists all templates with links. ### Specialized prompts -Located in `agents/prompts/`. Cursor IDE wrappers are in `.cursor/rules/`. +Located in `claude-plugins/inki/references/prompts/`. Cursor IDE wrappers are in `.cursor/rules/`. | Prompt | Path | Purpose | |--------|------|---------| -| **Orchestrator** | `agents/prompts/orchestrator.md` | Coordinates Review and Create workflows | -| **Router** | `agents/prompts/router.md` | Identifies doc type, determines placement, loads template and authoring guide | -| **Outliner** | `agents/prompts/outliner.md` | Routes to Outline Checker, UX Analyzer, or Outline Generator | -| **Outline Checker** | `agents/prompts/outline-checker.md` | Ensures template compliance, frontmatter, heading hierarchy | -| **Outline UX Analyzer** | `agents/prompts/outline-ux-analyzer.md` | Checks reader experience, section order, cognitive load | -| **Outline Generator** | `agents/prompts/outline-generator.md` | Creates outlines from source material (Notion, Jira, specs) | -| **Style Checker** | `agents/prompts/style-checker.md` | Ensures compliance to 12 Rules of Technical Writing | -| **Drafter** | `agents/prompts/drafter.md` | Drafts documentation based on inputs from Router and Outliner | -| **Integrity Checker** | `agents/prompts/integrity-checker.md` | Coordinates technical verification (code examples, cross-page coherence) | - -Shared resources: `agents/prompts/shared/github-mcp-usage.md` (how to fetch PR content using GitHub MCP tools). +| **Orchestrator** | `claude-plugins/inki/references/prompts/orchestrator.md` | Coordinates Review and Create workflows | +| **Router** | `claude-plugins/inki/references/prompts/router.md` | Identifies doc type, determines placement, loads template and authoring guide | +| **Outliner** | `claude-plugins/inki/references/prompts/outliner.md` | Routes to Outline Checker, UX Analyzer, or Outline Generator | +| **Outline Checker** | `claude-plugins/inki/references/prompts/outline-checker.md` | Ensures template compliance, frontmatter, heading hierarchy | +| **Outline UX Analyzer** | `claude-plugins/inki/references/prompts/outline-ux-analyzer.md` | Checks reader experience, section order, cognitive load | +| **Outline Generator** | `claude-plugins/inki/references/prompts/outline-generator.md` | Creates outlines from source material (Notion, Jira, specs) | +| **Style Checker** | `claude-plugins/inki/references/prompts/style-checker.md` | Ensures compliance to 12 Rules of Technical Writing | +| **Drafter** | `claude-plugins/inki/references/prompts/drafter.md` | Drafts documentation based on inputs from Router and Outliner | +| **Integrity Checker** | `claude-plugins/inki/references/prompts/integrity-checker.md` | Coordinates technical verification (code examples, cross-page coherence) | + +Shared resources: `claude-plugins/inki/references/prompts/shared/github-mcp-usage.md` (how to fetch PR content using GitHub MCP tools). ### Workflows @@ -153,7 +154,7 @@ These prompts are designed for use in: - **Cursor IDE**: Use the `.cursor/rules/*.mdc` wrappers - **Other AI tools (Copilot, Cline, Windsurf…)**: Copy prompt content or use as system prompts -See `agents/prompts/README.md` for detailed usage instructions. +See `claude-plugins/inki/references/prompts/README.md` for detailed usage instructions. ## PR, branch, and git rules diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d00a701d2d..150842eeba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -109,6 +109,40 @@ That’s it! 🥳 Once the pull request is [reviewed and approved](#review-and-m If your contribution takes part in the [Docs Contribution Program](https://strapi.notion.site/Documentation-Contribution-Program-1d08f359807480d480fdde68bb7a5a71), as soon as your pull request is merged, you should receive an email with a link to the Strapi Shop where points you have earned will have been granted to your account. +## 🤖 Working with the Inki Claude Code plugin + +This repository hosts the **Inki** Claude Code plugin under `claude-plugins/inki/`. Inki bundles skills, prompts, templates, and authoring guides used to maintain these docs. + +### What Inki does + +Inki organizes 21 skills into four families: **Discover** (find what exists), **Write** (outline and draft new pages), **Review** (style, structure, code, coherence, pitfalls), and **Submit** (branch, commit, push, open or rewrite a PR). + +A few examples: +- `/inki:exists ` checks whether a topic is already covered before you write. +- `/inki:review ` runs the full review pipeline on a documentation file. +- `/inki:pr` opens a PR with a compliant title and description. + +For the full skill catalog, install instructions, and editing rules, see [`claude-plugins/inki/README.md`](claude-plugins/inki/README.md). + +### Installing Inki + +If you use Claude Code, you can install Inki with two slash commands: + +```bash +/plugin marketplace add strapi/documentation +/plugin install inki@strapi-documentation +``` + +### Editing canonical rules + +`git-rules.md` and `12-rules-of-technical-writing.md` at the repository root are the **canonical** versions. Copies live in `claude-plugins/inki/references/` for the plugin's autonomy, and are auto-synced by a GitHub Action on every PR. + +Always edit the root file, never the copy inside `claude-plugins/inki/references/`. CI rejects PRs that modify only the plugin copies. + +### Editing agent prompts, templates, and authoring guides + +These now live inside the plugin at `claude-plugins/inki/references/prompts/`, `references/templates/`, and `references/authoring/`. The historical `agents/` folder contains only a pointer README. + ## Review and management of pull requests The pull request review process and timeline are based on the availability of the Strapi Documentation team to handle community contributions. The workflow is as follows: diff --git a/agents/README.md b/agents/README.md index decb1f6660..8aff02c1bb 100644 --- a/agents/README.md +++ b/agents/README.md @@ -1,51 +1,20 @@ -# Agents folder +# agents/ — content moved -This directory stores authoring guidance, templates, and review prompts used to maintain the documentation repository. Nothing here is published on the website. +The agent prompts, templates, and authoring guides that used to live here are now part of the Inki Claude Code plugin. -## What lives here +You can find them under `../claude-plugins/inki/references/`: -| Folder | Purpose | Entry point | -|--------|---------|-------------| -| `authoring/` | Area‑specific writing rules: expected sections, components, frontmatter, and conventions per doc type | [`/agents/authoring/README.md`](https://github.com/strapi/documentation/blob/main/agents/authoring/README.md) | -| `templates/` | Copy‑paste skeletons for new pages, with correct structure and placeholders | [`/agents/templates/README.md`](https://github.com/strapi/documentation/blob/main/agents/templates/README.md) | -| `prompts/` | Specialized prompts for reviewing and creating documentation (style, structure, UX) | [`/agents/prompts/README.md`](https://github.com/strapi/documentation/blob/main/agents/prompts/README.md) | +- Prompts → `../claude-plugins/inki/references/prompts/` +- Templates → `../claude-plugins/inki/references/templates/` +- Authoring guides → `../claude-plugins/inki/references/authoring/` -How these pieces connect: **authoring guides** define the rules, **templates** encode them as ready‑to‑use skeletons, and **prompts** automate checking against them. +To install and use the plugin: -## Audience +```bash +/plugin marketplace add strapi/documentation +/plugin install inki@strapi-documentation +``` -- Human authors and reviewers who want consistent page structure and conventions. -- Automation and AI tools that scaffold or validate docs without touching published content. +See `../claude-plugins/inki/README.md` for the full overview. -## Quick start (human authors) - -1) Find the right template in `agents/templates/README.md`. -2) Copy it into `docusaurus/docs/...`, fill in placeholders, and read the corresponding authoring guide for area‑specific conventions. -3) Open a PR following the commit and branch rules in `AGENTS.md`. - -For the full step‑by‑step, see `agents/templates/README.md`. - -## Quick start (AI tools) - -- Read area guides (`agents/authoring/AGENTS.*.md`) for expected structure. -- Use templates (`agents/templates/*.md`) when scaffolding new pages. -- Use prompts (`agents/prompts/*.md`) to decide where and what to write, then run style, structure, and UX checks. -- Never write to `agents/**` when publishing docs; always target `docusaurus/docs/**`. - -## Safety rails - -- Excluded from build: `docusaurus/docusaurus.config.js` excludes `AGENTS.*`, `templates/**`, and `../agents/**` patterns. -- Not in sidebars: no agent files are referenced in `docusaurus/sidebars.js`. -- Excluded from LLMs: generators ignore `AGENTS` and `templates` (and any `agents/**`) paths. - -## Do and Don't - -- Do keep repo‑relative, clickable paths when linking files. -- Do keep templates minimal, with clear placeholders and path hints in code fences (e.g., `title="/config/.js"`). -- Don't place agent files back under `docusaurus/docs/**`. -- Don't include agents/templates in search configs or LLM datasets. - -## References - -- Root agent guide: `AGENTS.md` -- Authoring area guides: `/agents/authoring/AGENTS.*.md` +This `agents/` directory is preserved as a landmark for existing bookmarks and external links. diff --git a/claude-plugins/inki/.claude-plugin/plugin.json b/claude-plugins/inki/.claude-plugin/plugin.json new file mode 100644 index 0000000000..03edf69b16 --- /dev/null +++ b/claude-plugins/inki/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "inki", + "version": "0.1.0", + "description": "Inki — discover, write, review, submit your docs. A Claude Code plugin encapsulating the Strapi documentation toolkit.", + "author": { + "name": "Pierre Wizla" + } +} diff --git a/claude-plugins/inki/CHANGELOG.md b/claude-plugins/inki/CHANGELOG.md new file mode 100644 index 0000000000..864b741071 --- /dev/null +++ b/claude-plugins/inki/CHANGELOG.md @@ -0,0 +1,15 @@ +# Inki Changelog + +## v0.1.0 — 2026-05-22 + +### Added + +- Plugin scaffolding (`.claude-plugin/plugin.json`, README, CHANGELOG). +- Self-hosted marketplace manifest at `.claude-plugin/marketplace.json`. +- Discover family: `/inki:discover`, `/inki:exists`, `/inki:route`, `/inki:coverage`. +- Write family: `/inki:write`, `/inki:outline`, `/inki:draft`. +- Review family: `/inki:review`, `/inki:style-check`, `/inki:outline-check`, `/inki:outline-ux-analyzer`, `/inki:code-verify`, `/inki:coherence-check`, `/inki:pitfalls-check`. +- Submit family: `/inki:submit`, `/inki:branch`, `/inki:commit`, `/inki:push`, `/inki:pr`, `/inki:pr-title-fix`, `/inki:pr-description-fix`, `/inki:pr-body-fix` (alias). +- 1-way root → plugin sync GitHub Action with drift guard. +- Migration of prompts, templates, and authoring guides into `claude-plugins/inki/references/`. +- Pointer README at the previous location for backward discoverability. diff --git a/claude-plugins/inki/README.md b/claude-plugins/inki/README.md new file mode 100644 index 0000000000..6413a140f1 --- /dev/null +++ b/claude-plugins/inki/README.md @@ -0,0 +1,79 @@ +# Inki — discover, write, review, submit your docs + +Inki is a Claude Code plugin bundling the skills, prompts, templates, and rules used to author and maintain the Strapi documentation. It lives in this repository (`claude-plugins/inki/`) and is installable via the repo's self-hosted marketplace. + +## Install + +```bash +/plugin marketplace add strapi/documentation +/plugin install inki@strapi-documentation +``` + +After install, the skills are available at `/inki:`. The plugin is persistent across Claude Code sessions. + +## Skill families + +**Notation for skill arguments:** + +- `` = required argument. +- `[arg]` = optional argument. +- `` = a topic description, either as inline text (e.g., "MCP server feature, AI tools section, similar to existing AI pages") or as a path to a `.md` file containing the description. +- `` = path to an outline file produced by `/inki:outline`. +- `` = path to a documentation file (under `docusaurus/docs/`). +- `` = a keyword or short phrase to search for (e.g., "MCP server"). +- `[hint]` = an optional issue reference (e.g., `Fixes #2143`) or short topic hint passed through to the PR. +- `[PR#]` = a pull request number (e.g., `2143`). + +### Discover — before you write + +Find out what already exists, where to put new content, what's missing. + +- `/inki:discover ` — orchestrator: dispatches to the right sub-skill based on input shape. +- `/inki:exists ` — search docs + sidebars + open PRs for a topic. +- `/inki:route ` — given a code PR, identify which docs to update. +- `/inki:coverage ` — audit documentation coverage of a Strapi feature. + +### Write — produce new content + +- `/inki:write ` — orchestrator: outline then draft. +- `/inki:outline ` — generate an outline from a brief and template. +- `/inki:draft ` — draft a page from an outline + template + authoring guide. + +### Review — check what you wrote + +- `/inki:review [--fix]` — orchestrator: runs all 6 review sub-skills. +- `/inki:style-check ` — style lint (deterministic + AI). +- `/inki:outline-check ` — verify outline matches template. +- `/inki:outline-ux-analyzer ` — audit pedagogical UX. +- `/inki:code-verify ` — verify code blocks. +- `/inki:coherence-check ` — check cross-page coherence. +- `/inki:pitfalls-check ` — audit against known pitfalls. + +### Submit — get it to GitHub + +- `/inki:submit [hint]` — orchestrator: branch + commit + push + PR. +- `/inki:branch` — create a properly prefixed branch. +- `/inki:commit` — stage + commit with a compliant message. +- `/inki:push` — push with validation. +- `/inki:pr [issue]` — open a PR with a compliant title and description. +- `/inki:pr-title-fix [PR#...]` — rewrite the title of existing PRs. +- `/inki:pr-description-fix [PR#...]` — rewrite the body of existing PRs. +- `/inki:pr-body-fix [PR#...]` — alias of `/inki:pr-description-fix`. + +## How it integrates with this repo + +- The canonical rules (`git-rules.md`, `12-rules-of-technical-writing.md`) live at the repo root. They are auto-synced into `claude-plugins/inki/references/` by a GitHub Action. +- The agent prompts, templates, and authoring guides live inside the plugin at `claude-plugins/inki/references/`. They used to live in `agents/`; that folder now contains only a pointer README. + +## Editing rules + +- Edit the canonical rules at the **repo root**, not in `claude-plugins/inki/references/`. The plugin copies are synced automatically. CI fails if you edit only the plugin copies. +- Edit agent prompts, templates, and authoring guides inside `claude-plugins/inki/references/`. These are now the canonical home. + +## Status + +v0.1.0 — initial release. See `CHANGELOG.md` for details. + +## License + +MIT (inherits from the strapi/documentation repository). diff --git a/claude-plugins/inki/references/12-rules-of-technical-writing.md b/claude-plugins/inki/references/12-rules-of-technical-writing.md new file mode 100644 index 0000000000..d3501fcc9b --- /dev/null +++ b/claude-plugins/inki/references/12-rules-of-technical-writing.md @@ -0,0 +1,24 @@ +# 12 Rules of Technical Writing (Concise Reference) + +- This concise version is optimized for LLMs and quick reviews. +- Canonical full text: https://strapi.notion.site/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04 + +1. Remember your audience but don't assume anything: document the obvious. +2. Don't try reinventing the wheel: what you write must blend in, never step out. +3. Adopt a direct and neutral tone: no jokes, no random emojis, no funny GIFs. +4. Stick to simple English: one shouldn't need a dictionary to understand documentation. +5. Write concise, straight-to-the-point content with short sentences separated into sections. +6. Never say something is "easy" or "difficult". +7. Make sure your directions are displayed in numbered lists. Remember: one step = one action. +8. Replace enumerations with bullet lists and complex lists with tables. +9. Keep away from ambiguous pronouns and abbreviations, and use acronyms sparingly. +10. Take advantage of the power of illustrations: screenshots and schemas are sometimes better than long sentences. +11. Avoid using pronouns too much. +12. Don't overuse capital letters and bold: use proper content formatting instead (see STYLE_GUIDE.pdf). + +Quick checklist before review +- Headings meaningful; sections short; sentences concise. +- Numbered steps for procedures; bullets for unordered items. +- Consistent terminology; avoid ambiguity; define acronyms once. +- Include useful visuals when they clarify a concept. +- Wrap commands, file paths, and code identifiers in backticks. diff --git a/agents/authoring/AGENTS.cloud.md b/claude-plugins/inki/references/authoring/AGENTS.cloud.md similarity index 100% rename from agents/authoring/AGENTS.cloud.md rename to claude-plugins/inki/references/authoring/AGENTS.cloud.md diff --git a/agents/authoring/AGENTS.cms.api.md b/claude-plugins/inki/references/authoring/AGENTS.cms.api.md similarity index 94% rename from agents/authoring/AGENTS.cms.api.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.api.md index 3bedee9f04..f520cfdc09 100644 --- a/agents/authoring/AGENTS.cms.api.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.api.md @@ -14,8 +14,8 @@ Frontmatter (mandatory) - Optional: `displayed_sidebar`, `sidebar_label` as needed by navigation. Templates -- Start from `agents/templates/api-template.md` to align sections and example layout. -- See `agents/templates/INDEX.md` for a quick catalog of available templates with paths and purposes. +- Start from `claude-plugins/inki/references/templates/api-template.md` to align sections and example layout. +- See `claude-plugins/inki/references/templates/INDEX.md` for a quick catalog of available templates with paths and purposes. API Overview Pages (e.g., Content API) 1) H1 title — matches `title` frontmatter. diff --git a/agents/authoring/AGENTS.cms.breaking-changes.md b/claude-plugins/inki/references/authoring/AGENTS.cms.breaking-changes.md similarity index 98% rename from agents/authoring/AGENTS.cms.breaking-changes.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.breaking-changes.md index 5d87a60637..356d3ded59 100644 --- a/agents/authoring/AGENTS.cms.breaking-changes.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.breaking-changes.md @@ -164,7 +164,7 @@ Summary paragraph (1 sentence) ## Template -Start from `agents/templates/breaking-change-template.md` to get the correct skeleton with all required imports, components, and sections. +Start from `claude-plugins/inki/references/templates/breaking-change-template.md` to get the correct skeleton with all required imports, components, and sections. ## Quality checklist (before commit) diff --git a/agents/authoring/AGENTS.cms.configurations.md b/claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md similarity index 94% rename from agents/authoring/AGENTS.cms.configurations.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md index 528de1f5ba..4cc7456d95 100644 --- a/agents/authoring/AGENTS.cms.configurations.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md @@ -50,8 +50,8 @@ Heading Conventions - Use sentence case for all headings. Templates -- Start from `agents/templates/configuration-template.md` for frontmatter, H1/TL;DR placement, and building block examples. -- Quick overview of all templates (paths and purposes): `agents/templates/README.md`. +- Start from `claude-plugins/inki/references/templates/configuration-template.md` for frontmatter, H1/TL;DR placement, and building block examples. +- Quick overview of all templates (paths and purposes): `claude-plugins/inki/references/templates/README.md`. Quality Checklist (before commit) - TL;DR present and precise about file paths and scope. diff --git a/agents/authoring/AGENTS.cms.features.md b/claude-plugins/inki/references/authoring/AGENTS.cms.features.md similarity index 96% rename from agents/authoring/AGENTS.cms.features.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.features.md index 33b100d412..3e80ae579c 100644 --- a/agents/authoring/AGENTS.cms.features.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.features.md @@ -68,4 +68,4 @@ Quality Checklist (before commit) - Links and references to related features/APIs are included where helpful. Templates -- See `agents/templates/feature-template.md` for a ready‑to‑use skeleton aligned with these conventions. +- See `claude-plugins/inki/references/templates/feature-template.md` for a ready‑to‑use skeleton aligned with these conventions. diff --git a/agents/authoring/AGENTS.cms.guides.md b/claude-plugins/inki/references/authoring/AGENTS.cms.guides.md similarity index 95% rename from agents/authoring/AGENTS.cms.guides.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.guides.md index 17806393f8..600edb3c52 100644 --- a/agents/authoring/AGENTS.cms.guides.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.guides.md @@ -48,4 +48,4 @@ Tabs reminder - For install commands, use Tabs with `groupId="yarn-npm"` and values `yarn`/`npm` (labels `Yarn`/`NPM`). Templates -- Start from `agents/templates/guide-template.md` to ensure frontmatter, H1/TL;DR placement, and step structure are consistent. \ No newline at end of file +- Start from `claude-plugins/inki/references/templates/guide-template.md` to ensure frontmatter, H1/TL;DR placement, and step structure are consistent. \ No newline at end of file diff --git a/agents/authoring/AGENTS.cms.md b/claude-plugins/inki/references/authoring/AGENTS.cms.md similarity index 81% rename from agents/authoring/AGENTS.cms.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.md index 375fee824c..c2299cc5c3 100644 --- a/agents/authoring/AGENTS.cms.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.md @@ -14,8 +14,8 @@ Frontmatter and structure - Include a section at the top summarizing the page. Templates -- CMS authoring templates live in `agents/templates/` (guide, API, configuration, feature, migration, plugin). Start from a template to ensure structure and frontmatter are correct. -- For a quick overview of available templates (paths and purposes), see `agents/templates/INDEX.md`. +- CMS authoring templates live in `claude-plugins/inki/references/templates/` (guide, API, configuration, feature, migration, plugin). Start from a template to ensure structure and frontmatter are correct. +- For a quick overview of available templates (paths and purposes), see `claude-plugins/inki/references/templates/INDEX.md`. MDX and code blocks - Use MDX Tabs for language variants (JS/TS) under the same example. @@ -23,7 +23,7 @@ MDX and code blocks - Never place a code block, table, or other structured element immediately after a heading or another block without an introductory sentence. Every block must be preceded by a complete sentence (subject + verb) that tells the reader what the block contains or demonstrates. End the sentence with a colon when it directly introduces the block. Examples: "The function accepts the following parameters:", "The following example shows how to configure the server:". Annotations -- Use the `` component for inline glossary tooltips. See `agents/templates/components/annotation.md` for full rules, props, and canonical examples. +- Use the `` component for inline glossary tooltips. See `claude-plugins/inki/references/templates/components/annotation.md` for full rules, props, and canonical examples. Preflight checks before PR - `npm run generate:llms-code` (anchors + file checks by default) diff --git a/agents/authoring/AGENTS.cms.plugins.md b/claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md similarity index 96% rename from agents/authoring/AGENTS.cms.plugins.md rename to claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md index a05dd2efc9..62d9d2722e 100644 --- a/agents/authoring/AGENTS.cms.plugins.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md @@ -63,4 +63,4 @@ Quality Checklist (before commit) - Links to Marketplace and related docs included. Templates -- See `agents/templates/plugin-template.md` for a ready‑to‑use skeleton aligned with these conventions. +- See `claude-plugins/inki/references/templates/plugin-template.md` for a ready‑to‑use skeleton aligned with these conventions. diff --git a/agents/authoring/AGENTS.snippets.md b/claude-plugins/inki/references/authoring/AGENTS.snippets.md similarity index 97% rename from agents/authoring/AGENTS.snippets.md rename to claude-plugins/inki/references/authoring/AGENTS.snippets.md index 4a768e008e..ef9b38caa3 100644 --- a/agents/authoring/AGENTS.snippets.md +++ b/claude-plugins/inki/references/authoring/AGENTS.snippets.md @@ -41,4 +41,4 @@ Quality Checklist (before commit) Templates - When a snippet evolves into a full page, prefer starting from a suitable CMS template: -- For a compact overview of all templates with paths and purposes, see `agents/templates/INDEX.md`. +- For a compact overview of all templates with paths and purposes, see `claude-plugins/inki/references/templates/INDEX.md`. diff --git a/agents/authoring/README.md b/claude-plugins/inki/references/authoring/README.md similarity index 65% rename from agents/authoring/README.md rename to claude-plugins/inki/references/authoring/README.md index a697d70f3c..d30deb6e2f 100644 --- a/agents/authoring/README.md +++ b/claude-plugins/inki/references/authoring/README.md @@ -8,19 +8,19 @@ These guides are the reference that writers follow when creating or editing page 1) Identify which area of the docs the page belongs to (features, plugins, configurations, etc.). 2) Read the corresponding guide below for section order, required components, and area-specific conventions. -3) Use the matching template from `agents/templates/` as a starting point for new pages. +3) Use the matching template from `claude-plugins/inki/references/templates/` as a starting point for new pages. ## Catalog | Guide | Scope | Matching template | |-------|-------|-------------------| | `AGENTS.cms.md` | All CMS docs — shared rules, frontmatter, TL;DR, code blocks, Tabs | — (root rules, no template) | -| `AGENTS.cms.api.md` | API reference pages under `docusaurus/docs/cms/api/` | `agents/templates/api-template.md` | -| `AGENTS.cms.breaking-changes.md` | Breaking change pages under `docusaurus/docs/cms/migration/**/breaking-changes/` | `agents/templates/breaking-change-template.md` | -| `AGENTS.cms.configurations.md` | Configuration pages under `docusaurus/docs/cms/configurations/` | `agents/templates/configuration-template.md` | -| `AGENTS.cms.features.md` | Feature pages under `docusaurus/docs/cms/features/` | `agents/templates/feature-template.md` | -| `AGENTS.cms.guides.md` | How-to guides across CMS docs | `agents/templates/guide-template.md` | -| `AGENTS.cms.plugins.md` | Plugin pages under `docusaurus/docs/cms/plugins/` | `agents/templates/plugin-template.md` | +| `AGENTS.cms.api.md` | API reference pages under `docusaurus/docs/cms/api/` | `claude-plugins/inki/references/templates/api-template.md` | +| `AGENTS.cms.breaking-changes.md` | Breaking change pages under `docusaurus/docs/cms/migration/**/breaking-changes/` | `claude-plugins/inki/references/templates/breaking-change-template.md` | +| `AGENTS.cms.configurations.md` | Configuration pages under `docusaurus/docs/cms/configurations/` | `claude-plugins/inki/references/templates/configuration-template.md` | +| `AGENTS.cms.features.md` | Feature pages under `docusaurus/docs/cms/features/` | `claude-plugins/inki/references/templates/feature-template.md` | +| `AGENTS.cms.guides.md` | How-to guides across CMS docs | `claude-plugins/inki/references/templates/guide-template.md` | +| `AGENTS.cms.plugins.md` | Plugin pages under `docusaurus/docs/cms/plugins/` | `claude-plugins/inki/references/templates/plugin-template.md` | | `AGENTS.cloud.md` | Cloud documentation under `docusaurus/docs/cloud/` | — | | `AGENTS.snippets.md` | Shared snippets under `docusaurus/docs/snippets/` | — | @@ -35,5 +35,5 @@ When rules conflict, the most specific guide wins. ## References - Root agent guide: `AGENTS.md` -- Templates catalog: `agents/templates/README.md` -- Prompts catalog: `agents/prompts/README.md` \ No newline at end of file +- Templates catalog: `claude-plugins/inki/references/templates/README.md` +- Prompts catalog: `claude-plugins/inki/references/prompts/README.md` \ No newline at end of file diff --git a/claude-plugins/inki/references/git-rules.md b/claude-plugins/inki/references/git-rules.md new file mode 100644 index 0000000000..d719d98913 --- /dev/null +++ b/claude-plugins/inki/references/git-rules.md @@ -0,0 +1,116 @@ +# Git Rules and Conventions + +Scope +- Applies to everyone contributing to this repository (humans and agents). +- Complements AGENTS.md; this file is the detailed, canonical guide for Git usage. + +Commit Messages +- Start with an action verb in imperative mood (Add, Update, Fix, Document, Improve, Remove, Refactor, Rename). +- Keep ≤ 80 characters; be succinct about what/why. +- Do not prefix with "feat:", "chore:", "fix:", or similar tags. +- Do not use PR-style phrasing (never start with "This PR …"). +- Prefer specificity over vagueness (name the area/file/feature touched). + +Examples (good) +- Add initial AGENTS.md for repo and cms/cloud/snippets +- Update llms-code generator to add anchors by default +- Improve sidebar width stability to reduce layout shift +- Remove outdated Amplitude integration docs +- Fix typo in configuration section + +Anti‑examples (and why) +- fix: small changes — banned prefix; vague +- tweak stuff — vague; not actionable +- This PR updates docs — PR phrasing; non-specific +- Centralize guidance in AGENTS.md; add local 12 rules file — should have been 2 commits + +Pull Request Titles +- Start with either an action verb or a specific feature noun phrase. +- Optional bracket qualifier allowed first (e.g., [experimental]) but must be followed by a compliant title. +- Do not start with feat:/chore:/fix:, ticket IDs, emojis, or bracket tags as the core content. +- Keep it concise (aim ≤ 80 chars) and capitalize the first word. +- Place issue references at the end of the description body when needed: “… (#2143) (#2159)”. + +Acceptable openings (illustrative, not exhaustive) +- Action verbs (examples): Add, Update, Improve, Fix, Document, Rework, Clarify, Refactor, Remove, Allow, Introduce +- Specific feature noun phrases (examples): SSO configuration, Document Service API, Lifecycle functions, AI tools page +Note: These examples do not restrict titles. Any clear action verb or specific feature noun is acceptable. + +Examples (good) +- Checklist in SSO configuration documentation +- Document Service API intro rework: more details, updated structure +- Lifecycle functions: more details & examples of usage +- More details regarding image uploading +- [experimental] Allow setting a preferred AI toolbar default action +- Add AI tools page +- Add tip about nested page hierarchies in Content-type Builder documentation +- Add documentation about the strapi-plugin generate command +- Document auth fix for 5.24.0+ +- Add openapi.json route documentation (#2143) (#2159) + +Anti‑examples (and why) with suggested fixes +- Plugin documentation → too vague → Improve plugin documentation structure and navigation +- sugguest using npm for package manager → typo, capitalization → Suggest using npm as the package manager +- feat(upload): add documentation for new setting → banned prefix → Document new upload setting + +Branch and History Safety +- Never force‑push, rebase shared branches, or push to `main` without explicit maintainer consent. In case of ambiguity, whether the user or maintainer consent was explicit or implicit, NEVER do it and ask again for user confirmation. +- Never delete local or remote branches unless explicitly instructed by the maintainer. +- Get explicit consent before any history rewrite (rebase, squash, filter‑branch); propose the plan first. +- Prefer creating a new branch over rewriting history unless asked otherwise. +- When asked to stay low profile, do not open PRs; share progress in the chat only. + +Branch Naming +- Every branch must be prefixed based on the documentation area it touches: + - `/cms` — branch touches only files under `docs/cms/` and/or `static/` + - `/cloud` — branch touches only files under `docs/cloud/` and/or `static/` + - `/repo` — branch touches files outside those two areas, or across both +- Do NOT invent other prefixes (`/doc`, `/docs`, `/feat`, `/fix`, etc.). +- Format: `//` (e.g., `/cms/add-transfer-tokens-page`, `/cloud/fix-deployment-steps`, `/repo/update-sidebar-config`). +- If a branch touches both `docs/cms/` and `docs/cloud/`, use `/repo` or ask the user. +- User choice always supersedes auto-branch naming. + +Examples (good) +- /cms/add-transfer-tokens-page +- /cloud/update-deployment-guide +- /repo/fix-sidebar-layout-shift +- /repo/add-agents-md + +Anti-examples (and why) +- /doc/update-middlewares — `/doc` is not a valid prefix; use `/cms` +- /docs/new-feature — `/docs` is not a valid prefix; use `/cms` or `/cloud` +- /feat/add-page — `/feat` is not a valid prefix; use the area-based prefix +- update-middlewares — missing prefix entirely + +Pushing and PRs +- When pushing a new branch, set upstream: `git push -u origin ` (this does not create a PR). +- Open PRs only when explicitly requested and follow the title/description rules above. +- Titles must not start with feat:/chore:/fix:; use action verbs or clear feature nouns. +- PR descriptions must start with “This PR ...” and remain minimal; bullets allowed; no sections. +- No headings (##), no “Test plan” section, no checklists. Flat text only. +- Keep it short: 1-3 sentences or a short bullet list summarizing what changed and why. +- Issue references go at the end: “Fixes #2143”. + +PR Description Examples (good) +- This PR adds conditional retrieval rules to the Code Verifier and Coherence Checker agent prompts, and a new “separate facts from prose” behavioral note to the Drafter. +- This PR documents the new `hasPublishedVersion` parameter added in strapi/strapi#2847. + - Adds parameter to the findMany() parameters table + - Updates the filtering description + - Adds usage tip + +PR Description Anti-examples (and why) +- “## Summary\n\n## Test plan\n- [ ] Run tests” -- headings and test plan are not allowed +- “Updated docs” -- too vague; say what changed +- Empty description -- always include at least one sentence + +Optional Validation Hints +- Disallow prefixes: `^(?:feat|chore|fix)\s*:` +- Allow optional bracket qualifier: `^(?:\[[^\]]+\]\s*)?` +- Require initial capital: `^(?:\[[^\]]+\]\s*)?[A-Z]` +- Flag too-short or vague titles (e.g., ≤ 2 words, “update stuff”). + +Quick Checklist +- Commit messages: imperative, ≤ 80 chars, specific, no feat:/chore:/fix:. +- PR titles: verb or specific noun; concise; optional brackets OK; issues at end. +- Never rewrite or delete branches/history without explicit consent. +- No PRs unless explicitly requested. diff --git a/agents/prompts/README.md b/claude-plugins/inki/references/prompts/README.md similarity index 91% rename from agents/prompts/README.md rename to claude-plugins/inki/references/prompts/README.md index 43f3152b45..1c54d81cb6 100644 --- a/agents/prompts/README.md +++ b/claude-plugins/inki/references/prompts/README.md @@ -46,7 +46,7 @@ Router → Outline Generator → Drafter → Style Checker → Integrity Checker These prompts can be used in several ways: - **Claude Projects** — import the `.md` files as project knowledge. Use `claude-project-instructions.md` as the custom instructions (system prompt). -- **Claude Code** — the prompt files live in `agents/prompts/`. Claude Code reads them directly from disk. `AGENTS.md` at the repo root serves as an alternative entry point. +- **Claude Code** — the prompt files live in `claude-plugins/inki/references/prompts/`. Claude Code reads them directly from disk. `AGENTS.md` at the repo root serves as an alternative entry point. - **Cursor / Windsurf / IDE agents** — add prompt files to workspace context (e.g., `.cursor/rules/`, `@file` references, or equivalent). The agent must be able to read the full prompt spec before executing. - **ChatGPT / other LLMs** — upload prompt files to the conversation or copy the relevant prompt's content when needed. - **API integrations** — use as system prompts or tool definitions. For machine-only consumers, the Router can return only the YAML block. @@ -61,5 +61,5 @@ Regardless of platform, the agent must **read the full prompt file before execut - Entry point (system prompt): `claude-project-instructions.md` - Root agent guide: `AGENTS.md` -- Authoring area guides: `agents/authoring/AGENTS.*.md` -- Templates catalog: `agents/templates/README.md` \ No newline at end of file +- Authoring area guides: `claude-plugins/inki/references/authoring/AGENTS.*.md` +- Templates catalog: `claude-plugins/inki/references/templates/README.md` \ No newline at end of file diff --git a/agents/prompts/claude-project-instructions.md b/claude-plugins/inki/references/prompts/claude-project-instructions.md similarity index 96% rename from agents/prompts/claude-project-instructions.md rename to claude-plugins/inki/references/prompts/claude-project-instructions.md index 52962922b0..1c2f01f9f1 100644 --- a/agents/prompts/claude-project-instructions.md +++ b/claude-plugins/inki/references/prompts/claude-project-instructions.md @@ -287,10 +287,10 @@ When a prompt needs to run, search project knowledge for the file name (e.g., se ### Claude Code -The prompt files live in the repository at `agents/prompts/`. Claude Code can read them directly from disk: +The prompt files live in the repository at `claude-plugins/inki/references/prompts/`. Claude Code can read them directly from disk: ``` -cat agents/prompts/router.md +cat claude-plugins/inki/references/prompts/router.md ``` The `AGENTS.md` file at the repo root can serve as an alternative entry point, but this system prompt provides more detailed orchestration logic. @@ -299,7 +299,7 @@ The `AGENTS.md` file at the repo root can serve as an alternative entry point, b Add the prompt files to the workspace context. Depending on the IDE: -- **Cursor**: Reference prompt files with `@file` (e.g., `@agents/prompts/router.md`) or add them to `.cursor/rules/`. See [Cursor Rules Setup](#cursor-rules-setup) below. +- **Cursor**: Reference prompt files with `@file` (e.g., `@claude-plugins/inki/references/prompts/router.md`) or add them to `.cursor/rules/`. See [Cursor Rules Setup](#cursor-rules-setup) below. - **Windsurf**: Add to `.windsurfrules` or reference in workspace context. - **Other IDE agents**: Add the prompt files to whatever context/knowledge mechanism the IDE provides. @@ -493,8 +493,8 @@ The `shared/` folder contains guides used by multiple prompts: ## References - **12 Rules of Technical Writing:** https://github.com/strapi/documentation/blob/main/12-rules-of-technical-writing.md -- **Templates:** [`agents/templates/` in the repository](https://github.com/strapi/documentation/tree/main/agents/templates) -- **Authoring guides:** [`agents/authoring/AGENTS.*.md` in the repository](https://github.com/strapi/documentation/tree/main/agents/authoring) +- **Templates:** [`claude-plugins/inki/references/templates/` in the repository](https://github.com/strapi/documentation/tree/main/claude-plugins/inki/references/templates) +- **Authoring guides:** [`claude-plugins/inki/references/authoring/AGENTS.*.md` in the repository](https://github.com/strapi/documentation/tree/main/claude-plugins/inki/references/authoring) - **Root agent guide:** [`AGENTS.md` in the repository](https://github.com/strapi/documentation/blob/main/AGENTS.md) --- @@ -648,12 +648,12 @@ Detected: **[Type]** (from path `[path]`) | Path pattern | Type | Template | |-------------|------|----------| -| `cms/features/*` | Feature | `agents/templates/feature-template.md` | -| `cms/plugins/*` | Plugin | `agents/templates/plugin-template.md` | -| `cms/configurations/*` | Configuration | `agents/templates/configuration-template.md` | -| `cms/api/*` | API | `agents/templates/api-template.md` | -| `cms/migration/**/breaking-changes/*` | Breaking Change | `agents/templates/breaking-change-template.md` | -| `**/guides/*` or "How to..." | Guide | `agents/templates/guide-template.md` | +| `cms/features/*` | Feature | `claude-plugins/inki/references/templates/feature-template.md` | +| `cms/plugins/*` | Plugin | `claude-plugins/inki/references/templates/plugin-template.md` | +| `cms/configurations/*` | Configuration | `claude-plugins/inki/references/templates/configuration-template.md` | +| `cms/api/*` | API | `claude-plugins/inki/references/templates/api-template.md` | +| `cms/migration/**/breaking-changes/*` | Breaking Change | `claude-plugins/inki/references/templates/breaking-change-template.md` | +| `**/guides/*` or "How to..." | Guide | `claude-plugins/inki/references/templates/guide-template.md` | --- diff --git a/agents/prompts/drafter.md b/claude-plugins/inki/references/prompts/drafter.md similarity index 98% rename from agents/prompts/drafter.md rename to claude-plugins/inki/references/prompts/drafter.md index de878240cf..60a3a6c75a 100644 --- a/agents/prompts/drafter.md +++ b/claude-plugins/inki/references/prompts/drafter.md @@ -50,7 +50,7 @@ The Drafter operates in one of 3 modes, determined by the target's `priority` an **Mode selection rule:** If an outline is provided → Compose. If a `micro_instruction` is provided → Micro-edit. Otherwise (existing page + edits needed) → Patch. -See the interface specification (`agents/prompts/shared/drafter-interface.md`) for the full mode selection logic. +See the interface specification (`claude-plugins/inki/references/prompts/shared/drafter-interface.md`) for the full mode selection logic. --- @@ -60,8 +60,8 @@ See the interface specification (`agents/prompts/shared/drafter-interface.md`) f ```yaml doc_type: feature | plugin | configuration | guide | api | ... -template: agents/templates/feature-template.md # or null -guide: agents/authoring/AGENTS.cms.features.md # or null +template: claude-plugins/inki/references/templates/feature-template.md # or null +guide: claude-plugins/inki/references/authoring/AGENTS.cms.features.md # or null key_topics: [topic1, topic2] target: @@ -82,7 +82,7 @@ The outline contains: - `sections` — the heading tree with `intent`, `content_hints`, `source_refs`, and `components` per node - `drafter_notes` — free-text notes about gaps, ambiguities, and cross-links -See the interface specification (`agents/prompts/shared/drafter-interface.md`) for the full outline schema. +See the interface specification (`claude-plugins/inki/references/prompts/shared/drafter-interface.md`) for the full outline schema. #### Source material diff --git a/agents/prompts/integrity-checker.md b/claude-plugins/inki/references/prompts/integrity-checker.md similarity index 100% rename from agents/prompts/integrity-checker.md rename to claude-plugins/inki/references/prompts/integrity-checker.md diff --git a/agents/prompts/integrity-code-verifier.md b/claude-plugins/inki/references/prompts/integrity-code-verifier.md similarity index 98% rename from agents/prompts/integrity-code-verifier.md rename to claude-plugins/inki/references/prompts/integrity-code-verifier.md index 0ce5ad1a01..98f240a638 100644 --- a/agents/prompts/integrity-code-verifier.md +++ b/claude-plugins/inki/references/prompts/integrity-code-verifier.md @@ -18,7 +18,7 @@ For the confidence model, risk assessment, and annotation format, see the parent - **content**: Markdown/MDX content to verify (documentation page, draft, or PR diff) - **codebase_access**: Ability to search and fetch files from the Strapi codebase. Methods, in order of preference: - 1. Local filesystem access (fastest: `grep` and `cat` are near-instant). The codebase location varies by setup. Common paths: `strapi-codebase/` in the `strapi/strapi-docs-product-merger` repo, or a local clone of `strapi/strapi`. The agent should receive the path as input or detect it from context, never assume a hardcoded location. + 1. Local filesystem access (fastest: `grep` and `cat` are near-instant). The codebase location varies by setup. Common path: a local clone of `strapi/strapi`. The agent should receive the path as input or detect it from context, never assume a hardcoded location. 2. GitHub MCP tools (`github:get_file_contents`, `github:search_code`) 3. Raw GitHub fetch (`https://raw.githubusercontent.com/strapi/strapi/develop/[path]`) diff --git a/agents/prompts/integrity-coherence-checker.md b/claude-plugins/inki/references/prompts/integrity-coherence-checker.md similarity index 97% rename from agents/prompts/integrity-coherence-checker.md rename to claude-plugins/inki/references/prompts/integrity-coherence-checker.md index 59e1acf3c8..f98121c533 100644 --- a/agents/prompts/integrity-coherence-checker.md +++ b/claude-plugins/inki/references/prompts/integrity-coherence-checker.md @@ -19,7 +19,7 @@ For the confidence model, risk assessment, and annotation format, see the parent - **content**: Markdown/MDX content to verify (documentation page, draft, or PR diff) - **file_path**: Path of the documentation file being verified. Needed to resolve relative links and identify the page's position in the docs structure. - **docs_access**: Ability to fetch other documentation pages. Methods, in order of preference: - 1. Local filesystem access (fastest). The docs location varies by setup. Common paths: `main-documentation/` in the `strapi/strapi-docs-product-merger` repo, or a local clone of `strapi/documentation`. The agent should receive the path as input or detect it from context, never assume a hardcoded location. + 1. Local filesystem access (fastest). The docs location varies by setup. Common path: a local clone of `strapi/documentation`. The agent should receive the path as input or detect it from context, never assume a hardcoded location. 2. GitHub MCP tools (`github:get_file_contents` on `strapi/documentation` repo) 3. Raw GitHub fetch (`https://raw.githubusercontent.com/strapi/documentation/main/docusaurus/docs/[path]`) diff --git a/agents/prompts/integrity-known-pitfalls.md b/claude-plugins/inki/references/prompts/integrity-known-pitfalls.md similarity index 100% rename from agents/prompts/integrity-known-pitfalls.md rename to claude-plugins/inki/references/prompts/integrity-known-pitfalls.md diff --git a/agents/prompts/orchestrator.md b/claude-plugins/inki/references/prompts/orchestrator.md similarity index 100% rename from agents/prompts/orchestrator.md rename to claude-plugins/inki/references/prompts/orchestrator.md diff --git a/agents/prompts/outline-checker.md b/claude-plugins/inki/references/prompts/outline-checker.md similarity index 90% rename from agents/prompts/outline-checker.md rename to claude-plugins/inki/references/prompts/outline-checker.md index e5492fde33..d386b9997d 100644 --- a/agents/prompts/outline-checker.md +++ b/claude-plugins/inki/references/prompts/outline-checker.md @@ -52,12 +52,12 @@ The Outline Checker determines the document type using this priority: | Path pattern | Document type | Template path | |--------------|---------------|---------------| -| `cms/features/*` | Feature | `agents/templates/feature-template.md` | -| `cms/plugins/*` (not plugins-development) | Plugin | `agents/templates/plugin-template.md` | -| `cms/configurations/*` | Configuration | `agents/templates/configuration-template.md` | -| `cms/api/*` | API | `agents/templates/api-template.md` | -| `cms/migration/**/breaking-changes/*.md` | Breaking Change | `agents/templates/breaking-change-template.md` | -| `**/guides/*` or title starts with "How to" | Guide | `agents/templates/guide-template.md` | +| `cms/features/*` | Feature | `claude-plugins/inki/references/templates/feature-template.md` | +| `cms/plugins/*` (not plugins-development) | Plugin | `claude-plugins/inki/references/templates/plugin-template.md` | +| `cms/configurations/*` | Configuration | `claude-plugins/inki/references/templates/configuration-template.md` | +| `cms/api/*` | API | `claude-plugins/inki/references/templates/api-template.md` | +| `cms/migration/**/breaking-changes/*.md` | Breaking Change | `claude-plugins/inki/references/templates/breaking-change-template.md` | +| `**/guides/*` or title starts with "How to" | Guide | `claude-plugins/inki/references/templates/guide-template.md` | | No match | General | No specific template — apply general rules only | ### Outputs @@ -185,7 +185,7 @@ When required, `` must appear immediately after the H1. > **IMPORTANT — Single Source of Truth (SSOT)** > -> The templates in `agents/templates/` are the authoritative source for required sections, components, and structure. Before checking a page against its template, **READ the corresponding template file** to get the exact requirements. +> The templates in `claude-plugins/inki/references/templates/` are the authoritative source for required sections, components, and structure. Before checking a page against its template, **READ the corresponding template file** to get the exact requirements. > > The fallback information below is provided only for cases where templates cannot be accessed. Always prefer the template file. @@ -193,7 +193,7 @@ When required, `` must appear immediately after the H1. #### Feature Pages (`cms/features/*`) -**Template (SSOT):** `agents/templates/feature-template.md` +**Template (SSOT):** `claude-plugins/inki/references/templates/feature-template.md` **Fallback — Key components:** - `` — Required, immediately after H1 @@ -205,7 +205,7 @@ When required, `` must appear immediately after the H1. #### Plugin Pages (`cms/plugins/*`) -**Template (SSOT):** `agents/templates/plugin-template.md` +**Template (SSOT):** `claude-plugins/inki/references/templates/plugin-template.md` **Fallback — Key components:** - `` — Required @@ -217,7 +217,7 @@ When required, `` must appear immediately after the H1. #### Guide Pages (`**/guides/*` or "How to..." titles) -**Template (SSOT):** `agents/templates/guide-template.md` +**Template (SSOT):** `claude-plugins/inki/references/templates/guide-template.md` **Fallback — Key components:** - `` — Required @@ -230,7 +230,7 @@ When required, `` must appear immediately after the H1. #### Configuration Pages (`cms/configurations/*`) -**Template (SSOT):** `agents/templates/configuration-template.md` +**Template (SSOT):** `claude-plugins/inki/references/templates/configuration-template.md` **Fallback — Key components:** - `` — Required @@ -241,7 +241,7 @@ When required, `` must appear immediately after the H1. #### API Pages (`cms/api/*`) -**Template (SSOT):** `agents/templates/api-template.md` +**Template (SSOT):** `claude-plugins/inki/references/templates/api-template.md` **Fallback — Key components:** - `` — Required @@ -252,7 +252,7 @@ When required, `` must appear immediately after the H1. #### Breaking Change Pages (`cms/migration/**/breaking-changes/*.md`) -**Template (SSOT):** `agents/templates/breaking-change-template.md` +**Template (SSOT):** `claude-plugins/inki/references/templates/breaking-change-template.md` **Fallback — Key components:** - `import Intro from '/docs/snippets/breaking-change-page-intro.md'` — Required diff --git a/agents/prompts/outline-generator.md b/claude-plugins/inki/references/prompts/outline-generator.md similarity index 90% rename from agents/prompts/outline-generator.md rename to claude-plugins/inki/references/prompts/outline-generator.md index 0596e5d032..0b597bff74 100644 --- a/agents/prompts/outline-generator.md +++ b/claude-plugins/inki/references/prompts/outline-generator.md @@ -42,8 +42,8 @@ The machine-readable YAML from the Router, containing: ```yaml doc_type: feature | plugin | configuration | guide | api | breaking-change -template: agents/templates/feature-template.md # or null -guide: agents/authoring/AGENTS.cms.features.md # or null +template: claude-plugins/inki/references/templates/feature-template.md # or null +guide: claude-plugins/inki/references/authoring/AGENTS.cms.features.md # or null key_topics: [topic1, topic2, topic3] targets: @@ -69,7 +69,7 @@ The raw input that describes what needs to be documented: **Not required when:** `action: create_page` — the page doesn't exist yet. -**How to obtain it:** Use GitHub MCP tools to fetch the file from the repository (see `agents/prompts/shared/github-mcp-usage.md`). +**How to obtain it:** Use GitHub MCP tools to fetch the file from the repository (see `claude-plugins/inki/references/prompts/shared/github-mcp-usage.md`). --- @@ -89,8 +89,8 @@ If the Router output contains multiple `primary` targets (rare), generate a sepa **Before analyzing source material**, read the template and authoring guide specified in the Router output: -1. **Read the template file** (e.g., `agents/templates/feature-template.md`). This is the Single Source of Truth (SSOT) for required sections, components, and structure. -2. **Read the authoring guide** (e.g., `agents/authoring/AGENTS.cms.features.md`). This provides additional conventions, heading rules, and quality expectations. +1. **Read the template file** (e.g., `claude-plugins/inki/references/templates/feature-template.md`). This is the Single Source of Truth (SSOT) for required sections, components, and structure. +2. **Read the authoring guide** (e.g., `claude-plugins/inki/references/authoring/AGENTS.cms.features.md`). This provides additional conventions, heading rules, and quality expectations. If both `template` and `guide` are null (rare), fall back to the type-specific heuristics in the "Document type handling" section below plus the 12 Rules of Technical Writing. @@ -145,8 +145,8 @@ Generate the structured YAML outline following the output format defined below. ### Feature (`doc_type: feature`) -**Template:** `agents/templates/feature-template.md` -**Guide:** `agents/authoring/AGENTS.cms.features.md` +**Template:** `claude-plugins/inki/references/templates/feature-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.features.md` **Skeleton:** H1 → `` → Intro → `` → `## Configuration` → `## Usage` @@ -158,8 +158,8 @@ Generate the structured YAML outline following the output format defined below. ### Plugin (`doc_type: plugin`) -**Template:** `agents/templates/plugin-template.md` -**Guide:** `agents/authoring/AGENTS.cms.plugins.md` +**Template:** `claude-plugins/inki/references/templates/plugin-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md` **Skeleton:** H1 → `` → `` → `## Installation` → `## Configuration` → `## Usage` @@ -176,8 +176,8 @@ Generate the structured YAML outline following the output format defined below. ### Configuration (`doc_type: configuration`) -**Template:** `agents/templates/configuration-template.md` -**Guide:** `agents/authoring/AGENTS.cms.configurations.md` +**Template:** `claude-plugins/inki/references/templates/configuration-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md` **Common core:** H1 → `` → `:::caution` (if applicable) → Intro paragraph (names file paths) @@ -192,8 +192,8 @@ Generate the structured YAML outline following the output format defined below. ### Guide (`doc_type: guide`) -**Template:** `agents/templates/guide-template.md` -**Guide:** `agents/authoring/AGENTS.cms.guides.md` +**Template:** `claude-plugins/inki/references/templates/guide-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.guides.md` **Skeleton:** H1 → `` → Intro → `:::prerequisites` → Steps → `## Troubleshooting` (optional) @@ -206,8 +206,8 @@ Generate the structured YAML outline following the output format defined below. ### API (`doc_type: api`) -**Template:** `agents/templates/api-template.md` -**Guide:** `agents/authoring/AGENTS.cms.api.md` +**Template:** `claude-plugins/inki/references/templates/api-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.api.md` API pages have **3 sub-types**. Determine from source material: @@ -238,8 +238,8 @@ Each endpoint H2 has H3s: Path/query parameters, Request body, Responses, Exampl ### Breaking Change (`doc_type: breaking-change`) -**Template:** `agents/templates/breaking-change-template.md` -**Guide:** `agents/authoring/AGENTS.cms.breaking-changes.md` +**Template:** `claude-plugins/inki/references/templates/breaking-change-template.md` +**Guide:** `claude-plugins/inki/references/authoring/AGENTS.cms.breaking-changes.md` **Skeleton:** imports → H1 → Summary → `` → `` → `## Breaking change description` → `## Migration` diff --git a/agents/prompts/outline-ux-analyzer.md b/claude-plugins/inki/references/prompts/outline-ux-analyzer.md similarity index 100% rename from agents/prompts/outline-ux-analyzer.md rename to claude-plugins/inki/references/prompts/outline-ux-analyzer.md diff --git a/agents/prompts/outliner.md b/claude-plugins/inki/references/prompts/outliner.md similarity index 100% rename from agents/prompts/outliner.md rename to claude-plugins/inki/references/prompts/outliner.md diff --git a/agents/prompts/router.md b/claude-plugins/inki/references/prompts/router.md similarity index 95% rename from agents/prompts/router.md rename to claude-plugins/inki/references/prompts/router.md index 8ad9c3910b..f7650bef33 100644 --- a/agents/prompts/router.md +++ b/claude-plugins/inki/references/prompts/router.md @@ -30,7 +30,7 @@ The Router cannot make reliable placement decisions without these files. If neit When the user provides a GitHub PR as source material, use the GitHub MCP tools to fetch the PR content directly. -👉 **See [GitHub MCP Usage Guide](agents/prompts/shared/github-mcp-usage.md)** for the full workflow. +👉 **See [GitHub MCP Usage Guide](claude-plugins/inki/references/prompts/shared/github-mcp-usage.md)** for the full workflow. **Quick reference:** 1. `github:get_pull_request(owner, repo, pull_number)` → PR title, description @@ -68,7 +68,7 @@ A structured Markdown report containing: | Page | What to do | |------|------------| -| `path/to/new-page.md` | **Create** new page — follow [Feature template](https://github.com/strapi/documentation/blob/main/agents/templates/feature-template.md) + [Features authoring guide](https://github.com/strapi/documentation/blob/main/agents/authoring/AGENTS.cms.features.md) | +| `path/to/new-page.md` | **Create** new page — follow [Feature template](https://github.com/strapi/documentation/blob/main/claude-plugins/inki/references/templates/feature-template.md) + [Features authoring guide](https://github.com/strapi/documentation/blob/main/claude-plugins/inki/references/authoring/AGENTS.cms.features.md) | | `path/to/existing.md` | **Update** — add [description] to "[Section name]" section | | `path/to/other.md` | **Update** — add row to "[Table name]" table | | `path/to/conditional.md` | **Later** — [condition, e.g., "when X feature ships"] | @@ -304,12 +304,12 @@ Set `ask_user` (as a top-level YAML field or as the placement decision) when: | Type | Path patterns | Template | Authoring guide | |------|--------------|----------|-----------------| -| **Feature** | `cms/features/*` | `agents/templates/feature-template.md` | `agents/cms/features/AGENTS.md` | -| **Plugin** | `cms/plugins/*` (not `plugins-development`) | `agents/templates/plugin-template.md` | `agents/cms/plugins/AGENTS.md` | -| **Configuration** | `cms/configurations/*` | `agents/templates/configuration-template.md` | `agents/cms/configurations/AGENTS.md` | -| **Guide** | `**/guides/*` or task-oriented "How to…" | `agents/templates/guide-template.md` | `agents/cms/AGENTS.guides.md` | -| **API** | `cms/api/*` | `agents/templates/api-template.md` | `agents/cms/api/AGENTS.md` | -| **Breaking Change** | `cms/migration/**/breaking-changes/*.md` | `agents/templates/breaking-change-template.md` | `agents/cms/migration/AGENTS.md` | +| **Feature** | `cms/features/*` | `claude-plugins/inki/references/templates/feature-template.md` | `agents/cms/features/AGENTS.md` | +| **Plugin** | `cms/plugins/*` (not `plugins-development`) | `claude-plugins/inki/references/templates/plugin-template.md` | `agents/cms/plugins/AGENTS.md` | +| **Configuration** | `cms/configurations/*` | `claude-plugins/inki/references/templates/configuration-template.md` | `agents/cms/configurations/AGENTS.md` | +| **Guide** | `**/guides/*` or task-oriented "How to…" | `claude-plugins/inki/references/templates/guide-template.md` | `agents/cms/AGENTS.guides.md` | +| **API** | `cms/api/*` | `claude-plugins/inki/references/templates/api-template.md` | `agents/cms/api/AGENTS.md` | +| **Breaking Change** | `cms/migration/**/breaking-changes/*.md` | `claude-plugins/inki/references/templates/breaking-change-template.md` | `agents/cms/migration/AGENTS.md` | | **Concept** | Introductions, overviews, conceptual pages | None | `agents/cms/AGENTS.concepts.md` | | **Cloud** | `cloud/*` | None | `agents/cloud/AGENTS.md` | | **Snippet** | `snippets/*` | None | `agents/snippets/AGENTS.md` | @@ -402,7 +402,7 @@ For **each target** in the routing: 1. **Determine document type** from the target's path (see Document Types table) 2. **Locate the template** (if one exists for this type) 3. **Locate the authoring guide** (if one exists for this type) -4. If no template or guide exists for a target, note that the [12 Rules of Technical Writing](https://strapi.notion.site/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04) and the [Style Checker](https://github.com/strapi/documentation/blob/main/agents/prompts/style-checker.md) are the minimum standards. +4. If no template or guide exists for a target, note that the [12 Rules of Technical Writing](https://strapi.notion.site/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04) and the [Style Checker](https://github.com/strapi/documentation/blob/main/claude-plugins/inki/references/prompts/style-checker.md) are the minimum standards. **Important:** Each target may have a different document type. For example, a routing with both `cms/features/mcp-server.md` and `cms/configurations/server.md` requires: - Feature template + Features authoring guide for the feature page @@ -430,7 +430,7 @@ The "Existing pages found" table must show the correct template and authoring gu 8. **Respect existing architecture.** Prefer fitting content into the existing structure over creating new categories. `create_category` should be rare and always confirmed with the user. -9. **Use GitHub MCP when available.** When the source is a GitHub PR, use the GitHub MCP tools to fetch the PR content directly rather than asking the user to paste it. See [GitHub MCP Usage Guide](agents/prompts/shared/github-mcp-usage.md). +9. **Use GitHub MCP when available.** When the source is a GitHub PR, use the GitHub MCP tools to fetch the PR content directly rather than asking the user to paste it. See [GitHub MCP Usage Guide](claude-plugins/inki/references/prompts/shared/github-mcp-usage.md). 10. **Stay in scope.** The Router decides *where* content goes. It does NOT: - Extract detailed specifications from the source material (→ Outline Generator) @@ -636,7 +636,7 @@ targets: **Source:** User says "Route PR #1542 from strapi/documentation" -**Expected workflow:** See [GitHub MCP Usage Guide](agents/prompts/shared/github-mcp-usage.md) +**Expected workflow:** See [GitHub MCP Usage Guide](claude-plugins/inki/references/prompts/shared/github-mcp-usage.md) 1. Fetch PR metadata → Title: "Add MCP Server documentation" 2. Fetch changed files → `docs/cms/features/mcp-server.md` (added), `docs/cms/configurations/server.md` (modified) diff --git a/agents/prompts/shared/drafter-interface.md b/claude-plugins/inki/references/prompts/shared/drafter-interface.md similarity index 99% rename from agents/prompts/shared/drafter-interface.md rename to claude-plugins/inki/references/prompts/shared/drafter-interface.md index 3a00694d9a..e962a4c0d0 100644 --- a/agents/prompts/shared/drafter-interface.md +++ b/claude-plugins/inki/references/prompts/shared/drafter-interface.md @@ -28,7 +28,7 @@ These fields are always present, regardless of mode: ```yaml # From the Router doc_type: feature | plugin | configuration | guide | api | ... -template: agents/templates/feature-template.md # or null +template: claude-plugins/inki/references/templates/feature-template.md # or null guide: agents/cms/features/AGENTS.md # or null key_topics: [topic1, topic2] diff --git a/agents/prompts/shared/github-mcp-usage.md b/claude-plugins/inki/references/prompts/shared/github-mcp-usage.md similarity index 100% rename from agents/prompts/shared/github-mcp-usage.md rename to claude-plugins/inki/references/prompts/shared/github-mcp-usage.md diff --git a/agents/prompts/style-checker.md b/claude-plugins/inki/references/prompts/style-checker.md similarity index 100% rename from agents/prompts/style-checker.md rename to claude-plugins/inki/references/prompts/style-checker.md diff --git a/agents/templates/README.md b/claude-plugins/inki/references/templates/README.md similarity index 72% rename from agents/templates/README.md rename to claude-plugins/inki/references/templates/README.md index 4503e08a67..ee4f17fce9 100644 --- a/agents/templates/README.md +++ b/claude-plugins/inki/references/templates/README.md @@ -19,11 +19,11 @@ How to use | Template | Target path | Purpose | Authoring guide | |----------|-------------|---------|-----------------| -| `feature-template.md` | `docusaurus/docs/cms/features/` | Feature pages: TL;DR, intro, identity card, configuration, usage | `agents/authoring/AGENTS.cms.features.md` | -| `plugin-template.md` | `docusaurus/docs/cms/plugins/` | Plugin pages: identity details, install steps, configuration (admin UI and code), usage tasks | `agents/authoring/AGENTS.cms.plugins.md` | -| `configuration-template.md` | `docusaurus/docs/cms/configurations/` | Configuration pages: file location, available options, env variables, per‑environment overrides | `agents/authoring/AGENTS.cms.configurations.md` | -| `guide-template.md` | `docusaurus/docs/cms/` (varies) | How‑to guides: prerequisites, numbered steps, validation, troubleshooting | `agents/authoring/AGENTS.cms.guides.md` | -| `api-template.md` | `docusaurus/docs/cms/api/` | API reference pages: endpoints, auth, parameters, example requests/responses | `agents/authoring/AGENTS.cms.api.md` | +| `feature-template.md` | `docusaurus/docs/cms/features/` | Feature pages: TL;DR, intro, identity card, configuration, usage | `claude-plugins/inki/references/authoring/AGENTS.cms.features.md` | +| `plugin-template.md` | `docusaurus/docs/cms/plugins/` | Plugin pages: identity details, install steps, configuration (admin UI and code), usage tasks | `claude-plugins/inki/references/authoring/AGENTS.cms.plugins.md` | +| `configuration-template.md` | `docusaurus/docs/cms/configurations/` | Configuration pages: file location, available options, env variables, per‑environment overrides | `claude-plugins/inki/references/authoring/AGENTS.cms.configurations.md` | +| `guide-template.md` | `docusaurus/docs/cms/` (varies) | How‑to guides: prerequisites, numbered steps, validation, troubleshooting | `claude-plugins/inki/references/authoring/AGENTS.cms.guides.md` | +| `api-template.md` | `docusaurus/docs/cms/api/` | API reference pages: endpoints, auth, parameters, example requests/responses | `claude-plugins/inki/references/authoring/AGENTS.cms.api.md` | | `breaking-change-template.md` | `docusaurus/docs/cms/migration/**/breaking-changes/` | Breaking‑change pages: BreakingChangeIdCard, v4/v5 comparison, migration notes | — | ## What every template provides @@ -33,13 +33,13 @@ How to use - **`` component** at the top for the page summary. - **Standard section headings** in the expected order for that page type. - **Placeholder comments** (``) explaining what content to write in each section. -- **Multi‑language patterns** using Tabs where applicable (see `agents/templates/components/tabs.md` for Tabs/TabItem rules). -- **Progressive disclosure** using ExpandableContent where applicable (see `agents/templates/components/expandable-content.md` for usage rules). +- **Multi‑language patterns** using Tabs where applicable (see `claude-plugins/inki/references/templates/components/tabs.md` for Tabs/TabItem rules). +- **Progressive disclosure** using ExpandableContent where applicable (see `claude-plugins/inki/references/templates/components/expandable-content.md` for usage rules). ## References - Root agent guide: `AGENTS.md` -- Authoring area guides: `agents/authoring/AGENTS.*.md` -- Tabs/TabItem rules: `agents/templates/components/tabs.md` -- ExpandableContent rules: `agents/templates/components/expandable-content.md` -- Annotation rules: `agents/templates/components/annotation.md` \ No newline at end of file +- Authoring area guides: `claude-plugins/inki/references/authoring/AGENTS.*.md` +- Tabs/TabItem rules: `claude-plugins/inki/references/templates/components/tabs.md` +- ExpandableContent rules: `claude-plugins/inki/references/templates/components/expandable-content.md` +- Annotation rules: `claude-plugins/inki/references/templates/components/annotation.md` \ No newline at end of file diff --git a/agents/templates/api-template.md b/claude-plugins/inki/references/templates/api-template.md similarity index 100% rename from agents/templates/api-template.md rename to claude-plugins/inki/references/templates/api-template.md diff --git a/agents/templates/breaking-change-template.md b/claude-plugins/inki/references/templates/breaking-change-template.md similarity index 100% rename from agents/templates/breaking-change-template.md rename to claude-plugins/inki/references/templates/breaking-change-template.md diff --git a/agents/templates/components/annotation.md b/claude-plugins/inki/references/templates/components/annotation.md similarity index 100% rename from agents/templates/components/annotation.md rename to claude-plugins/inki/references/templates/components/annotation.md diff --git a/agents/templates/components/expandable-content.md b/claude-plugins/inki/references/templates/components/expandable-content.md similarity index 100% rename from agents/templates/components/expandable-content.md rename to claude-plugins/inki/references/templates/components/expandable-content.md diff --git a/agents/templates/components/tabs.md b/claude-plugins/inki/references/templates/components/tabs.md similarity index 100% rename from agents/templates/components/tabs.md rename to claude-plugins/inki/references/templates/components/tabs.md diff --git a/agents/templates/configuration-template.md b/claude-plugins/inki/references/templates/configuration-template.md similarity index 100% rename from agents/templates/configuration-template.md rename to claude-plugins/inki/references/templates/configuration-template.md diff --git a/agents/templates/feature-template.md b/claude-plugins/inki/references/templates/feature-template.md similarity index 100% rename from agents/templates/feature-template.md rename to claude-plugins/inki/references/templates/feature-template.md diff --git a/agents/templates/guide-template.md b/claude-plugins/inki/references/templates/guide-template.md similarity index 100% rename from agents/templates/guide-template.md rename to claude-plugins/inki/references/templates/guide-template.md diff --git a/agents/templates/plugin-template.md b/claude-plugins/inki/references/templates/plugin-template.md similarity index 100% rename from agents/templates/plugin-template.md rename to claude-plugins/inki/references/templates/plugin-template.md diff --git a/claude-plugins/inki/scripts/style-lint.sh b/claude-plugins/inki/scripts/style-lint.sh new file mode 100755 index 0000000000..1e2a192054 --- /dev/null +++ b/claude-plugins/inki/scripts/style-lint.sh @@ -0,0 +1,319 @@ +#!/usr/bin/env bash +# style-lint.sh -- Deterministic style linting for Strapi documentation +# Checks Markdown/MDX files against regex-based rules from the 12 Rules of Technical Writing. +# Outputs: ::: +# Exit codes: 0 = clean, 1 = errors found, 2 = warnings only (no errors) +# +# macOS-compatible: uses grep -E (no PCRE dependency). + +set -euo pipefail + +# Known acronyms that are allowed in ALL CAPS +KNOWN_ACRONYMS="API|CLI|CSS|HTML|JS|JSON|NPM|REST|SDK|SQL|UI|URL|UUID|HTTP|HTTPS|CMS|SSO|RBAC|JWT|CORS|DNS|FTP|SSH|CDN|SEO|RSS|SMTP|IMAP|POP3|LDAP|SAML|OIDC|OAuth|CRUD|ORM|MVC|SPA|SSR|CSR|PWA|DOM|YAML|TOML|XML|CSV|TSV|AWS|GCP|IAM|EC2|S3|RDS|ECS|EKS|VPC|MDX|JSX|TSX|GDPR|SSG|ISR|TLS|SSL|TCP|UDP|IDE|VSC|EOF|USA|FAQ|PDF|PNG|JPG|GIF|SVG|RGB|HEX|HSL|ISO|UTC|GMT" + +# Literal em dash character for matching (UTF-8) +EM_DASH=$'\xe2\x80\x94' + +usage() { + echo "Usage: $0 [file2.md ...]" >&2 + echo " Runs deterministic style checks on Markdown/MDX files." >&2 + echo " Exit codes: 0 = clean, 1 = errors found, 2 = warnings only" >&2 + exit 1 +} + +if [[ $# -eq 0 ]]; then + usage +fi + +has_errors=0 +has_warnings=0 + +# --- Preprocessing: strip code blocks, HTML comments, and inline code --- +# Returns a version of the file where excluded content is replaced with blank +# lines (preserving line numbers) or spaces (for inline code). + +strip_excluded_content() { + local file="$1" + awk ' + BEGIN { in_code_block = 0; in_html_comment = 0 } + + # Toggle code blocks (``` fences) + /^[[:space:]]*```/ { + if (in_code_block) { + in_code_block = 0 + print "" + next + } else { + in_code_block = 1 + print "" + next + } + } + + in_code_block { + print "" + next + } + + # Handle multi-line HTML comments + { + line = $0 + + # Remove complete single-line HTML comments + while (match(line, //)) { + before = substr(line, 1, RSTART - 1) + after = substr(line, RSTART + RLENGTH) + replacement = "" + for (i = 0; i < RLENGTH; i++) replacement = replacement " " + line = before replacement after + } + + # Start of multi-line HTML comment + if (!in_html_comment && match(line, //)) { + in_html_comment = 0 + after = substr(line, RSTART + RLENGTH) + before = "" + for (i = 0; i < RSTART + RLENGTH - 1; i++) before = before " " + line = before after + } else { + print "" + next + } + } + + # Remove inline code (backtick-wrapped content) + while (match(line, /`[^`]+`/)) { + before = substr(line, 1, RSTART - 1) + after = substr(line, RSTART + RLENGTH) + replacement = "" + for (i = 0; i < RLENGTH; i++) replacement = replacement " " + line = before replacement after + } + + print line + } + ' "$file" +} + +# Helper: case-insensitive word match using grep -Ei with word boundaries +# macOS grep -E does not support \b, so we use [[:<:]] and [[:>:]] on macOS +# and \b on Linux. +word_boundary_start='[[:<:]]' +word_boundary_end='[[:>:]]' +if grep -E '\b' /dev/null 2>/dev/null; then + word_boundary_start='\b' + word_boundary_end='\b' +fi + +lint_file() { + local file="$1" + + if [[ ! -f "$file" ]]; then + echo "error:0:file-not-found:File not found: $file" >&2 + has_errors=1 + return + fi + + # Get stripped content (code blocks, comments, inline code removed) + local stripped + stripped=$(strip_excluded_content "$file") + + local line_num=0 + local in_frontmatter=0 + local frontmatter_started=0 + + while IFS= read -r line; do + line_num=$((line_num + 1)) + + # Handle frontmatter (YAML between --- delimiters at start of file) + if [[ $line_num -eq 1 && "$line" == "---" ]]; then + in_frontmatter=1 + frontmatter_started=1 + continue + fi + if [[ $in_frontmatter -eq 1 ]]; then + if [[ "$line" == "---" ]]; then + in_frontmatter=0 + fi + continue + fi + + # Skip empty lines + [[ -z "$line" ]] && continue + + # Skip import statements and JSX component-only lines + if echo "$line" | grep -qE '^import[[:space:]]'; then + continue + fi + if echo "$line" | grep -qE '^<[A-Z]'; then + continue + fi + + # ===================== + # ERROR-LEVEL CHECKS + # ===================== + + # Em dashes in prose (not in URLs) + if echo "$line" | grep -q "${EM_DASH}"; then + # Check it is not inside a URL + local is_url=0 + if echo "$line" | grep -qE "https?://[^[:space:]]*${EM_DASH}"; then + is_url=1 + fi + if [[ $is_url -eq 0 ]]; then + echo "error:${line_num}:em-dash:Em dash found -- replace with colon, period, or restructure" + has_errors=1 + fi + fi + + # Double hyphens used as dashes in prose (not in frontmatter or HTML comments) + if echo "$line" | grep -qE " -- "; then + # Exclude frontmatter separators (---) and HTML comments ( main +Commits: +Files changed: + +Title: + +Description: + + +Command: gh pr create --title "..." --body "..." +``` + +Wait for the user's approval. If the user edits title or description, re-validate. + +## Create PR + +```bash +gh pr create --title "" --body "$(cat <<'EOF' +<description> +EOF +)" +``` + +After creation, show the PR URL. + +## Do not + +- Do not open a PR from `main` as the source branch (a PR requires a feature branch; `main` is the merge target, never the source) +- Do not use feat:/chore:/fix: in the title +- Do not start the description with anything other than "This PR ..." +- Do not create a PR without showing the plan first +- Do not force-push or rewrite history diff --git a/claude-plugins/inki/skills/_shared/pr-title-rules.md b/claude-plugins/inki/skills/_shared/pr-title-rules.md new file mode 100644 index 0000000000..b01c70d798 --- /dev/null +++ b/claude-plugins/inki/skills/_shared/pr-title-rules.md @@ -0,0 +1,27 @@ +# Shared PR Title Rules + +These rules apply to every PR title created on strapi/documentation. + +## Generate or rewrite a PR title + +1. Start with an action verb (Add, Update, Fix, Document, Improve, Remove, Refactor, Rename, Clarify, Rework, Introduce, Allow) OR a specific feature noun phrase. +2. Optional bracket qualifier first (e.g., `[experimental]`). +3. No `feat:`, `chore:`, `fix:` prefix. +4. No ticket IDs or emojis as the core content. +5. Capitalize the first word. +6. Keep it at most 80 characters. +7. Be specific — name the area, page, or feature. + +## Good titles (illustrative) + +- `Checklist in SSO configuration documentation` +- `Document Service API intro rework: more details, updated structure` +- `Add tip about nested page hierarchies in Content-type Builder documentation` +- `Document auth fix for 5.24.0+` +- `[experimental] Allow setting a preferred AI toolbar default action` + +## Anti-titles (and how to fix them) + +- `Plugin documentation` → too vague → `Improve plugin documentation structure and navigation` +- `feat(upload): add documentation for new setting` → banned prefix → `Document new upload setting` +- `Update stuff` → too vague and lowercase → name what was updated and capitalize diff --git a/claude-plugins/inki/skills/_shared/push-rules.md b/claude-plugins/inki/skills/_shared/push-rules.md new file mode 100644 index 0000000000..225c31da52 --- /dev/null +++ b/claude-plugins/inki/skills/_shared/push-rules.md @@ -0,0 +1,92 @@ +# Shared Push Rules + +These rules apply to all pushes made on strapi/documentation. + +## Gather branch state + +Run in parallel: + +```bash +git branch --show-current +``` + +```bash +git rev-parse --show-toplevel +``` + +```bash +git status --short +``` + +```bash +git log --oneline -5 +``` + +```bash +git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "NO_UPSTREAM" +``` + +## Safety checks + +**If on `main` (or `master`, `develop`, `next`):** refuse immediately. + +> You are on `main`. Pushing directly to main is not allowed without explicit maintainer consent. + +Stop here. Do not proceed. + +**If on a feature branch:** Continue. + +## Check upstream status + +**If upstream exists:** + +```bash +git log @{upstream}..HEAD --oneline +``` + +Show commits that will be pushed. + +**If no upstream:** + +Show all commits since divergence from the default branch: + +```bash +git log main..HEAD --oneline 2>/dev/null || git log master..HEAD --oneline 2>/dev/null || git log --oneline -10 +``` + +## Show push plan for approval + +Present to the user: + +``` +Repo: <repo-name> +Branch: <branch-name> +Upstream: <upstream or "none (will create)"> +Commits to push: + - <commit1> + - <commit2> + ... + +Command: git push -u origin <branch-name> +``` + +Wait for the user's approval before pushing. + +**Exception:** If the user said "commit and push" (or similar) in the current session, the push is pre-approved. Skip the confirmation and execute directly. + +## Execute push + +```bash +git push -u origin <branch-name> +``` + +Always use `-u` to set upstream tracking. NEVER use `--force` or `--force-with-lease`. + +Report success or failure. + +## Do not + +- Do not push to `main`/`master`/`develop` without double confirmation from the user +- Do not force-push under any circumstances +- Do not push without showing the plan first, unless explicitly instructed so by the user for the current session +- Do not delete any branches diff --git a/claude-plugins/inki/skills/branch/SKILL.md b/claude-plugins/inki/skills/branch/SKILL.md new file mode 100644 index 0000000000..d78af01345 --- /dev/null +++ b/claude-plugins/inki/skills/branch/SKILL.md @@ -0,0 +1,40 @@ +--- +name: branch +description: "Create a new branch in strapi/documentation with auto-detected prefix (cms/, cloud/, repo/) based on the files that will be touched." +argument-hint: [description of the work] +user-invocable: true +--- + +# Documentation Branch + +**Scope:** designed for strapi/documentation (and its forks). + +## Input + +`$ARGUMENTS`: description of the work (e.g., "add MCP server page", "fix deployment steps for cloud"). + +If no arguments provided, ask what the branch is for. + +## Step 1: Detect prefix + +Ask which area the work will touch, or infer from the description: + +- Work only under `docs/cms/` and/or `static/` --> `cms/` +- Work only under `docs/cloud/` and/or `static/` --> `cloud/` +- Work touching both areas, or repo-level files --> `repo/` + +If ambiguous, default to `repo/` and mention it. + +## Step 2: Generate branch name + +From the description, generate a slug: lowercase, hyphens, no special characters, concise. + +Format: `<prefix>/<slug>` (e.g., `cms/add-mcp-server-page`, `cloud/fix-deployment-steps`). + +## Step 3: Create the branch + +```bash +git checkout -b <branch-name> +``` + +Confirm with the branch name. diff --git a/claude-plugins/inki/skills/code-verify/SKILL.md b/claude-plugins/inki/skills/code-verify/SKILL.md new file mode 100644 index 0000000000..9473270550 --- /dev/null +++ b/claude-plugins/inki/skills/code-verify/SKILL.md @@ -0,0 +1,42 @@ +--- +name: code-verify +description: "Verify code blocks in a documentation file: check syntax, references, and consistency with the underlying Strapi APIs." +argument-hint: "<file path>" +user-invocable: true +--- + +# /inki:code-verify — verify code blocks + +## Prerequisites + +This skill compares the code blocks in a documentation page against the actual Strapi codebase. It needs access to the source, in one of these forms (by preference): + +1. **A local clone of `strapi/strapi`.** Fastest and most reliable. Pass the path as input or ask the user. +2. **Raw GitHub fetch** (`https://raw.githubusercontent.com/strapi/strapi/develop/<path>`). Works without a local clone but rate-limited and slower. + +If neither is available, ask the user for a path or fall back to GitHub fetches. + +## Step 1: Read the target file + +`$ARGUMENTS` is a relative path to a `.md` or `.mdx` file under `docusaurus/docs/`. + +## Step 2: Extract all fenced code blocks + +Parse the file and list every fenced code block with its language and content. + +## Step 3: Apply the migrated code-verifier prompt + +Read `../../references/prompts/integrity-code-verifier.md` and use it as the system prompt to evaluate each code block for: +- Syntax validity for the declared language +- References to functions/types that exist in the version of Strapi this page targets +- Consistency with surrounding prose + +## Step 4: Report + +For each code block, output: + +``` +Block <N> (lang=<lang>, lines <start>-<end>): +- Status: ok | suspicious | broken +- Notes: <short explanation> +``` diff --git a/claude-plugins/inki/skills/coherence-check/SKILL.md b/claude-plugins/inki/skills/coherence-check/SKILL.md new file mode 100644 index 0000000000..209ac30083 --- /dev/null +++ b/claude-plugins/inki/skills/coherence-check/SKILL.md @@ -0,0 +1,27 @@ +--- +name: coherence-check +description: "Check a documentation file for cross-page coherence: terminology, links, and consistency with related pages." +argument-hint: "<file path>" +user-invocable: true +--- + +# /inki:coherence-check — cross-page coherence + +## Step 1: Read the target file and identify related pages + +For the target file, find related pages by: +- Walking links from the target file +- Searching `docusaurus/static/llms.txt` for entries on the same topic + +## Step 2: Apply the migrated coherence-checker prompt + +Read `../../references/prompts/integrity-coherence-checker.md` and use it as the system prompt. Compare the target against each related page. + +## Step 3: Report + +``` +Target: <path> +Related pages compared: <list> +Coherence issues: +- <description>: <where it conflicts> +``` diff --git a/claude-plugins/inki/skills/commit/SKILL.md b/claude-plugins/inki/skills/commit/SKILL.md new file mode 100644 index 0000000000..cec6e89328 --- /dev/null +++ b/claude-plugins/inki/skills/commit/SKILL.md @@ -0,0 +1,45 @@ +--- +name: commit +description: "Stage and commit documentation changes in strapi/documentation. Enforces git-rules.md, protected paths, and branch prefix detection." +argument-hint: [optional commit message] +user-invocable: true +--- + +# Documentation Commit + +**Scope:** designed for strapi/documentation (and its forks). + +## Input + +`$ARGUMENTS`: optional commit message. If not provided, one is generated from the diff. + +## Step 1: Apply shared commit rules + +Read and follow `../_shared/commit-rules.md` for: gathering context, validating/generating the commit message, and executing the commit. + +## Step 2: Protect infrastructure files + +Before staging, check if any changed files are protected: + +- `.github/workflows/*` -- deployment infrastructure +- `docusaurus/docusaurus.config.js` -- core site config +- `docusaurus/sidebars.js` -- navigation structure + +If protected files are present, require **double confirmation** before including them: + +1. List each protected file with a warning +2. **First confirmation:** "Include these protected files?" +3. **Second confirmation:** Show the diff of each and ask: "Confirm you have reviewed these changes?" + +If declined, commit only the non-protected files. + +## Step 3: Auto-push + +After a successful commit, push automatically if on a working branch: + +```bash +BRANCH=$(git branch --show-current) +``` + +- If `$BRANCH` is `main` or `next`: do NOT push. Warn the user. +- Otherwise: `git push -u origin $BRANCH` diff --git a/claude-plugins/inki/skills/coverage/SKILL.md b/claude-plugins/inki/skills/coverage/SKILL.md new file mode 100644 index 0000000000..e48f6eb171 --- /dev/null +++ b/claude-plugins/inki/skills/coverage/SKILL.md @@ -0,0 +1,46 @@ +--- +name: coverage +description: "Audit the documentation coverage of a Strapi feature or module: list what is documented vs missing." +argument-hint: "<feature or module name>" +user-invocable: true +--- + +# /inki:coverage — feature documentation gap audit + +## Prerequisites + +This skill compares a Strapi feature's public surface against the documentation. It needs access to the Strapi codebase, in one of these forms (by preference): + +1. **A local clone of `strapi/strapi`.** Fastest and most reliable. Pass the path as input or ask the user. +2. **Raw GitHub fetch** (`https://raw.githubusercontent.com/strapi/strapi/develop/<path>`). Works without a local clone but rate-limited and slower. + +If neither is available, ask the user for a path or fall back to GitHub fetches. + +## Step 1: Identify the feature + +`$ARGUMENTS` is a Strapi feature name (e.g., "Users & Permissions plugin", "Document Service API"). Resolve to a set of source files using one of the sources listed in Prerequisites. + +## Step 2: Enumerate the public surface + +List the public APIs, methods, hooks, configuration options, and CLI commands of the feature. + +## Step 3: Cross-reference with docs + +For each public element, search `docusaurus/docs/cms` and `docusaurus/docs/cloud` for mentions. Bucket as: +- documented +- partially documented +- undocumented + +## Step 4: Report + +``` +Feature: <name> +Documented (N/M): +- <element>: <doc path> + +Partially documented: +- <element>: <doc path> (notes) + +Undocumented: +- <element>: <suggested doc path> +``` diff --git a/claude-plugins/inki/skills/discover/SKILL.md b/claude-plugins/inki/skills/discover/SKILL.md new file mode 100644 index 0000000000..80b3de34f9 --- /dev/null +++ b/claude-plugins/inki/skills/discover/SKILL.md @@ -0,0 +1,34 @@ +--- +name: discover +description: "Top-level discover orchestrator: combines exists, route, and coverage to give a complete picture before writing." +argument-hint: "<topic, feature name, or strapi/strapi PR>" +user-invocable: true +--- + +# /inki:discover — pre-writing scout + +## Workflow + +Given `$ARGUMENTS`, classify the input: +- Looks like a topic/keyword → invoke `/inki:exists $ARGUMENTS` +- Looks like a feature/module name → invoke `/inki:coverage $ARGUMENTS` +- Looks like a strapi/strapi PR (number or URL) → invoke `/inki:route $ARGUMENTS` + +If the input is ambiguous, run more than one and label sections clearly. + +## Output + +Combine sub-reports under labeled sections: + +``` +=== Existing coverage === +<output of /inki:exists, if invoked> + +=== Feature gaps === +<output of /inki:coverage, if invoked> + +=== Code change routing === +<output of /inki:route, if invoked> +``` + +Conclude with a single recommended next step (e.g., "Run /inki:write" or "Skip — already documented at <path>"). diff --git a/claude-plugins/inki/skills/draft/SKILL.md b/claude-plugins/inki/skills/draft/SKILL.md new file mode 100644 index 0000000000..9563565549 --- /dev/null +++ b/claude-plugins/inki/skills/draft/SKILL.md @@ -0,0 +1,31 @@ +--- +name: draft +description: "Draft a documentation page from an approved outline, the matching template, and the relevant authoring guide." +argument-hint: "<path to outline file>" +user-invocable: true +--- + +# /inki:draft — draft a documentation page from an outline + +## Step 1: Read the outline + +`$ARGUMENTS` is a path to an outline file produced by `/inki:outline`. + +## Step 2: Load supporting context + +- Read the template: `../../references/templates/<template>-template.md` +- Read the relevant authoring guide: `../../references/authoring/AGENTS.<area>.md` +- Read `../../references/12-rules-of-technical-writing.md` + +## Step 3: Apply the migrated drafter prompt + +Read `../../references/prompts/drafter.md`. Use it as the system prompt. Generate the draft, section by section. + +## Step 4: Save + +Save the draft as a `.md` file at the canonical path (drop the `.outline.md` suffix, use `.md`). Show the user the file path and a diff. + +## Rules + +- Do not invent facts that are not in the outline or in the template's referenced sources. +- Preserve the heading hierarchy from the outline exactly. diff --git a/claude-plugins/inki/skills/exists/SKILL.md b/claude-plugins/inki/skills/exists/SKILL.md new file mode 100644 index 0000000000..fe54ee67c9 --- /dev/null +++ b/claude-plugins/inki/skills/exists/SKILL.md @@ -0,0 +1,81 @@ +--- +name: exists +description: "Check whether a documentation topic is already covered on strapi/documentation: searches llms.txt, doc files, sidebars, and open GitHub PRs." +argument-hint: "<topic or keyword>" +user-invocable: true +--- + +# /inki:exists — find existing coverage on a topic + +## Input + +`$ARGUMENTS`: a topic or keyword (e.g. `MCP server`, `hasPublishedVersion`, `openapi.json route`). + +If no argument is provided and the conversation has context (e.g. a PR was just discussed), extract the relevant keywords from context. + +## Step 1: Search the page index + +Read `docusaurus/static/llms.txt` at the repo root and find lines mentioning the topic (case-insensitive). + +```bash +REPO_ROOT=$(git rev-parse --show-toplevel) +grep -i "<topic>" "$REPO_ROOT/docusaurus/static/llms.txt" | head -20 +``` + +## Step 2: Search doc files + +```bash +REPO_ROOT=$(git rev-parse --show-toplevel) +grep -rli "<topic>" "$REPO_ROOT/docusaurus/docs/cms" "$REPO_ROOT/docusaurus/docs/cloud" 2>/dev/null | head -20 +``` + +For each match, optionally check when it was last touched: + +```bash +git log -1 --format="%ai" -- "<path>" +``` + +## Step 3: Search sidebars + +```bash +REPO_ROOT=$(git rev-parse --show-toplevel) +grep -in "<topic>" "$REPO_ROOT/docusaurus/sidebars.js" | head -20 +``` + +## Step 4: Search GitHub PRs + +```bash +gh pr list --repo strapi/documentation --state all --search "<topic>" --limit 20 --json number,title,state,url +``` + +Bucket the PRs as: open (might be in progress), merged (might already cover the topic), closed-not-merged (abandoned attempts). + +## Step 5: Synthesize + +Report in this format: + +``` +Coverage check: "<query>" + +Pages on docs.strapi.io that mention it: +- <path 1> (last updated YYYY-MM-DD, coverage: full | partial | mention) +- <path 2> + +Sidebars referencing it: +- <entry> + +PRs: +- Open: #<num> "<title>" — <url> +- Merged: #<num> "<title>" — <url> +- Closed: #<num> "<title>" — <url> + +Verdict: COVERED | PARTIAL | IN PROGRESS | NOT DOCUMENTED + +Suggested next step: <e.g. "Run /inki:route with the related strapi/strapi PR" | "Run /inki:outline to start a new page" | none> +``` + +## Rules + +- Never modify files. +- If none of the 4 sources match, report NOT DOCUMENTED clearly and suggest the next step. +- When several pages match, surface at most 5, ordered by relevance. diff --git a/claude-plugins/inki/skills/outline-check/SKILL.md b/claude-plugins/inki/skills/outline-check/SKILL.md new file mode 100644 index 0000000000..7076ac59b5 --- /dev/null +++ b/claude-plugins/inki/skills/outline-check/SKILL.md @@ -0,0 +1,25 @@ +--- +name: outline-check +description: "Check the structural outline of a documentation page: heading hierarchy, section order, completeness against the template." +argument-hint: "<file path>" +user-invocable: true +--- + +# /inki:outline-check — outline structure audit + +## Step 1: Identify the target and its template + +`$ARGUMENTS` is a relative path to a documentation page. Identify which template this page should match (feature, plugin, guide, API, configuration, breaking-change) by reading the page's frontmatter and content. + +## Step 2: Apply the migrated outline-checker prompt + +Read `../../references/prompts/outline-checker.md` and use it as the system prompt. Compare the page's outline to the expected template at `../../references/templates/<template-name>.md`. + +## Step 3: Report + +``` +Target: <path> +Expected template: <template name> +Outline issues: +- <heading missing | order wrong | extra section>: <details> +``` diff --git a/claude-plugins/inki/skills/outline-ux-analyzer/SKILL.md b/claude-plugins/inki/skills/outline-ux-analyzer/SKILL.md new file mode 100644 index 0000000000..fc4386b5a7 --- /dev/null +++ b/claude-plugins/inki/skills/outline-ux-analyzer/SKILL.md @@ -0,0 +1,25 @@ +--- +name: outline-ux-analyzer +description: "Analyze the pedagogical UX of a documentation outline: progression from beginner to advanced, signposting, and reading flow." +argument-hint: "<file path>" +user-invocable: true +--- + +# /inki:outline-ux-analyzer — pedagogical UX audit + +## Step 1: Read the target + +`$ARGUMENTS` is a relative path to a documentation page. + +## Step 2: Apply the migrated outline-ux-analyzer prompt + +Read `../../references/prompts/outline-ux-analyzer.md` and use it as the system prompt over the target. + +## Step 3: Report + +``` +Target: <path> +UX score: <1-5> +Findings: +- <section/heading>: <UX issue>: <suggestion> +``` diff --git a/claude-plugins/inki/skills/outline/SKILL.md b/claude-plugins/inki/skills/outline/SKILL.md new file mode 100644 index 0000000000..aa251932ea --- /dev/null +++ b/claude-plugins/inki/skills/outline/SKILL.md @@ -0,0 +1,28 @@ +--- +name: outline +description: "Generate an outline for a new documentation page from a topic brief and the appropriate template." +argument-hint: "<topic brief or path to a brief file>" +user-invocable: true +--- + +# /inki:outline — generate a page outline + +## Step 1: Read the brief + +`$ARGUMENTS` is either inline text or a path to a `.md` file containing the brief. + +## Step 2: Pick the template + +Decide which template applies (feature, plugin, guide, API, configuration, breaking-change) based on the brief. Read the relevant template at `../../references/templates/<template>-template.md`. + +## Step 3: Apply the migrated outliner prompts + +Read `../../references/prompts/outliner.md` and `../../references/prompts/outline-generator.md`. Use them as system prompts to produce an outline. + +## Step 4: Show the outline for approval + +Display the outline. Wait for `y` (accept) / `n` (discard) / `e` (edit inline). + +## Step 5: Save + +On `y`, save the outline as a `.md` file at a path the user confirms (typically under `docusaurus/docs/<area>/<slug>.outline.md`). diff --git a/claude-plugins/inki/skills/pitfalls-check/SKILL.md b/claude-plugins/inki/skills/pitfalls-check/SKILL.md new file mode 100644 index 0000000000..883e01ad60 --- /dev/null +++ b/claude-plugins/inki/skills/pitfalls-check/SKILL.md @@ -0,0 +1,24 @@ +--- +name: pitfalls-check +description: "Audit a documentation file against the known-pitfalls list: common mistakes, outdated patterns, deprecated APIs." +argument-hint: "<file path>" +user-invocable: true +--- + +# /inki:pitfalls-check — known pitfalls audit + +## Step 1: Read the target file + +`$ARGUMENTS` is a relative path. + +## Step 2: Load the known-pitfalls catalog + +Read `../../references/prompts/integrity-known-pitfalls.md`. This file is a reference catalog of documented hallucination patterns (organized by category, with tables mapping the wrong pattern to the correct one and a short context note). For each entry, check whether the target file matches the hallucinated pattern. + +## Step 3: Report + +``` +Target: <path> +Pitfalls found: +- <pitfall name>: <line or section reference>: <suggested fix> +``` diff --git a/claude-plugins/inki/skills/pr-body-fix/SKILL.md b/claude-plugins/inki/skills/pr-body-fix/SKILL.md new file mode 100644 index 0000000000..17bd38ef6c --- /dev/null +++ b/claude-plugins/inki/skills/pr-body-fix/SKILL.md @@ -0,0 +1,16 @@ +--- +name: pr-body-fix +description: "Alias for /inki:pr-description-fix. Rewrite the body/description of one or more open PRs on strapi/documentation." +argument-hint: "[PR#] [PR#] ..." +user-invocable: true +--- + +# /inki:pr-body-fix — alias for /inki:pr-description-fix + +This skill is a convenience alias. The gh CLI uses the word "body" for what `/inki:pr-description-fix` rewrites. Both names invoke the same workflow. + +## What this skill does + +Read and follow `../pr-description-fix/SKILL.md` end to end. Pass `$ARGUMENTS` through unchanged. + +That is the full content of the skill. The alias exists only to match gh CLI terminology; behavior is identical to `/inki:pr-description-fix`. diff --git a/claude-plugins/inki/skills/pr-description-fix/SKILL.md b/claude-plugins/inki/skills/pr-description-fix/SKILL.md new file mode 100644 index 0000000000..3b4619a12c --- /dev/null +++ b/claude-plugins/inki/skills/pr-description-fix/SKILL.md @@ -0,0 +1,84 @@ +--- +name: pr-description-fix +description: "Rewrite the description of one or more open PRs on strapi/documentation to match git-rules.md. Strict one-by-one confirmation." +argument-hint: "[PR#] [PR#] ... (no args = all open PRs on strapi/documentation)" +user-invocable: true +--- + +# Rewrite PR descriptions on strapi/documentation + +**Repo:** strapi/documentation only. Refuses elsewhere. + +## Input + +`$ARGUMENTS`: zero or more PR numbers separated by spaces. + +- If empty: list all open PRs on `strapi/documentation` via `gh pr list --repo strapi/documentation --state open --limit 100 --json number,body,title,author`. +- If one or more numbers: fetch each with `gh pr view <num> --repo strapi/documentation --json number,body,title,author`. + +## Step 0: Validate environment + +```bash +command -v gh >/dev/null || { echo "gh CLI required"; exit 1; } +``` + +## Step 1: Load the canonical rules + +Read `../_shared/pr-description-rules.md` and `../../references/git-rules.md` (the description section). Layer the strict strapi/documentation overrides on top: + +1. Must start with "This PR ..." +2. No headings (no `##`, no `###`) +3. No "Test plan" section +4. No checklists +5. Flat text only +6. Issue references at the very end + +## Step 2: Classify each PR + +For each PR, evaluate the current body. Bucket as: + +- **compliant** → silently skip +- **non-compliant** → propose a rewrite + +Reasons for non-compliance: missing "This PR ..." opener, contains `##`/`###` heading, contains "Test plan" section, contains `- [ ]` checklist, contains boilerplate sections, empty body, body is just "Updated docs" type vagueness. + +## Step 3: Propose rewrites one by one + +For each non-compliant PR, display the current body and the proposal in linear before/after form: + +``` +PR #<num> — author: @<login> + Title: <current title (for context, not edited here)> + + --- Current description --- + <current body, line by line> + + --- Proposed description --- + <proposed body, line by line> + + Reason: <short explanation> + [y]es / [n]o / [e]dit / [s]kip +``` + +If the user types `e`, open a temporary file with the proposal pre-filled, let the user edit it, then re-display before applying. + +Branch on response: + +- `y` → run `gh pr edit <num> --repo strapi/documentation --body-file <tmpfile>` (write the proposed body to a tmpfile first to preserve line breaks reliably). +- `n` or `s` → record as skipped. +- `e` → after edit, re-display the new proposal, ask `y`/`n` again. + +## Step 4: Vercel preview link handling + +If the original description had a `Direct preview link 👉 [here](https://...)` line as its last line, preserve that line at the end of the new description. Otherwise do not add one (this skill is for rewriting, not creation; that is `/inki:pr`'s job). + +## Step 5: Final summary + +Same table format as `/inki:pr-title-fix`. + +## Rules + +- Never edit a description without explicit confirmation. +- Never propose a description that itself fails the rules. +- Do not touch the PR title. +- Do not add new sections, links, or @mentions that weren't in the original. diff --git a/claude-plugins/inki/skills/pr-title-fix/SKILL.md b/claude-plugins/inki/skills/pr-title-fix/SKILL.md new file mode 100644 index 0000000000..37144c125b --- /dev/null +++ b/claude-plugins/inki/skills/pr-title-fix/SKILL.md @@ -0,0 +1,72 @@ +--- +name: pr-title-fix +description: "Rewrite the title of one or more open PRs on strapi/documentation to match git-rules.md. Strict one-by-one confirmation." +argument-hint: "[PR#] [PR#] ... (no args = all open PRs on strapi/documentation)" +user-invocable: true +--- + +# Rewrite PR titles on strapi/documentation + +**Repo:** strapi/documentation only. Refuses elsewhere. + +## Input + +`$ARGUMENTS`: zero or more PR numbers separated by spaces (e.g. `2143 2159 2160`). + +- If empty: list all open PRs on `strapi/documentation` via `gh pr list --repo strapi/documentation --state open --limit 100 --json number,title,author`. +- If one or more numbers: target those PRs (fetch each with `gh pr view <num> --repo strapi/documentation --json number,title,author`). + +## Step 0: Validate environment + +```bash +command -v gh >/dev/null || { echo "gh CLI required"; exit 1; } +``` + +## Step 1: Load the canonical rules + +Read `../_shared/pr-title-rules.md` and `../../references/git-rules.md` (section "Pull Request Titles"). Use both as the single source of truth for what counts as compliant. + +## Step 2: Classify each PR + +For each PR, evaluate the current title against the rules. Bucket as: + +- **compliant** → silently skip (do not display) +- **non-compliant** → propose a rewrite + +Reasons for non-compliance include: `feat:/chore:/fix:` prefix, lowercase first word, vague wording (1-2 generic words like "Update docs"), missing verb or specific noun, ticket ID at start, emoji at start, length over 80 characters. + +## Step 3: Propose rewrites one by one + +For each non-compliant PR, display: + +``` +PR #<num> — author: @<login> + Current: <current title> + Proposed: <proposed title> + Reason: <short explanation> + [y]es / [n]o / [e]dit <new title> / [s]kip +``` + +Wait for input. Branch on response: + +- `y` → run `gh pr edit <num> --repo strapi/documentation --title "<proposed>"`, then move to next PR. +- `n` or `s` → record as skipped, move to next PR. +- `e <new title>` → run `gh pr edit <num> --repo strapi/documentation --title "<new title>"`, move to next PR. + +## Step 4: Final summary + +After all PRs are processed, print a table: + +``` +| PR# | Action | New title | +|-----|---------|-----------| +| ... | edited | ... | +| ... | skipped | (unchanged)| +``` + +## Rules + +- Never edit a title without explicit confirmation. +- Never propose a title that itself fails the rules. +- If the rewrite would change meaning (not just form), prefer to surface that in the Reason line so the user can intervene. +- Do not touch the PR description. diff --git a/claude-plugins/inki/skills/pr/SKILL.md b/claude-plugins/inki/skills/pr/SKILL.md new file mode 100644 index 0000000000..2b12b1c780 --- /dev/null +++ b/claude-plugins/inki/skills/pr/SKILL.md @@ -0,0 +1,51 @@ +--- +name: pr +description: "Create a pull request on strapi/documentation following git-rules.md. Strict flat-text description, no headings, no test plan." +argument-hint: [optional issue reference, e.g. "Fixes #2143"] +user-invocable: true +--- + +# Documentation Pull Request + +**Scope:** designed for strapi/documentation (and its forks). + +## Input + +`$ARGUMENTS`: optional issue reference (e.g., `Fixes #2143`, `#2143`) or additional context. + +## Step 1: Apply shared PR rules + +Read and follow `../_shared/pr-rules.md` for: gathering context, analyzing changes, generating the title (delegates to `../_shared/pr-title-rules.md`), generating the description (delegates to `../_shared/pr-description-rules.md`), showing the plan, and creating the PR. + +## Step 2: Add Vercel preview link + +Append a Vercel preview link as the last line of the PR body. Build it from the branch name: + +1. Get the branch name and replace `/` with `-` to get the slug (e.g., `cms/mcp-server` → `cms-mcp-server`) +2. Identify the primary page path from the changed files (the most important new or modified `.md` file under `docusaurus/docs/`, stripped of the `docusaurus/docs/` prefix and `.md` extension) +3. Append this line to the body: + +``` +Direct preview link 👉 [here](https://documentation-git-<branch-slug>-strapijs.vercel.app/<page-path>) +``` + +For example: `https://documentation-git-cms-mcp-server-strapijs.vercel.app/cms/features/strapi-mcp-server` + +## Step 3: Suggest push first if needed + +If no upstream exists, suggest running `/inki:push` first. + +## Good description examples + +``` +This PR documents the new hasPublishedVersion parameter added in strapi/strapi#2847. +- Adds parameter to the findMany() parameters table +- Updates the filtering description +- Adds usage tip + +Fixes #2143 +``` + +``` +This PR adds conditional retrieval rules to the Code Verifier and Coherence Checker agent prompts, and a new "separate facts from prose" behavioral note to the Drafter. +``` diff --git a/claude-plugins/inki/skills/push/SKILL.md b/claude-plugins/inki/skills/push/SKILL.md new file mode 100644 index 0000000000..ca242281e7 --- /dev/null +++ b/claude-plugins/inki/skills/push/SKILL.md @@ -0,0 +1,28 @@ +--- +name: push +description: "Push the current branch in strapi/documentation to origin. Validates branch name against git-rules.md conventions." +argument-hint: (no arguments) +user-invocable: true +--- + +# Documentation Push + +**Scope:** designed for strapi/documentation (and its forks). + +## Step 1: Apply shared push rules + +Read and follow `../_shared/push-rules.md` for: gathering state, safety checks, upstream status, showing the plan, and executing the push. + +## Step 2: Branch name validation (extra, doc-specific) + +Check the branch name follows git-rules.md conventions: +- Must start with `/cms/`, `/cloud/`, or `/repo/` +- No other prefixes (`/doc/`, `/docs/`, `/feat/`, `/fix/`, etc.) + +If non-compliant, warn the user but do not block (renaming an existing branch is disruptive). Suggest the correct prefix for future reference. + +## Step 3: Suggest branch creation if on main + +If on `main`, analyze recent changes to detect the area (cms/cloud/repo), then suggest: + +> Suggested: `git checkout -b /<prefix>/<description>` diff --git a/claude-plugins/inki/skills/review/SKILL.md b/claude-plugins/inki/skills/review/SKILL.md new file mode 100644 index 0000000000..2cd28a5f8b --- /dev/null +++ b/claude-plugins/inki/skills/review/SKILL.md @@ -0,0 +1,43 @@ +--- +name: review +description: "Top-level review orchestrator: runs style-check, outline-check, outline-ux-analyzer, code-verify, coherence-check, and pitfalls-check on the target." +argument-hint: "<file or directory path> [--fix]" +user-invocable: true +--- + +# /inki:review — full documentation review + +## Step 1: Resolve target + +`$ARGUMENTS`: either a path (file or directory under `docusaurus/docs/`) or empty (default to `git diff main...HEAD --name-only -- '*.md'`). + +## Step 2: Run the 6 sub-skills in parallel where possible + +Invoke: +- `/inki:style-check <target>` (with `--fix` if requested) +- `/inki:outline-check <target>` +- `/inki:outline-ux-analyzer <target>` +- `/inki:code-verify <target>` +- `/inki:coherence-check <target>` +- `/inki:pitfalls-check <target>` + +Collect each report. + +## Step 3: Synthesize + +Output a combined table: + +``` +| Sub-skill | Issues found | Severity | +|-----------|--------------|----------| +| style-check | <N> | low/med/high | +| outline-check | ... | ... | +| ... | ... | ... | +``` + +Then list issues by file, ordered by severity. + +## Rules + +- Each sub-skill stays atomic. Do not duplicate their logic here. +- If `--fix` is passed, only the auto-fixable findings from `style-check` are applied automatically. All others remain suggestions. diff --git a/claude-plugins/inki/skills/route/SKILL.md b/claude-plugins/inki/skills/route/SKILL.md new file mode 100644 index 0000000000..6312557520 --- /dev/null +++ b/claude-plugins/inki/skills/route/SKILL.md @@ -0,0 +1,30 @@ +--- +name: route +description: "Given a strapi/strapi PR, identify which documentation pages and sections must be updated to cover the change." +argument-hint: "<strapi/strapi PR number or URL>" +user-invocable: true +--- + +# /inki:route — route a code PR to its docs targets + +## Step 1: Fetch the strapi/strapi PR + +`$ARGUMENTS` is a PR number or URL on `strapi/strapi`. Fetch with `gh pr view <num> --repo strapi/strapi --json title,body,files,labels`. + +## Step 2: Apply the migrated router prompt + +Read `../../references/prompts/router.md`. Use it as the system prompt over the PR data. + +## Step 3: Report + +``` +strapi/strapi PR #<num>: <title> + +Recommended docs targets: +- File: <doc path> + Section: <heading> + Action: <add | update | rework> + Template: <feature | plugin | guide | api | configuration | breaking-change> + +Suggested branch name: <prefix>/<slug> +``` diff --git a/claude-plugins/inki/skills/style-check/SKILL.md b/claude-plugins/inki/skills/style-check/SKILL.md new file mode 100644 index 0000000000..d7c78a733b --- /dev/null +++ b/claude-plugins/inki/skills/style-check/SKILL.md @@ -0,0 +1,47 @@ +--- +name: style-check +description: "Run deterministic style checks on a documentation file or directory, then layer AI judgment on top using the migrated style-checker prompt." +argument-hint: "<file or directory path>" +user-invocable: true +--- + +# /inki:style-check — style lint for documentation files + +## Step 1: Determine target + +`$ARGUMENTS` is a relative path. If empty, use the diff between current branch and `main`: + +```bash +git diff main...HEAD --name-only -- '*.md' +``` + +## Step 2: Run the deterministic style script + +The plugin ships a deterministic linter at `claude-plugins/inki/scripts/style-lint.sh`. It checks Markdown/MDX files against regex-based rules from the 12 Rules of Technical Writing (em dashes, casual language, simplification suggestions, bold prefixes that should be admonitions, etc.). Exit codes: `0` clean, `1` errors found, `2` warnings only. + +Resolve the script path from the skill's location and run it on the target: + +```bash +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../../scripts" && pwd)" +"$SCRIPT_DIR/style-lint.sh" <target> +``` + +If invoked from a Claude Code session, the equivalent is to read `../../scripts/style-lint.sh` relative to this SKILL.md and execute it on the target. + +## Step 3: Apply the migrated style-checker prompt + +Read `../../references/prompts/style-checker.md` (relative to this SKILL.md location) and use it as the system prompt for an AI judgment pass over the target file's content. + +## Step 4: Report + +Output findings in this format: + +``` +File: <path> +Deterministic issues: +- <line>: <issue> +AI-judged issues: +- <issue>: <suggested fix> +``` + +If invoked with `--fix` in `$ARGUMENTS`, apply non-controversial fixes (typos, formatting) and leave the rest as suggestions. diff --git a/claude-plugins/inki/skills/submit/SKILL.md b/claude-plugins/inki/skills/submit/SKILL.md new file mode 100644 index 0000000000..848518f576 --- /dev/null +++ b/claude-plugins/inki/skills/submit/SKILL.md @@ -0,0 +1,22 @@ +--- +name: submit +description: "Top-level orchestrator: branch (if needed), commit, push, then open a PR. Each step asks for confirmation before continuing." +argument-hint: "[optional: issue reference or topic hint, e.g. 'Fixes #2143']" +user-invocable: true +--- + +# /inki:submit — branch + commit + push + PR + +## Workflow + +1. **Branch**: if currently on `main`, invoke `/inki:branch` to create a properly prefixed branch. +2. **Commit**: invoke `/inki:commit` to stage and write a commit message. +3. **Push**: invoke `/inki:push` (with explicit confirmation). +4. **PR**: invoke `/inki:pr` to draft and open the PR. + +the user confirms at each gate. + +## Rules + +- If any sub-step fails or the user cancels, stop immediately. Do not skip a step. +- Pass through `$ARGUMENTS` (if any) as an issue reference hint to `/inki:pr`. diff --git a/claude-plugins/inki/skills/write/SKILL.md b/claude-plugins/inki/skills/write/SKILL.md new file mode 100644 index 0000000000..f4ba15931d --- /dev/null +++ b/claude-plugins/inki/skills/write/SKILL.md @@ -0,0 +1,18 @@ +--- +name: write +description: "Top-level write orchestrator: outline a new page, get user approval, then draft from the outline." +argument-hint: "<topic brief or path to a brief file>" +user-invocable: true +--- + +# /inki:write — outline then draft + +## Workflow + +1. Invoke `/inki:outline $ARGUMENTS`. Wait for user approval (handled inside the sub-skill). +2. Once an outline file exists, invoke `/inki:draft <outline-path>`. + +## Rules + +- If the user rejects the outline, stop. Do not draft anything. +- Do not skip the outline step even if the brief looks straightforward.