harness-everything 0.2.0

package/create-agent-launcher/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: create-agent-launcher
+description: Sub-agent generator for orchestrating multi-domain specialized agents to avoid token waste.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Create Agent Launcher
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Invoked by `fable-mode` for Tier 3 tasks needing domain-specific division of labor — task complexity exceeds a single context, or spans disjoint tech stacks. |
+| **Expected Output** | One or more sub-agents launched with an explicit persona, a resource-isolated scope (only the file paths relevant to their task), and a model-tier assignment (Haiku / Sonnet / Opus by sub-task complexity). |
+| **State Mutations** | None directly to files — mutates the active session's delegation state (which sub-agents are live, what each was briefed to touch). |
+| **Enforcement Gate** | Every sub-agent MUST return a structured handoff report (files modified, new APIs/interfaces exposed, downstream concerns) before its output is trusted. Creating a sub-agent is **PROHIBITED** if the task fits in ≤2 files / ≤300 lines — resolve directly under `tdd` instead. |
+
+This skill is automatically invoked by `fable-mode` when handling Tier 3 (Macro Tasks) that require domain-specific division of labor.
+Its purpose is to avoid wasting Tokens and losing attention caused by a single General Agent handling everything, by creating highly specialized Sub-agents to solve complex problems.
+
+## 1. Responsibilities and Use Cases
+Launch this skill when the task complexity exceeds what a single context can handle, or when switching between entirely different tech stacks is necessary (e.g., the same feature requires modifying Postgres Schema, Node.js Backend, and React Frontend).
+
+## 2. Standard Procedure for Creating Sub-agents
+
+### Step 1: Persona Definition
+Before calling a secondary model (or instantiating a new Agent), you MUST explicitly give it a specialized persona definition.
+- **Bad Example**: "Help me fix these frontend and backend codes."
+- **Good Example**: "You are now a Senior Database Architect. Your sole task is to optimize the indexing and write performance of the User Table for this requirement. You are PROHIBITED from modifying any frontend code."
+
+### Step 2: Resource Isolation
+- Limit the Sub-agent's field of view. Only provide it with the file paths and Context necessary to complete its task.
+- Do not feed the entire project structure to an Agent that is only responsible for writing a single SQL Migration.
+
+### Step 3: Model Selection Strategy
+Based on the complexity of the sub-task, select the most cost-effective model (assuming the underlying Harness supports switching):
+- **Exploration/Finding Files/Simple Edits**: Assign to a fast, low-cost small model (like Claude 3.5 Haiku).
+- **Multi-file Implementation/General Logic**: Assign to a medium-sized main model (like Claude 3.5 Sonnet).
+- **Extremely Complex Algorithms/Security Audits**: Assign to a deep reasoning model (like Claude 3 Opus).
+
+### Step 4: Handoff Contract
+- Tell the Sub-agent that once it completes its task, it MUST output a report in a specific format to the main Orchestrator (`fable-mode`).
+- The report MUST include: which files were modified, what new APIs/interfaces were exposed, and what downstream Agents need to pay attention to.
+
+## 3. Foolproofing Mechanism
+- Avoid over-segmentation: If a cross-stack task can be resolved within 2 files and 300 lines of code, establishing a Sub-agent is **PROHIBITED**. Resolve it directly in the current Context using `tdd` mode.
+- Sub-agents are also Agents, equally bound by the `install-cognitive-os` physical laws and the `zoom-out` circuit breaker.

package/create-agent-launcher/examples/csharp-monorepo.md

@@ -0,0 +1,123 @@
+---
+description: "Output example for create-agent-launcher applied to a fictional C# super-monorepo project (Contoso Workbench). Shows the Context Profile from project discovery and the expected generated agent content."
+---
+
+# Example: C# Super-Monorepo (Contoso Workbench)
+
+This example shows what the Project Discovery step should extract from the project, and what the generated agent files should contain. **Contoso Workbench is a fictional project** — substitute your own project's real names, paths, and build commands.
+
+---
+
+## Input: Project Discovery Findings
+
+After reading `README.md`, `AGENTS.md` (or `.github/copilot-instructions.md`), and `.gitmodules`, the LLM should record this Context Profile:
+
+```
+Project Name:       Contoso Workbench
+Primary Language:   C# (.NET Framework 4.7.2)
+Full Build Command: dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj  (or via ./compile)
+Local Build Command:dotnet build <specific.csproj> inside the affected submodule
+Key Source Paths:   Workbench.App/Workbench.App/ (main desktop app), Workbench.Common/ (shared utils),
+                    Workbench.VcsBridge/ (VCS integration), Workbench.Reporting/ (report engine)
+AI Plan Path:       docs/ai_plans/ at the MAIN REPO ROOT (not inside submodules)
+Monorepo Type:      git submodules (level-1 only)
+Workspace File:     Workbench.sln
+Special Constraints:Source code MUST live in submodules — never commit source to the main repo.
+                    Each submodule must be level-1.
+```
+
+**Key signals discovered from README.md:**
+- "In the super project, only solution file (.sln), cmake list and other collective control files are placed, and **no source code is allowed**."
+- "All reference projects in the super project must be located under the git submodule."
+- List of submodule directories: `Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/`, `Workbench.Reporting/`, etc.
+
+---
+
+## Output: Generated Agent Files
+
+**`requirement-analyzer.agent.md` — Approach section:**
+```markdown
+## Approach
+
+1. **Analyze Requirements**: Review the requirements. Use `search` and `read` tools to
+   gather context from the relevant submodule(s): `Workbench.App/Workbench.App/` (main app
+   project), `Workbench.Common/` (shared utilities), `Workbench.VcsBridge/` (VCS
+   integration), and others as applicable. All source code lives in level-1 git
+   submodules — never in the main repo.
+2. **Handle Ambiguities**: Note critical ambiguities for the user; otherwise proceed.
+3. **Document**: Save a detailed implementation document at the **main repo root** as
+   `docs/ai_plans/implement_<feature-name>.md`
+   (e.g., `docs/ai_plans/implement_vcs_tag_merge_support.md`). Include:
+   - Implementation Goals
+   - Approach / Methodology
+   - Detailed Implementation Steps
+   - Implementation Details (classes, APIs, files, submodule paths)
+   - Architecture Diagrams (if applicable)
+```
+
+**`backend-developer.agent.md` — full file:**
+```markdown
+---
+name: "Backend Developer"
+description: "Use when: you need to implement C# source code based on a requirement list or AI plan. This agent implements features and verifies them using 'dotnet build'."
+tools: [read, edit, search, execute]
+---
+
+You are an expert C# Backend Developer working in the **Contoso Workbench** solution.
+Your primary responsibility is to implement C# source code strictly based on a
+provided requirement list or AI implementation document.
+
+## Approach
+
+1. **Analyze Requirements**: Read the provided implementation document in
+   `docs/ai_plans/`. Use `search` and `read` to understand the existing C# codebase
+   in the relevant submodule(s): `Workbench.App/Workbench.App/`, `Workbench.Common/`,
+   `Workbench.VcsBridge/`.
+2. **Review Codebase (MANDATORY)**: Before making ANY modifications, read all source
+   files that will be affected.
+3. **Implement**: Use the `edit` tool to modify or create C# source code inside the
+   appropriate submodule. Do NOT add source files to the main repo.
+4. **Verify via Compilation — choose minimum scope**:
+   - **Step 1 — Assess scope**: Did you only change private/internal code within a single `.csproj`
+     (method bodies, private fields, internal classes)? → **Local build**.
+     Did you change a public/protected API, an interface, an enum, or a `.csproj` dependency? → **Cross-project build**.
+   - **Local build** (single project, fastest): `dotnet build <changed-project>.csproj`
+     inside the affected submodule (e.g., `dotnet build Workbench.VcsBridge/VcsBridge/VcsBridge.csproj`).
+   - **Cross-project build** (when public API changes may break dependents):
+     `dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj`
+   - Prefer local build first. Escalate to cross-project only when the assessment above requires it.
+
+## Constraints
+
+- DO NOT modify the requirements. Your job is strictly implementation.
+- ALWAYS ensure the code compiles successfully before considering your task complete.
+- Fix all compiler errors before finishing.
+- All source code changes MUST be made inside the relevant submodule — never in the main repo.
+```
+
+**`agent-launcher/SKILL.md` — Project-Specific Notes section:**
+```markdown
+## Project-Specific Notes
+
+- **Build verification**: `dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj`
+  (or scope to specific `.csproj` for isolated changes)
+- **AI plan documents**: Save at `docs/ai_plans/implement_<name>.md` at the **main repo root**
+  (repo-root-relative — never an absolute disk path, and never inside a submodule)
+- **Primary language**: C# (.NET Framework 4.7.2)
+- **Monorepo notes**: Super monorepo — all source code lives in level-1 git submodules
+  (`Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/`, etc.). Never commit
+  source to the main repo.
+```
+
+---
+
+## Key Specificity Points
+
+| Element | Expected in Generated Agent |
+|---------|-----------------------------|
+| Source paths | `Workbench.App/Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/` (with role annotations) |
+| AI plan location | `docs/ai_plans/` **at the main repo root** — explicitly, not inside submodules |
+| Path style | Always repo-root-relative — generated agents must never contain absolute disk paths |
+| Architecture constraint | "Never add source files to the main repo" |
+| Build scope decision | Assess scope first; prefer `dotnet build <X.csproj>` before escalating to solution-wide |
+| Project identity | "the **Contoso Workbench** solution" |

package/create-agent-launcher/examples/typescript-cli.md

@@ -0,0 +1,126 @@
+---
+description: "Output example for create-agent-launcher applied to a fictional TypeScript npm-workspaces monorepo CLI project (Acme CLI). Shows the Context Profile from project discovery and the expected generated agent content."
+---
+
+# Example: TypeScript npm Monorepo CLI (Acme CLI)
+
+This example shows what the Project Discovery step should extract from the project, and what the generated agent files should contain. **Acme CLI is a fictional project** — substitute your own project's real names, paths, and build commands.
+
+---
+
+## Input: Project Discovery Findings
+
+After reading `README.md`, `AGENTS.md` (project-specific AI notes), and `package.json`, the LLM should record this Context Profile:
+
+```
+Project Name:       Acme CLI
+Primary Language:   TypeScript / Node.js
+Full Build Command: npm run build  (runs scripts/build.sh across all packages)
+Local Build Command:npm run build -w packages/<package-name>
+Key Source Paths:   packages/core/src/ (core agent logic),
+                    packages/cli/src/ (CLI entry point and commands),
+                    packages/vscode-companion/ (VSCode integration)
+AI Plan Path:       docs/ai_plans/ at the repo root
+Monorepo Type:      npm workspaces
+Workspace File:     package.json (workspaces: ["packages/*"])
+Special Constraints:Run 'npm run lint' after build. Integration tests in integration-tests/.
+```
+
+**Key signals discovered from README.md and package.json:**
+- `"workspaces": ["packages/*"]` → npm workspaces monorepo
+- `"build": "scripts/build.sh"` → custom build script (not bare `tsc`)
+- `"lint": "eslint ."` → ESLint configured
+- Packages: `@acme/cli` (CLI entry), `@acme/cli-core` (core logic)
+- TypeScript config at root `tsconfig.json` and per-package
+
+---
+
+## Output: Generated Agent Files
+
+**`requirement-analyzer.agent.md` — Approach section:**
+```markdown
+## Approach
+
+1. **Analyze Requirements**: Review the requirements. Use `search` and `read` tools to
+   gather context from the relevant packages: `packages/core/src/` (core logic, tools,
+   and model integration), `packages/cli/src/` (CLI entry point, commands, and REPL),
+   and `packages/vscode-companion/` (VSCode companion extension) as applicable.
+2. **Handle Ambiguities**: Note critical ambiguities for the user; otherwise proceed.
+3. **Document**: Save a detailed implementation document at `docs/ai_plans/` as
+   `implement_<feature-name>.md` (e.g., `docs/ai_plans/implement_cli_auth.md`).
+   Include:
+   - Implementation Goals
+   - Approach / Methodology
+   - Detailed Implementation Steps
+   - Implementation Details (classes, APIs, files, package paths)
+   - Architecture Diagrams (if applicable)
+```
+
+**`backend-developer.agent.md` — full file:**
+```markdown
+---
+name: "Backend Developer"
+description: "Use when: you need to implement TypeScript/Node.js source code based on a requirement list or AI plan. This agent implements features and verifies them using 'npm run build'."
+tools: [read, edit, search, execute]
+---
+
+You are an expert TypeScript/Node.js Developer working in the **Acme CLI** monorepo.
+Your primary responsibility is to implement TypeScript source code strictly based on a
+provided requirement list or AI implementation document.
+
+## Approach
+
+1. **Analyze Requirements**: Read the provided implementation document in `docs/ai_plans/`.
+   Use `search` and `read` to understand the existing codebase in the relevant packages:
+   `packages/core/src/` (core logic and tools), `packages/cli/src/` (CLI commands
+   and REPL), and `packages/vscode-companion/` (VSCode integration).
+2. **Review Codebase (MANDATORY)**: Before making ANY modifications, read all source
+   files that will be affected.
+3. **Implement**: Use the `edit` tool to modify or create TypeScript source code.
+4. **Verify via Compilation/Linting — choose minimum scope**:
+   - **Step 1 — Assess scope**: Did you only change files inside a single package (e.g., only
+     `packages/cli/src/`)? → **Local build**. Did you change a shared type, a public export
+     from `packages/core/`, or a root-level config? → **Full workspace build**.
+   - **Local build** (single package, fastest):
+     `npm run build -w packages/<package-name>`
+     (e.g., `npm run build -w packages/cli`)
+   - **Full workspace build** (when shared exports or cross-package types change):
+     `npm run build` (runs the full `scripts/build.sh` pipeline)
+   - **After any build**: Run `npm run lint` to ensure linting passes.
+   - Prefer local build first. Escalate to full workspace only when the assessment above requires it.
+
+## Constraints
+
+- DO NOT modify the requirements. Your job is strictly implementation.
+- You MUST thoroughly read all relevant existing files before writing any code.
+- ALWAYS ensure the code compiles and lint passes before considering your task complete.
+- Fix all compilation and lint errors before finishing.
+```
+
+**`agent-launcher/SKILL.md` — Project-Specific Notes section:**
+```markdown
+## Project-Specific Notes
+
+- **Build verification**: `npm run build` (full workspace via `scripts/build.sh`)
+  or `npm run build -w packages/<name>` for a single package
+- **Lint**: Always run `npm run lint` after build
+- **AI plan documents**: Save at `docs/ai_plans/implement_<name>.md` (or `fix_<name>.md`),
+  repo-root-relative — never an absolute disk path
+- **Primary language**: TypeScript / Node.js
+- **Monorepo notes**: npm workspaces (`packages/*`). Key packages:
+  `packages/core` (`@acme/cli-core`) and `packages/cli` (`@acme/cli`).
+  Integration tests live in `integration-tests/`.
+```
+
+---
+
+## Key Specificity Points
+
+| Element | Expected in Generated Agent |
+|---------|-----------------------------|
+| Source paths | `packages/core/src/` (core logic), `packages/cli/src/` (CLI commands), with role annotations |
+| Path style | Always repo-root-relative — generated agents must never contain absolute disk paths |
+| Build scope decision | Assess scope first; prefer `npm run build -w packages/<name>` before escalating to full build |
+| Lint requirement | Explicit: always run `npm run lint` after any build |
+| Package identity | `@acme/cli-core` and `@acme/cli` (not just "the workspace") |
+| AI plan example | `docs/ai_plans/implement_cli_auth.md` (real naming pattern) |

package/create-agent-launcher/guidelines/platform-claude.md

@@ -0,0 +1,77 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Claude Code (Anthropic CLI). Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: Claude Code (Anthropic CLI)
+
+## Naming Convention
+
+- Agent names must use **lowercase with hyphens** (e.g., `requirement-analyzer`, `backend-developer`).
+- No spaces allowed in agent names or identifiers.
+- File names follow the same convention (e.g., `requirement-analyzer.md`).
+
+## Tools Declaration
+
+Use Claude Code's exact tool name strings as a YAML array:
+
+```yaml
+tools: ["Read", "Edit", "Glob", "Grep", "Bash", "AskUserQuestion"]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: ["Read", "Edit", "Glob", "Grep", "Bash", "AskUserQuestion"]` (exclude `"Bash"` for Requirement Analyzer)
+- `{{READ_TOOL_NAME}}`: `"Read"`
+- `{{EDIT_TOOL_NAME}}`: `"Edit"`
+- `{{SEARCH_TOOL_NAME}}`: `"Glob" and "Grep"`
+- `{{EXECUTE_TOOL_NAME}}`: `"Bash"`
+
+> **CRITICAL RULE — AskUserQuestion is MANDATORY**: When generating a **restricted** tool list (i.e., any list that does not include all tools), you MUST always include `"AskUserQuestion"` in the array. If this tool is omitted, the agent will lose the ability to ask clarifying questions and will enter a **deadlock state** — unable to proceed or request help.
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Agent definitions | `.claude/agents/*.md` |
+| Output styles | `.claude/output-styles/` |
+| System prompt | `CLAUDE.md` (project root) |
+| Global config | `~/.claude/output-styles/` |
+
+Default target directory is `.claude/`.
+
+## User Interaction Mechanism
+
+Use the built-in `AskUserQuestion` tool to pause the agent loop and prompt the user:
+
+```
+AskUserQuestion(
+  question: "Where should the agent scaffold be created?",
+  options: [".claude/ (default)", "Custom path"]
+)
+```
+
+This renders as an interactive prompt in the CLI terminal, blocking execution until the user responds.
+
+## System Prompt / Instructions File
+
+After generating agents, ensure `CLAUDE.md` at the project root contains the orchestrator rules. If `CLAUDE.md` does not exist, create it with the State Machine block.
+
+## Agent File Format
+
+Plain Markdown files under `.claude/agents/`:
+
+```markdown
+# requirement-analyzer
+
+**Role**: Requirement Analyzer  
+**Tools**: Read, Edit, Glob, Grep, AskUserQuestion
+
+You are an expert AI Architect...
+
+## Constraints
+...
+
+## Approach
+...
+```
+
+YAML frontmatter is optional in Claude agents; use a `# heading` and `**field**:` pattern instead if preferred.

package/create-agent-launcher/guidelines/platform-codex.md

@@ -0,0 +1,146 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Codex / Custom API environments. Covers naming, OpenAI Tool Spec / JSON Schema format, directory layout, and custom ask_user function calling."
+---
+
+# Platform Guidelines: Codex / Custom API Environment
+
+## Naming Convention
+
+- Follow system variable / key-value naming conventions (e.g., `requirement_analyzer`, `backend_developer`).
+- Use lowercase with underscores or hyphens; avoid spaces.
+- Names serve as JSON object keys — they must be valid identifiers in most languages.
+
+## Tools Declaration
+
+There are **no built-in tools**. All tools must be defined using the **OpenAI Tool Spec (JSON Schema)** format and implemented in your local orchestrator code.
+
+When generating agent files from templates (if not using pure JSON), substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: *(Leave empty in Markdown, handled via JSON configuration)*
+- `{{READ_TOOL_NAME}}`: `read_file`
+- `{{EDIT_TOOL_NAME}}`: `write_file`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute_command`
+
+Each agent definition includes a `tools` array of JSON Schema objects:
+
+```json
+{
+  "agents": {
+    "requirement_analyzer": {
+      "name": "requirement_analyzer",
+      "description": "Analyzes user requirements and creates implementation documents.",
+      "tools": [
+        {
+          "type": "function",
+          "function": {
+            "name": "read_file",
+            "description": "Read a file from the project.",
+            "parameters": {
+              "type": "object",
+              "properties": {
+                "path": { "type": "string", "description": "File path to read." }
+              },
+              "required": ["path"]
+            }
+          }
+        },
+        {
+          "type": "function",
+          "function": {
+            "name": "ask_user",
+            "description": "Pause the agent loop and ask the user a question.",
+            "parameters": {
+              "type": "object",
+              "properties": {
+                "question": { "type": "string" },
+                "options": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              },
+              "required": ["question"]
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Directory Layout
+
+All paths are **custom** — defined by the local orchestrator implementation:
+
+| Artifact | Suggested Path |
+|----------|---------------|
+| Agent definitions | `config/agents/*.json` or `config/agents.json` |
+| System prompt | `config/system_prompt.txt` |
+| Tool schemas | `config/tools/*.json` |
+| Global config | `~/.config/myapp/` or as defined by your app |
+
+Default target directory is `config/`.
+
+## User Interaction Mechanism
+
+There is **no built-in confirmation mechanism**. Implement a custom `ask_user` function tool that follows the OpenAI Function Calling / Tool Use pattern:
+
+1. The agent calls `ask_user` with a `question` and optional `options`.
+2. The API returns the function call in its response.
+3. Your **local orchestrator code** intercepts the call, renders the UI (terminal prompt, web form, etc.), and submits the user's answer back as a tool result.
+4. The agent resumes execution.
+
+The `ask_user` schema should mirror `vscode_askQuestions` for portability:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "ask_user",
+    "description": "Ask the user a question and wait for their response before continuing.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "header": { "type": "string", "description": "Short identifier for the question." },
+        "question": { "type": "string", "description": "The question to ask." },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": { "type": "string" },
+              "recommended": { "type": "boolean" }
+            },
+            "required": ["label"]
+          }
+        },
+        "allowFreeformInput": { "type": "boolean", "default": true }
+      },
+      "required": ["header", "question"]
+    }
+  }
+}
+```
+
+## System Prompt / Instructions File
+
+The system prompt format is fully custom. Suggested location: `config/system_prompt.txt` or `config/system_prompt.md`. Include the orchestrator rules adapted for your API loop implementation.
+
+## Agent File Format
+
+Agent definitions are typically JSON objects:
+
+```json
+{
+  "name": "requirement_analyzer",
+  "description": "Analyzes requirements and creates implementation documents.",
+  "system_prompt": "You are an expert AI Architect...",
+  "tools": ["read_file", "edit_file", "ask_user"],
+  "constraints": [
+    "DO NOT implement features yourself.",
+    "ALWAYS create a structured implementation document first."
+  ]
+}
+```
+
+Implement `read_file`, `edit_file`, and all other tools referenced in `tools` arrays in your orchestrator's backend code.

package/create-agent-launcher/guidelines/platform-copilot.md

@@ -0,0 +1,74 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting GitHub Copilot (VS Code). Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: GitHub Copilot (VS Code)
+
+## Naming Convention
+
+- Agent names are **flexible** — spaces, Chinese characters, and mixed case are allowed.
+- Recommended style: Title Case with spaces (e.g., `Requirement Analyzer`, `Backend Developer`).
+- File names use kebab-case (e.g., `requirement-analyzer.agent.md`).
+
+## Tools Declaration
+
+Use the VS Code-encapsulated permission names as a YAML array:
+
+```yaml
+tools: [read, edit, search, execute]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: [read, edit, search, execute]` (exclude `execute` for Requirement Analyzer)
+- `{{READ_TOOL_NAME}}`: `read`
+- `{{EDIT_TOOL_NAME}}`: `edit`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute`
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Agent definitions | `<target_dir>/agents/*.agent.md` |
+| Orchestrator instructions | `<target_dir>/instructions/orchestrator.instructions.md` |
+| Skill entry point | `<target_dir>/skills/agent-launcher/SKILL.md` |
+| System prompt | `.github/copilot-instructions.md` |
+| Global config | `~/.config/github-copilot/` |
+
+Default `<target_dir>` is `.github/`.
+
+## User Interaction Mechanism
+
+Use the `vscode_askQuestions` tool to pause the workflow and prompt the user for decisions.
+
+```json
+[{
+  "header": "unique_key",
+  "question": "Your question here?",
+  "options": [
+    { "label": "Option A", "recommended": true },
+    { "label": "Option B" }
+  ],
+  "allowFreeformInput": true
+}]
+```
+
+This renders as a dropdown or input box in the VS Code window.
+
+## System Prompt / Instructions File
+
+After generating agents, ensure `.github/copilot-instructions.md` contains the `## 🤖 State Machine Orchestrator Instructions` block. If the file does not exist, create it.
+
+## Agent File Format
+
+Standard `.agent.md` file with YAML frontmatter:
+
+```yaml
+---
+name: "Requirement Analyzer"
+description: "Use when: ..."
+tools: [read, edit, search]
+---
+```
+
+All files MUST include a YAML frontmatter `description` field for context optimization.