Acreadiness Generate Instructions

AgentRC instruction generation

Generate or refresh repository instruction files through AgentRC's Measure → Generate → Maintain loop, choosing the right output target, strategy, and scoped applyTo layout for GitHub Copilot and other agents.

When to invoke

• "Generate Copilot instructions for this repo."
• "Refresh our AI agent instructions after acreadiness assess."
• "Create AGENTS.md and scoped instructions."
• "Use AgentRC instructions with nested strategy."
• "Add per-area .instructions.md files with applyTo globs."

Inputs

Use $ARGUMENTS as command-line options for AgentRC generation. Validate supported flags before running anything: --output, --strategy, --areas, --area, --areas-only, --apply-to, --claude-md, --dry-run, and --force when overwriting is confirmed. If $ARGUMENTS is empty, default to .github/copilot-instructions.md and ask which strategy to use unless the user already specified one.

Output options

Strategy choices

For GitHub Copilot, native scoped files live in .github/instructions/ with applyTo frontmatter. AgentRC's default nested layout writes .agents/ for agent-agnostic repositories; rewrite to .github/instructions/ when the main output is .github/copilot-instructions.md. If --output AGENTS.md is chosen, keep AgentRC's native .agents/ layout.

Area-scoped instructions

When agentrc.config.json declares areas, default to offering per-area .instructions.md files. Each area file must be lowercase kebab-case and start with applyTo frontmatter.

---
applyTo: "apps/frontend/**"
---

# Frontend area instructions

...AgentRC-generated content for this area...

Procedure

1. Pick the target file. Default to .github/copilot-instructions.md; switch to AGENTS.md only for multi-agent, Claude, Cursor, or explicit user request.

2. Ask which strategy to use, flat or nested, unless supplied by user or $ARGUMENTS. Recommend nested when the repo has more than 5 top-level directories, multiple stacks, or monorepo tooling such as turbo, nx, or pnpm workspaces.

3. Read agentrc.config.json to discover areas. If areas exist, ask whether to generate per-area .instructions.md files; default to yes. If an area lacks paths, ask for a glob such as src/api/**. If --apply-to <glob> is supplied for a single area, use it verbatim.

4. Run a dry run first:

   npx -y github:microsoft/agentrc instructions --output <file> --strategy <flat|nested> [--areas|--area <name>] [--claude-md] --dry-run
   

5. Show a short summary of files to create or overwrite, area count and their applyTo globs, and the model used, default claude-sonnet-4.6.

6. On confirmation, run the same command without --dry-run, adding --force only if overwriting existing files was confirmed.

7. Post-process layout for GitHub Copilot output:

   • If --output ends in copilot-instructions.md and strategy is nested, move or rewrite .agents/<topic>.md to .github/instructions/<topic>.instructions.md, add suitable applyTo, and delete now-empty .agents/.
   • If --areas or --area <name> was used, write .github/instructions/<area>.instructions.md for each area using paths from agentrc.config.json unless overridden by --apply-to.
   • If --output AGENTS.md was chosen, keep .agents/ for nested output.

8. Verify by reading generated files back and summarize detected stack, conventions captured, length, and .instructions.md files with their globs.

9. Suggest next steps: rerun the assess skill to confirm AI Tooling improved; consolidate if both copilot-instructions.md and AGENTS.md already exist.

Topic applyTo defaults

Gotchas

• Always dry-run first: instruction files are repository policy and should be reviewed before overwrite.
• Do not run non-interactively in CI: generated instructions should land through a PR.
• Copilot scoped files are not .agents/: use .github/instructions/*.instructions.md with applyTo when targeting .github/copilot-instructions.md.
• AgentRC reads actual code: do not replace generated content with generic templates.

This is the highest-leverage AgentRC action for AI Tooling. VS Code auto-discovers .github/instructions/*.instructions.md; examples include .github/instructions/frontend.instructions.md, .github/instructions/api.instructions.md, and .github/instructions/infra.instructions.md. per-language guidance belongs in scoped files when useful. For monorepos, agentrc instructions --areas can generate area-scoped content. In a single-area call, --apply-to overrides the area path. Nested Copilot output may require move/rewrite from .agents/ into .github/instructions/. Present the flat versus nested trade-off for small/medium repositories and detect turbo/nx/pnpm workspaces. Area files MUST include applyTo.

Output template

## AgentRC instruction generation result

**Status:** generated | previewed | blocked
**Target:** `.github/copilot-instructions.md` | `AGENTS.md`
**Strategy:** `flat` | `nested`

| File | Scope | applyTo | Status |
| --- | --- | --- | --- |
| `<path>` | `<root/topic/area/Claude>` | `<glob or always-on>` | `<created/updated/previewed>` |

**Command**
`npx -y github:microsoft/agentrc instructions --output <file> --strategy <flat|nested> ...`

**Synopsis:** <stack detected, conventions captured, length>
**Next steps:** <assess rerun or consolidation advice>

Quality gate

• $ARGUMENTS was parsed and unsupported options were rejected or ignored safely.
• The target defaulted to .github/copilot-instructions.md unless the user requested AGENTS.md or multi-agent output.
• Strategy was supplied or confirmed before generation.
• agentrc.config.json areas and paths were read when area output was requested or available.
• A dry run was shown before any overwrite or generation.
• GitHub Copilot nested output was rewritten to .github/instructions/*.instructions.md with applyTo frontmatter.
• AGENTS.md nested output kept .agents/ when chosen.
• Generated files were read back and summarized with lengths and globs.