Two files, one repository
vctmasters1/PDS-Layered-AI-Instruct-Template-V5 ships 5 formats across 5 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 10 | 4 | 0% |
| Commands | 0 | 1 | 0 | 0% |
| Section tags | 1 | 1 | 1 | 33% |
What each file covers
Sections
0 shared · 10 only in A · 4 only in B- − AGENTS.md — Entry Point for AI Coding Agents
- − 🚀 The Core Feature: Routing Gateway
- − Where the rules live
- − Quick reference
- − **CRITICAL: Import/Merge Workflows are Governed**
- − Tool compatibility
- − Adopting this template
- − Autonomous layer (opt-in, disabled by default)
- − How to enable
- − Limitations (intentional)
- + CLAUDE.md — Claude Code pointer
- + Project rules location
- + Cross-cutting rules
- + Do not
Commands
0 shared · 1 only in A · 0 only in B- − git clone
Section tags
1 shared · 1 only in A · 1 only in B- − git-pr
- + agent-behaviour
- do-not
Line diff
vctmasters1/PDS-Layered-AI-Instruct-Template-V5 · AGENTS.md
@@ −1 @@
1# AGENTS.md — Entry Point for AI Coding Agents
2
3> **READ THIS FIRST.** This file is the **discovery anchor** for any AI agent or tool entering this repository.
4> This repository uses the **Depth-Priority Hierarchical AI-INSTRUCT V6** system with unified `.hi/` governance and **Routing Gateway** at its core.
5
6## 🚀 The Core Feature: Routing Gateway
7
8**Every major workflow in this project flows through `/ai-route`** — a central orchestration layer that:
9
10✅ Resolves which `.hi/instruct.md` is authoritative for your current scope
11✅ Applies governance rules automatically
12✅ Routes to the domain manager/supervisor that owns that scope
13✅ Logs all decisions for audit trails
14✅ Halts gracefully on conflicts
15
16**This is not optional.** It is the **defining feature** that makes depth-priority hierarchy practical at scale.
17
18→ **Start with [The Routing Gateway](.github/copilot-instructions.md#the-routing-gateway--core-orchestration-layer)** in `.github/copilot-instructions.md` (2-min read)
19
20## Where the rules live
21
22Rules are stored as per-directory `.hi/instruct.md` files. **Deeper always wins.**
23
24Start here, in this order:
25
261. **[The Routing Gateway](.github/copilot-instructions.md#the-routing-gateway--core-orchestration-layer)** in `.github/copilot-instructions.md` — WHY routing exists, how it works, which workflows use it (start here 🚀)
272. [.github/copilot-instructions.md](.github/copilot-instructions.md) — META: complete layering system (read once per session)
283. [.github/dev-specs.md](.github/dev-specs.md) — **CRITICAL**: Read the Project Mode field (Template Development vs Production) before any other decision. Then: Platform, shell, language, frameworks. If template-empty, run `/hip-onboard` to fill values.
294. [.hi/index.md](.hi/index.md) — Master index of every instruction section. Jump from here to the canonical source for any topic.
305. [.hi/instruct.md](.hi/instruct.md) — Root-level project authority. Confirms the [Routing & Orchestration Gateway](.hi/instruct.md#routing--orchestration-gateway) section.
316. `[module]/.hi/instruct.md` — Module-level authority. Authoritative when working inside that module.
32
33## Quick reference
34
35| If you are looking for… | Go to |
36|-------------------------|-------|
37| Naming and file organization | [.hi/conventions.md](.hi/conventions.md) |
38| Archive / never-delete / never-reset-db | [.hi/maintenance.md](.hi/maintenance.md) |
39| Credentials, `.env`, `.gitignore` | [.hi/credentials.md](.hi/credentials.md) |
40| Host vs. container isolation (never silently mutate host) | [.hi/environment.md](.hi/environment.md) |
41| Full topic map | [.hi/index.md](.hi/index.md) |
42
43## **CRITICAL: Import/Merge Workflows are Governed**
44
45⚠️ **If the user mentions any of these, you MUST use `/hip-import-execute` — DO NOT run ad-hoc `git clone`, `Move-Item`, `cp`, or manual directory copies:**
46
47- "clone" + project/repo reference
48- "import" + external project name
49- "merge" + another project
50- "adopt" + external codebase
51- "migrate" + project / code
52- "consolidate" + multiple projects
53- "integrate" + external repo
54
55**Why?** Ad-hoc imports cause:
56- **Registry corruption** — naming violations, module conflicts
57- **Credential leakage** — `.env` files committed unintentionally
58- **Authority drift** — module `.ai/instruct.md` rules ignored
59- **Audit trail loss** — no record of what was merged or why
60
61**Correct flow:** Recognize pattern → `invoke /hip-import-execute` → orchestration layer handles Phase 0 (validation) + Phases 1-6 (integration).
62
63See [Governed Workflows section](.github/copilot-instructions.md#governed-workflows--importmerge-pattern-guard) in copilot-instructions.md for full details.
64
65## Tool compatibility
66
67This repo's instruction system is designed primarily for **GitHub Copilot** (which reads `.github/copilot-instructions.md` automatically). It is also usable with:
68
69- **OpenAI Codex CLI** — auto-discovers this `AGENTS.md`.
70- **Aider** — does **not** auto-discover `AGENTS.md`. Point it at the instruction files explicitly via `--read .hi/conventions.md --read .hi/instruct.md` (or list them under `read:` in `.aider.conf.yml`).
71- **Cursor** — pre-configured via [`.cursor/rules/project.mdc`](.cursor/rules/project.mdc), a pointer rule that directs Cursor to read the same `.hi/` hierarchy. Do not duplicate rules into `.cursor/rules/`.
72- **Claude Code** — pre-configured via [`CLAUDE.md`](CLAUDE.md) at the repo root, a pointer file that directs Claude Code to read the same `.hi/` hierarchy. Do not put project rules into `CLAUDE.md`.
73- **Continue** — pre-configured via [`.continue/rules/project.md`](.continue/rules/project.md), a pointer rule that directs Continue to read the same `.hi/` hierarchy. Do not duplicate rules into `.continue/rules/`.
74- **Cline** — pre-configured via [`.clinerules/project.md`](.clinerules/project.md), a pointer rule that directs Cline to read the same `.hi/` hierarchy. Do not duplicate rules into `.clinerules/`.
75
76Other agents not listed above can be pointed at the files listed above via their own configuration mechanism — add a new pointer file following the same pattern.
77
78For any tool: the contract is "read the files referenced above; the deepest `.hi/instruct.md` in your current working directory is authoritative."
79
80## Adopting this template
81
82See [TEMPLATE-USAGE.md](TEMPLATE-USAGE.md) for setup steps.
83Use `/hip-onboard` to convert template placeholders into project-specific values, including `.github/dev-specs.md`.
84
85## Autonomous layer (opt-in, disabled by default)
86
87This template ships a **lightweight autonomous orchestration layer** under [`.hi/autonomous/`](.hi/autonomous/). It composes the existing 19-agent network — it adds no new authority and **no new agents**. It is **disabled by default**.
88
89### How to enable
90
911. Read, in this order: [`.hi/autonomous/safety-guardrails.md`](.hi/autonomous/safety-guardrails.md), [`.hi/autonomous/orchestrator.md`](.hi/autonomous/orchestrator.md), [`.hi/autonomous/task-queue.md`](.hi/autonomous/task-queue.md).
922. Edit [`.hi/autonomous/autonomy-config.yaml`](.hi/autonomous/autonomy-config.yaml) and set `enabled: true`.
933. Keep `human_approval.mode: "always"` for the first runs.
944. Try the worked example: [`workflow-examples/feature-implementation.md`](.hi/autonomous/workflow-examples/feature-implementation.md).
955. Invoke with [`/hip-autonomous-start`](.github/.hi/prompts/hip-autonomous-start.prompt.md). The command refuses if the master switch is off.
96
97### Limitations (intentional)
98
99- Single goal at a time (`max_parallel_workers: 1`).
100- Hard ceilings: 25 steps, 30 minutes, 20 files modified per run.
101- Cannot edit `.ai/instruct.md`, `.ai/governance/`, `.ai/index.md`, `.env`, secrets, or DB schemas. Those are reserved for human-driven flows (`/ai-reflect`, `/ai-update-index`, `pds-man-curator`).
102- Cannot invoke `pds-man-curator` or `pds-meta-learner` — governance edits stay human-driven.
103- Heartbeat re-reads of the scope authority and guardrails files; any drift halts the run.
104- All standing safety contracts apply unchanged: archive-first, never-reset-db, credential isolation, host isolation, depth-priority instructions.
105- A `.ai/PAUSE` file halts every run at the next iteration.
106
107If any limitation gets in the way, the correct response is **not** to relax the orchestrator — it is to keep using the existing slash commands directly.
108
vctmasters1/PDS-Layered-AI-Instruct-Template-V5 · CLAUDE.md
@@ +1 @@
1# CLAUDE.md — Claude Code pointer
2
3> Claude Code auto-discovers `CLAUDE.md` at the repository root (and additional `CLAUDE.md` files in subdirectories). This file is a **pointer** — the authoritative rules live in [`.ai/`](.ai/) and per-directory `.ai/instruct.md` files. Do not duplicate rules into `CLAUDE.md`.
4
5## Project rules location
6
7This project uses the **Depth-Priority Hierarchical AI-INSTRUCT V5** system. **The deepest `.ai/instruct.md` always wins.**
8
9Before suggesting any change, read in this order:
10
111. [.github/dev-specs.md](.github/dev-specs.md) — **CRITICAL**: Are we in Template Development or Production mode? Then: developer OS, shell, language versions, frameworks.
122. [.github/copilot-instructions.md](.github/copilot-instructions.md) — meta: how the layering works.
133. [.hi/index.md](.hi/index.md) — master index of every instruction section.
144. [.hi/instruct.md](.hi/instruct.md) — workspace-root authority.
155. `[current-directory]/.hi/instruct.md` and every ancestor — **the deepest is authoritative**, shallower files are background context only.
16
17## Cross-cutting rules
18
19| Topic | Canonical file |
20|-------|---------------|
21| Naming, file organization | [.hi/conventions.md](.hi/conventions.md) |
22| Archive / never-delete / never-reset-db | [.hi/maintenance.md](.hi/maintenance.md) |
23| Credentials, `.env`, `.gitignore` | [.hi/credentials.md](.hi/credentials.md) |
24
25## Do not
26
27- Do not put project rules into this `CLAUDE.md` — they belong in the appropriate `.hi/` file.
28- Do not duplicate content from `.hi/` here. If Claude Code needs additional context, add a one-line pointer that links to the canonical file.
29- If you create per-module `CLAUDE.md` files, keep them as pointers to the matching `[module]/.hi/instruct.md` — never restate rules.
30
@@ −1 +1 @@
1−# AGENTS.md — Entry Point for AI Coding Agents
1+# CLAUDE.md — Claude Code pointer
22
3−> **READ THIS FIRST.** This file is the **discovery anchor** for any AI agent or tool entering this repository.
4−> This repository uses the **Depth-Priority Hierarchical AI-INSTRUCT V6** system with unified `.hi/` governance and **Routing Gateway** at its core.
3+> Claude Code auto-discovers `CLAUDE.md` at the repository root (and additional `CLAUDE.md` files in subdirectories). This file is a **pointer** — the authoritative rules live in [`.ai/`](.ai/) and per-directory `.ai/instruct.md` files. Do not duplicate rules into `CLAUDE.md`.
54
6−## 🚀 The Core Feature: Routing Gateway
5+## Project rules location
76
8−**Every major workflow in this project flows through `/ai-route`** — a central orchestration layer that:
7+This project uses the **Depth-Priority Hierarchical AI-INSTRUCT V5** system. **The deepest `.ai/instruct.md` always wins.**
98
10−✅ Resolves which `.hi/instruct.md` is authoritative for your current scope
11−✅ Applies governance rules automatically
12−✅ Routes to the domain manager/supervisor that owns that scope
13−✅ Logs all decisions for audit trails
14−✅ Halts gracefully on conflicts
9+Before suggesting any change, read in this order:
1510
16−**This is not optional.** It is the **defining feature** that makes depth-priority hierarchy practical at scale.
11+1. [.github/dev-specs.md](.github/dev-specs.md) — **CRITICAL**: Are we in Template Development or Production mode? Then: developer OS, shell, language versions, frameworks.
12+2. [.github/copilot-instructions.md](.github/copilot-instructions.md) — meta: how the layering works.
13+3. [.hi/index.md](.hi/index.md) — master index of every instruction section.
14+4. [.hi/instruct.md](.hi/instruct.md) — workspace-root authority.
15+5. `[current-directory]/.hi/instruct.md` and every ancestor — **the deepest is authoritative**, shallower files are background context only.
1716
18−→ **Start with [The Routing Gateway](.github/copilot-instructions.md#the-routing-gateway--core-orchestration-layer)** in `.github/copilot-instructions.md` (2-min read)
17+## Cross-cutting rules
1918
20−## Where the rules live
21−
22−Rules are stored as per-directory `.hi/instruct.md` files. **Deeper always wins.**
23−
24−Start here, in this order:
25−
26−1. **[The Routing Gateway](.github/copilot-instructions.md#the-routing-gateway--core-orchestration-layer)** in `.github/copilot-instructions.md` — WHY routing exists, how it works, which workflows use it (start here 🚀)
27−2. [.github/copilot-instructions.md](.github/copilot-instructions.md) — META: complete layering system (read once per session)
28−3. [.github/dev-specs.md](.github/dev-specs.md) — **CRITICAL**: Read the Project Mode field (Template Development vs Production) before any other decision. Then: Platform, shell, language, frameworks. If template-empty, run `/hip-onboard` to fill values.
29−4. [.hi/index.md](.hi/index.md) — Master index of every instruction section. Jump from here to the canonical source for any topic.
30−5. [.hi/instruct.md](.hi/instruct.md) — Root-level project authority. Confirms the [Routing & Orchestration Gateway](.hi/instruct.md#routing--orchestration-gateway) section.
31−6. `[module]/.hi/instruct.md` — Module-level authority. Authoritative when working inside that module.
32−
33−## Quick reference
34−
35−| If you are looking for… | Go to |
36−|-------------------------|-------|
37−| Naming and file organization | [.hi/conventions.md](.hi/conventions.md) |
19+| Topic | Canonical file |
20+|-------|---------------|
21+| Naming, file organization | [.hi/conventions.md](.hi/conventions.md) |
3822 | Archive / never-delete / never-reset-db | [.hi/maintenance.md](.hi/maintenance.md) |
3923 | Credentials, `.env`, `.gitignore` | [.hi/credentials.md](.hi/credentials.md) |
40−| Host vs. container isolation (never silently mutate host) | [.hi/environment.md](.hi/environment.md) |
41−| Full topic map | [.hi/index.md](.hi/index.md) |
4224
43−## **CRITICAL: Import/Merge Workflows are Governed**
25+## Do not
4426
45−⚠️ **If the user mentions any of these, you MUST use `/hip-import-execute` — DO NOT run ad-hoc `git clone`, `Move-Item`, `cp`, or manual directory copies:**
46−
47−- "clone" + project/repo reference
48−- "import" + external project name
49−- "merge" + another project
50−- "adopt" + external codebase
51−- "migrate" + project / code
52−- "consolidate" + multiple projects
53−- "integrate" + external repo
54−
55−**Why?** Ad-hoc imports cause:
56−- **Registry corruption** — naming violations, module conflicts
57−- **Credential leakage** — `.env` files committed unintentionally
58−- **Authority drift** — module `.ai/instruct.md` rules ignored
59−- **Audit trail loss** — no record of what was merged or why
60−
61−**Correct flow:** Recognize pattern → `invoke /hip-import-execute` → orchestration layer handles Phase 0 (validation) + Phases 1-6 (integration).
62−
63−See [Governed Workflows section](.github/copilot-instructions.md#governed-workflows--importmerge-pattern-guard) in copilot-instructions.md for full details.
64−
65−## Tool compatibility
66−
67−This repo's instruction system is designed primarily for **GitHub Copilot** (which reads `.github/copilot-instructions.md` automatically). It is also usable with:
68−
69−- **OpenAI Codex CLI** — auto-discovers this `AGENTS.md`.
70−- **Aider** — does **not** auto-discover `AGENTS.md`. Point it at the instruction files explicitly via `--read .hi/conventions.md --read .hi/instruct.md` (or list them under `read:` in `.aider.conf.yml`).
71−- **Cursor** — pre-configured via [`.cursor/rules/project.mdc`](.cursor/rules/project.mdc), a pointer rule that directs Cursor to read the same `.hi/` hierarchy. Do not duplicate rules into `.cursor/rules/`.
72−- **Claude Code** — pre-configured via [`CLAUDE.md`](CLAUDE.md) at the repo root, a pointer file that directs Claude Code to read the same `.hi/` hierarchy. Do not put project rules into `CLAUDE.md`.
73−- **Continue** — pre-configured via [`.continue/rules/project.md`](.continue/rules/project.md), a pointer rule that directs Continue to read the same `.hi/` hierarchy. Do not duplicate rules into `.continue/rules/`.
74−- **Cline** — pre-configured via [`.clinerules/project.md`](.clinerules/project.md), a pointer rule that directs Cline to read the same `.hi/` hierarchy. Do not duplicate rules into `.clinerules/`.
75−
76−Other agents not listed above can be pointed at the files listed above via their own configuration mechanism — add a new pointer file following the same pattern.
77−
78−For any tool: the contract is "read the files referenced above; the deepest `.hi/instruct.md` in your current working directory is authoritative."
79−
80−## Adopting this template
81−
82−See [TEMPLATE-USAGE.md](TEMPLATE-USAGE.md) for setup steps.
83−Use `/hip-onboard` to convert template placeholders into project-specific values, including `.github/dev-specs.md`.
84−
85−## Autonomous layer (opt-in, disabled by default)
86−
87−This template ships a **lightweight autonomous orchestration layer** under [`.hi/autonomous/`](.hi/autonomous/). It composes the existing 19-agent network — it adds no new authority and **no new agents**. It is **disabled by default**.
88−
89−### How to enable
90−
91−1. Read, in this order: [`.hi/autonomous/safety-guardrails.md`](.hi/autonomous/safety-guardrails.md), [`.hi/autonomous/orchestrator.md`](.hi/autonomous/orchestrator.md), [`.hi/autonomous/task-queue.md`](.hi/autonomous/task-queue.md).
92−2. Edit [`.hi/autonomous/autonomy-config.yaml`](.hi/autonomous/autonomy-config.yaml) and set `enabled: true`.
93−3. Keep `human_approval.mode: "always"` for the first runs.
94−4. Try the worked example: [`workflow-examples/feature-implementation.md`](.hi/autonomous/workflow-examples/feature-implementation.md).
95−5. Invoke with [`/hip-autonomous-start`](.github/.hi/prompts/hip-autonomous-start.prompt.md). The command refuses if the master switch is off.
96−
97−### Limitations (intentional)
98−
99−- Single goal at a time (`max_parallel_workers: 1`).
100−- Hard ceilings: 25 steps, 30 minutes, 20 files modified per run.
101−- Cannot edit `.ai/instruct.md`, `.ai/governance/`, `.ai/index.md`, `.env`, secrets, or DB schemas. Those are reserved for human-driven flows (`/ai-reflect`, `/ai-update-index`, `pds-man-curator`).
102−- Cannot invoke `pds-man-curator` or `pds-meta-learner` — governance edits stay human-driven.
103−- Heartbeat re-reads of the scope authority and guardrails files; any drift halts the run.
104−- All standing safety contracts apply unchanged: archive-first, never-reset-db, credential isolation, host isolation, depth-priority instructions.
105−- A `.ai/PAUSE` file halts every run at the next iteration.
106−
107−If any limitation gets in the way, the correct response is **not** to relax the orchestrator — it is to keep using the existing slash commands directly.
27+- Do not put project rules into this `CLAUDE.md` — they belong in the appropriate `.hi/` file.
28+- Do not duplicate content from `.hi/` here. If Claude Code needs additional context, add a one-line pointer that links to the canonical file.
29+- If you create per-module `CLAUDE.md` files, keep them as pointers to the matching `[module]/.hi/instruct.md` — never restate rules.
10830
