fix(instructions): deduplicate workspace content in nested AGENTS.md generation

[dsk-dev-ai]

Summary

Fixes #45. When agentrc instructions generates nested instruction files for a
large monorepo (e.g. a Rust workspace with 24+ crates), the per-crate
AGENTS.md files no longer duplicate the workspace-wide root instructions, drop
the misleading # Copilot Instructions: <crate> crate heading, and now know what
the root file already covers so the LLM only emits crate-unique context.

Approach

The content of these files is LLM-generated from skills (see
plugin/skills/nested-hub/SKILL.md, plugin/skills/nested-detail/SKILL.md), so
deduplication is done at generation time: after the root AGENTS.md hub is
generated, its content is fed back into the per-area / per-crate generation
prompts as a "Root instructions already cover" section, and the skill prompt
explicitly instructs the model to only cover crate-unique details and never
repeat the root file. A deterministic post-processing step normalizes the
top-level heading.

Changes (per issue findings)

Finding	Addressed by
F2 "Kitchen sink" – per-crate files repeated root conventions ({ workspace = true }, error types, logging, testing, build commands)	Root hub content is threaded into nested generation (rootContent on the generation options), embedded in the prompt via buildRootContextSection() (## Root instructions already cover … Do NOT repeat or restate it), and the nested-hub skill instructs crate-unique-only output.
F3 Redundant "Monorepo Context" section	Covered by the same root-context injection; the nested-hub skill drops the crate-unique-only rule and the root-context section, so workspace-wide facts live only in the root file.
F4 Title mismatch – # Copilot Instructions: <crate> crate heading on AGENTS.md	normalizeAgentsHeading() rewrites the heading to # <crate> (falling back to the name in the heading) for all nested AGENTS.md output.
F1 Dual file types	The generator now honors a configurable instructionFile (default unchanged: .github/copilot-instructions.md), so a repo can consistently reference a single instruction file in VS Code settings. Choosing one strategy per repo remains an explicit agentrc instructions --strategy decision.

Commit history (branch feature/deduplicate-agents-md, base 8d0c05c)

734e812 refactor(instructions): prepare nested generation context
8e98a35 feat(skills): reduce duplicated workspace instructions
775d426 feat(instructions): normalize AGENTS headings
f1aa05b fix(generator): respect selected instruction output
7a19fd7 refactor(cli): propagate nested generation context
f702d50 test(instructions): cover nested AGENTS generation

Files changed

packages/core/src/services/instructions.ts   root-context plumbing + heading normalization
packages/core/src/services/generator.ts      configurable instructionFile in VS Code settings
plugin/skills/nested-hub/SKILL.md            crate-unique-only + root-context guidance
src/commands/instructions.ts                 CLI wiring of root content into area generation
src/services/__tests__/instructions.test.ts  +8 tests (buildRootContextSection, normalizeAgentsHeading, integration)
src/services/__tests__/generator.test.ts     +2 tests (instructionFile honored / default)

Net: +213 / −14 across 6 files.

Verification

• npm run lint, npm run typecheck, npm test all green (685 tests across 31 files, +10 new).
• Existing behavior preserved when rootContent is unset (--areas-only, single --area, flat strategy) — falls back to the previous prompt.

Confidence

High for F2/F3/F4 (~90%): heading normalization is deterministic, and the
root-context prompt section + skill guidance directly target the observed
duplication. Note the dedup itself is prompt-driven (LLM), so output varies per
model run — the deterministic fallback (buildExistingInstructionsSection
"do not restate it" rule) remains as a safety net.

Partial for F1 (~70%): the generator can now reference a single instruction
file, but enforcing a single strategy per repo (root AGENTS.md + per-directory
vs. copilot-instructions.md + .github/instructions/*.instructions.md globs)
and the post-generation dedup pass listed under "Suggested improvements" are
not implemented and can be follow-ups.

Follow-ups (out of scope here)

• Wire instructionFile through init/pr/generate CLI + VS Code extension callers (currently API-available, callers keep the default).
• Optional post-generation dedup pass that diffs generated files against the root and warns on detected duplication.

[Copilot]

Pull request overview

This PR improves agentrc instructions generation for large monorepos by reducing duplicated workspace-wide content in nested AGENTS.md outputs, normalizing nested hub headings, and allowing VS Code settings to reference a configurable instruction file path.

Changes:

• Thread root AGENTS.md content into nested hub/detail generation prompts to discourage restating workspace-wide conventions.
• Normalize nested AGENTS.md headings to avoid “Copilot Instructions:” titles.
• Add instructionFile support so generated VS Code settings can reference a selected instruction file (default remains .github/copilot-instructions.md), with new tests covering the behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/core/src/services/instructions.ts	Adds root-context prompt section plumbing and heading normalization for nested hubs/details.
packages/core/src/services/generator.ts	Allows VS Code settings generation to reference a configurable instruction file path.
plugin/skills/nested-hub/SKILL.md	Updates nested hub generation guidance to avoid repeating root content and adjust headings.
src/commands/instructions.ts	Wires root hub content into subsequent per-area generation in the CLI flow.
src/services/tests/instructions.test.ts	Adds tests for root-context prompt section, heading normalization, and propagation into nested area generation.
src/services/tests/generator.test.ts	Adds tests ensuring VS Code settings respect instructionFile and the default.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/commands/instructions.ts:95

• rootContent is set to the freshly generated hub content before writing it to disk. If writeNestedInstructions(...) later skips the root AGENTS.md because it already exists and --force isn’t set, the subsequent per-area generation will be deduped against unwritten root instructions (potentially causing area/crate files to omit workspace-wide guidance that isn’t actually present in the on-disk root file). Consider only propagating rootContent when the root hub was actually written (or, if skipped, load the existing root file content instead).

            detailDir,
            claudeMd
          });
          rootContent = nestedResult.hub.content;

[dsk-dev-ai]

I've addressed the Copilot review feedback, updated the implementation accordingly, and all checks continue to pass. Happy to make any additional changes based on maintainer feedback.