feat: multi directory AGENT.md support

Author: l-you

AGENTS.md

@@ -9,7 +9,7 @@ It stores strict project rules that define architecture policy including:
 - code patterns
 - custom strict rules
 
-Based on the target project, stack modules are combined into a single root `AGENTS.md` via the appropriate skill. It assembles project-specific rules while preserving shared conventions.
+Based on the target project, stack modules are combined into root and nested `AGENTS.md` files via the appropriate skill when subprojects need more specific policy. It assembles project-specific rules while preserving shared conventions.
 
 # Folder Structure
 Current repository layout:
@@ -28,6 +28,8 @@ Current repository layout:
       SKILL.md
   modules/              # stack-specific guidance
     <module-name>/doc.md
+  <subproject>/
+    AGENTS.md           # nested policy for a specific app/service/package
 ```
 
 # Root AGENTS.md rules
@@ -41,12 +43,18 @@ Current repository layout:
 - `doc.md` must include references to all baseline and stack modules.
 - `doc.md` must provide a canonical table with short stack key, full stack name, module path, and `load_when`.
 - `doc.md` must instruct agents to always load baseline modules and load project-specific stacks by `load_when` signals.
+- `doc.md` must define when to create nested `AGENTS.md` files and how parent/child precedence works.
 - `doc.md` must define section semantics: `Strict rules` for technical constraints, and `Working Agreements` for user-agent interaction protocol.
 - `doc.md` must define how to load and enforce `awesome/index.md` and matching awesome files.
 - Changes to module paths or routing signals must update `doc.md` in the same change.
 - When adding a new stack, update `doc.md` with both the short stack key and full stack name.
 - Root `doc.md` should contain only routing/composition logic and helpers to assemble target `AGENTS.md`.
 
+## Target Output
+- Target repositories may contain a root `AGENTS.md` plus nested `AGENTS.md` files for subprojects with distinct stack, runtime, or ownership boundaries.
+- Root `AGENTS.md` should stay repository-wide; nested `AGENTS.md` files should narrow rules for their subtree.
+- Nested `AGENTS.md` files should be created only for meaningful architecture boundaries such as apps, services, or packages with distinct tooling.
+
 ## Stack
 - Stack-specific guidance is maintained in `modules/*/doc.md`.
 - Enforced stack or capability libraries/utilities are maintained in `awesome/*`.
@@ -57,6 +65,7 @@ Current repository layout:
 ## Skills
 - Skills are maintained in `skills/<skill-name>/SKILL.md`.
 - Skills must treat `doc.md` and `awesome/index.md` as the source of truth and must not introduce alternate router filenames.
+- Skills must support root and nested `AGENTS.md` output when the repository contains multiple app or service boundaries.
 - Skills that initialize from scratch or refactor existing repositories must run an architecture interview before selecting modules or refactoring code.
 - Skills must wait for explicit `Accept` before writing `AGENTS.md` or performing architecture-driven refactors.
 - Skills that mutate an existing codebase must propose a phased plan before editing files.

README.md

@@ -19,6 +19,25 @@ Central source for shared AGENTS policies of [RevoTale](https://revotale.com).
 - `modules/<stack>/doc.md`: stack-specific modules.
 - `skills/<skill-name>/SKILL.md`: operational skills for greenfield init, AGENTS refresh, and guided refactors.
 
+## Nested AGENTS.md
+
+Target repositories may use a root `AGENTS.md` plus nested `AGENTS.md` files when different subprojects need more specific stack rules.
+
+Example:
+
+```text
+<repo-root>/
+  AGENTS.md
+  frontend/
+    AGENTS.md
+    package.json
+  backend/
+    AGENTS.md
+    go.mod
+```
+
+Use nested files for meaningful architecture boundaries such as apps, services, or packages with distinct tooling. The nearest `AGENTS.md` should apply to the active subtree, while parent files stay additive for shared rules.
+
 ## Skill Workflows
 
 Use the skill that matches the repository stage.
@@ -28,21 +47,21 @@ Use the skill that matches the repository stage.
 Skill path: `skills/init-project-from-agent-docs/SKILL.md`
 
 Example request:
-`Use https://github.com/RevoTale/agent-docs/skills/init-project-from-agent-docs skill to design the initial AGENTS.md for this new repository.`
+`Use https://github.com/RevoTale/agent-docs/skills/init-project-from-agent-docs skill to design the initial root and nested AGENTS.md files for this new repository.`
 
 ### Existing Repo AGENTS Refresh
 
 Skill path: `skills/refresh-project-agents-from-agent-docs/SKILL.md`
 
 Example request:
-`Use https://github.com/RevoTale/agent-docs/skills/refresh-project-agents-from-agent-docs skill to refresh AGENTS.md for this repository.`
+`Use https://github.com/RevoTale/agent-docs/skills/refresh-project-agents-from-agent-docs skill to refresh the root and nested AGENTS.md files for this repository.`
 
 ### Existing Repo Refactor
 
 Skill path: `skills/refactor-project-to-agent-docs/SKILL.md`
 
 Example request:
-`Use https://github.com/RevoTale/agent-docs/skills/refactor-project-to-agent-docs skill to align this repository with the recommended stack after an architecture interview.`
+`Use https://github.com/RevoTale/agent-docs/skills/refactor-project-to-agent-docs skill to align this repository and its nested subprojects with the recommended stack after an architecture interview.`
 
 ## Update Manually
 

doc.md

@@ -1,6 +1,6 @@
 # Overview
 This file is the universal AGENTS router and composition contract.
-It defines which module files to load and how to merge them into a target repository `AGENTS.md`.
+It defines which module files to load and how to merge them into target repository `AGENTS.md` files.
 
 # Canonical Module Registry
 Use this table as the single source of truth for module routing.
@@ -21,6 +21,16 @@ Use this table as the single source of truth for module routing.
 3. If multiple modules match, load all matched modules.
 4. Any module add/remove/rename or signal change must update this table in the same change.
 
+# Nested AGENTS.md Output
+- MUST create a root `AGENTS.md` for repository-wide topology, shared workflows, and cross-project constraints.
+- MUST create nested `AGENTS.md` files for deployable apps, backend services, frontend apps, packages, or subprojects with distinct stack signals, runtime boundaries, or policy needs.
+- MUST detect boundaries such as `frontend/`, `backend/`, `apps/*`, `services/*`, `packages/*`, or equivalent user-declared subprojects.
+- MUST select modules and matching awesome files independently for each nested subproject.
+- MUST apply the nearest `AGENTS.md` to files in its subtree.
+- MUST keep parent `AGENTS.md` files additive for shared rules.
+- MUST let the more specific nested `AGENTS.md` override parent rules when stack-specific or subtree-specific rules conflict.
+- MUST NOT create nested `AGENTS.md` files for ordinary folders that do not introduce distinct architecture, tooling, runtime, or ownership rules.
+
 # Awesome Registry
 Use `awesome/index.md` as the entrypoint for enforced utility/library choices by stack or capability.
 
@@ -91,6 +101,18 @@ When merging two project structures, produce a union of paths and preserve `OR`
  |bun.lock|bun.lockb
 ```
 
+#### Example of nested project structures
+```text
+<monorepo-root>/
+ |AGENTS.md
+ |frontend/
+ | |AGENTS.md
+ | |package.json
+ |backend/
+ | |AGENTS.md
+ | |go.mod
+```
+
 ### Strict rules
 - MUST merge compatible requirements additively.
 - MUST treat stack modules as higher priority than baseline modules when strict rules conflict.

scripts/validate-agent-docs.go

@@ -238,6 +238,21 @@ func parseSkillDoc(path string) (skillDoc, error) {
 	return doc, nil
 }
 
+func checkRequiredSubstrings(v *validator, path string, required ...string) {
+	lines, err := readLines(path)
+	if err != nil {
+		v.failf("%s cannot be read: %v", path, err)
+		return
+	}
+
+	fullText := strings.Join(lines, "\n")
+	for _, needle := range required {
+		if !strings.Contains(fullText, needle) {
+			v.failf("%s must mention %q", path, needle)
+		}
+	}
+}
+
 func checkNormativeBullets(v *validator, filePath string, sectionTitle string) {
 	lines, err := readLines(filePath)
 	if err != nil {
@@ -403,20 +418,32 @@ func checkSkillFile(v *validator, skillPath string) {
 		if !strings.Contains(lowerText, "interview") {
 			v.failf("%s must require an architecture interview", skillPath)
 		}
+		if !strings.Contains(lowerText, "nested") {
+			v.failf("%s must describe nested AGENTS.md creation", skillPath)
+		}
 		if !strings.Contains(fullText, "Accept") {
 			v.failf("%s must require explicit Accept before writing", skillPath)
 		}
 	case "refresh-project-agents-from-agent-docs":
 		if !strings.Contains(lowerText, "signal") {
 			v.failf("%s must describe repository-signal based selection", skillPath)
 		}
+		if !strings.Contains(lowerText, "nested") {
+			v.failf("%s must describe nested AGENTS.md refresh", skillPath)
+		}
+		if !strings.Contains(lowerText, "frontend/") && !strings.Contains(lowerText, "apps/*") {
+			v.failf("%s must describe nested app or service boundaries", skillPath)
+		}
 		if !strings.Contains(fullText, "Accept") {
 			v.failf("%s must require explicit Accept before writing", skillPath)
 		}
 	case "refactor-project-to-agent-docs":
 		if !strings.Contains(lowerText, "interview") {
 			v.failf("%s must require an architecture interview", skillPath)
 		}
+		if !strings.Contains(lowerText, "subtree") && !strings.Contains(lowerText, "subproject") {
+			v.failf("%s must describe per-subtree or per-subproject refactoring", skillPath)
+		}
 		if !strings.Contains(lowerText, "plan") {
 			v.failf("%s must require a refactor plan before edits", skillPath)
 		}
@@ -535,6 +562,10 @@ func main() {
 		checkSkillFile(v, skillPath)
 	}
 
+	checkRequiredSubstrings(v, routerDocPath, "nested `AGENTS.md`", "nearest `AGENTS.md`", "root `AGENTS.md`")
+	checkRequiredSubstrings(v, rootPolicyPath, "nested `AGENTS.md`", "subprojects", "multiple app or service boundaries")
+	checkRequiredSubstrings(v, "README.md", "nested `AGENTS.md`", "frontend/", "backend/")
+
 	filesToCheck := make([]string, 0, len(moduleDocs)+2)
 	filesToCheck = append(filesToCheck, rootPolicyPath, routerDocPath)
 	filesToCheck = append(filesToCheck, moduleDocs...)

scripts/validate-agent-docs_test.go

@@ -155,3 +155,35 @@ Ask for explicit Accept before writing files.
 		t.Fatalf("expected interview requirement failure, got none")
 	}
 }
+
+func TestCheckRequiredSubstringsFailsWhenTextIsMissing(t *testing.T) {
+	path := writeTempDoc(t, `# Overview
+Root policy only.
+`)
+
+	v := &validator{}
+	checkRequiredSubstrings(v, path, "nested `AGENTS.md`")
+
+	if len(v.failures) == 0 {
+		t.Fatalf("expected required substring failure, got none")
+	}
+}
+
+func TestCheckSkillFileRequiresNestedSupportForRefreshSkill(t *testing.T) {
+	path := writeTempFile(t, "skills/refresh-project-agents-from-agent-docs/SKILL.md", `---
+name: refresh-project-agents-from-agent-docs
+description: Refresh AGENTS for an existing repository.
+---
+
+# Skill
+
+Use repository signals and ask for explicit Accept before writing files.
+`)
+
+	v := &validator{}
+	checkSkillFile(v, path)
+
+	if len(v.failures) == 0 {
+		t.Fatalf("expected nested support failure, got none")
+	}
+}

skills/init-project-from-agent-docs/SKILL.md

@@ -10,37 +10,41 @@ Use this skill when the repository is empty or early-stage and the user wants th
 ## Workflow
 
 1. Run a short architecture interview.
-- Ask only the questions needed to choose architecture: app purpose, user-facing surfaces, runtime shape (`web app`, `API`, `worker`, `CLI`), data and storage, auth and identity, key integrations, deployment constraints, and any mandated technologies.
+- Ask only the questions needed to choose architecture: app purpose, whether the repository is single-app or multi-app, user-facing surfaces, runtime shape (`web app`, `API`, `worker`, `CLI`), data and storage, auth and identity, key integrations, deployment constraints, and any mandated technologies.
 - If an answer is missing but a safe default exists, state the assumption explicitly instead of blocking.
 - If the repository already has substantial code or tooling, switch to `refresh-project-agents-from-agent-docs` or `refactor-project-to-agent-docs`.
 
 2. Load the current policy source of truth.
 - Resolve `doc.md` first, then `awesome/index.md`.
 - Load always-on modules from `doc.md`.
-- Load stack modules whose `load_when` conditions match the interview answers or any existing repository signals.
-- Load matching awesome files by stack and capability.
+- Detect meaningful subproject boundaries such as `frontend/`, `backend/`, `apps/*`, `services/*`, `packages/*`, or user-declared app and service directories.
+- Load stack modules whose `load_when` conditions match the interview answers or the signals for each subproject boundary.
+- Load matching awesome files by stack and capability for the root and each nested subproject.
 - Do not hardcode technology names when the router or awesome registry can decide them.
 
 3. Propose the initial architecture before writing.
 - Summarize the project brief in 3-6 bullets.
-- Show selected modules and why they match.
-- Show selected awesome capabilities and the required libraries they imply.
-- Draft the target `AGENTS.md` structure with `Overview`, `Base Policy Links (Load First)`, and `Local Details`.
+- Show the proposed repository topology, including whether nested `AGENTS.md` files are needed.
+- Show selected modules and why they match for the root and each nested subproject.
+- Show selected awesome capabilities and the required libraries they imply for each boundary.
+- Draft the target `AGENTS.md` structure for the root and any nested subprojects with `Overview`, `Base Policy Links (Load First)`, and `Local Details`.
+- Explain that the nearest `AGENTS.md` applies to a subtree while parent files stay additive for shared rules.
 - Call out assumptions, open questions, and non-default choices.
 
 4. Wait for explicit approval.
 - Ask for explicit `Accept` before creating or updating `AGENTS.md` or suggesting code scaffolding.
 - If the user changes scope, revise the proposal and ask again.
 
-5. Write the initial `AGENTS.md`.
-- Create a repository-specific `Overview`.
-- Add links to `doc.md`, `awesome/index.md`, always-on modules, and matched stack modules.
+5. Write the initial `AGENTS.md` files.
+- Create a repository-specific root `Overview`.
+- Add links to `doc.md`, `awesome/index.md`, always-on modules, and matched stack modules for the root and each nested subproject.
 - Use latest default-branch links unless the user asked for commit-pinned links.
-- Keep `Local Details` limited to project-specific constraints, decisions, and approved exceptions.
+- Keep root `Local Details` focused on shared constraints and keep nested `Local Details` focused on subtree-specific constraints, decisions, and approved exceptions.
 - Do not inline module policy text when links are sufficient.
 - Do not copy awesome registry tables into the target `AGENTS.md`.
 
 6. Validate and report.
 - Confirm every linked file exists in the selected `agent-docs` revision.
-- Report which router, module, and awesome files were selected and why.
+- Report which root and nested `AGENTS.md` files were created and why those boundaries were chosen.
+- Report which router, module, and awesome files were selected for each boundary.
 - Report any assumptions that still need user confirmation.

skills/refactor-project-to-agent-docs/SKILL.md

@@ -20,36 +20,38 @@ Use this workflow when the goal is to align an existing project with `agent-docs
 ## Workflow
 
 1. Run the architecture interview.
-- Capture app purpose, critical flows, runtime surfaces, data and storage, auth and identity, integrations, deployment constraints, mandated technologies, and allowed migration risk.
+- Capture app purpose, whether the repository is single-app or multi-app, critical flows, runtime surfaces, data and storage, auth and identity, integrations, deployment constraints, mandated technologies, and allowed migration risk.
 - Separate what may change now from what must stay stable.
 - If the repository intent is already documented, confirm it instead of re-asking everything.
 
 2. Load the current `agent-docs` source of truth.
 - Resolve `doc.md` first, then `awesome/index.md`.
-- Load always-on modules, matched stack modules, and matching awesome files.
-- Use repository signals and interview answers together to choose the target architecture.
+- Detect app and service boundaries such as `frontend/`, `backend/`, `apps/*`, `services/*`, `packages/*`, or equivalent user-declared subprojects.
+- Load always-on modules, matched stack modules, and matching awesome files for the root and each subtree.
+- Use repository signals and interview answers together to choose the target architecture for each subtree.
 - Treat the current repository `AGENTS.md` as local input to preserve valid repository-specific exceptions, not as the router source of truth.
 
 3. Audit the target project against policy.
-- Inspect structure, dependency and runtime setup, task runner config, lint and format config, tests, build entrypoints, and major code patterns.
-- Identify mismatches between current project state and loaded policy rules.
+- Inspect structure, dependency and runtime setup, task runner config, lint and format config, tests, build entrypoints, and major code patterns for the root and each subtree.
+- Identify mismatches between current project state and loaded policy rules per subtree.
 - Capture baseline command results for lint, test, and build when those commands exist.
 
 4. Propose the target architecture and plan.
-- Summarize selected modules, awesome capabilities, and required library or tooling changes.
+- Summarize selected modules, awesome capabilities, and required library or tooling changes for the root and each nested subproject.
+- Explain where nested `AGENTS.md` files are required and how nearest-file precedence applies to each subtree.
 - Output an ordered phase plan with goals, impacted files, risks, validations, and rollback notes for risky steps.
-- Cover at minimum: structure, task runner/tasks, linting/formatting, code-style normalization, dependency alignment, and `AGENTS.md` updates.
+- Cover at minimum: structure, task runner/tasks, linting/formatting, code-style normalization, dependency alignment, and root plus nested `AGENTS.md` updates.
 - Ask for explicit `Accept` before editing.
 
 5. Execute by phase.
 - Refactor structure to the approved policy-aligned layout and naming.
 - Refactor automation and tasking to match expected workflow patterns.
 - Refactor lint, format, and dependency setup to the approved stack and capability choices.
-- Refactor code style and architecture incrementally while preserving approved behavior.
-- Update `AGENTS.md` and developer documentation so commands and rules remain accurate.
+- Refactor code style and architecture incrementally per subtree while preserving approved behavior.
+- Update root and nested `AGENTS.md` files and developer documentation so commands and rules remain accurate.
 
 6. Verify `agent-docs` compliance.
-- Build a rule-by-rule checklist from the loaded modules and awesome files.
+- Build a rule-by-rule checklist from the loaded modules and awesome files for the root and each subtree.
 - Mark each rule as `pass`, `fail`, or `not-applicable` with file or command evidence.
 - Fix `fail` items that are in scope.