Documentation Index

documentation
index
reference
Complete guide to all documentation automation files and resources in this repository
Author

Dario Airoldi

Published

December 26, 2025

📚 Documentation Index

Complete guide to all documentation automation files and resources in this repository.

📂 Documentation by Category

🛠️ Setup & Installation

File Purpose Audience
GETTING-STARTED.md Complete IQPilot setup guide All Users
idea/IQPilot/02. IQPilot Getting started.md Detailed installation & configuration All Users
.copilot/scripts/build-iqpilot.ps1 Build automation script Developers

🏗️ Architecture & Implementation

File Purpose Audience
idea/IQPilot/03. IQPilot Implementation details.md Architecture, folder structure, MCP integration Developers
idea/IQPilot/01. IQPilot overview.md Concepts, philosophy, use cases All Users
src/IQPilot/README.md C# MCP Server source code documentation Developers
.github/STRUCTURE-README.md Repository structure & automation overview All Users

✍️ Content Creation

File Purpose Audience
.github/templates/article-template.md General technical article template Writers
.github/templates/howto-template.md Step-by-step guide template Writers
.github/templates/tutorial-template.md Multi-step tutorial template Writers
.github/templates/issue-template.md Problem + solution template Writers
.github/templates/recording-summary-template.md Conference/video notes template Writers
.github/templates/recording-analysis-template.md Deep analysis template Writers
.github/templates/metadata-template.yml Metadata schema template Writers

📏 Editorial Standards

File Purpose Audience
.github/copilot-instructions.md Global editorial & validation standards All Users
.copilot/context/style-guide.md Writing style & formatting rules Writers
.copilot/context/validation-criteria.md Quality thresholds for publishing Writers
.copilot/context/domain-concepts.md Core concepts & terminology All Users

🔄 Workflows & Processes

File Purpose Audience
.copilot/context/workflows/article-creation-workflow.md Step-by-step article creation process Writers
.copilot/context/workflows/review-workflow.md Maintenance & update workflow Writers
.copilot/context/workflows/series-planning-workflow.md Multi-article series planning Writers

🤖 AI Prompt Files

IQPilot supports dual-mode operation:

Standalone Prompts (Work Without IQPilot)

Located in .github/prompts/ - accessible via natural language with GitHub Copilot:

Content Creation:

Validation:

Analysis:

Publishing:

Enhanced Prompts (Require IQPilot MCP)

Located in .iqpilot/prompts/ - used automatically when IQPilot is in MCP mode:

Automatic Selection: Copilot automatically chooses enhanced version if IQPilot MCP is active, falls back to standalone if not.

📋 Path-Specific Instructions

Automatically applied to files in specific folders:

File Applies To Purpose
.github/instructions/documentation.instructions.md **/*.md All Markdown files
.github/instructions/tech-articles.instructions.md tech/**/*.md Technical content
.github/instructions/prompts.instructions.md .github/prompts/**/*.md Prompt file creation
.github/instructions/agents.instructions.md .github/agents/**/*.agent.md Agent file creation
.github/instructions/context-files.instructions.md .copilot/context/**/*.md Context file creation

🤖 Prompt Engineering Ecosystem

Complete guide to prompt, agent, and context engineering in this repository.

Core Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    INSTRUCTION LAYER                            │
│  .github/instructions/*.instructions.md                         │
│  (Auto-applied based on file path globs)                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CONTEXT LAYER                                │
│  .copilot/context/prompt-engineering/*.md                       │
│  (Shared principles, patterns, and guidelines)                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OPERATIONAL LAYER                            │
│  .github/prompts/*.prompt.md  |  .github/agents/*.agent.md     │
│  (Task workflows)             |  (Role-based specialists)       │
└─────────────────────────────────────────────────────────────────┘

Context Files (Shared Principles)

Location: .copilot/context/prompt-engineering/

File Purpose Key Content
context-engineering-principles.md Core principles 6 principles: Narrow Scope, Early Commands, Imperative Language, Three-Tier Boundaries, Context Minimization, Tool Scoping
tool-composition-guide.md Tool selection Priority rules, role-based tool sets, composition patterns
validation-caching-pattern.md 7-day caching Dual YAML architecture, cache check workflow
handoffs-pattern.md Multi-agent coordination Handoff patterns: Linear Chain, Parallel Research, Validation Loop, Supervised

Prompt Files

Location: .github/prompts/

Prompt Creation/Update:

Guidance Maintenance:

Agent Files

Location: .github/agents/

Agent Creation/Update:

Specialized Agents by Role:

Role Agent Purpose Tools
Researcher @prompt-researcher Pattern discovery Read-only
Builder @prompt-builder File creation Read + Write
Validator @prompt-validator Quality assurance Read-only
Updater @prompt-updater Fix issues Read + Write

Tech Articles (Learning)

Location: tech/PromptEngineering/

Article Topic
01. Copilot File Consumption How Copilot reads files
02. Naming Conventions File and folder organization
03. Prompt Structure YAML frontmatter and sections
04. Agent Structure Personas, handoffs, boundaries
05. Instruction Structure Path-specific instructions
06. Multi-Agent Prompts Orchestration patterns
07. Implementation Example Real-world multi-agent workflow
08. Documentation Site Repository-specific patterns

Templates

Location: .github/templates/

Template Use Case
prompt-simple-validation-template.md Read-only validation with 7-day caching
prompt-implementation-template.md File creation/modification workflows
prompt-multi-agent-orchestration-template.md Multi-agent coordination
prompt-analysis-only-template.md Research and reporting

Quick Reference: Creating New Files

To create a new prompt:

/prompt-createorupdate-prompt-file-v2 [describe purpose]

To create a new agent:

/agent-createorupdate-agent-file-v2 [describe role]

To update guidance files:

/prompt-createorupdate-prompt-guidance [describe updates needed]

🔧 Automation Scripts

File Purpose Usage
.copilot/scripts/build-metadata-watcher.ps1 Build LSP server & extension .\.copilot\scripts\build-metadata-watcher.ps1
.copilot/scripts/validate-metadata.ps1 Validate metadata schema .\.copilot\scripts\validate-metadata.ps1
.copilot/scripts/check-stale-validations.ps1 Find outdated validations .\.copilot\scripts\check-stale-validations.ps1

⚙️ VS Code Configuration

File Purpose Audience
.vscode/tasks.json Build & publish tasks Developers
.vscode/launch.json Debug configurations Developers
.vscode/settings.json Workspace settings All Users
.vscode/extensions.json Recommended extensions All Users

📦 Source Code

Directory Purpose Audience
src/IQPilot/ C# MCP Server source code Developers
.vscode/extensions/iqpilot/ VS Code extension (TypeScript) Developers

🗺️ Documentation Roadmap

Phase 1: IQPilot Core ✅

Phase 2: Integration 🚧

Phase 3: User Guides ✅

Phase 4: Deployment (Planned)

📊 Documentation Statistics

Category Count Total Lines
Setup Guides 2 ~5,000
Technical Docs 3 ~10,000
Templates 7 ~700
Prompts 13 ~3,000
Instructions 3 ~300
Workflows 3 ~600
Scripts 3 ~500
Total 34 ~20,100

🔍 Finding What You Need

By Task

I want to understand IQPilot: → idea/IQPilot/01. IQPilot overview.md

I want to set up the repository: → GETTING-STARTED.md

I want to write a new article: → article-creation-workflow.md → Choose template from .github/templates/

I want to validate my content: → Use prompts in .github/prompts/ (via /command in Copilot)

I want to understand the architecture: → idea/IQPilot/03. IQPilot Implementation details.md

I want to develop IQPilot: → src/IQPilot/README.md

I want to configure settings: → .vscode/settings.json

By Role

Content Writer:

  1. GETTING-STARTED.md - Setup
  2. .copilot/context/style-guide.md - Writing standards
  3. .github/templates/ - Templates
  4. .github/prompts/ - Validation tools

Developer:

  1. idea/IQPilot/03. IQPilot Implementation details.md - Architecture
  2. src/IQPilot/README.md - Technical details
  3. .vscode/tasks.json - Build tasks
  4. .vscode/launch.json - Debug configs

Editor/Reviewer:

  1. .github/copilot-instructions.md - Standards
  2. .copilot/context/validation-criteria.md - Quality thresholds
  3. .copilot/context/workflows/review-workflow.md - Review process

By File Type

Markdown Documentation:

  • All .md files in root directory
  • .copilot/context/*.md
  • src/IQPilot/README.md, src/IQPilot/README.IQPilot.md

YAML Configuration:

  • .github/templates/metadata-template.yml
  • .vscode/settings.json (JSON, but related)

PowerShell Scripts:

  • .copilot/scripts/*.ps1

TypeScript Source:

  • .vscode/extensions/iqpilot/src/*.ts

C# Source:

  • src/IQPilot/*.cs

🆘 Quick Help

Most Common Needs

  1. Setup: GETTING-STARTED.md ← Start here!
  2. Write Article: Use template + /article-writing
  3. Validate: /structure-validation → /grammar-review → /publish-ready
  4. Rename Article: F2 in VS Code (metadata syncs automatically)
  5. Troubleshoot: Check logs via status bar

Key Commands

  • Reload VS Code: Ctrl+Shift+P → “Developer: Reload Window”
  • Run Task: Ctrl+Shift+P → “Tasks: Run Task”
  • Restart IQPilot: Ctrl+Shift+P → “IQPilot: Restart Server”
  • Show Logs: Click status bar ✓ IQPilot

🎯 Next Steps

  1. ✅ Read idea/IQPilot/01. IQPilot overview.md to understand the concepts
  2. ✅ Read GETTING-STARTED.md for setup instructions
  3. ✅ Build IQPilot: .\.copilot\scripts\build-iqpilot.ps1
  4. ✅ Reload VS Code
  5. ✅ Create test article
  6. ✅ Try validation prompts via GitHub Copilot
  7. ✅ Start writing real content!

Last Updated: 2025-11-23
Total Documentation Files: 34
Repository: darioairoldi/Learn