Skip to content

Commit 3003f16

Browse files
gregsdennisgregsdennis
committed
add ai instructions
1 parent c0b626e commit 3003f16

11 files changed

Lines changed: 259 additions & 0 deletions

‎.github/copilot-instructions.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copilot Instructions
2+
3+
This file is a mandatory entry point for AI agents working in this repository.
4+
5+
## Required Preflight (Blocking)
6+
7+
Before any analysis, search, planning, code edits, test execution, or other tool use, read this file using a tool call:
8+
9+
1. `.github/instructions/workflow.instructions.md`
10+
11+
That file defines all further required reads. Follow every step in it.
12+
13+
If this preflight cannot be completed, stop and ask the user how to proceed.
14+
15+
Do not treat this as optional guidance.

‎.github/instructions/apis.instructions.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# APIs
6+
7+
This repository documents APIs; it does not define runtime API behavior.
8+
9+
- Treat `_docs/api/**` as generated reference content synced from the main `json-everything` repository.
10+
- Do not hand-edit generated API member pages unless explicitly requested for a one-off docs hotfix.
11+
- Preferred flow for API reference changes:
12+
1. Update source comments or API docs generator behavior in the main repository.
13+
2. Regenerate/sync API docs into this repo.
14+
3. Validate navigation, permalinks, and rendering in this repo.
15+
- Safe manual edits in this repo are usually limited to navigation wrappers (for example API section title/close pages) and cross-links outside generated member content.
16+
17+
When a request mixes product behavior and docs behavior, document current behavior and call out uncertainty instead of inventing API semantics.

‎.github/instructions/architecture.instructions.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# Architecture
6+
7+
This repository is a Jekyll documentation site (Chirpy-based) for the `json-everything` ecosystem.
8+
9+
## Major Areas
10+
11+
- `_docs/`: Primary authored content collection. Each page is rendered as documentation content.
12+
- `_docs/api/`: Generated API reference pages (sync target, not primary authoring surface).
13+
- `_layouts/`, `_includes/`, `_sass/`, `_javascript/`: Theme and rendering customizations.
14+
- `_data/`: Site data (locales, contact links, sharing config, asset settings).
15+
- `assets/`: Static assets served by the site.
16+
- `tools/`, `run.*`, `init.*`: Local helper scripts.
17+
- `_site/`: Build output only. Never hand-edit.
18+
19+
## Content Organization
20+
21+
- Documentation pages are files under `_docs/**` with front matter.
22+
- Navigation hierarchy is controlled by front matter (`order`, `bookmark`, `folder`, `separator`) and directory structure.
23+
- Permalinks are generally section-scoped and explicitly set for many pages.
24+
25+
## Change Boundaries
26+
27+
- Prefer content edits in `_docs/**` for documentation requests.
28+
- Touch templates/assets only when the request needs presentation or behavior changes.
29+
- Do not commit intentional edits to generated output under `_site/`.
30+
- Keep changes targeted; avoid broad refactors to theme/template code during content tasks.

‎.github/instructions/code-style.instructions.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
applyTo: "**/*.{html,md,markdown,css,scss,js,mjs,ts,yml,yaml,rb}"
3+
---
4+
5+
# Code Style
6+
7+
Follow repository formatting configuration first:
8+
9+
- `.editorconfig` is authoritative for indentation, charset, line endings, and final newline.
10+
- `.prettierrc` is authoritative where Prettier is used.
11+
- `.stylelintrc.json` is authoritative for SCSS/CSS lint behavior.
12+
13+
## Markdown and Docs Content
14+
15+
- Use valid YAML front matter for docs pages.
16+
- Use 2-space indentation for documentation files and front matter.
17+
- Keep existing front matter key conventions when editing pages:
18+
- content pages commonly include `layout`, `title`, `bookmark`, `permalink`, `order`.
19+
- section wrapper pages may use `folder: true`, `separator: true`, and `close: true`.
20+
- Preserve permalink and heading anchor stability unless the task explicitly asks to change URLs.
21+
- Keep code fences language-tagged where possible.
22+
- In markdown `c#`/`csharp` fenced code blocks, use 4-space indentation for code.
23+
24+
## Jekyll/Liquid/Theme Files
25+
26+
- Match the surrounding Liquid and HTML style in each file; do not reformat unrelated blocks.
27+
- Keep include/layout changes minimal and scoped to the requested behavior.
28+
- Avoid introducing new template abstractions unless reuse is clear and requested.
29+
30+
## JS/SCSS
31+
32+
- Run `npm run test` after SCSS changes when possible.
33+
- Run `npm run build` after JS changes that affect bundled assets.
34+
- Keep vendor-prefix and stylelint rule exceptions aligned with `.stylelintrc.json`; do not invent local deviations without reason.

‎.github/instructions/commands.instructions.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# Commands
6+
7+
Use these as safe defaults when working in this repository.
8+
9+
## Setup
10+
11+
- Install JS dependencies and build JS bundle:
12+
- Windows: `init.bat`
13+
- Unix: `./init.sh`
14+
- Equivalent manual steps:
15+
- `npm install`
16+
- `npm run build`
17+
- `bundle install`
18+
19+
## Local Development
20+
21+
- Start local site with incremental rebuild and live reload:
22+
- Windows: `run.bat`
23+
- Unix: `./run.sh`
24+
- Direct Jekyll serve equivalent:
25+
- `bundle exec jekyll serve --incremental --livereload`
26+
27+
## Validation
28+
29+
- SCSS lint: `npm run test`
30+
- Rebuild JS assets: `npm run build`
31+
- Full site build: `bundle exec jekyll build`
32+
- Link/content validation (when htmlproofer is available):
33+
- Unix: `./tools/test`
34+
35+
## Agent Safety Rules
36+
37+
- Do not run `tools/init` unless explicitly requested; it performs destructive git operations (`git reset --hard`) as part of template initialization.
38+
- Do not run release scripts for routine docs edits.
39+
- Prefer the smallest validation set that matches the change scope, then report what was and was not executed.

‎.github/instructions/domain-knowledge.instructions.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# Domain Knowledge
6+
7+
This site documents multiple libraries in the `json-everything` ecosystem plus generated API reference and release notes.
8+
9+
## Documentation Taxonomy
10+
11+
- `_docs/schema`, `_docs/pointer`, `_docs/path`, `_docs/patch`, `_docs/logic`, `_docs/json-e`, `_docs/yaml`, etc. are product/topic sections.
12+
- `_docs/release-notes` contains versioned change logs by library. These are edited in the main `json-everything` repository and copied here. Do not edit release note pages in this repo.
13+
- `_docs/api` is API reference content, generally generated. Do not edit generated API member pages in this repo.
14+
15+
## Terminology and Naming
16+
17+
- Prefer official library naming as used in existing docs (for example `JsonSchema.Net`, `JsonLogic`, `JsonE.Net`).
18+
- Distinguish clearly between:
19+
- JSON Schema specification behavior.
20+
- `json-everything` implementation behavior.
21+
- For behavior claims, prefer explicit wording and examples over marketing language.
22+
23+
## Cross-Linking and Versions
24+
25+
- Prefer relative links to pages within this site.
26+
- Use stable external links to specs and official project resources where helpful.
27+
- When documenting version-specific behavior, name the library/package and version explicitly.
28+
29+
## Voice and Audience
30+
31+
- Audience is developers using .NET libraries and adjacent JSON tooling.
32+
- Keep voice technical, direct, and pragmatic.
33+
- Aim for friendly but not personal: approachable and human, but not informal or chatty.
34+
- Prefer active voice and concrete behavior statements over abstract wording.
35+
- Include concise examples when they reduce ambiguity.
36+
- Distinguish style by content type:
37+
- Tutorial/basics pages: explanatory with practical examples.
38+
- Warnings and gotchas: explicit about risk and impact.
39+
- Prefer precision over promotion:
40+
- State defaults, constraints, edge cases, and failure behavior.
41+
- Avoid marketing language and unsupported claims.

‎.github/instructions/instructions.instructions.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
applyTo: ".github/instructions/*.instructions.md"
3+
---
4+
5+
# Instruction Files
6+
7+
Guidance for editing instruction files in this repository.
8+
9+
- Keep instructions concise, actionable, and testable.
10+
- Avoid contradictions across instruction files.
11+
- Update workflow references when adding or removing instruction files.
12+
- Prefer incremental updates over large rewrites.
13+
- Keep examples and commands synchronized with actual repository scripts and config.
14+
- Use imperative phrasing for required behavior (for example: "Do X", "Do not Y").
15+
- When introducing a new rule, place it in the most specific instruction file and avoid duplicating it broadly.

‎.github/instructions/workflow.instructions.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# Agent Workflow
6+
7+
This file defines how AI agents MUST orient themselves before making changes in this repository.
8+
9+
Each step in this section MUST be executed as an explicit tool call. A step MUST NOT be skipped; having a file's content already in context is not a valid reason to omit the tool call.
10+
11+
## Before Making Any Code Changes
12+
13+
1. List instruction files in `.github/instructions/*.instructions.md` and read relevant files for the task.
14+
2. The following files MUST always be read via explicit tool calls before any other action:
15+
- `workflow.instructions.md`
16+
- `commands.instructions.md`
17+
- `personal-preferences.instructions.md`
18+
3. Read additional files by concern:
19+
- `code-style.instructions.md` when editing HTML, CSS, JS, Jekyll templates, or Ruby scripts.
20+
- `architecture.instructions.md` when changing repository structure, tooling, or build pipeline.
21+
- `domain-knowledge.instructions.md` when editing site content conventions or docs information architecture.
22+
- `instructions.instructions.md` when editing `.instructions.md` files.
23+
4. For formatting and style, treat `.editorconfig`, `.prettierrc`, and `.stylelintrc.json` as authoritative where applicable.
24+
5. Prefer minimal, targeted changes. Do not refactor unrelated code.
25+
26+
## Principles
27+
28+
- Treat instruction files as the desired state for future contributions.
29+
- Keep changes aligned with a documentation-first workflow.
30+
- Add or update validation where practical for behavioral changes.
31+
- Keep instructions dynamic. If feedback reveals a missing or incorrect rule, update instruction files alongside the fix.
32+
33+
## Docs-First Defaults
34+
35+
- Default to editing documentation content under `_docs/**` unless the request clearly requires theme/script changes.
36+
- Treat `_docs/api/**` as generated/synced content and avoid manual member-page edits.
37+
- Avoid touching `_site/**` except as transient local build output.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ node_modules
1919

2020
# Misc
2121
assets/js/dist
22+
.github/instructions/personal-preferences.instructions.md

‎AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# AGENTS.md
2+
3+
This file is a mandatory entry point for AI agents working in this repository.
4+
5+
## Required Preflight (Blocking)
6+
7+
Before any analysis, search, planning, code edits, test execution, or other tool use, read this file using a tool call:
8+
9+
1. `.github/instructions/workflow.instructions.md`
10+
11+
That file defines all further required reads. Follow every step in it.
12+
13+
If this preflight cannot be completed, stop and ask the user how to proceed.
14+
15+
Do not treat this as optional guidance.

0 commit comments

Comments
 (0)