structured-doc-validate

Name: structured-doc-validate
Author: PriNova

80stars2forks

How to install structured-doc-validate?

prinova/pi-agent-codebase-workflows/structured-doc-validate

$npx -y skills add PriNova/pi-agent-codebase-workflows --skill structured-doc-validate

Installs into the current project.

Summary

Validate canonical structured YAML artifacts for schema shape, reference integrity, evidence quality, coverage, and granularity. Read-only by default; no legacy prose docs.

Files · 1

View on GitHub

SKILL.md

1	# Structured Docs Validation
2
3	Goal: audit canonical structured YAML artifacts so agents can trust, repair, or safely avoid stale project context.
4
5	## Structured Artifact API Contract
6
7	Legacy prose artifacts are deprecated. Do not create, update, or rely on `docs/agent/*.md`, scoped prose docs, or generated human-readable Markdown views. Use structured YAML as the source of truth. Root `AGENTS.md` is only harness interoperability output from workflows that explicitly produce it.
8
9	Resolved structured docs root:
10
11	Treat `docs/agent/api` as a logical layout rooted at a resolved structured docs root, not a fixed repo path.
12
13	Resolution rules:
14	1. Resolve `workspace_root` with `git rev-parse --show-toplevel 2>/dev/null` or fallback to `pwd`.
15	2. Canonicalize `workspace_root` before fingerprinting when possible (`realpath`, `pwd -P`, `Path(...).resolve()`, or equivalent).
16	3. `structured-doc-validate` reads repo-local only when `<workspace_root>/docs/agent/api` already exists.
17	4. Otherwise read the global overlay root: `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`.
18	5. Compute `<workspace-fingerprint>` exactly from canonical `workspace_root`: strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, then wrap with `--`.
19	6. Example: `/data/data/com.termux/files/home/CodeProjects/pi-mono` -> `--data-data-com.termux-files-home-CodeProjects-pi-mono--`.
20	7. Do not create new repo-local structured docs in unadopted repos unless the user explicitly asks for repo-local adoption there.
21
22	Logical structured layout under the resolved docs root:
23
24	```text
25	repo/
26	scopes.yaml
27	repo-inventory.yaml
28	project-intent.yaml
29	architecture.yaml
30	data-flow.yaml
31	data-model.yaml
32	invariants.yaml
33	dependency-rules.yaml
34	design-issues.yaml
35	risk-register.yaml
36	change-guide.yaml
37	testing-strategy.yaml
38	validation-baseline.yaml
39	contracts.yaml
40	adr.yaml
41	agent-operating-guide.yaml
42	scopes/
43	by-path/<repo-relative-path>/...
44	by-domain/<slug>/...
45	```
46
47	Every structured artifact should conform to `../_shared/references/schemas/common.schema.json` plus its artifact-specific schema. Stable IDs include `scope:`, `component:`, `entity:`, `invariant:`, `risk:`, `contract:`, `flow:`, `command:`, `issue:`, `adr:`, and `testplan:*`.
48
49	## Runtime Schema Loading
50
51	When validating structured artifacts, read `../_shared/references/artifact-api.md` first. Then read only the shared skill package schemas needed for artifacts being validated:
52	- `../_shared/references/schemas/common.schema.json`
53	- `../_shared/references/schemas/<artifact-file-base>.schema.json`
54
55	Do not read all schemas unless the validation target is the whole docs root. Do not use templates. Schemas are runtime API contracts; project docs outside the shared runtime refs are maintainer aids unless the user asks about this package itself.
56
57	## Invocation
58
59	Use this skill directly or use `/validate-structured-docs` as the prompt-template shortcut.
60
61	Supported tasks:
62	- Validate structured docs for this repo/docs root.
63	- Audit docs after this diff.
64	- Check whether docs are granular enough for agent workflows.
65	- Find stale evidence or invalid refs.
66	- Report documentation quality without editing artifacts.
67
68	## Rules
69
70	- Read-only by default. Do not edit code or artifacts unless the user explicitly asks for repair.
71	- Do not read legacy prose Markdown docs.
72	- Resolve `<docs-root>` exactly before reading artifacts.
73	- If a focus is provided, read `<docs-root>/repo/scopes.yaml` first when present and select matching scope artifacts by longest path prefix or explicit domain match.
74	- If no focus is provided, validate repo-level artifacts first, then scoped artifacts as context budget allows.
75	- Prefer exact, evidence-backed findings over broad opinions.
76	- Broken schemas, missing shared schema coverage for canonical artifact files, parse failures, and dangling refs are errors. Fuzzy evidence, coverage, and granularity concerns are warnings unless they block safe use.
77	- If structured artifacts predate newer schema requirements, missing now-required fields are schema errors, not compatibility notes.
78	- Every finding must include artifact path, record ID when available, severity, evidence, impact, and recommended next step.
79	- If a validation command exists in `validation-baseline.yaml`, prefer running or recommending that command; otherwise validate by inspection and targeted shell checks.
80
81	## Four-Layer Validation Workflow
82
83	### 1. Schema validity
84
85	Check:
86	- YAML parses cleanly.
87	- Every canonical artifact file being validated has matching shared schema coverage.
88	- Common envelope fields exist and are consistently shaped.
89	- Artifact-specific top-level keys match the matching schema.
90	- Required arrays/items are present, including newer req

People who liked this also viewed

6 picks

Type

structured-doc-validate

80stars2forks

View on GitHub

How to install structured-doc-validate?

prinova/pi-agent-codebase-workflows/structured-doc-validate

$npx -y skills add PriNova/pi-agent-codebase-workflows --skill structured-doc-validate

Installs into the current project.

Summary

Validate canonical structured YAML artifacts for schema shape, reference integrity, evidence quality, coverage, and granularity. Read-only by default; no legacy prose docs.

Files · 1

View on GitHub

SKILL.md

1	# Structured Docs Validation
2
3	Goal: audit canonical structured YAML artifacts so agents can trust, repair, or safely avoid stale project context.
4
5	## Structured Artifact API Contract
6
7	Legacy prose artifacts are deprecated. Do not create, update, or rely on `docs/agent/*.md`, scoped prose docs, or generated human-readable Markdown views. Use structured YAML as the source of truth. Root `AGENTS.md` is only harness interoperability output from workflows that explicitly produce it.
8
9	Resolved structured docs root:
10
11	Treat `docs/agent/api` as a logical layout rooted at a resolved structured docs root, not a fixed repo path.
12
13	Resolution rules:
14	1. Resolve `workspace_root` with `git rev-parse --show-toplevel 2>/dev/null` or fallback to `pwd`.
15	2. Canonicalize `workspace_root` before fingerprinting when possible (`realpath`, `pwd -P`, `Path(...).resolve()`, or equivalent).
16	3. `structured-doc-validate` reads repo-local only when `<workspace_root>/docs/agent/api` already exists.
17	4. Otherwise read the global overlay root: `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`.
18	5. Compute `<workspace-fingerprint>` exactly from canonical `workspace_root`: strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, then wrap with `--`.
19	6. Example: `/data/data/com.termux/files/home/CodeProjects/pi-mono` -> `--data-data-com.termux-files-home-CodeProjects-pi-mono--`.
20	7. Do not create new repo-local structured docs in unadopted repos unless the user explicitly asks for repo-local adoption there.
21
22	Logical structured layout under the resolved docs root:
23
24	```text
25	repo/
26	scopes.yaml
27	repo-inventory.yaml
28	project-intent.yaml
29	architecture.yaml
30	data-flow.yaml
31	data-model.yaml
32	invariants.yaml
33	dependency-rules.yaml
34	design-issues.yaml
35	risk-register.yaml
36	change-guide.yaml
37	testing-strategy.yaml
38	validation-baseline.yaml
39	contracts.yaml
40	adr.yaml
41	agent-operating-guide.yaml
42	scopes/
43	by-path/<repo-relative-path>/...
44	by-domain/<slug>/...
45	```
46
47	Every structured artifact should conform to `../_shared/references/schemas/common.schema.json` plus its artifact-specific schema. Stable IDs include `scope:`, `component:`, `entity:`, `invariant:`, `risk:`, `contract:`, `flow:`, `command:`, `issue:`, `adr:`, and `testplan:*`.
48
49	## Runtime Schema Loading
50
51	When validating structured artifacts, read `../_shared/references/artifact-api.md` first. Then read only the shared skill package schemas needed for artifacts being validated:
52	- `../_shared/references/schemas/common.schema.json`
53	- `../_shared/references/schemas/<artifact-file-base>.schema.json`
54
55	Do not read all schemas unless the validation target is the whole docs root. Do not use templates. Schemas are runtime API contracts; project docs outside the shared runtime refs are maintainer aids unless the user asks about this package itself.
56
57	## Invocation
58
59	Use this skill directly or use `/validate-structured-docs` as the prompt-template shortcut.
60
61	Supported tasks:
62	- Validate structured docs for this repo/docs root.
63	- Audit docs after this diff.
64	- Check whether docs are granular enough for agent workflows.
65	- Find stale evidence or invalid refs.
66	- Report documentation quality without editing artifacts.
67
68	## Rules
69
70	- Read-only by default. Do not edit code or artifacts unless the user explicitly asks for repair.
71	- Do not read legacy prose Markdown docs.
72	- Resolve `<docs-root>` exactly before reading artifacts.
73	- If a focus is provided, read `<docs-root>/repo/scopes.yaml` first when present and select matching scope artifacts by longest path prefix or explicit domain match.
74	- If no focus is provided, validate repo-level artifacts first, then scoped artifacts as context budget allows.
75	- Prefer exact, evidence-backed findings over broad opinions.
76	- Broken schemas, missing shared schema coverage for canonical artifact files, parse failures, and dangling refs are errors. Fuzzy evidence, coverage, and granularity concerns are warnings unless they block safe use.
77	- If structured artifacts predate newer schema requirements, missing now-required fields are schema errors, not compatibility notes.
78	- Every finding must include artifact path, record ID when available, severity, evidence, impact, and recommended next step.
79	- If a validation command exists in `validation-baseline.yaml`, prefer running or recommending that command; otherwise validate by inspection and targeted shell checks.
80
81	## Four-Layer Validation Workflow
82
83	### 1. Schema validity
84
85	Check:
86	- YAML parses cleanly.
87	- Every canonical artifact file being validated has matching shared schema coverage.
88	- Common envelope fields exist and are consistently shaped.
89	- Artifact-specific top-level keys match the matching schema.
90	- Required arrays/items are present, including newer req

People who liked this also viewed

6 picks

Type