AGENTS.md

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