Copilot instructions

1# Copilot Meta-Instructions — Depth-Priority Hierarchical AI-INSTRUCT V6
2 
3**Role of this file**: META — defines AI tooling conventions and meta-rules for how the instruction system operates. Business domain rules live in `.hi/instruct.md` files throughout the directory tree.
4 
5**Template Version**: V6.0.0
6**Last Updated**: 2026-06-05
7 
8---
9 
10## Contents
11 
12| Section | What's here |
13|---------|-------------|
14| [Read Project Specs First](#read-project-specs-first) | AI must load `dev-specs.md` at session start |
15| [The Depth-Priority Hierarchical Paradigm](#the-depth-priority-hierarchical-paradigm) | How layering works |
16| [Global Shared Instructions (`.ai/`)](#global-shared-instructions-ai) | Cross-cutting canonical files |
17| [Agentic Runtime (`.ai/`)](#agentic-runtime-ai) | Governed tools, foresight, self-improvement, heartbeat |
18| [AI Prompt Files (`.github/prompts/`)](#ai-prompt-files-githubprompts) | Slash commands |
19| [Workflow Invocation Pattern](#workflow-invocation-pattern) | Workflows are repeatable; workflows vs. utilities; do not treat them as one-time setup |
20| [Governed Workflows — Import/Merge Pattern Guard](#governed-workflows--importmerge-pattern-guard) | **CRITICAL:** Imports are orchestrated workflows, not ad-hoc copy operations |
21| [Custom Agents (`.github/agents/`)](#custom-agents-githubagents) | Specialized personas |
22| [Skills (`.github/skills/`)](#skills-githubskills) | Domain knowledge packs |
23| [Git Hooks (`.github/hooks/`)](#git-hooks-githubhooks) | Commit-time safety checks |
24| [YAML Frontmatter Schema](#yaml-frontmatter-schema) | Required and optional fields for prompts, agents, skills |
25| [`.dev-docs/` — Development Documentation Convention](#dev-docs--development-documentation-convention) | Pointer to canonical rules |
26| [Code Comment Convention](#code-comment-convention) | Why-not-what; no docblocks unless asked |
27| [AI-INSTRUCT Maintenance Rule](#ai-instruct-maintenance-rule) | Update instructions with every architectural change |
28| [`.github/` File Placement Rules](#github-file-placement-rules) | Where prompts, agents, debug scripts, tmp go |
29| [Automatic Date Maintenance](#automatic-date-maintenance) | Auto-fill `Last Updated` and placeholders |
30 
31---
32 
33## Read Project Specs First
34 
35Before suggesting commands, file paths, line endings, or tooling, **read [`.github/dev-specs.md`](dev-specs.md)** to determine:
36 
371. **Project Mode** (MOST IMPORTANT): Are we in **Template Development** mode (building the framework) or **Production/Adoption** mode (using the framework for a real project)?
38   - Template mode: Framework files in `.ai/`, `.github/` are authoritative and can be modified
39   - Production mode: Never commit adopter-specific configs; only commit project source and templates
402. Developer OS, shell, target platform, language versions, and frameworks
41 
42Do not assume the platform or mode from the user's prompt or your environment. The contents of `dev-specs.md` are authoritative for these facts.
43 
44For template-first repositories, `dev-specs.md` may still be partially unfilled during onboarding. In that case, ask to run `/ai-onboard` (or ask focused follow-up questions) so inferred values are confirmed and written before giving platform-specific guidance.
45 
46---
47 
48## The Routing Gateway — Core Orchestration Layer
49 
50**This is the magic.** The `/ai-route` gateway is the central nervous system that powers every major workflow in this project. It is **not optional** — it is the defining feature that makes depth-priority hierarchy practical at scale.
51 
52### What Routing Does
53 
54Before any workflow (import, validation, module creation, etc.) executes, the router:
55 
561. **Resolves scope** — finds the deepest `.ai/instruct.md` that governs the affected paths
572. **Checks governance** — applies any external rules or constraints
583. **Routes to authority** — delegates to the domain manager/supervisor that owns that scope
594. **Enables escalation** — halts on conflicts and explains why
60 
61### Why This Matters
62 
63Without routing, each workflow would need to implement scope resolution independently → **duplicate logic, brittleness, easy to bypass.**
64 
65With routing, all workflows speak the same language → **consistent, auditable, scope-aware.**
66 
67### Routed Workflows (Today)
68 
69| Workflow | Routed to |
70|----------|-----------|
71| `/ai-import-execute` | `pds-man-imports` (Phase 0-7 orchestration) |
72| `/ai-adapt-infrastructure` | `pds-man-infrastructure` (infrastructure compliance & adaptation) |
73| `/ai-validate` | `pds-pipe-validator` (scope-aware validation) |
74| `/ai-reflect` | `pds-meta-learner` (gap analysis) |
75| `/ai-update-index` | `pds-man-curator` (index rebuild) |
76| `/ai-new-module` | `pds-pipe-scaffolder` (module scaffolding) |
77 
78Each workflow does **not** know how to resolve scope or apply governance—it delegates that to the router and lets the router decide who should execute.
79 
80### The Router Itself
81 
82→ **[/ai-route prompt](prompts/ai-route.prompt.md)** — invoke when you need scope resolution before delegating  
83→ **[pds-meta-router agent](agents/pds-meta-router.agent.md)** — technical details and governance resolution logic
84 
85---
86 
87## The Depth-Priority Hierarchical Paradigm
88 
89This project uses **Hierarchical Layering by Directory Depth**. The deeper your current working directory, the more authoritative its `.hi/instruct.md` becomes.
90 
91### Precedence Rules
92 
93When working in a directory:
94- **That directory's `.hi/instruct.md` is authoritative** for your current context
95- Shallower `.hi/instruct.md` files provide **background/context only**
96- Each level is **self-contained** — no delegation upward
97- **Deeper always wins** over shallower
98 
99### Resolution Order
100 
101```
102.github/copilot-instructions.md              ← META: explains HOW layering works (this file)
103    ↓
104.hi/instruct.md                              ← AUTHORITATIVE at workspace root
105    ↓
106[module]/.hi/instruct.md                     ← AUTHORITATIVE when working in that module
107    ↓
108[module]/[submodule]/.hi/instruct.md         ← AUTHORITATIVE when working in that submodule
109```
110 
111### How to Use
112 
1131. **When you start working**: check what directory you're in
1142. **Find the deepest `.ai/instruct.md`** in or above your current directory
1153. **That file is authoritative** — follow it precisely
1164. **Parent files** provide architectural context only
1175. **Do not mix contexts** across modules
118 
119---
120 
121## Global Shared Instructions (`.hi/`)
122 
123Cross-cutting rules that would otherwise be duplicated across many files live here as single sources of truth.
124 
125```
126.hi/
127├── conventions.md    ← Naming, file organization, TOC rules (canonical)
128├── maintenance.md    ← Archive patterns, never-delete, never-reset-db rules (canonical)
129├── credentials.md    ← Credential warehousing + .gitignore rules (canonical)
130├── environment.md    ← Host-vs-container isolation rules; never silently mutate the host (canonical)
131├── index.md          ← MASTER INDEX of all instruction sections across the project
132├── agent-config.yaml ← Agentic runtime config: heartbeat, log format, safety, foresight, self-improvement
133├── heartbeat.md      ← Heartbeat procedure: what agents do every N steps to re-align
134├── engine/           ← Runtime scripts (foresight_engine.py, get_effective_instructions.py)
135├── agents/tools/     ← Governed tool checklists read by agents (not MCP wire-protocol tools)
136├── mcp/tools/        ← Project-specific governed tool checklists
137├── foresight/        ← Foresight analysis outputs (runtime; gitignored)
138├── knowledge/        ← Accumulated knowledge base (runtime; gitignored)
139└── logs/             ← Agent audit logs (runtime; gitignored)
140```
141 
142**Rule**: If a directory's `.hi/instruct.md` needs to reference a global convention, it **links** to `.hi/` rather than restating it. Never copy content from these files.
143 
144---
145 
146## Agentic Runtime (`.hi/`)
147 
148The `.hi/` directory doubles as the agentic runtime platform, layering proactive capabilities on top of the depth-priority instruction system.
149 
150**Key capabilities:**
151 
152| Capability | Mechanism |
153|---|---|
154| **Heartbeat** | Every 6 steps, agents re-read the active instruction scope and re-align |
155| **Foresight** | Before acting, `foresight_engine.py` anticipates gaps (error handling, logging, tests) and forecasts risks |
156| **Self-improvement** | After major tasks, agents reflect and propose edits to `.ai/instruct.md` files |
157| **Governed tools** | Governed tool JSON files in `.ai/agents/tools/` include a `checklist` and `safety_level` — agents must follow the checklist before acting |
158| **Audit logging** | All agent changes are logged to `.ai/logs/` for traceability |
159 
160**Rules:**
161- `agent-config.yaml` is the single source of truth for runtime behavior — do not duplicate its settings elsewhere
162- `.hi/foresight/`, `.hi/knowledge/`, and `.hi/logs/` are runtime outputs — gitignored; never commit them
163- Governed tool checklists live in `.hi/agents/tools/` (built-in) or `.hi/mcp/tools/` (project-specific) — these are **governance documents read by agents**, not MCP wire-protocol tool definitions
164- `heartbeat.md` defines the procedure agents follow at every heartbeat interval — configurable in `agent-config.yaml`
165- `get_effective_instructions.py` implements depth-priority resolution — do not alter its traversal logic
166- Heartbeat and foresight are configured via `agent-config.yaml`; adjust `heartbeat_interval` and `foresight:` keys to tune
167 
168---
169 
170## AI Prompt Files (`.github/prompts/`)
171 
172AI-invocable slash commands live as `.prompt.md` files in `.github/prompts/`.
173 
174```
175.hi/prompts/
176├── hip-onboard.prompt.md        ← /hip-onboard: Interactive wizard (also absorbs existing-project import)
177├── hip-update-index.prompt.md   ← /hip-update-index: Rebuild .hi/index.md after changes
178├── hip-archive.prompt.md        ← /hip-archive: Archive a file following the convention
179├── hip-new-module.prompt.md     ← /hip-new-module: Scaffold a new module and register it
180├── hip-env-check.prompt.md      ← /hip-env-check: Audit host-vs-container isolation; report only, never installs
181├── hip-validate.prompt.md       ← /hip-validate: Run the AI-INSTRUCT drift validator
182├── hip-foresight.prompt.md      ← /hip-foresight: Run foresight gap/risk analysis on current task before acting
183├── hip-reflect.prompt.md        ← /hip-reflect: Post-task reflection; identify instruction gaps and propose .hi/ improvements
184├── hip-plugin-discover.prompt.md ← /hip-plugin-discover: Enumerate optional plugins under .hi/plugins/; read-only
185└── hip-git.prompt.md            ← /hip-git: Version control (subcommands: branch | commit | pr | status)
186```
187 
188Type the slash command in Copilot Chat to invoke. All project-specific commands use the `/hip-` prefix to distinguish them from built-in Copilot commands.
189 
190**Create when**: a multi-step workflow is executed more than twice in a session, or a workflow is complex enough that the AI needs explicit sequencing to do it correctly.
191 
192---
193 
194## Workflow Invocation Pattern
195 
196**Workflows** are repeatable, idempotent operations that can be invoked at any time — not one-time setup tasks.
197 
198### Workflows (Repeatable)
199 
200Invoke these whenever the operation is needed, not just during initial setup:
201 
202| Workflow | Purpose | Repeatable? |
203|----------|---------|------------|
204| `/hip-onboard` | Initialize or update project metadata (identity, dev-specs, module list) | Yes — re-run to refresh identity or add modules |
205| `/hip-import-execute` | Import/merge external projects with full Phase 0-6 orchestration | Yes — use each time you merge a new project |
206| `/hip-new-module` | Scaffold a new module (instruct.md, dev-docs, registration) | Yes — invoke per module |
207| `/hip-update-index` | Rebuild `.hi/index.md` from current state | Yes — run after editing any `.hi/instruct.md` |
208| `/hip-archive` | Archive (never delete) a file or directory | Yes — use per archival task |
209 
210### Utilities (Informational, No State Change)
211 
212Run these to inspect or analyze; they do not modify the project:
213 
214| Utility | Purpose |
215|---------|---------|
216| `/hip-validate` | Audit instruction drift; report findings |
217| `/hip-env-check` | Audit host-vs-container isolation |
218| `/hip-foresight` | Analyze gaps/risks before acting |
219| `/hip-reflect` | Post-task reflection; propose improvements |
220| `/hip-observe` | Display runtime observability and metrics |
221| `/hip-git` | Query version control state (no auto-commits) |
222 
223### Key Principle
224 
225**Do not treat workflows as one-time setup.** They are on-demand operations:
226 
227- **First time:** `/hip-onboard` fills template placeholders → project becomes usable
228- **Later:** `/hip-onboard` again to update project name, add/remove modules, refresh dev-specs
229- **Each import:** `/hip-import-execute` with a new source project → orchestrated Phase 0-6 pipeline
230- **Each module:** `/hip-new-module` to scaffold a new capability
231 
232---
233 
234## Governed Workflows — Import/Merge Pattern Guard
235 
236**CRITICAL SAFETY RULE:** Importing, cloning, or merging external projects is a **governed workflow**, not a vanilla file-copy operation. This section explains why and enforces the guardrail.
237 
238### Pattern Recognition
239 
240If the user **mentions any of these**, you **MUST** recognize it as an import workflow trigger:
241 
242- "clone" + project/repo reference
243- "import" + external project name or path
244- "merge" + another project / workspace
245- "adopt" + external codebase
246- "migrate" + project / code
247- "consolidate" + multiple projects
248- "integrate" + external repo
249 
250### The Non-Negotiable Rule
251 
252**DO NOT:**
253- Run ad-hoc `git clone` or `Move-Item` / `cp -r` commands
254- Manually copy directories from one project to another without orchestration
255- Decide module structure, naming, or registration on the fly
256- Bypass Phase 0 validation (LLM dispatch, environment, credentials, naming conventions)
257 
258**DO:**
2591. **Stop** and acknowledge the import request
2602. **Read** `.ai/instruct.md` to understand the authoritative import strategy for this project
2613. **Invoke `/ai-import-execute`** (or the project's equivalent import orchestration prompt)
2624. **Let the agent orchestration layer** (pds-meta-migrator → pds-pipe-importer) handle:
263   - Phase 0: Operational validation (LLM dispatch, env, credentials, naming)
264   - Phase 1-6: Artifact preservation, analysis, integration, modernization, and registry updates
2655. **Wait for completion** before suggesting next steps
266 
267### Why This Matters
268 
269- **Naming conflicts** — Projects have different conventions; ad-hoc copies violate the registry
270- **Module authority drift** — Each module's `.ai/instruct.md` is authoritative; manual moves break the hierarchy
271- **Credential leakage** — Phase 0 validation catches `.env` files; ad-hoc copies miss them
272- **Registry corruption** — Module lists, naming conventions, error codes, API endpoints all need updates; manual copies bypass the updater
273- **Audit trail loss** — Proper import logs every decision; ad-hoc commands leave no trace
274 
275### Example (What NOT to Do)
276 
277```
278User: "Clone https://github.com/user/project.git and move it into src/"
279 
280❌ WRONG:
281  git clone https://github.com/user/project.git
282  Move-Item project/* -Destination src/
283  (no validation, no registry updates, no module supervision)
284 
285✅ RIGHT:
286  Recognize: This is an import workflow
287  → Invoke /ai-import-execute with the source URL
288  → Let orchestration handle Phase 0 + Phases 1-6
289  → Confirm completion before offering next steps
290```
291 
292---
293 
294## Custom Agents (`.github/agents/`)
295 
296Custom Copilot agent modes live in `.github/agents/`. Each `.agent.md` defines a specialized persona with restricted tools and behavior.
297 
298```
299.hi/agents/
300├── tier-1/ (router, curator, imports, infrastructure, super)
301├── tier-2/workers/ (scaffolder, generator, validator, tester, reviewer)
302├── tier-2/observers/ (explorer, compliance, learner, observer)
303└── tier-2/specialists/ (naming, ports, environment, deployment, workflow, prompt, todo, versioncontrol, cleanup)
304```
305 
306**Create when**: a constrained persona (restricted tools, specific behavior) adds meaningful safety or quality value. Examples: read-only exploration agents, agents scoped to a single directory or task type.
307 
308---
309 
310## Skills (`.github/skills/`)
311 
312Domain knowledge skill packs for AI specialization. A skill is invoked when a task falls within its described domain.
313 
314```
315.hi/skills/
316└── project-navigation/
317    └── SKILL.md                ← How to navigate this project's AI-INSTRUCT hierarchy
318```
319 
320Skills are **knowledge packs**, not task scripts — they describe how to orient, not what to do.
321 
322**Create when**: a domain has enough specialized conventions that the AI needs a briefing to act correctly and general instructions are insufficient to reliably guide it.
323 
324---
325 
326## Git Hooks (`.github/hooks/`)
327 
328Commit-time safety checks. Scripts in `.github/hooks/` must be installed into `.git/hooks/` during project setup.
329 
330```
331.hi/hooks/
332├── post-merge                   ← Regenerate discovery registries after merge
333├── install-hooks.sh             ← Activate via `git config core.hooksPath .hi/hooks` (POSIX)
334└── install-hooks.ps1            ← Same, for Windows PowerShell
335```
336 
337To install (run once per clone): `bash .github/hooks/install-hooks.sh` or `pwsh .github/hooks/install-hooks.ps1`
338 
339**Create when**: a class of commit-time errors can be prevented automatically. Examples: blocking `.env` commits, checking for credential patterns, enforcing instruction drift checks.
340 
341> **Tooling discipline**: Every facility above must be earned — create it when it provides clear, reusable value, not speculatively. The AI **may** proactively suggest creating tooling when a pattern is observed, but **must ask before creating** any `.github/` tooling file.
342 
343---
344 
345## YAML Frontmatter Schema
346 
347All three customization file types use a YAML frontmatter block. The fields differ by type.
348 
349### `.github/prompts/*.prompt.md` (slash commands)
350 
351```yaml
352---
353mode: agent          # required. One of: ask | edit | agent. Use `agent` for prompts that need full tool access (file edits, terminal, etc.); `edit` for surgical multi-file edits; `ask` for read-only Q&A.
354description: ...     # required. One-line user-facing summary shown when the slash command surfaces in pickers.
355---
356```
357 
358Notes:
359- All `/ai-*` prompts in this template use `mode: agent` because they perform multi-step file operations.
360- Do not add a `tools:` list to prompts — prompts inherit the active chat's tool set.
361 
362### `.github/agents/*.agent.md` (custom agents)
363 
364```yaml
365---
366description: ...    # required. One-line summary of the agent's purpose and when to invoke it.
367tools:              # optional but recommended. Whitelist of tools the agent may use. Omit to inherit the workspace default.
368  - file_search
369  - grep_search
370  - read_file
371---
372```
373 
374Notes:
375- Agents do **not** take a `mode:` field — they *are* a mode.
376- When defining a read-only or scoped agent, always set a `tools:` whitelist so the constraint is enforced, not aspirational.
377 
378### `.github/skills/<skill>/SKILL.md` (knowledge packs)
379 
380```yaml
381---
382description: >      # required. Multi-line description is fine. Surfaces in the skill catalog;
383  ...               # also used by the model to decide when to invoke the skill.
384---
385```
386 
387Notes:
388- `SKILL.md` uppercase casing is required by the VS Code Copilot skill discovery system — do not rename.
389- Skills do not declare `tools:` or `mode:`; they only provide knowledge.
390 
391---
392 
393## `.dev-docs/` — Development Documentation Convention
394 
395> **→ [`.dev-docs` Convention](.hi/conventions.md#dev-docs-convention)** — canonical rules for `.dev-docs/`, its `.old/` archive, and the required `index.md`.
396 
397Do not restate the rules here. Copilot must ignore `.dev-docs/.old/` unless the user explicitly asks otherwise.
398 
399---
400 
401## Code Comment Convention
402 
403- Comment on **why**, not what
404- One line preferred; no rambling
405- Do not add comments to code you did not touch in the current change
406- Do not add header blocks, file-level docstrings, or function docstrings unless explicitly asked
407- If a line implements a non-obvious architectural constraint, a comment **may** name the governing `.ai/instruct.md`:
408 
409```js
410// See .ai/credentials.md — all secrets must come from environment variables
411const secret = process.env.JWT_SECRET;
412```
413 
414---
415 
416## AI-INSTRUCT Maintenance Rule
417 
418**Whenever an architectural change is made, the relevant `.hi/instruct.md` file(s) must be updated in the same operation.** Then run `/hip-update-index` to rebuild the index.
419 
420An architectural change includes:
421- Adding, removing, or renaming a module, package, layer, or subsystem
422- Changing a data format, protocol, or schema
423- Adding a new integration, block type, or subsystem
424- Any change that would make existing `.hi/` instruction guidance incorrect or incomplete
425 
426Do not defer `.hi/instruct.md` updates. They are part of the change, not a follow-up task.
427 
428---
429 
430## `.github/` File Placement Rules
431 
432| What | Where |
433|------|-------|
434| Copilot meta-instructions | `.github/copilot-instructions.md` |
435| Project specs (platform, frameworks, dev environment) | `.github/dev-specs.md` |
436| Prompt files (slash commands) | `.hi/prompts/` |
437| Custom agents | `.hi/agents/` |
438| Domain knowledge skills | `.hi/skills/` |
439| Git hook scripts | `.hi/hooks/` |
440| Project-level TODO lists | `.github/todo/` |
441| Debug/helper scripts created by AI | `.github/debug/` |
442| Temporary output files | `.github/tmp/` |
443 
444**VS Code settings** live in `.vscode/` (committed for shared project defaults; personal overrides use `settings.local.json` which is gitignored).
445 
446**Rules:**
447- Debug scripts must **never** be placed in the workspace root
448- Temporary files must **never** be placed in the workspace root
449- `.github/tmp/` contents are ephemeral — may be deleted at any time
450- `.github/debug/` scripts are AI-generated utilities — not part of the production codebase
451 
452---
453 
454## Deployment Modes — `.deployment/`
455 
456Deployment modes are first-class **depth-priority scopes** keyed by the `DEPLOY_MODE` environment variable. See [`.deployment/README.md`](../.deployment/README.md) for the convention and [`/hip-deploy-mode`](prompts/hip-deploy-mode.prompt.md) to inspect or switch.
457 
458```
459.deployment/
460├── README.md                          ← convention + required-section list for each mode
461├── dev-local/.hi/instruct.md          ← AUTHORITATIVE when DEPLOY_MODE=dev-local
462├── dev-lan/.hi/instruct.md            ← AUTHORITATIVE when DEPLOY_MODE=dev-lan
463├── prod-railway/.hi/instruct.md       ← AUTHORITATIVE when DEPLOY_MODE=prod-railway
464└── prod-self-serve/.hi/instruct.md    ← AUTHORITATIVE when DEPLOY_MODE=prod-self-serve
465```
466 
467**Rules:**
468- A mode's `.hi/instruct.md` is authoritative whenever `DEPLOY_MODE` matches its directory name. The depth-priority winner is `.deployment/<active>/.hi/instruct.md` for any deployment-relevant question.
469- A mode **cannot relax** a rule from a shallower `.hi/*.md` (e.g., a mode cannot permit committing `.env`).
470- Mode names are kebab-case and registered with the `naming` agent (Mode 3) — never invent one without a consultation.
471- The [`deployment-manager`](agents/pds-man-deployment.agent.md) agent watches `.deployment/` for drift and proposes `update / add / retire / rename`.
472- Switching mode is a **human action** — agents emit shell-export snippets but never mutate the active shell.
473 
474---
475 
476## Automatic Date Maintenance
477 
478> **→ [Versioning](.hi/conventions.md#versioning)** — canonical rules for `Last Updated` auto-fill and `[PLACEHOLDER]` resolution.
479 
480Summary (do not restate; this is a one-line reminder only): the AI updates `**Last Updated**` to today whenever it edits a `.hi/*.md` file, and fills any `[PLACEHOLDER]` whose value is unambiguous from context, without waiting to be asked.
481