write-instructions

Prompt file imported from GurkeX/FreeRTOS-ai-optimized-codebase (.github/prompts/operations/write-instructions.prompt.md). Copyright stays with the author.

Help me create modular copilot instructions for this codebase. The global agent writes .github/copilot-instructions.md; specialized sub-agents write each component's local copilot-instructions.md.

Process

Step 1: Analyze the Codebase

Ground rule: only document what actually exists. Never infer, assume, or describe intended behavior — read the code.

1. Read the entry point(s) — trace the real startup/execution sequence from the actual source
2. Read the build config (CMakeLists.txt, package.json, pyproject.toml, etc.) — extract the true tech stack, versions, and build commands
3. Walk the directory tree — note only directories that contain code or are operationally relevant; skip generated/vendor/build output
4. Grep for real conventions — scan 5–10 representative source files to extract actual naming patterns, logging calls, and error handling (do not guess from file names alone)
5. Identify components — list only modules with non-trivial APIs or integration requirements; a simple utility file does not need its own instructions
6. Check existing docs — read README, AGENTS.md, inline comments; treat them as hints, not ground truth; verify against the code

Quality over quantity: one accurate, verified fact is worth more than five inferred ones. If something is unclear from the code, note it as unknown rather than filling it in.

Step 2: Delegate Components to Sub-Agents

For each identified component, spin off a sub-agent loaded with .github/prompts/operations/write-component-instructions.prompt.md, passing:

• Component name and path
• One-sentence purpose

Sub-agents operate independently and write directly into their component directories. Continue to Step 3 in parallel — do not wait.

Step 3: Write the Global File

Write .github/copilot-instructions.md (100–500 lines) covering:

1. Architecture at a Glance (10–30 lines)

• Annotated directory tree — one line per key directory
• Entry point(s) and high-level execution flow in 2–3 sentences
• Key platform constraints (e.g., "all compilation inside Docker", "SMP dual-core")

2. Build & Workflow Commands

• Copy-pasteable build, flash, test, and lint commands
• Any required environment setup

3. Global Coding Standards

• Naming conventions (files, functions, classes, variables)
• Logging format and severity levels
• Error handling patterns

4. AI Agent Instructions

• 5–10 bullets on how agents should work with this codebase
• Always include: "Check for a local copilot-instructions.md before working in any component directory"

5. Component Instructions Index (populated in Step 4)

• One line per component: path and one-sentence purpose

Step 4: Verify and Link

Confirm each component copilot-instructions.md was created by sub-agents, then populate the Component Instructions Index in the global file.

Output Template

# Project Name — AI Agent Operations Manual

> **Target**: [platform] · **Stack**: [language/framework] · **Version**: [version]

## 1. Architecture
[Annotated directory tree + 2–3 sentence execution flow. 10–30 lines max.]

## 2. Build & Workflow
[Copy-pasteable commands]

## 3. Coding Standards
[Naming, logging, error handling — bullets only]

## 4. AI Agent Instructions
[5–10 bullets]

## 5. Component Instructions
- `path/to/component/` — one-sentence purpose

Start by analyzing the codebase structure now. If this is a new project, ask clarifying questions before identifying components.