AI-Augmented Development Framework

Provides GitHub Copilot with context and instructions for working with the AI-Augmented Project (AIAP) system—a universal framework for integrating AI agents into software development workflows across any technology stack.

What This Skill Does

This skill configures GitHub Copilot to understand and work effectively with AIAP's architecture, including:

**Specialized AI Agents**: 18+ agent profiles for different development roles (developer, architect, QA, security, DevOps, etc.)

**Token-Optimized Context**: Query scripts that reduce token usage by 85-95% compared to full documentation reads

**Multi-Project Orchestration**: Coordinate AI assistance across multiple projects with different technology stacks

**Stack-Agnostic Integration**: Plugin-based adapters for .NET, Python, TypeScript, Java, and any other stack

**Workflow Governance**: Templates, conventions, and best practices for AI-augmented development

Instructions for the AI Agent

Core Principles

1. **AIAP is a framework, not a project**: It contains agent profiles, orchestration tools, query scripts, and templates—but no project-specific source code.

2. **Projects integrate via `.aiap/` folder**: Any project (regardless of stack) adds a `.aiap/` configuration folder to enable AI-augmented capabilities.

3. **Use query scripts first**: Before reading documentation files, always use token-optimized query scripts located in `tools/query-scripts/`.

Token-Efficient Context Loading

**CRITICAL**: Choose the right context mechanism to minimize token usage.

**Context Loading Decision Tree**:

**Need AIAP structure/agents/vision?**

→ Use query scripts (85-95% token savings)

```bash

./tools/query-scripts/quick-ref.sh agents

./tools/query-scripts/ai-context.sh project

./tools/query-scripts/query-docs.sh --topic X

```

**Need specific code files/classes?**

→ Use # references (targeted, 50-70% savings)

```

#MyClass.cs

#src/services/UserService.ts

```

**Need exploratory codebase analysis?**

→ Use @workspace (comprehensive but token-heavy, last resort)

**Need project-wide rules?**

→ Already loaded automatically via `.github/copilot-instructions.md` (zero token cost)

**Query Script Tools**:

`quick-ref.sh` - Ultra-fast lookups (< 500 tokens)

- `./tools/query-scripts/quick-ref.sh agents` - List all agents

- `./tools/query-scripts/quick-ref.sh vision` - Vision summary

- `./tools/query-scripts/quick-ref.sh structure` - Folder layout

`ai-context.sh` - Context building (1-4K tokens)

- `./tools/query-scripts/ai-context.sh project` - Project overview

- `./tools/query-scripts/ai-context.sh architecture` - Architecture summary

- `./tools/query-scripts/ai-context.sh conventions` - Coding standards

`query-docs.sh` - Documentation search (500-3K tokens)

- `./tools/query-scripts/query-docs.sh --agent developer` - Find agent

- `./tools/query-scripts/query-docs.sh --issue 39` - Issue docs

- `./tools/query-scripts/query-docs.sh --topic auth` - Search topic

`query-metadata.sh` - Metadata extraction (100-500 tokens)

- `./tools/query-scripts/query-metadata.sh --stats` - Statistics

- `./tools/query-scripts/query-metadata.sh --list-types` - Document types

**Token Savings Examples**:

List agents: 99.2% savings (200 tokens vs 25K)

Project overview: 93.3% savings (800 tokens vs 12K)

Find issue docs: 98% savings (2K tokens vs 100K)

Working with AI Agents

**Quick Agent Invocation** (short names):

```bash

Core agents - frequently used

/agent stakeholder # Business & requirements

/agent architect # System design & ADRs

/agent dev # Code implementation

/agent qa # Testing & quality assurance

/agent docs # Technical documentation

/agent devops # CI/CD & deployment

/agent security # Security review

/agent perf # Performance optimization

Specialist agents

/agent bugfix # Bug fixing

/agent review # Code review

/agent refactor # Refactoring

/agent planner # Implementation planning

```

**Agent Capabilities**:

All agents have access to MCP (Model Context Protocol) servers for extended capabilities

Each agent has clearly defined tools and responsibilities

Agents can coordinate on multi-step workflows

AIAP Architecture Understanding

**Framework Structure**:

```

ai-augmented-project-template/

├── .aiap/ # Integration templates (for projects to copy)

│ ├── project-context.yml # Project identity template

│ ├── stack-config.yml # Stack-specific config template

│ └── integration-hooks.yml # Tool integration template

├── agents/ # 18+ AI agent profiles

├── tools/query-scripts/ # Token-optimized query tools

├── src/aiap-core/ # Core framework code

│ └── integrations/ # Stack adapters (.NET, Python, TypeScript, Java, etc.)

├── docs/ # Architecture & guides

├── docs-site/ # Docusaurus published documentation

└── ai-agent-docs-web/ # Docs drafting workspace (never committed)

├── README.md # Workflow explanation

└── _work/ # Draft content (git-ignored)

```

**Project Integration Pattern**:

```

your-project/ # Any stack (.NET, Python, etc.)

├── .aiap/ # AIAP configuration (ADD THIS)

│ ├── project-context.yml # Project identity & tech stack

│ ├── stack-config.yml # Stack-specific configuration

│ └── integration-hooks.yml # Tool integrations

├── src/ # Your source code (UNCHANGED)

├── tests/ # Your tests (UNCHANGED)

└── docs/ # Your documentation (UNCHANGED)

```

Stack Adapters

AIAP uses plugin-based adapters to understand different technology stacks:

**`.NET`**: Understands .csproj, NuGet, C# complexity metrics

**`Python`**: Understands requirements.txt, pip, Python conventions

**`TypeScript`**: Understands package.json, npm, TypeScript config

**`Java`**: Understands pom.xml, Maven/Gradle, Java conventions

**`Generic`**: Basic file structure analysis for any stack

Located in: `src/aiap-core/integrations/`

Coding Standards

**General Principles**:

Clarity over cleverness

DRY (Don't Repeat Yourself)

YAGNI (You Aren't Gonna Need It)

Fail fast with clear error messages

Prefer immutability

**C# Conventions** (when working with C# projects):

PascalCase for classes, methods, properties, constants

camelCase for local variables and parameters

_camelCase for private fields (underscore prefix)

Use `var` when type is obvious

Always use braces for control structures

Opening braces on new lines (Allman style)

Maximum line length: 120 characters

**Naming**:

Use descriptive, meaningful names

Interfaces start with 'I' (e.g., `IRepository`)

Async methods end with 'Async' (e.g., `GetUserAsync`)

Boolean variables/methods read like questions (e.g., `IsValid`, `CanExecute`)

Documentation Requirements

**Code Comments**:

Explain "why", not "what"

Keep comments concise and relevant

Update comments when code changes

Add XML documentation for all public APIs

**Documentation Workflow**:

Drafts go in `ai-agent-docs-web/_work/` (never committed)

Published docs go in `docs-site/docs/` (after review)

Technical deep-dives go in `docs/` (ADRs, design guides)

Testing Requirements

**Test Coverage**:

Aim for 80%+ on business logic

100% coverage on critical paths

Every bug fix requires a regression test

**Test Structure**:

Follow Arrange-Act-Assert (AAA) pattern

Descriptive names: `MethodName_Scenario_ExpectedBehavior`

One assertion per test (logical unit)

Tests should be isolated and independent

Commit Message Format

Follow Conventional Commits:

```

[optional body]

[optional footer]

```

**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`

**Examples**:

```

feat(auth): add password reset functionality

fix(api): handle null reference in user controller

docs(readme): update installation instructions

test(users): add integration tests for user service

```

Security Guidelines

Never trust user input (validate and sanitize)

Use parameterized queries (prevent SQL injection)

Validate file uploads (type, size, content)

Implement rate limiting on public endpoints

Never commit secrets to version control

Use environment variables or secure vaults

Redact sensitive data in logs

Performance Considerations

Use async/await for I/O-bound operations

Implement caching strategies where appropriate

Profile before optimizing

Consider pagination for large data sets

Use appropriate HTTP status codes and headers

Error Handling

Use exceptions for exceptional cases only

Create custom exception types for domain errors

Log all exceptions with context

Return meaningful error messages to clients

Implement global exception handling

Usage Examples

Example 1: Understanding AIAP Architecture

**User**: "Explain how AIAP handles multiple projects with different stacks."

**AI Response**:

```bash

First, get token-efficient overview

./tools/query-scripts/ai-context.sh architecture

Result shows:

- AIAP is stack-agnostic framework

- Projects integrate via .aiap/ folder

- Stack adapters in src/aiap-core/integrations/

- Multi-project orchestration coordinates across stacks

```

Example 2: Working with a Specific Agent

**User**: "I need to review code for security issues."

**AI Response**:

```bash

Quick reference to security agent

./tools/query-scripts/quick-ref.sh agents | grep security

Invoke security agent

/agent security

Agent performs:

- Input validation checks

- Authentication/authorization review

- Sensitive data handling audit

- OWASP top 10 vulnerability scan

```

Example 3: Integrating a New Project

**User**: "How do I add AIAP to my Python project?"

**AI Response**:

```bash

Get integration template info

./tools/query-scripts/ai-context.sh project

Steps:

1. Copy .aiap/ templates to your project root

2. Edit .aiap/project-context.yml (set name, stack: python)

3. Edit .aiap/stack-config.yml (python-specific settings)

4. AIAP will use Python adapter from src/aiap-core/integrations/

```

Example 4: Finding Documentation Efficiently

**User**: "Where are the testing guidelines?"

**AI Response**:

```bash

Search documentation without loading everything

./tools/query-scripts/query-docs.sh --topic testing

Returns:

- Test coverage requirements (80%+ business logic)

- AAA pattern usage

- Test naming conventions

- Test categories (unit, integration, e2e)

```

Constraints and Important Notes

1. **Never commit drafts**: Content in `ai-agent-docs-web/_work/` must never be committed to version control.

2. **Query scripts first**: Always attempt to use query scripts before loading full documentation to minimize token usage.

3. **Stack adapters are plugins**: When working with a new technology stack, check if an adapter exists in `src/aiap-core/integrations/` or create one following the plugin pattern.

4. **AIAP does not contain project code**: AIAP is a framework. Project-specific implementations live in separate repositories and integrate via `.aiap/` folder.

5. **Agent specialization**: Each agent has specific responsibilities. Use the right agent for the task (e.g., `/agent security` for security reviews, `/agent qa` for testing).

6. **Multi-project coordination**: When working across multiple projects, AIAP can coordinate AI assistance even if projects use different technology stacks.

7. **Documentation sites**: Published documentation goes in `docs-site/` (Docusaurus), deep technical docs in `docs/` (ADRs, architecture).

8. **Folder policies must be respected**:

- Only Docs Web Agent writes to `ai-agent-docs-web/`

- All published content requires human review before merging

- Follow the Draft → Review → Publish workflow

9. **Security is paramount**: Follow all security guidelines, especially for input validation, authentication, and sensitive data handling.

10. **Token efficiency is critical**: The query scripts can reduce token usage by 85-95%. Use them proactively to avoid wasting context window space.

AI-Augmented Development Framework

AI-Augmented Development Framework

What This Skill Does

Instructions for the AI Agent

Core Principles

Token-Efficient Context Loading

Working with AI Agents

Core agents - frequently used

Specialist agents

AIAP Architecture Understanding

Stack Adapters

Coding Standards

Documentation Requirements

Testing Requirements

Commit Message Format

Security Guidelines

Performance Considerations

Error Handling

Usage Examples

Example 1: Understanding AIAP Architecture

First, get token-efficient overview

Result shows:

- AIAP is stack-agnostic framework

- Projects integrate via .aiap/ folder

- Stack adapters in src/aiap-core/integrations/

- Multi-project orchestration coordinates across stacks

Example 2: Working with a Specific Agent

Quick reference to security agent

Invoke security agent

Agent performs:

- Input validation checks

- Authentication/authorization review

- Sensitive data handling audit

- OWASP top 10 vulnerability scan

Example 3: Integrating a New Project

Get integration template info

Steps:

1. Copy .aiap/ templates to your project root

2. Edit .aiap/project-context.yml (set name, stack: python)

3. Edit .aiap/stack-config.yml (python-specific settings)

4. AIAP will use Python adapter from src/aiap-core/integrations/

Example 4: Finding Documentation Efficiently

Search documentation without loading everything

Returns:

- Test coverage requirements (80%+ business logic)

- AAA pattern usage

- Test naming conventions

- Test categories (unit, integration, e2e)

Constraints and Important Notes

Reviews (0)