diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000000..0deaf64470 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,13 @@ +{ + "name": "strapi-documentation", + "owner": { + "name": "Strapi Documentation" + }, + "plugins": [ + { + "name": "inki", + "description": "Inki — research, 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..2e2fd5ac4b 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: **Research** (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..ba26900d0a --- /dev/null +++ b/claude-plugins/inki/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "inki", + "version": "0.1.0", + "description": "Inki — research, 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..9c7697acde --- /dev/null +++ b/claude-plugins/inki/CHANGELOG.md @@ -0,0 +1,48 @@ +# Inki Changelog + +## Unreleased + +### Added + +- `/inki:pr-fix ` skill, with `action` being `title`, `description`, or `body` (alias of `description`). Replaces the previous separate `pr-title-fix`, `pr-description-fix`, and `pr-body-fix` skills. +- `--yes` / `-y` non-interactive auto mode on `/inki:pr-fix`, `/inki:review`, `/inki:submit`, and `/inki:write`. Skips confirmation prompts so the skills can be chained or scripted. +- `--include-old` flag on `/inki:pr-fix`: when no PR IDs are listed, include open PRs older than 30 days. By default, stale PRs are excluded to avoid bumping them with a title/description change notification. +- Safety bracket on `--yes` mode: when `--yes` is used without explicit PR IDs, the skill presents a batch-review prompt (`y` / `n` / `s ` to skip individual items) before applying any edit. +- URL parsing across skills: `/inki:pr-fix`, `/inki:route`, and `/inki:review` accept bare PR numbers (`3204`), hashed numbers (`#3204`), full URLs (`https://github.com/.../pull/3204`), and URLs with sub-paths (`/files`, `/commits`). +- `references/target-resolver.md`: centralized target resolution for `/inki:review`. The skill now accepts a path, a directory, a bare markdown filename, a GitHub PR, a `docs.strapi.io` URL, pasted Markdown content, or no argument (changed files on the current branch). +- `scripts/main-worktree.sh` helper: create or destroy a detached `origin/main` worktree, used by `/inki:review` for docs.strapi.io URL resolution. +- `scripts/pr-worktree.sh` helper: create or destroy a PR-checkout worktree, used by `/inki:review` for PR-scope reviews. +- `scripts/style-lint.sh` migrated into the plugin (previously at the repo root). Wired into `/inki:style-check`. Added acronyms: JWKS, OIDC, JWE, JWS. +- Notation legend in the README to explain skill argument placeholders (``, `[arg]`, etc.). + +### Changed + +- Renamed the first family from "Discover" to "Research" to align with the standard writer workflow (research → write → review → publish). The orchestrator slash command changed from `/inki:discover` to `/inki:research`. Sub-skills (`/inki:exists`, `/inki:coverage`, `/inki:route`) are unchanged. +- `/inki:review` now accepts more target types (path, directory, bare filename, PR, docs.strapi.io URL, pasted content, or no argument). Target resolution is centralized in `references/target-resolver.md`. +- `/inki:review` resolves a `docs.strapi.io` URL against the published `origin/main` source in a temporary worktree (never a stale working copy or a destructive pull), keeping coherence-check and code-verify fully functional, and flags local uncommitted changes that were excluded. +- `/inki:pr-fix description` (PR description rewrite): build the Vercel preview link from the bot comment when available (real host, including hash for long branch names), with the branch slug as a fallback for brand-new PRs. Verify the link returns HTTP 200 before publishing. +- PR recency filter on `/inki:pr-fix`: switched from `updatedAt` to `createdAt` so bot-bumped PRs are not incorrectly classified as recently active. +- Hardened `_shared/push-rules.md` and `_shared/pr-rules.md` to apply to forks (removed restrictive working-dir check on git skills) and to make the "Do not" lists explicit (each item now starts with "Do not"). +- Read `git-rules.md` from `references/` instead of the repo root, so the plugin is autonomous. +- Removed references to private `strapi-docs-product-merger` repo from the plugin. Inki is now self-contained. +- Rewrote orphan `agents/...` paths in migrated prompts and authoring guides to use `inki/references/` consistently. + +### Fixed + +- `plugin.json` author field: expect object schema (`{ name }`), not string. +- Pitfalls catalog clarification: `known-pitfalls.md` is a reference catalog, not a prompt — the `pitfalls-check` skill loads it as data. +- `code-verify` and `coverage` skills: document the Strapi codebase prerequisite (path to a local clone or fallback to GitHub fetch). + +## v0.1.0 — 2026-05-22 + +### Added + +- Plugin scaffolding (`.claude-plugin/plugin.json`, README, CHANGELOG). +- Self-hosted marketplace manifest at `.claude-plugin/marketplace.json`. +- Research family: `/inki:research`, `/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-fix `. +- 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..7a12a5b12a --- /dev/null +++ b/claude-plugins/inki/README.md @@ -0,0 +1,178 @@ +# Inki — research, write, review, submit your docs + +Inki is a Claude Code plugin that turns the way we author Strapi docs into a toolkit anyone can install in two commands. It bundles the skills, prompts, templates, and rules used to write and maintain the Strapi documentation. It lives in this repository (`claude-plugins/inki/`) and is installable via the repo's own self-hosted marketplace. + +## The problem it solves + +Writing good Strapi docs means juggling a lot of tribal knowledge: what's already documented, which pages a code change affects, the style guide and the 12 rules of technical writing, verifying code blocks against the real source, naming branches correctly, writing PR descriptions the way `git-rules.md` demands. + +Inki encodes all of it into one plugin, so high-quality docs become the easy default for the whole team. + +## Install + +```bash +/plugin marketplace add strapi/documentation +/plugin install inki@strapi-documentation +``` + +After install, the skills are available at `/inki:`, persistent across Claude Code sessions. + +## The four families: a docs workflow end to end + +Inki ships 20 skills organized into 4 families that mirror the life of a documentation change: figure out **where** the doc goes, **write** it, **review** it, then **submit** it. Each family has a top-level **orchestrator** with the same name that runs the whole stage, plus **granular skills** you can call on their own for finer control. + +| Stage | Family | Orchestrator | Granular skills | +|-------|--------|-------------|-----------------| +| 1 | 🔍 Research | `/inki:research` | `exists`, `route`, `coverage` | +| 2 | ✍️ Write | `/inki:write` | `outline`, `draft` | +| 3 | 🔬 Review | `/inki:review` | `style-check`, `outline-check`, `outline-ux-analyzer`, `code-verify`, `coherence-check`, `pitfalls-check` | +| 4 | 🚀 Submit | `/inki:submit` | `branch`, `commit`, `push`, `pr`, `pr-fix` | + +You can run the full chain for a new page, or jump straight to a single stage (e.g. just `/inki:review` on an existing file). + +### 1. 🔍 Research — figure out where the doc goes + +Before writing a line, find out what already exists and where new content belongs, so you don't duplicate a page or put it in the wrong section. + +- Run `/inki:research` and let it dispatch based on what you give it, or call a sub-skill directly: + - `/inki:exists "MCP server"` — is this topic already documented? Searches the docs, the sidebars, and open PRs. + - `/inki:route ` — given a code PR, which doc pages and sections need to change to cover it. + - `/inki:coverage ` — audit how well an existing feature is documented and what's missing. + +The output tells you whether to edit an existing page or create a new one, and exactly where it should live. + +### 2. ✍️ Write — do the actual writing + +Turn a topic brief into a drafted page, grounded in the right template and authoring guide so the structure and tone are correct from the start. + +- `/inki:write ` runs the whole stage: it generates an outline, then drafts the page from it. +- Or drive it in two steps: + - `/inki:outline ` — produce an outline from the brief and the matching template. Review and tweak it. + - `/inki:draft ` — draft the page from that outline, the template, and the relevant authoring guide. + +A `` can be inline text (e.g. "MCP server feature, AI tools section, similar to existing AI pages") or a path to a `.md` file describing what you want. + +### 3. 🔬 Review — check what you wrote + +One command runs six reviewers in parallel against your page and returns a single report, sorted by severity. + +``` +/inki:review https://github.com/strapi/documentation/pull/1234 + │ + ├─ style-check ──────── deterministic lint + AI judgment + ├─ outline-check ─────── structure vs the official template + ├─ outline-ux-analyzer ─ pedagogical UX: beginner → advanced flow + ├─ code-verify ───────── every code block vs the real Strapi source ⭐ + ├─ coherence-check ───── terminology + links vs related pages + └─ pitfalls-check ────── deprecated patterns, known mistakes + │ + └─ one report, issues sorted by severity +``` + +What makes it powerful: + +1. **It accepts anything.** A local file, a bare filename, a GitHub PR number or URL, a published `docs.strapi.io` URL, or pasted Markdown. It resolves the target itself (cloning a worktree for a PR if needed) and cleans up after. +2. **Six reviewers in parallel, one verdict.** No human reviewer runs all six checks by hand, every time, consistently. +3. **`--fix` closes the loop.** It can auto-apply the style fixes, not just flag them. + +The standout sub-skill is **`/inki:code-verify`**: it reads every fenced code block in a page and checks it against the actual `strapi/strapi` source — syntax, whether referenced functions and types really exist, and consistency with the surrounding prose. It proves the code in the docs matches the code that ships. + +### 4. 🚀 Submit — get it to GitHub + +Once the page passes review, one command takes it all the way to an open PR, delegating to four granular skills that each already know our conventions. + +``` +/inki:submit + │ + ├─ /inki:branch ── auto-detects the right prefix (cms/, cloud/, repo/) from the files touched + ├─ /inki:commit ── compliant message, respects protected paths + ├─ /inki:push ──── validates the branch name against git-rules.md + └─ /inki:pr ────── opens a PR with a compliant title + flat description (no headings, no test plan) +``` + +Composition, not duplication: `submit` doesn't reinvent git logic. Each sub-skill encodes a slice of `git-rules.md` once and is reused everywhere. Already opened a PR and need to fix its title or description? `/inki:pr-fix` rewrites them to match `git-rules.md`. + +## Command reference + +**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`). + +### Research — before you write + +Find out what already exists, where to put new content, what's missing. + +- `/inki:research ` — 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 [--yes] ` — 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 [--yes] [--fix] ` — orchestrator: runs all 6 review sub-skills against any supported target. +- `/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 [--yes] [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-fix [--yes] [--include-old] [PR# or URL...]` — rewrite the title or body of existing PRs (`body` is an alias of `description`). + +### Common flags + +- `--yes` / `-y` — non-interactive mode: skip confirmation prompts. Useful for chaining skills or scripting. +- `--include-old` (only on `pr-fix`) — when no PR IDs are listed, include open PRs older than 30 days. By default, stale PRs are excluded to avoid bumping them with a title/description change notification. + +## 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. + +## For plugin developers: refreshing changes + +When you edit a skill in this plugin and want to see your changes locally, the marketplace cache keeps the previously-installed version of each `SKILL.md` until you fully reinstall the plugin. `/plugin marketplace update` refreshes metadata (skill names and descriptions visible in the skill list) but does not refresh the content of skill files. + +To pick up local edits to skill files, run this 4-step cycle: + +``` +/plugin uninstall inki@strapi-documentation +/plugin marketplace update strapi-documentation +/plugin install inki@strapi-documentation +/reload-plugins +``` + +This cycle is only needed during plugin development. End users running `/plugin install` get the latest version whenever they update the marketplace. + +## 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 82fb101c51..5ed49cb42f 100644 --- a/agents/authoring/AGENTS.cms.features.md +++ b/claude-plugins/inki/references/authoring/AGENTS.cms.features.md @@ -72,4 +72,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/claude-plugins/inki/references/target-resolver.md b/claude-plugins/inki/references/target-resolver.md new file mode 100644 index 0000000000..d41dcc98f9 --- /dev/null +++ b/claude-plugins/inki/references/target-resolver.md @@ -0,0 +1,116 @@ +# Target resolver + +Shared logic for resolving an inki skill's target argument to a concrete set of local files to operate on. Skills that accept a review target (`review`, and any future skill that reviews existing content) reference this file instead of duplicating the parsing rules. + +The resolver takes whatever the user passed (after flags are stripped) and returns: + +- `FILES`: a list of local file paths the sub-skills operate on. +- `SCOPE`: a short human label describing the target (used in report headers), e.g. `PR #3204 (1 doc file)`, `docusaurus/docs/cms/intro.md`, or `pasted content`. +- `CLEANUP`: an optional command to run after the skill finishes (worktree teardown, temp-file removal). May be empty. + +The repo is always `strapi/documentation`. Docs live under `docusaurus/docs/`. + +## Accepted input types + +The target is classified by inspecting its shape, in this order (first match wins): + +| # | Input type | How to detect | Resolves to | +|---|-----------|---------------|-------------| +| 1 | Empty | No argument left after stripping flags | Changed `.md` files on the current branch | +| 2 | GitHub PR | URL `github.com/strapi/documentation/pull/`, `#`, or a bare integer | The PR's changed doc files, in a temporary worktree | +| 3 | docs.strapi.io URL | Starts with `https://docs.strapi.io/` (or `http://`) | The published source file the URL maps to, read from `origin/main` | +| 4 | Local path | Contains a `/` or ends in `.md`/`.mdx`, and exists on disk | That file, or all docs under it if a directory | +| 5 | Bare filename | A `.md`/`.mdx` name with no directory part, not found as a literal path | The unique file of that name under `docusaurus/docs/` | +| 6 | Pasted content | None of the above; the argument is multi-line or clearly Markdown body/frontmatter | A temp file written from the pasted text | + +When a target is ambiguous (e.g. a bare integer that is also a plausible filename), prefer the PR interpretation only when the value is purely numeric; otherwise treat it as a filename. State the chosen interpretation in the report header so the user can correct it. + +## Resolution by type + +### 1 — Empty + +```bash +git diff main...HEAD --name-only -- '*.md' '*.mdx' +``` + +Operates on the current working tree. `CLEANUP` is empty. + +### 2 — GitHub PR + +1. Extract the PR number: strip a leading `#`, strip URL tails (`/files`, `/changes`), then take the trailing `[0-9]+`. +2. Fetch the PR's changed files: + + ```bash + gh pr view --repo strapi/documentation --json files,headRefName --jq '.files[].path' + ``` + +3. Filter to `.md` and `.mdx` only. If the PR changes no documentation file, report that and stop. +4. Check the PR out in a temporary worktree so sub-skills see the PR's version, not `main`: + + ```bash + WORKTREE=$(./claude-plugins/inki/scripts/pr-worktree.sh create ) + ``` + +5. `FILES` = each path from step 3, prefixed with `$WORKTREE/`. +6. `CLEANUP` = `./claude-plugins/inki/scripts/pr-worktree.sh destroy `. + +`SCOPE` = `PR # ( doc file[s])`. + +### 3 — docs.strapi.io URL + +A `docs.strapi.io` URL points at the *published* page, so the review must run against the published source on `origin/main`, not a possibly-stale working copy. Check the page out in a temporary worktree on `origin/main` so the file sits at its real path under `docusaurus/docs/` — this keeps coherence-check and code-verify fully functional (relative links and sibling pages resolve), unlike a loose temp file: + +1. Strip the origin (`https://docs.strapi.io`) and any trailing slash, query string, or `#anchor`. +2. The remaining path is the doc route, e.g. `/cms/features/strapi-mcp-server`. +3. Create the worktree (it fetches `origin/main` first); sub-skills see the published version, not the current branch. This never touches the working tree, so no stash or commit is needed first: + + ```bash + WORKTREE=$(./claude-plugins/inki/scripts/main-worktree.sh create) + ``` + +4. The source file is that route under `$WORKTREE/docusaurus/docs/`, trying `.md` then `.mdx`: + - `$WORKTREE/docusaurus/docs/cms/features/strapi-mcp-server.md` + - if absent, `…/strapi-mcp-server.mdx` + - if the route ends in a segment that is a directory, try `…//index.md` / `index.mdx`. +5. `FILES` = the first candidate that exists. `CLEANUP` = `./claude-plugins/inki/scripts/main-worktree.sh destroy`. +6. If the local working tree (in the main checkout) has uncommitted changes to the same path, note in the report header that the review ran against `origin/main` and that those local uncommitted changes were **not** included. +7. If no candidate exists on `origin/main` (e.g. the page is generated, or the route uses a sidebar alias), destroy the worktree and fall back to fetching the rendered page with WebFetch, treating the result as **pasted content** (type 6) — note in the report that the review ran against the published HTML, not local source. + +`SCOPE` = `docs.strapi.io (origin/main)`, or `docs.strapi.io (fetched)` for the WebFetch fallback. `CLEANUP` tears down the worktree (or removes the WebFetch temp file in the fallback). + +### 4 — Local path + +Use the path directly. If it is a directory, recursively collect `.md` and `.mdx` files under it. `CLEANUP` is empty. + +`SCOPE` = the path. + +### 5 — Bare filename + +The user passed a filename with no directory, e.g. `strapi-mcp-server.md`: + +```bash +find docusaurus/docs -type f \( -name '' \) 2>/dev/null +``` + +- Exactly one match: use it. +- Multiple matches: list them and ask the user which one (or, with `--yes`, review all of them). +- No match: report that the file was not found and stop. + +`SCOPE` = the resolved path. + +### 6 — Pasted content + +The user pasted Markdown directly (frontmatter, headings, prose) instead of a reference: + +1. Derive a slug from the first `# H1` or frontmatter `title:`, falling back to `pasted`. +2. Write the content verbatim to `/tmp/inki-review-paste-.md`. +3. `FILES` = that temp file. +4. `CLEANUP` = `rm -f /tmp/inki-review-paste-.md`. + +`SCOPE` = `pasted content ()`. + +Note: coherence-check and code-verify are less reliable on pasted content, because the file is outside the docs tree (relative links and sibling-page lookups will not resolve). Note this limitation in the report when the target is pasted content. + +## Cleanup contract + +Always run `CLEANUP` after the skill finishes, including on failure. In a Claude-Code-driven run (where a bash `trap` may not survive across separate tool calls), invoke the `CLEANUP` command explicitly as the final step rather than relying on `trap`. 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/main-worktree.sh b/claude-plugins/inki/scripts/main-worktree.sh new file mode 100755 index 0000000000..264162624b --- /dev/null +++ b/claude-plugins/inki/scripts/main-worktree.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +# main-worktree.sh — Helper to manage a temporary, detached git worktree on origin/main. +# +# Used to review a published page (resolved from a docs.strapi.io URL) against the +# version on origin/main, with the file at its real path inside docusaurus/docs/ so +# that coherence-check and code-verify can resolve relative links and sibling pages. +# +# Subcommands: +# create Fetch origin/main and create a detached worktree at /tmp/inki-review-main. +# Prints the worktree path on stdout. +# destroy Remove the worktree. +# +# Usage in a skill (bash): +# WORKTREE=$(./main-worktree.sh create) +# # ... review files inside $WORKTREE (e.g. $WORKTREE/docusaurus/docs/) ... +# ./main-worktree.sh destroy +# +# Detached (no temporary branch): the worktree only needs to read origin/main, never commit. + +set -euo pipefail + +usage() { + echo "Usage: $0 {create|destroy}" >&2 + exit 1 +} + +[ $# -eq 1 ] || usage +ACTION="$1" + +REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +WORKTREE_DIR="/tmp/inki-review-main" + +case "$ACTION" in + create) + # Clean up any leftover from a previous run. + git -C "$REPO_ROOT" worktree remove --force "$WORKTREE_DIR" 2>/dev/null || true + rm -rf "$WORKTREE_DIR" + + # Refresh origin/main, then create a detached worktree pointing at it. + git -C "$REPO_ROOT" fetch origin main >&2 + git -C "$REPO_ROOT" worktree add --detach "$WORKTREE_DIR" origin/main >&2 + echo "$WORKTREE_DIR" + ;; + destroy) + git -C "$REPO_ROOT" worktree remove --force "$WORKTREE_DIR" 2>/dev/null || true + ;; + *) + usage + ;; +esac diff --git a/claude-plugins/inki/scripts/pr-worktree.sh b/claude-plugins/inki/scripts/pr-worktree.sh new file mode 100755 index 0000000000..6825845252 --- /dev/null +++ b/claude-plugins/inki/scripts/pr-worktree.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# pr-worktree.sh — Helper to manage a temporary git worktree for reviewing a PR. +# +# Subcommands: +# create Fetch the PR head and create a worktree at /tmp/inki-review-pr-. +# Prints the worktree path on stdout. +# destroy Remove the worktree and the temporary branch. +# +# Usage in a skill (bash): +# WORKTREE=$(./pr-worktree.sh create 3204) +# trap "$(dirname "$0")/pr-worktree.sh destroy 3204" EXIT +# # ... run sub-skills on files inside $WORKTREE ... +# +# The temporary branch is named `inki-tmp-review-` and points to the PR head. +# The worktree path is /tmp/inki-review-pr-. + +set -euo pipefail + +usage() { + echo "Usage: $0 {create|destroy} " >&2 + exit 1 +} + +[ $# -eq 2 ] || usage +ACTION="$1" +PR_NUM="$2" + +[[ "$PR_NUM" =~ ^[0-9]+$ ]] || { echo "PR number must be numeric: $PR_NUM" >&2; exit 1; } + +REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +WORKTREE_DIR="/tmp/inki-review-pr-${PR_NUM}" +TMP_BRANCH="inki-tmp-review-${PR_NUM}" + +case "$ACTION" in + create) + # Clean up any leftover from a previous run. + git -C "$REPO_ROOT" worktree remove --force "$WORKTREE_DIR" 2>/dev/null || true + git -C "$REPO_ROOT" branch -D "$TMP_BRANCH" 2>/dev/null || true + rm -rf "$WORKTREE_DIR" + + # Fetch the PR head into a local branch, then create the worktree. + git -C "$REPO_ROOT" fetch origin "pull/${PR_NUM}/head:${TMP_BRANCH}" >&2 + git -C "$REPO_ROOT" worktree add "$WORKTREE_DIR" "$TMP_BRANCH" >&2 + echo "$WORKTREE_DIR" + ;; + destroy) + git -C "$REPO_ROOT" worktree remove --force "$WORKTREE_DIR" 2>/dev/null || true + git -C "$REPO_ROOT" branch -D "$TMP_BRANCH" 2>/dev/null || true + ;; + *) + usage + ;; +esac diff --git a/claude-plugins/inki/scripts/style-lint.sh b/claude-plugins/inki/scripts/style-lint.sh new file mode 100755 index 0000000000..0c12799405 --- /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|ULID|HTTP|HTTPS|CMS|SSO|RBAC|JWT|JWK|JWKS|JWS|JWE|JWA|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|VPN|WAF|MDX|JSX|TSX|GDPR|SSG|ISR|TLS|SSL|TCP|UDP|IDE|VSC|EOF|USA|FAQ|PDF|PNG|JPG|JPEG|GIF|SVG|WEBP|AVIF|RGB|HEX|HSL|ISO|UTC|GMT|MFA|TOTP|HOTP|ACL|PII|CRON|IPV4|IPV6|MIME|TTL|CTA|KPI|IIFE|GZIP" + +# 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/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-fix/SKILL.md b/claude-plugins/inki/skills/pr-fix/SKILL.md new file mode 100644 index 0000000000..a9e89c59e2 --- /dev/null +++ b/claude-plugins/inki/skills/pr-fix/SKILL.md @@ -0,0 +1,292 @@ +--- +name: pr-fix +description: "Rewrite the title or description/body of one or more open PRs on strapi/documentation to match git-rules.md. Strict one-by-one confirmation, or auto-edit with --yes." +argument-hint: "<title|description|body> [--yes|-y] [--include-old] [PR# or URL] [PR# or URL] ..." +user-invocable: true +--- + +# Rewrite PR title or description/body on strapi/documentation + +**Scope:** designed for strapi/documentation (and its forks). + +## Input + +`$ARGUMENTS` is `<action> [flags] [PR identifiers...]`. + +### Required action (first positional argument) + +| Action | What it rewrites | +|---|---| +| `title` | The PR title | +| `description` | The PR body/description | +| `body` | Alias of `description` (matches `gh pr edit --body` vocabulary) | + +If no action is given, or if the first token is not one of the above, report the error and stop. + +### Optional flags (anywhere after the action) + +- `--yes` or `-y` → `AUTO=true` (non-interactive: skip confirmation prompts) +- `--include-old` → `INCLUDE_OLD=true` (only meaningful when no PR identifiers are given; includes open PRs older than 30 days) + +### Optional PR identifiers + +Zero or more, each as a bare number (`2143`), a hashed number (`#2143`), or a full URL (`https://github.com/strapi/documentation/pull/2143`, with optional `/files` or `/changes` suffix). + +If no PR identifiers are given: +- By default, list **recent open PRs** (created within the last 30 days) via: + ```bash + gh pr list --repo strapi/documentation --state open \ + --search "created:>=$(date -v-30d +%Y-%m-%d 2>/dev/null || date -d '30 days ago' +%Y-%m-%d)" \ + --limit 100 --json number,title,body,author,createdAt + ``` +- If `--include-old` is set, drop the `--search` filter to list all open PRs. + +The 30-day cutoff uses `createdAt` (not `updatedAt`) because bot activity bumps `updatedAt` on otherwise stale PRs. + +## Step 0: Parse arguments + +1. Read the first positional token as `ACTION` (must be `title`, `description`, or `body`). Normalize `body` → `description` internally. +2. Detect `--yes`/`-y` → `AUTO=true`. Remove from list. +3. Detect `--include-old` → `INCLUDE_OLD=true`. Remove from list. +4. For each remaining token, extract trailing digits to get the PR number: + - `2143` → `2143` + - `#2143` → `2143` + - `https://github.com/strapi/documentation/pull/2143` → `2143` + - `https://github.com/strapi/documentation/pull/2143/files` → `2143` + Regex `[0-9]+$` after stripping trailing path segments and a leading `#`. +5. Report any token that doesn't yield a numeric PR ID and skip it. + +## Step 1: Validate environment + +```bash +command -v gh >/dev/null || { echo "gh CLI required"; exit 1; } +``` + +## Step 2: Load the canonical rules + +Depending on `ACTION`: + +- `title`: read `../_shared/pr-title-rules.md` and `../../references/git-rules.md` (section "Pull Request Titles"). +- `description` (and `body`): 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 3: Fetch and classify each PR + +For each PR number, fetch metadata: + +```bash +gh pr view <num> --repo strapi/documentation --json number,title,body,author +``` + +Bucket each PR: + +- **compliant** → silently skip (do not display, do not edit) +- **non-compliant** → produce a proposed rewrite + +### Title non-compliance reasons + +`feat:/chore:/fix:/docs:` (or any `word(scope):`) 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. + +### Description non-compliance reasons + +Missing "This PR ..." opener, contains `##`/`###` heading, contains "Test plan" section, contains `- [ ]` checklist, contains boilerplate sections, empty body, body is just "Updated docs" type vagueness, **missing the trailing "Direct preview link 👉 [here](...)" line** (see Step 5 for the construction logic). + +## Step 4: Apply rewrites + +### If `AUTO=true` + +**Case A — PR identifiers were given explicitly** + +Edit immediately without further prompting: + +- For `ACTION=title`: `gh pr edit <num> --repo strapi/documentation --title "<proposed>"` +- For `ACTION=description`: write the proposed body to a tmpfile, then `gh pr edit <num> --repo strapi/documentation --body-file <tmpfile>` + +Announce each change inline: + +``` +PR #<num>: edited — "<proposed title>" (for title) +PR #<num>: edited (description rewritten) (for description) +``` + +**Case B — No PR identifiers given** (targets all recent open PRs) + +A batch confirmation is required as a safety bracket. Display the full list of proposed edits first: + +``` +Review batch (--yes without PR IDs targets all recent open PRs): + +| PR# | Author | Current | Proposed | Reason | (for title) +| PR# | Author | Reason | Preview of new description | (for description) +| ... | ... | ... | ... | ... | + +Compliant (no changes needed): N PRs + +Type `y` to apply all, `n` to cancel, or `s <PR#> <PR#> ...` to skip specific PRs and apply the rest. +``` + +Branch on the user's single response: + +- `y` → apply all listed edits. +- `n` → cancel entirely, edit nothing, exit. +- `s <PR#> <PR#> ...` → remove those PRs from the batch, then apply the remaining edits. + +### If `AUTO=false` + +For each non-compliant PR, display the proposal and wait for input. + +**For `ACTION=title`:** + +``` +PR #<num> — author: @<login> + Current: <current title> + Proposed: <proposed title> + Reason: <short explanation> + [y]es / [n]o / [e]dit <new title> / [s]kip +``` + +Branch on response: +- `y` → `gh pr edit <num> --repo strapi/documentation --title "<proposed>"` +- `n` or `s` → record as skipped +- `e <new title>` → edit with the user-provided title + +**For `ACTION=description`:** + +``` +PR #<num> — author: @<login> + Title: <current title (for context, not edited here)> + + --- Current description --- + <current body> + + --- Proposed description --- + <proposed body> + + Reason: <short explanation> + [y]es / [n]o / [e]dit / [s]kip +``` + +Branch: +- `y` → write proposed body to tmpfile, `gh pr edit <num> --repo strapi/documentation --body-file <tmpfile>` +- `n` or `s` → record as skipped +- `e` → open temp file with proposal pre-filled, let user edit, re-display, ask `y`/`n` + +## Step 5: Vercel preview link handling (description action only) + +The proposed description MUST end with a Vercel preview link line. If the original description has one as its last line, preserve it. If it does not, build one and append it. + +### How to build the Vercel preview link + +The link has two parts: the **deployment host** (`https://documentation-git-<...>-strapijs.vercel.app`) and the **page path**. + +#### Deployment host: read it from the Vercel bot comment first + +Do NOT naively build the host from the branch name. Vercel truncates long branch slugs to a ~63-character DNS label and appends a short hash (e.g. branch `cms/move-mcp-plugin-api-to-plugins-dev` deploys to `documentation-git-cms-move-mcp-plugin-api-to-pl-704ff2-strapijs.vercel.app`, NOT `documentation-git-cms-move-mcp-plugin-api-to-plugins-dev-strapijs.vercel.app`). A slug-built host for a long branch will fail to resolve. + +1. **Primary method, extract the real host from the Vercel bot comment:** + ```bash + gh pr view <num> --repo strapi/documentation --json comments \ + -q '.comments[] | select(.author.login | test("vercel"; "i")) | .body' \ + | grep -oE 'https://documentation-git-[a-z0-9-]+\.vercel\.app' | sort -u | head -1 + ``` + This returns the exact deployed host, hash and all. + +2. **Fallback, build the slug from the branch name** (only when no Vercel comment exists yet, e.g. a brand-new PR whose deployment has not been posted): + - Read the head branch (`gh pr view <num> --repo strapi/documentation --json headRefName`). + - Replace `/` with `-`: `cms/mcp-server` → `cms-mcp-server`. + - Host: `https://documentation-git-<branch-slug>-strapijs.vercel.app`. + - This only works for short branch names. If the branch slug would exceed ~50 characters, the slug-built host is unreliable; note in the Reason line that the link should be verified once Vercel posts its comment. + +#### Page path + +3. Identify the primary page path to deep-link to: + - Fetch the PR's changed files via `gh pr view <num> --repo strapi/documentation --json files --jq '.files[].path'`. + - Filter to `.md`/`.mdx` files under `docusaurus/docs/`. + - Prefer the **newly added** page (a file added by the PR). If several added pages exist, take the first. If none were added, pick the most representative modified page; if several are equally central, prefer the hub/parent page (e.g., `cms/features/users-permissions.md` over its sub-pages). + - Strip the `docusaurus/docs/` prefix and the `.md`/`.mdx` extension: `docusaurus/docs/cms/features/users-permissions.md` → `/cms/features/users-permissions`. + - If no `.md`/`.mdx` files are touched (rare for a docs PR), fall back to the root path (empty string). + +#### Assemble and verify + +4. Assemble the line (`<host>` from step 1/2, `<page-path>` with its leading `/`): + + ``` + Direct preview link 👉 [here](<host><page-path>) + ``` + +5. **Verify the URL resolves** before proposing it: + ```bash + curl -s -o /dev/null -w '%{http_code}' -L --max-time 25 "<url>" + ``` + A non-200 (or `000` host-resolution failure) means the host is wrong; re-derive from the Vercel comment (step 1) rather than the slug. Surface the status in the Reason line. + +6. Append the line as the last line of the proposed description, separated from the body by a blank line. + +### Examples + +- Long branch `cms/move-mcp-plugin-api-to-plugins-dev`: the Vercel comment yields host `https://documentation-git-cms-move-mcp-plugin-api-to-pl-704ff2-strapijs.vercel.app`; added page `cms/plugins-development/extend-mcp-server` → `https://documentation-git-cms-move-mcp-plugin-api-to-pl-704ff2-strapijs.vercel.app/cms/plugins-development/extend-mcp-server` +- Short branch `repo/contact-support-mention` (slug fallback safe) + page `cms/intro` → `https://documentation-git-repo-contact-support-mention-strapijs.vercel.app/cms/intro` + +### Edge cases + +- If the description already has a preview link **but it points to a wrong/outdated page** (e.g., the branch was renamed, or a different page is now more representative), the skill MAY propose a corrected line and surface the reason. Do not silently replace — surface the proposed change in the `Reason` so the user can opt out. +- For PRs from external forks, the standard `strapijs.vercel.app` pattern still works (Vercel deploys all branches under the strapijs subdomain), so no special handling needed. +- If the description body is itself compliant but the Vercel link is the ONLY missing piece, classify the PR as non-compliant on the basis of the missing link alone, and propose the addition. + +## Step 6: Final summary + +After all PRs are processed: + +``` +| PR# | Action | New title/description | +|-----|---------|------------------------| +| ... | edited | ... | +| ... | skipped | (unchanged) | +``` + +Include PRs classified as compliant in a separate count below the table (e.g., `Compliant (no changes needed): 5 PRs`). + +## Rules + +- In interactive mode (`AUTO=false`), never edit without explicit confirmation. +- In auto mode (`AUTO=true`), still respect the compliant filter — never rewrite content that already passes the rules. +- Never propose content that itself fails the rules. +- `title` action only modifies the title. `description`/`body` action only modifies the body. Cross-pollination is not allowed. +- If the rewrite would change meaning (not just form), surface that in the Reason line so the user can intervene. In auto mode, this is informational only — the edit still proceeds. + +## Examples + +Interactive title rewrite on a single PR: +``` +/inki:pr-fix title 3204 +``` + +Interactive description rewrite from a URL: +``` +/inki:pr-fix description https://github.com/strapi/documentation/pull/3204 +``` + +Body alias (same behavior as description): +``` +/inki:pr-fix body 3204 +``` + +Auto title rewrite on multiple PRs: +``` +/inki:pr-fix title --yes 3204 3202 #3199 +``` + +Auto title rewrite on all recent open PRs (with batch review): +``` +/inki:pr-fix title --yes +``` + +Auto title rewrite on all open PRs including stale ones: +``` +/inki:pr-fix title --yes --include-old +``` 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/research/SKILL.md b/claude-plugins/inki/skills/research/SKILL.md new file mode 100644 index 0000000000..47ff53b665 --- /dev/null +++ b/claude-plugins/inki/skills/research/SKILL.md @@ -0,0 +1,34 @@ +--- +name: research +description: "Top-level research 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:research — pre-writing research + +## 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/review/SKILL.md b/claude-plugins/inki/skills/review/SKILL.md new file mode 100644 index 0000000000..be22df6ad2 --- /dev/null +++ b/claude-plugins/inki/skills/review/SKILL.md @@ -0,0 +1,121 @@ +--- +name: review +description: "Top-level review orchestrator: runs style-check, outline-check, outline-ux-analyzer, code-verify, coherence-check, and pitfalls-check on a file, directory, or PR." +argument-hint: "[--yes|-y] [--fix] <path | filename | PR# | PR URL | docs.strapi.io URL | pasted content>" +user-invocable: true +--- + +# /inki:review — full documentation review + +## Step 0: Parse arguments + +From `$ARGUMENTS`, detect optional flags anywhere in the list: + +- `--yes` or `-y` → `AUTO=true` (non-interactive: skip any confirmation gates inside sub-skills) +- `--fix` → `FIX=true` (apply auto-fixable findings from `style-check`) + +Remove the flags. What remains is the **target**. + +## Step 1: Resolve target to a set of files + +Resolve the target by following `../../references/target-resolver.md`. It accepts any of: a local path or directory, a bare markdown filename, a GitHub PR (number, `#number`, or URL), a docs.strapi.io URL, pasted Markdown content, or nothing (changed files on the current branch). + +The resolver returns: + +- `FILES` — the list of local files the sub-skills operate on. +- `SCOPE` — a short label for the report header. +- `CLEANUP` — a command to run when the review finishes (worktree teardown or temp-file removal); may be empty. + +If resolution fails (PR has no doc files, filename not found, URL maps to nothing), report why and stop. + +## Step 2: Run the 6 sub-skills in parallel where possible + +For each file in `FILES`, invoke: + +- `/inki:style-check <target>` (with `--fix` if `FIX=true`) +- `/inki:outline-check <target>` +- `/inki:outline-ux-analyzer <target>` +- `/inki:code-verify <target>` +- `/inki:coherence-check <target>` +- `/inki:pitfalls-check <target>` + +If `AUTO=true`, pass `--yes` to any sub-skill that supports it (so the whole pipeline runs without prompts). Read-only sub-skills ignore the flag gracefully. + +Collect each report. + +## Step 3: Synthesize + +Output a combined table: + +``` +Review of: <SCOPE> + +| Sub-skill | Issues found | Severity | +|-----------|--------------|----------| +| style-check | <N> | low/med/high | +| outline-check | ... | ... | +| outline-ux-analyzer | ... | ... | +| code-verify | ... | ... | +| coherence-check | ... | ... | +| pitfalls-check | ... | ... | +``` + +Then list issues by file, ordered by severity. For PR-scope reviews, prefix file paths with `(PR #<num>)` so it's clear the issues are in the PR's version. For a `docs.strapi.io` URL review, note that the review ran against the published `origin/main` version, and flag any local uncommitted changes that were excluded (per the resolver). For a pasted-content review, note that coherence and code-verification findings may be incomplete because the file sits outside the docs tree (see the resolver's note). + +## Step 4: Cleanup + +Run the `CLEANUP` command returned by the resolver (worktree teardown or temp-file removal), even if the review failed. In a Claude-Code-driven execution, invoke it explicitly after Step 3 rather than relying on a bash `trap`. If `CLEANUP` is empty, there is nothing to do. + +## 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. +- `--fix` on a PR-scope review applies fixes inside the temporary worktree only (the one created by the resolver). The PR itself is NOT modified by `/inki:review`. To push the fixes, the user must `gh pr checkout <num>` themselves and apply the suggestions manually (or use `/inki:commit` + `/inki:push` after a manual checkout). +- `--fix` on a `docs.strapi.io` URL review applies fixes inside the temporary `origin/main` worktree only (created by the resolver); that worktree is detached and torn down at cleanup, so nothing is written back. Surface the corrected content in the report, and tell the user to apply it on a real branch. +- `--fix` on a pasted-content review applies fixes to the temp file only; there is no source file to write back to. Surface the corrected content in the report instead. +- `--yes` only changes interaction behavior (no extra prompts). It does NOT change what gets auto-fixed — that stays controlled by `--fix`. +- Never push, commit, or modify the PR directly. The review is read-only by default. + +## Examples + +Review a single file by path: +``` +/inki:review docusaurus/docs/cms/intro.md +``` + +Review by bare filename (resolved under `docusaurus/docs/`): +``` +/inki:review strapi-mcp-server.md +``` + +Review changed files on the current branch (no argument): +``` +/inki:review +``` + +Review all `.md`/`.mdx` files modified by a PR: +``` +/inki:review https://github.com/strapi/documentation/pull/3204 +/inki:review 3204 +/inki:review #3204 +``` + +Review a published page by its docs.strapi.io URL: +``` +/inki:review https://docs.strapi.io/cms/features/strapi-mcp-server +``` + +Review pasted Markdown content (paste the page body as the argument): +``` +/inki:review --- +title: My page +--- + +# My page +... +``` + +Non-interactive review with auto-fixes applied locally: +``` +/inki:review --yes --fix docusaurus/docs/cms/features/strapi-mcp-server.md +``` diff --git a/claude-plugins/inki/skills/route/SKILL.md b/claude-plugins/inki/skills/route/SKILL.md new file mode 100644 index 0000000000..fbbe69d97e --- /dev/null +++ b/claude-plugins/inki/skills/route/SKILL.md @@ -0,0 +1,41 @@ +--- +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 0: Parse the input + +`$ARGUMENTS` can be one of: + +- A bare PR number: `26847` +- A hashed PR number: `#26847` +- A full URL: `https://github.com/strapi/strapi/pull/26847` +- A URL with a sub-path: `https://github.com/strapi/strapi/pull/26847/files` + +Extract the trailing digits to obtain the PR number. A simple regex `[0-9]+$` (after stripping a trailing `/files`, `/commits`, etc. if present) is sufficient. If no numeric PR ID can be extracted, report the error and stop. + +## Step 1: Fetch the strapi/strapi PR + +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..7e17916abe --- /dev/null +++ b/claude-plugins/inki/skills/submit/SKILL.md @@ -0,0 +1,35 @@ +--- +name: submit +description: "Top-level orchestrator: branch (if needed), commit, push, then open a PR. Each step asks for confirmation before continuing, unless --yes is passed." +argument-hint: "[--yes|-y] [issue reference or topic hint, e.g. 'Fixes #2143']" +user-invocable: true +--- + +# /inki:submit — branch + commit + push + PR + +## Step 0: Parse arguments + +From `$ARGUMENTS`, detect `--yes` or `-y` anywhere in the list. If present, set `AUTO=true` and remove the flag. What remains is the optional issue reference passed through to `/inki: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. + +### Interactive (`AUTO=false`, default) + +The user confirms at each gate. If any sub-step fails or the user cancels, stop immediately. + +### Auto (`AUTO=true`) + +Pass `--yes` to each sub-skill that supports it. The chain runs without prompts. If any sub-skill genuinely needs a decision that isn't trivially auto-derivable (e.g., branch prefix is ambiguous and no hint was provided), it will still ask. `--yes` skips confirmations, not informed decisions. + +The safety bracket from `pr-fix` does NOT apply here, because `/inki:submit` operates only on the current branch (single PR scope by construction). + +## Rules + +- If any sub-step fails, stop. Do not skip a step. +- Pass through the issue reference (if any) to `/inki:pr`. +- In `AUTO=true` mode, surface a summary at the end showing branch name, commit SHA, and PR URL. diff --git a/claude-plugins/inki/skills/write/SKILL.md b/claude-plugins/inki/skills/write/SKILL.md new file mode 100644 index 0000000000..aad101d263 --- /dev/null +++ b/claude-plugins/inki/skills/write/SKILL.md @@ -0,0 +1,34 @@ +--- +name: write +description: "Top-level write orchestrator: outline a new page, get user approval, then draft from the outline." +argument-hint: "[--yes|-y] <topic brief or path to a brief file>" +user-invocable: true +--- + +# /inki:write — outline then draft + +## Step 0: Parse arguments + +From `$ARGUMENTS`, detect `--yes` or `-y` anywhere in the list. If present, set `AUTO=true` and remove the flag. What remains is the topic brief (text or path to a `.md` file). + +## Workflow + +### Interactive (`AUTO=false`, default) + +1. Invoke `/inki:outline $ARGUMENTS`. Wait for user approval inside that sub-skill. +2. Once an outline file exists and the user accepted it, invoke `/inki:draft <outline-path>`. + +If the user rejects the outline, stop. Do not draft. + +### Auto (`AUTO=true`) + +1. Invoke `/inki:outline --yes $ARGUMENTS`. The outline is generated and saved without an approval gate. +2. Immediately invoke `/inki:draft <outline-path>` on the resulting outline. + +In auto mode, the user sees the outline and the draft only after both are produced. They can still discard the outputs if they don't fit — nothing is committed automatically. `--yes` here means "don't pause between outline and draft," not "trust the output blindly." + +## Rules + +- Even in auto mode, do not skip the outline step. The outline must exist as a file before drafting. +- Do not invent facts beyond what the brief and template support. +- Do not commit, push, or open a PR. Use `/inki:submit` for that.