feat: add nested instruction strategy with hub + detail files

[digitarald]

Summary

Adds a nested instruction strategy that generates a lean AGENTS.md hub with deep-dive detail files in a configurable directory (.agents/ by default), plus optional CLAUDE.md transclusion.

Changes

• Config & Types — InstructionStrategy type, parentArea, detailDir, claudeMd in AgentrcConfig with validation
• CLI — --strategy <mode> and --claude-md flags. CLI > config > default flat
• Nested Generation — Single CopilotClient, hub extracts topic JSON, per-topic detail sessions, slug sanitization
• File Writing — writeInstructionFile() with traversal validation, writeNestedInstructions() orchestrator
• Detection — detectExistingInstructions() finds .agents/*.md detail files
• VS Code Extension — Strategy and CLAUDE.md quick picks, nested generation flow
• Tests — 20+ new tests for parsing, writing, detection, and config validation

Verification

• Typecheck: clean
• Lint: clean
• Tests: 503/503 passed
• Build: CLI + extension clean

[Copilot]

Pull request overview

Adds a new nested instruction generation strategy (hub AGENTS.md + per-topic detail files in a configurable directory, plus optional CLAUDE.md transclusion) and wires it through the CLI and VS Code extension, with accompanying config parsing and expanded test coverage.

Changes:

• Introduces InstructionStrategy (flat | nested) and config support for strategy, detailDir, claudeMd, and parentArea (with validation).
• Implements nested instruction generation + writing (generateNested*, writeInstructionFile, writeNestedInstructions) and detection of existing nested detail files.
• Updates CLI/VS Code flows to select strategy and execute nested generation; adds tests for parsing/writing/detection/config.

Reviewed changes

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

Show a summary per file

File	Description
vscode-extension/src/services.ts	Re-exports new analyzer/config and nested instruction services for the extension.
vscode-extension/src/commands/instructions.ts	Adds strategy quick pick + nested generation flow in VS Code.
src/services/instructions.ts	Implements nested hub/detail generation, writing helpers, and nested detail detection.
src/services/analyzer.ts	Extends config/types to include strategy/detailDir/claudeMd/parentArea with validation.
src/services/tests/instructions.test.ts	Adds tests for nested parsing/writing/detection and new writer helper.
src/services/tests/analyzer.test.ts	Adds tests for new config fields and validation.
src/commands/instructions.ts	Adds --strategy / --claude-md behavior and nested generation/write flow in CLI.
src/commands/generate.ts	Plumbs --strategy through primer generate ... to instructions generation.
src/cli.ts	Adds CLI flags for --strategy and --claude-md.

Comments suppressed due to low confidence (2)

src/commands/instructions.ts:83

• Nested generation logs Skipped ... (exists, use --force) for every non-"wrote" action, but writeInstructionFile() can also skip due to symlink or empty content. With the current writeNestedInstructions() return shape, this message will be misleading in those cases. Either propagate a skip reason in the actions or use a more generic skip message here.

          for (const action of actions) {
            const relPath = path.relative(process.cwd(), action.path);
            if (action.action === "wrote") {
              if (shouldLog(options)) progress.succeed(`Wrote ${relPath}`);
            } else if (shouldLog(options)) {
              progress.update(`Skipped ${relPath} (exists, use --force)`);
            }

src/services/instructions.ts:782

• Same as above: this process.stderr.write warning is emitted from the service regardless of --quiet / UI context. Consider routing warnings through onProgress or returning them so the CLI/VS Code layer controls how (or whether) they are displayed.

      } catch (err) {
        const msg = err instanceof Error ? err.message : String(err);
        process.stderr.write(`Warning: Failed to generate detail for "${topic.title}": ${msg}\n`);
      }

[Copilot]

detailDir is treated as a single directory name (entry.name === detailDirName). However, loadAgentrcConfig() allows values containing / (e.g. docs/ai). In that case, existing detail files won’t be detected. Either constrain detailDir to a single path segment during config validation, or update findDetailFiles() to handle multi-segment relative paths.

[Copilot]

loadAgentrcConfig() now parses parentArea, but the analyzed Area objects used by CLI/extension appear to never receive this field (searching src/services/analyzer.ts shows no other parentArea assignments). As a result, downstream logic like areas.filter((a) => a.parentArea === area.name) and hub parentContext will never work. Ensure detectAreas()/the config-area→Area mapping propagates parentArea onto Area objects.

[Copilot]

generateNestedHub() calls detectExistingInstructions(options.repoPath) without passing the configured detailDir. If detailDir is customized (e.g. docs-ai), existing nested detail files won’t be detected and the hub prompt can duplicate content. Pass options.detailDir as the detailDirName argument so detection matches the strategy output directory.

Suggested change

	const existingCtx = await detectExistingInstructions(options.repoPath);
	const existingCtx = await detectExistingInstructions(options.repoPath, options.detailDir);