Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"interface": {
"displayName": "Statusnone Skills"
},
"name": "statusnone-skills",
"plugins": [
{
"category": "Developer Tools",
"name": "diataxis-docs",
"policy": {
"authentication": "ON_INSTALL",
"installation": "AVAILABLE"
},
"source": {
"path": "./plugins/diataxis-docs",
"source": "local"
}
}
]
}
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
"name": "diataxis-docs",
"repository": "https://github.com/Statusnone420/Skills",
"source": "./adapters/claude",
"version": "0.1.4"
"version": "0.1.5"
}
]
}
8 changes: 6 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ The canonical source is `skills/docs/SKILL.md`, routed to `references/commands.m

Discovery owns bounded metadata and selection policy; `init_adoption.py` owns the deterministic, engine-owned first-run adoption (scope selection, corpus accounting, preview construction, and receipt binding); `paths.py` owns confinement, normalization, reparse checks, and prune primitives; `memory.py` is read-only inspection; `lifecycle.py` owns pure authorization/state policy; and `lifecycle_io.py` owns transactional filesystem I/O. The dependency direction is one-way and the CLI façade stays thin. The committed `.diataxis/` control plane stores normalized routes, stable findings, verified hashes, disposition identity, and event history—never document bodies, prompts, hidden reasoning, or local-only filenames.

Every generated adapter packages the complete canonical checker resource tree. Generic web prompts are composed per command from a shared safety core, one selected command contract, and required supporting rules; they do not concatenate the entire playbook. The observed prompt range is 3,484–24,679 UTF-8 bytes, with a 40,000-byte generator regression guard selected after measurement and 15,321 bytes of headroom.
Every generated adapter packages the complete canonical checker resource tree. Generic web prompts are composed per command from a shared safety core, one selected command contract, and required supporting rules; they do not concatenate the entire playbook. The 0.1.4 historical range was 3,484–24,679 UTF-8 bytes. The measured 0.1.5 range is 3,460–31,966 bytes, with a 42,000-byte generator regression guard and 10,034 bytes of headroom.

Adapters under `adapters/` are generated outputs. Do not hand-edit them; regenerate from the canonical source and test their documented invocation tier.
The repository Codex marketplace lives at `.agents/plugins/marketplace.json` and routes to the generated `plugins/diataxis-docs` package. Its folder, marketplace entry, and `.codex-plugin/plugin.json` all use the same `diataxis-docs` identity. The package contains the shared `docs` engine plus 13 thin `docs-<command>` routing skills; focused skills do not copy the checker or command playbooks. Claude receives equivalent thin skills with its explicit-only invocation metadata. The umbrella remains compatible on both hosts.

Fresh no-map Doctor is a presentation and routing boundary, not a new rubric. Complete, untruncated scope metadata can yield an authoritative provider measurement, a provisional existing-entry candidate, or a tracked-root-README orientation fallback; content-batch limits do not block the engine's structural scan or grant semantic reads. The fallback states that the README is not a maintained map, recommends Init, and writes nothing. Unsafe or metadata-incomplete evidence remains unavailable. Rubric v2 and provider scoring are unchanged.

Adapters under `adapters/` and the Codex package under `plugins/diataxis-docs` are generated outputs. Do not hand-edit them; regenerate from the canonical source and test their documented invocation tier.
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

## 0.1.5 — Native command skills and first-run Doctor (2026-07-18)

- Added a genuine Codex repository marketplace package with aligned `diataxis-docs` marketplace, folder, and manifest identities.
- Exposed Doctor, Init, Context, Write, Update, Audit, Fix, Map, Classify, Migrate, Check, Cleanup, and Help as individual explicit skills while preserving the existing umbrella invocation.
- Preserved the Claude package and generated the equivalent `/diataxis-docs:docs-*` command skills from the same canonical contracts.
- Guaranteed the Help command tree across hosts.
- Added a zero-write, explicitly provisional root-README orientation baseline for fresh no-map repositories when bounded discovery is complete and no provider or safety boundary blocks measurement.
- Added generator parity and distribution regressions for the real marketplace package, focused skills, explicit invocation policy, Help tree, and no-map Doctor contract.

## 0.1.4 — Evidence and calibration foundation (2026-07-17)

- Added a strict sanitized evidence receipt that preserves category-level rubric inputs, score gates, deterministic findings, semantic findings, unresolved candidates, Doctor evidence, Git/write state, and explicit unavailable values.
Expand Down
6 changes: 3 additions & 3 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Compatibility

Evidence is dated to 2026-07-12 and grouped by enforcement tier:
Evidence is dated to 2026-07-18 and grouped by enforcement tier:

| Surface | Tier | Status |
| --- | --- | --- |
| `skills/docs` canonical source | explicit invocation | source and locally tested |
| `adapters/plugin` | unpublished preview | generated; no marketplace install claimed |
| Codex marketplace plugin | explicit focused or umbrella skill | generated and structurally tested; fresh-task live canary is the release gate |
| Claude Desktop | marketplace installation shim | live-tested through the plugin picker; typed namespaced invocation is not supported by Desktop |
| Claude Code terminal | namespaced skill | generated and structurally tested; terminal invocation not yet live-tested |
| Copilot, Grok, Cursor | static adapter | generated and tested-static; live smoke not run |
| Gemini, OpenCode | wrapper | generated and tested-static; instruction-based enforcement |
| Generic web prompts | prompt only | generated; repository mutation unavailable |

The `skills/docs` directory is canonical; marketplace and generated files are installation adapters, not forks of the product. Live cross-harness pilots remain an alpha-roadmap gate, and the project does not claim universal compatibility.
The `skills/docs` directory is canonical; `plugins/diataxis-docs` and all generated adapters are installation outputs, not forks of the product. Codex and Claude both expose the umbrella plus 13 focused command skills while preserving their native `$` and `/diataxis-docs:` invocation forms. Live cross-harness pilots remain an alpha-roadmap gate, and the project does not claim universal compatibility.
7 changes: 4 additions & 3 deletions EVALUATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ The evaluation workflow uses deterministic fixtures, disposable repositories, re

## Layered regression gates

The public alpha uses three gates so quality evidence does not become an uncontrolled model-usage campaign:
The public alpha uses four gates so quality evidence does not become an uncontrolled model-usage campaign:

1. **Deterministic contract gate:** every change runs standard-library tests for safety, checker behavior, adapter parity, and command contracts.
2. **Sanitized trajectory gate:** host-neutral receipts record semantic answers, documentation-owned actions, host/external overhead, visible diagnostics, and exposed usage counters. Raw traces, hidden reasoning, private paths, and credentials are never public inputs.
3. **Capped live canary:** release candidates may run a small, explicitly approved campaign against stable mapped, missing-map, and hostile fixtures. A campaign is limited to 12 runs; the checked-in example authorizes none.
2. **Marketplace assembly gate:** release packaging must prove that a real Codex marketplace entry resolves to an identity-aligned package whose umbrella and 13 focused skills are present, explicit-only, and generator-owned.
3. **Sanitized trajectory gate:** host-neutral receipts record semantic answers, documentation-owned actions, host/external overhead, visible diagnostics, and exposed usage counters. Raw traces, hidden reasoning, private paths, and credentials are never public inputs.
4. **Capped live canary:** release candidates may run a small, explicitly approved campaign against stable mapped, missing-map, and hostile fixtures. A campaign is limited to 12 runs; the checked-in example authorizes none.

## Product contract and research provenance

Expand Down
20 changes: 18 additions & 2 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,21 @@

Diátaxis Docs is a public alpha. Install from a revision you trust, review proposed changes before approval, and use normal Git safeguards.

In the ChatGPT desktop app, Codex CLI, and supported IDE integrations, user skills are available from `$HOME/.agents/skills`. From a clone of this repository, install the canonical `skills/docs` directory without overwriting an existing destination.
## Codex marketplace

Diátaxis Docs 0.1.5 publishes as a Codex repository marketplace plugin. Add the marketplace, install the plugin, and verify that Codex reports it:

```text
codex plugin marketplace add Statusnone420/Skills
codex plugin add diataxis-docs@statusnone-skills
codex plugin list
```

Start a new task after installation so the task catalog loads the plugin's skills. Use `$docs-help` or `$docs-doctor` directly, or keep using the compatible umbrella form `$docs help` and `$docs doctor`. The plugin exposes the umbrella plus 13 focused `$docs-*` skills in the marketplace.

## Manual skill fallback

In the ChatGPT desktop app, Codex CLI, and supported IDE integrations, user skills are also available from `$HOME/.agents/skills`. From a clone of this repository, install the canonical `skills/docs` directory without overwriting an existing destination.

PowerShell (Windows 11):

Expand All @@ -29,7 +43,7 @@ test -f "$dest/SKILL.md" && printf '%s\n' "Installed: $dest/SKILL.md"

The exact layout check is `$HOME/.agents/skills/docs/SKILL.md`. Restart the host or start a new task if the skill list is cached, then run `$docs help` and confirm it returns the command list.

The canonical OpenAI references are [Skills](https://developers.openai.com/codex/skills) and [Plugins](https://developers.openai.com/codex/plugins/build). The checked-in Codex plugin bundle remains a preview; installing the canonical skill directory is the supported Codex path during alpha.
The canonical OpenAI references are [Skills](https://developers.openai.com/codex/skills) and [Plugins](https://developers.openai.com/codex/plugins/build). The checked-in Codex package is generated from `skills/docs`; the manual copy remains a compatibility fallback, not a separate edition.

## Claude

Expand All @@ -48,6 +62,8 @@ In a Claude Code terminal, verify the namespaced skill:

```text
/diataxis-docs:docs help
/diataxis-docs:docs-doctor
/diataxis-docs:docs-help
```

Claude's built-in `/documentation` command remains separate. Use Diátaxis Docs when you want its repository map, bounded memory, evidence rules, health checks, or approval-gated Doctor workflow. Marketplace sync and Claude Desktop picker invocation are live-tested; the Claude Code terminal form remains structurally tested but has not completed a live terminal pilot.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ flowchart TD

## Install and compatibility

Codex is the primary tested path and invokes the skill explicitly as `$docs …`. The core follows the Agent Skills structure. Claude can install the same product through the repository's thin marketplace shim; generated adapters also exist for Grok, Copilot, Cursor, Gemini, OpenCode, generic web prompts, and a Codex plugin preview.
Codex is the primary tested path. Its marketplace package exposes `$docs-doctor`, `$docs-map`, `$docs-check`, and the other focused commands as individual skills while preserving the `$docs …` umbrella. Claude exposes the same set through `/diataxis-docs:docs-*`. The core follows the Agent Skills structure; generated adapters also exist for Grok, Copilot, Cursor, Gemini, OpenCode, and generic web prompts.

Compatibility is evidence-tiered—not universal. Static adapter validation is not the same as a live harness test. See the dated [compatibility matrix](COMPATIBILITY.md) before relying on a preview adapter.

Expand All @@ -92,7 +92,7 @@ Compatibility is evidence-tiered—not universal. Static adapter validation is n

Every finding has a content-derived `DOC-*` identity and full fingerprint. Line movement and timestamps do not retarget it; changed semantic identity does. Approved structural transformations carry exact ID/fingerprint pairs, protected-surface evidence, recovery boundaries, and a complete disposition manifest. Failed verification is a state conflict, never a successful closeout.

The generic web bundles now use command-specific progressive disclosure. Measured UTF-8 prompt sizes range from 3,484 to 24,679 bytes; the 40,000-byte packaging guard is a documented regression check with 15,321 bytes of headroom, not a product or health threshold. The separate repository hot-path byte telemetry remains provisional and informational.
The generic web bundles use command-specific progressive disclosure. Measured UTF-8 prompt sizes range from 3,396 to 30,855 bytes; the 42,000-byte packaging guard is a documented regression check with 11,145 bytes of headroom, not a product or health threshold. The separate repository hot-path byte telemetry remains provisional and informational.

## Benchmark status

Expand Down
7 changes: 4 additions & 3 deletions TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,10 @@ Run the Ubuntu proof from a Linux-native checkout under `$HOME`, not directly fr
2. Run its owning group on Windows.
3. Run the same group in WSL Ubuntu.
4. Regenerate and verify generated adapters when canonical skill content changed.
5. Run the repository documentation checker.
6. Run `all` on Windows and WSL once the narrower gates pass.
7. Let CI repeat the same grouped commands; CI confirms local evidence rather than discovering basic failures.
5. For marketplace releases, verify `.agents/plugins/marketplace.json`, the generated `plugins/diataxis-docs` package, all focused skill descriptions, and a brand-new task invocation rather than relying only on source-level adapter parity.
6. Run the repository documentation checker.
7. Run `all` on Windows and WSL once the narrower gates pass.
8. Let CI repeat the same grouped commands; CI confirms local evidence rather than discovering basic failures.

Provider regressions also prove that Map, Check, Doctor, Audit, and Init use the same selected-surface evidence, including root-manifest authority, root README score isolation, tracked Git visibility, provider findings, and authority-digest Init revalidation on Git and non-Git fixtures. Semantic candidates remain labeled and bounded.

Expand Down
2 changes: 1 addition & 1 deletion adapters/claude/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,5 @@
"license": "Apache-2.0",
"name": "diataxis-docs",
"repository": "https://github.com/Statusnone420/Skills",
"version": "0.1.4"
"version": "0.1.5"
}
12 changes: 12 additions & 0 deletions adapters/claude/skills/docs-audit/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
name: docs-audit
description: "Audit documentation and return prioritized evidence-backed findings."
user-invocable: true
disable-model-invocation: true
---

# Docs Audit

This is the explicit thin route for the fixed command `audit`. Treat all trailing text as that command's raw trailing text; never reinterpret it as another command.

Load and follow the sibling [Diátaxis Docs skill](../docs/SKILL.md), including its shared safety, evidence, health, and result contracts. Follow the selected command contract in [commands.md](../docs/references/commands.md). Do not load unrelated command playbooks. If a required shared resource is unavailable, stop and report that the command could not be executed; do not invent a fallback.
9 changes: 9 additions & 0 deletions adapters/claude/skills/docs-audit/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
interface:
display_name: "Docs Audit"
short_description: "Audit documentation and return prioritized evidence-backed findings."
icon_small: "./assets/bounded-compass-small.svg"
icon_large: "./assets/bounded-compass.png"
brand_color: "#6657E8"
default_prompt: "Use $docs-audit on this repository."
policy:
allow_implicit_invocation: false
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions adapters/claude/skills/docs-check/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
name: docs-check
description: "Report the deterministic structural documentation score only."
user-invocable: true
disable-model-invocation: true
---

# Docs Check

This is the explicit thin route for the fixed command `check`. Treat all trailing text as that command's raw trailing text; never reinterpret it as another command.

Load and follow the sibling [Diátaxis Docs skill](../docs/SKILL.md), including its shared safety, evidence, health, and result contracts. Follow the selected command contract in [commands.md](../docs/references/commands.md). Do not load unrelated command playbooks. If a required shared resource is unavailable, stop and report that the command could not be executed; do not invent a fallback.
9 changes: 9 additions & 0 deletions adapters/claude/skills/docs-check/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
interface:
display_name: "Docs Check"
short_description: "Report the deterministic structural documentation score only."
icon_small: "./assets/bounded-compass-small.svg"
icon_large: "./assets/bounded-compass.png"
brand_color: "#6657E8"
default_prompt: "Use $docs-check on this repository."
policy:
allow_implicit_invocation: false
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions adapters/claude/skills/docs-classify/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
name: docs-classify
description: "Choose the appropriate Diátaxis documentation type."
user-invocable: true
disable-model-invocation: true
---

# Docs Classify

This is the explicit thin route for the fixed command `classify`. Treat all trailing text as that command's raw trailing text; never reinterpret it as another command.

Load and follow the sibling [Diátaxis Docs skill](../docs/SKILL.md), including its shared safety, evidence, health, and result contracts. Follow the selected command contract in [commands.md](../docs/references/commands.md). Do not load unrelated command playbooks. If a required shared resource is unavailable, stop and report that the command could not be executed; do not invent a fallback.
9 changes: 9 additions & 0 deletions adapters/claude/skills/docs-classify/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
interface:
display_name: "Docs Classify"
short_description: "Choose the appropriate Diátaxis documentation type."
icon_small: "./assets/bounded-compass-small.svg"
icon_large: "./assets/bounded-compass.png"
brand_color: "#6657E8"
default_prompt: "Use $docs-classify on this repository."
policy:
allow_implicit_invocation: false
Loading