CHANGE: Update prompts for improved documentation
- Refactor input sections to use consistent headings. - Enhance clarity in documentation standards and requirements. - Update descriptions for better alignment with best practices. - Add comprehensive analysis and planning phases for LLMs. - Create new `llms.txt` file prompt for repository structure.
This commit is contained in:
Daniel Scott-Raynsford
parent
ef786a2120
commit
e935dc0ed0
@ -7,17 +7,17 @@ tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo',
|
||||
|
||||
Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability.
|
||||
|
||||
**Inputs:**
|
||||
## Inputs
|
||||
|
||||
- **Context**: `${input:Context}`
|
||||
- **Decision**: `${input:Decision}`
|
||||
- **Alternatives**: `${input:Alternatives}`
|
||||
- **Stakeholders**: `${input:Stakeholders}`
|
||||
|
||||
**Input Validation:**
|
||||
## Input Validation
|
||||
If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.
|
||||
|
||||
**Requirements:**
|
||||
## Requirements
|
||||
|
||||
- Use precise, unambiguous language
|
||||
- Follow standardized ADR format with front matter
|
||||
@ -28,7 +28,7 @@ If any of the required inputs are not provided or cannot be determined from the
|
||||
|
||||
The ADR must be saved in the `/docs/adr/` directory using the naming convention: `adr-NNNN-[title-slug].md`, where NNNN is the next sequential 4-digit number (e.g., `adr-0001-database-selection.md`).
|
||||
|
||||
**Required Documentation Structure:**
|
||||
## Required Documentation Structure
|
||||
|
||||
The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
|
||||
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Create GitHub Issue for feature request from specification file using feature_request.yml template.'
|
||||
description: Create GitHub Issue for feature request from specification file using feature_request.yml template.
|
||||
tools: ['codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
|
||||
---
|
||||
# Create GitHub Issue from Specification
|
||||
|
||||
Create GitHub Issue for the specification at `${file}`.
|
||||
|
||||
**Process:**
|
||||
## Process
|
||||
|
||||
1. Analyze specification file to extract requirements
|
||||
2. Check existing issues using `search_issues`
|
||||
3. Create new issue using `create_issue` or update existing with `update_issue`
|
||||
4. Use `feature_request.yml` template (fallback to default)
|
||||
|
||||
**Requirements:**
|
||||
## Requirements
|
||||
|
||||
- Single issue for the complete specification
|
||||
- Clear title identifying the specification
|
||||
- Include only changes required by the specification
|
||||
- Verify against existing issues before creation
|
||||
|
||||
**Issue Content:**
|
||||
## Issue Content
|
||||
|
||||
- Title: Feature name from specification
|
||||
- Description: Problem statement, proposed solution, and context
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates.'
|
||||
description: Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates.
|
||||
tools: ['codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
|
||||
---
|
||||
# Create GitHub Issue from Implementation Plan
|
||||
|
||||
Create GitHub Issues for the implementation plan at `${file}`.
|
||||
|
||||
**Process:**
|
||||
## Process
|
||||
|
||||
1. Analyze plan file to identify phases
|
||||
2. Check existing issues using `search_issues`
|
||||
3. Create new issue per phase using `create_issue` or update existing with `update_issue`
|
||||
4. Use `feature_request.yml` or `chore_request.yml` templates (fallback to default)
|
||||
|
||||
**Requirements:**
|
||||
## Requirements
|
||||
|
||||
- One issue per implementation phase
|
||||
- Clear, structured titles and descriptions
|
||||
- Include only changes required by the plan
|
||||
- Verify against existing issues before creation
|
||||
|
||||
**Issue Content:**
|
||||
## Issue Content
|
||||
|
||||
- Title: Phase name from implementation plan
|
||||
- Description: Phase details, requirements, and context
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template.'
|
||||
description: Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template.
|
||||
tools: ['codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
|
||||
---
|
||||
# Create GitHub Issues for Unmet Specification Requirements
|
||||
|
||||
Create GitHub Issues for unimplemented requirements in the specification at `${input:file}`.
|
||||
Create GitHub Issues for unimplemented requirements in the specification at `${file}`.
|
||||
|
||||
**Process:**
|
||||
## Process
|
||||
|
||||
1. Analyze specification file to extract all requirements
|
||||
2. Check codebase implementation status for each requirement
|
||||
@ -15,20 +15,20 @@ Create GitHub Issues for unimplemented requirements in the specification at `${i
|
||||
4. Create new issue per unimplemented requirement using `create_issue`
|
||||
5. Use `feature_request.yml` template (fallback to default)
|
||||
|
||||
**Requirements:**
|
||||
## Requirements
|
||||
|
||||
- One issue per unimplemented requirement from specification
|
||||
- Clear requirement ID and description mapping
|
||||
- Include implementation guidance and acceptance criteria
|
||||
- Verify against existing issues before creation
|
||||
|
||||
**Issue Content:**
|
||||
## Issue Content
|
||||
|
||||
- Title: Requirement ID and brief description
|
||||
- Description: Detailed requirement, implementation method, and context
|
||||
- Labels: feature, enhancement (as appropriate)
|
||||
|
||||
**Implementation Check:**
|
||||
## Implementation Check
|
||||
|
||||
- Search codebase for related code patterns
|
||||
- Check related specification files in `/spec/` directory
|
||||
|
||||
@ -5,28 +5,30 @@ tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo',
|
||||
---
|
||||
# Implementation Plan Update Prompt
|
||||
|
||||
**PRIMARY DIRECTIVE**: Your goal is to create a new implementation plan file for `${input:PlanPurpose}`. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
|
||||
## Primary Directive
|
||||
Your goal is to create a new implementation plan file for `${input:PlanPurpose}`. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
|
||||
|
||||
**EXECUTION CONTEXT**: This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
|
||||
## Execution Context
|
||||
This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
|
||||
|
||||
**CORE REQUIREMENTS**:
|
||||
## Core Requirements
|
||||
|
||||
- Generate implementation plans that are fully executable by AI agents or humans
|
||||
- Use deterministic language with zero ambiguity
|
||||
- Structure all content for automated parsing and execution
|
||||
- Ensure complete self-containment with no external dependencies for understanding
|
||||
|
||||
**PLAN STRUCTURE REQUIREMENTS**:
|
||||
## Plan Structure Requirements
|
||||
Plans must consist of discrete, atomic phases containing executable tasks. Each phase must be independently processable by AI agents or humans without cross-phase dependencies unless explicitly declared.
|
||||
|
||||
**PHASE ARCHITECTURE**:
|
||||
## Phase Architecture
|
||||
|
||||
- Each phase must have measurable completion criteria
|
||||
- Tasks within phases must be executable in parallel unless dependencies are specified
|
||||
- All task descriptions must include specific file paths, function names, and exact implementation details
|
||||
- No task should require human interpretation or decision-making
|
||||
|
||||
**AI-OPTIMIZED IMPLEMENTATION STANDARDS**:
|
||||
## AI-Optimized Implementation Standards
|
||||
|
||||
- Use explicit, unambiguous language with zero interpretation required
|
||||
- Structure all content as machine-parseable formats (tables, lists, structured data)
|
||||
@ -36,7 +38,7 @@ Plans must consist of discrete, atomic phases containing executable tasks. Each
|
||||
- Use standardized prefixes for all identifiers (REQ-, TASK-, etc.)
|
||||
- Include validation criteria that can be automatically verified
|
||||
|
||||
**OUTPUT FILE SPECIFICATIONS**:
|
||||
## Output File Specifications
|
||||
|
||||
- Save implementation plan files in `/plan/` directory
|
||||
- Use naming convention: `[purpose]-[component]-[version].md`
|
||||
@ -44,10 +46,10 @@ Plans must consist of discrete, atomic phases containing executable tasks. Each
|
||||
- Example: `upgrade-system-command-4.md`, `feature-auth-module-1.md`
|
||||
- File must be valid Markdown with proper front matter structure
|
||||
|
||||
**MANDATORY TEMPLATE STRUCTURE**:
|
||||
## Mandatory Template Structure
|
||||
All implementation plans must strictly adhere to the following template. Each section is required and must be populated with specific, actionable content. AI agents must validate template compliance before execution.
|
||||
|
||||
**TEMPLATE VALIDATION RULES**:
|
||||
## Template Validation Rules
|
||||
|
||||
- All front matter fields must be present and properly formatted
|
||||
- All section headers must match exactly (case-sensitive)
|
||||
|
||||
210
prompts/create_llms.prompt.md
Normal file
210
prompts/create_llms.prompt.md
Normal file
@ -0,0 +1,210 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: Create an llms.txt file from scratch based on repository structure following the llms.txt specification at https://llmstxt.org/
|
||||
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||
---
|
||||
# Create LLMs.txt File from Repository Structure
|
||||
|
||||
Create a new `llms.txt` file from scratch in the root of the repository following the official llms.txt specification at https://llmstxt.org/. This file provides high-level guidance to large language models (LLMs) on where to find relevant content for understanding the repository's purpose and specifications.
|
||||
|
||||
## Primary Directive
|
||||
|
||||
Create a comprehensive `llms.txt` file that serves as an entry point for LLMs to understand and navigate the repository effectively. The file must comply with the llms.txt specification and be optimized for LLM consumption while remaining human-readable.
|
||||
|
||||
## Analysis and Planning Phase
|
||||
|
||||
Before creating the `llms.txt` file, you must complete a thorough analysis:
|
||||
|
||||
### Step 1: Review llms.txt Specification
|
||||
|
||||
- Review the official specification at https://llmstxt.org/ to ensure full compliance
|
||||
- Understand the required format structure and guidelines
|
||||
- Note the specific markdown structure requirements
|
||||
|
||||
### Step 2: Repository Structure Analysis
|
||||
|
||||
- Examine the complete repository structure using appropriate tools
|
||||
- Identify the primary purpose and scope of the repository
|
||||
- Catalog all important directories and their purposes
|
||||
- List key files that would be valuable for LLM understanding
|
||||
|
||||
### Step 3: Content Discovery
|
||||
|
||||
- Identify README files and their locations
|
||||
- Find documentation files (`.md` files in `/docs/`, `/spec/`, etc.)
|
||||
- Locate specification files and their purposes
|
||||
- Discover configuration files and their relevance
|
||||
- Find example files and code samples
|
||||
- Identify any existing documentation structure
|
||||
|
||||
### Step 4: Create Implementation Plan
|
||||
|
||||
Based on your analysis, create a structured plan that includes:
|
||||
|
||||
- Repository purpose and scope summary
|
||||
- Priority-ordered list of essential files for LLM understanding
|
||||
- Secondary files that provide additional context
|
||||
- Organizational structure for the llms.txt file
|
||||
|
||||
## Implementation Requirements
|
||||
|
||||
### Format Compliance
|
||||
|
||||
The `llms.txt` file must follow this exact structure per the specification:
|
||||
|
||||
1. **H1 Header**: Single line with repository/project name (required)
|
||||
2. **Blockquote Summary**: Brief description in blockquote format (optional but recommended)
|
||||
3. **Additional Details**: Zero or more markdown sections without headings for context
|
||||
4. **File List Sections**: Zero or more H2 sections containing markdown lists of links
|
||||
|
||||
### Content Requirements
|
||||
|
||||
#### Required Elements
|
||||
|
||||
- **Project Name**: Clear, descriptive title as H1
|
||||
- **Summary**: Concise blockquote explaining the repository's purpose
|
||||
- **Key Files**: Essential files organized by category (H2 sections)
|
||||
|
||||
#### File Link Format
|
||||
|
||||
Each file link must follow: `[descriptive-name](relative-url): optional description`
|
||||
|
||||
#### Section Organization
|
||||
|
||||
Organize files into logical H2 sections such as:
|
||||
|
||||
- **Documentation**: Core documentation files
|
||||
- **Specifications**: Technical specifications and requirements
|
||||
- **Examples**: Sample code and usage examples
|
||||
- **Configuration**: Setup and configuration files
|
||||
- **Optional**: Secondary files (special meaning - can be skipped for shorter context)
|
||||
|
||||
### Content Guidelines
|
||||
|
||||
#### Language and Style
|
||||
|
||||
- Use concise, clear, unambiguous language
|
||||
- Avoid jargon without explanation
|
||||
- Write for both human and LLM readers
|
||||
- Be specific and informative in descriptions
|
||||
|
||||
#### File Selection Criteria
|
||||
|
||||
Include files that:
|
||||
- Explain the repository's purpose and scope
|
||||
- Provide essential technical documentation
|
||||
- Show usage examples and patterns
|
||||
- Define interfaces and specifications
|
||||
- Contain configuration and setup instructions
|
||||
|
||||
Exclude files that:
|
||||
- Are purely implementation details
|
||||
- Contain redundant information
|
||||
- Are build artifacts or generated content
|
||||
- Are not relevant to understanding the project
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Repository Analysis
|
||||
|
||||
1. Examine the repository structure completely
|
||||
2. Read the main README.md to understand the project
|
||||
3. Identify all documentation directories and files
|
||||
4. Catalog specification files and their purposes
|
||||
5. Find example files and configuration files
|
||||
|
||||
### Step 2: Content Planning
|
||||
|
||||
1. Determine the primary purpose statement
|
||||
2. Write a concise summary for the blockquote
|
||||
3. Group identified files into logical categories
|
||||
4. Prioritize files by importance for LLM understanding
|
||||
5. Create descriptions for each file link
|
||||
|
||||
### Step 3: File Creation
|
||||
|
||||
1. Create the `llms.txt` file in the repository root
|
||||
2. Follow the exact format specification
|
||||
3. Include all required sections
|
||||
4. Use proper markdown formatting
|
||||
5. Ensure all links are valid relative paths
|
||||
|
||||
### Step 4: Validation
|
||||
1. Verify compliance with https://llmstxt.org/ specification
|
||||
2. Check that all links are valid and accessible
|
||||
3. Ensure the file serves as an effective LLM navigation tool
|
||||
4. Confirm the file is both human and machine readable
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Format Validation
|
||||
|
||||
- ✅ H1 header with project name
|
||||
- ✅ Blockquote summary (if included)
|
||||
- ✅ H2 sections for file lists
|
||||
- ✅ Proper markdown link format
|
||||
- ✅ No broken or invalid links
|
||||
- ✅ Consistent formatting throughout
|
||||
|
||||
### Content Validation
|
||||
|
||||
- ✅ Clear, unambiguous language
|
||||
- ✅ Comprehensive coverage of essential files
|
||||
- ✅ Logical organization of content
|
||||
- ✅ Appropriate file descriptions
|
||||
- ✅ Serves as effective LLM navigation tool
|
||||
|
||||
### Specification Compliance
|
||||
|
||||
- ✅ Follows https://llmstxt.org/ format exactly
|
||||
- ✅ Uses required markdown structure
|
||||
- ✅ Implements optional sections appropriately
|
||||
- ✅ File located at repository root (`/llms.txt`)
|
||||
|
||||
## Example Structure Template
|
||||
|
||||
```txt
|
||||
# [Repository Name]
|
||||
|
||||
> [Concise description of the repository's purpose and scope]
|
||||
|
||||
[Optional additional context paragraphs without headings]
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Main README](README.md): Primary project documentation and getting started guide
|
||||
- [Contributing Guide](CONTRIBUTING.md): Guidelines for contributing to the project
|
||||
- [Code of Conduct](CODE_OF_CONDUCT.md): Community guidelines and expectations
|
||||
|
||||
## Specifications
|
||||
|
||||
- [Technical Specification](spec/technical-spec.md): Detailed technical requirements and constraints
|
||||
- [API Specification](spec/api-spec.md): Interface definitions and data contracts
|
||||
|
||||
## Examples
|
||||
|
||||
- [Basic Example](examples/basic-usage.md): Simple usage demonstration
|
||||
- [Advanced Example](examples/advanced-usage.md): Complex implementation patterns
|
||||
|
||||
## Configuration
|
||||
|
||||
- [Setup Guide](docs/setup.md): Installation and configuration instructions
|
||||
- [Deployment Guide](docs/deployment.md): Production deployment guidelines
|
||||
|
||||
## Optional
|
||||
|
||||
- [Architecture Documentation](docs/architecture.md): Detailed system architecture
|
||||
- [Design Decisions](docs/decisions.md): Historical design decision records
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The created `llms.txt` file should:
|
||||
1. Enable LLMs to quickly understand the repository's purpose
|
||||
2. Provide clear navigation to essential documentation
|
||||
3. Follow the official llms.txt specification exactly
|
||||
4. Be comprehensive yet concise
|
||||
5. Serve both human and machine readers effectively
|
||||
6. Include all critical files for project understanding
|
||||
7. Use clear, unambiguous language throughout
|
||||
8. Organize content logically for easy consumption
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards.'
|
||||
description: Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards.
|
||||
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||
---
|
||||
# Generate Standard OO Component Documentation
|
||||
@ -9,7 +9,7 @@ Create comprehensive documentation for the object-oriented component(s) at: `${i
|
||||
|
||||
Analyze the component by examining code in the provided path. If folder, analyze all source files. If single file, treat as main component and analyze related files in same directory.
|
||||
|
||||
**Documentation Standards:**
|
||||
## Documentation Standards
|
||||
|
||||
- DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code)
|
||||
- DOC-002: Align with Arc42 software architecture documentation template
|
||||
@ -17,7 +17,7 @@ Analyze the component by examining code in the provided path. If folder, analyze
|
||||
- DOC-004: Use Agile Documentation principles (just enough documentation that adds value)
|
||||
- DOC-005: Target developers and maintainers as primary audience
|
||||
|
||||
**Analysis Instructions:**
|
||||
## Analysis Instructions
|
||||
|
||||
- ANA-001: Determine path type (folder vs single file) and identify primary component
|
||||
- ANA-002: Examine source code files for class structures and inheritance
|
||||
@ -28,14 +28,14 @@ Analyze the component by examining code in the provided path. If folder, analyze
|
||||
- ANA-007: Assess performance, security, reliability, maintainability
|
||||
- ANA-008: Infer integration patterns and data flow
|
||||
|
||||
**Language-Specific Optimizations:**
|
||||
## Language-Specific Optimizations
|
||||
|
||||
- LNG-001: **C#/.NET** - async/await, dependency injection, configuration, disposal
|
||||
- LNG-002: **Java** - Spring framework, annotations, exception handling, packaging
|
||||
- LNG-003: **TypeScript/JavaScript** - modules, async patterns, types, npm
|
||||
- LNG-004: **Python** - packages, virtual environments, type hints, testing
|
||||
|
||||
**Error Handling:**
|
||||
## Error Handling
|
||||
|
||||
- ERR-001: Path doesn't exist - provide correct format guidance
|
||||
- ERR-002: No source files found - suggest alternative locations
|
||||
@ -43,15 +43,15 @@ Analyze the component by examining code in the provided path. If folder, analyze
|
||||
- ERR-004: Non-standard patterns - document custom approaches
|
||||
- ERR-005: Insufficient code - focus on available information, highlight gaps
|
||||
|
||||
**Output Format:**
|
||||
## Output Format
|
||||
|
||||
Generate well-structured Markdown with clear heading hierarchy, code blocks, tables, bullet points, and proper formatting for readability and maintainability.
|
||||
|
||||
**File Location:**
|
||||
## File Location
|
||||
|
||||
The documentation should be saved in the `/docs/components/` directory and named according to the convention: `[component-name]-documentation.md`.
|
||||
|
||||
**Required Documentation Structure:**
|
||||
## Required Documentation Structure
|
||||
|
||||
The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ Your goal is to create a new specification file for `${input:SpecPurpose}`.
|
||||
|
||||
The specification file must define the requirements, constraints, and interfaces for the solution components in a manner that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and ensure the content is machine-readable and self-contained.
|
||||
|
||||
**Best Practices for AI-Ready Specifications:**
|
||||
## Best Practices for AI-Ready Specifications
|
||||
|
||||
- Use precise, explicit, and unambiguous language.
|
||||
- Clearly distinguish between requirements, constraints, and recommendations.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Update Azure Verified Modules to latest versions in Bicep files.'
|
||||
description: Update Azure Verified Modules (AVM) to latest versions in Bicep files.
|
||||
tools: ['changes', 'codebase', 'editFiles', 'fetch', 'runCommands', 'azure_get_deployment_best_practices', 'azure_get_schema_for_Bicep']
|
||||
---
|
||||
# Update Azure Verified Modules in Bicep Files
|
||||
@ -19,6 +19,7 @@ Update Bicep file `${file}` to use latest Azure Verified Module (AVM) versions.
|
||||
## Breaking Change Policy
|
||||
|
||||
⚠️ **PAUSE for approval** if updates involve:
|
||||
|
||||
- Incompatible parameter changes
|
||||
- Security/compliance modifications
|
||||
- Behavioral changes
|
||||
|
||||
@ -5,28 +5,30 @@ tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo',
|
||||
---
|
||||
# Implementation Plan Update Prompt
|
||||
|
||||
**PRIMARY DIRECTIVE**: You are an AI agent tasked with updating the implementation plan file `${file}` based on new or updated requirements. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
|
||||
## Primary Directive
|
||||
You are an AI agent tasked with updating the implementation plan file `${file}` based on new or updated requirements. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
|
||||
|
||||
**EXECUTION CONTEXT**: This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
|
||||
## Execution Context
|
||||
This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
|
||||
|
||||
**CORE REQUIREMENTS**:
|
||||
## Core Requirements
|
||||
|
||||
- Generate implementation plans that are fully executable by AI agents or humans
|
||||
- Use deterministic language with zero ambiguity
|
||||
- Structure all content for automated parsing and execution
|
||||
- Ensure complete self-containment with no external dependencies for understanding
|
||||
|
||||
**PLAN STRUCTURE REQUIREMENTS**:
|
||||
## Plan Structure Requirements
|
||||
Plans must consist of discrete, atomic phases containing executable tasks. Each phase must be independently processable by AI agents or humans without cross-phase dependencies unless explicitly declared.
|
||||
|
||||
**PHASE ARCHITECTURE**:
|
||||
## Phase Architecture
|
||||
|
||||
- Each phase must have measurable completion criteria
|
||||
- Tasks within phases must be executable in parallel unless dependencies are specified
|
||||
- All task descriptions must include specific file paths, function names, and exact implementation details
|
||||
- No task should require human interpretation or decision-making
|
||||
|
||||
**AI-OPTIMIZED IMPLEMENTATION STANDARDS**:
|
||||
## AI-Optimized Implementation Standards
|
||||
|
||||
- Use explicit, unambiguous language with zero interpretation required
|
||||
- Structure all content as machine-parseable formats (tables, lists, structured data)
|
||||
@ -36,7 +38,7 @@ Plans must consist of discrete, atomic phases containing executable tasks. Each
|
||||
- Use standardized prefixes for all identifiers (REQ-, TASK-, etc.)
|
||||
- Include validation criteria that can be automatically verified
|
||||
|
||||
**OUTPUT FILE SPECIFICATIONS**:
|
||||
## Output File Specifications
|
||||
|
||||
- Save implementation plan files in `/plan/` directory
|
||||
- Use naming convention: `[purpose]-[component]-[version].md`
|
||||
@ -44,10 +46,10 @@ Plans must consist of discrete, atomic phases containing executable tasks. Each
|
||||
- Example: `upgrade-system-command-4.md`, `feature-auth-module-1.md`
|
||||
- File must be valid Markdown with proper front matter structure
|
||||
|
||||
**MANDATORY TEMPLATE STRUCTURE**:
|
||||
## Mandatory Template Structure
|
||||
All implementation plans must strictly adhere to the following template. Each section is required and must be populated with specific, actionable content. AI agents must validate template compliance before execution.
|
||||
|
||||
**TEMPLATE VALIDATION RULES**:
|
||||
## Template Validation Rules
|
||||
|
||||
- All front matter fields must be present and properly formatted
|
||||
- All section headers must match exactly (case-sensitive)
|
||||
|
||||
@ -1,38 +1,216 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Update the llms.txt file in the root folder to reflect changes in documentation or specifications'
|
||||
description: 'Update the llms.txt file in the root folder to reflect changes in documentation or specifications following the llms.txt specification at https://llmstxt.org/'
|
||||
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||
---
|
||||
# Update LLMs Guidance File
|
||||
# Update LLMs.txt File
|
||||
|
||||
Your task is to update the [llms.txt](/llms.txt) file located in the root of the repository. This file provides high-level guidance to large language models (LLMs) on where to find relevant content for understanding the solution's purpose and specifications.
|
||||
Update the existing `llms.txt` file in the root of the repository to reflect changes in documentation, specifications, or repository structure. This file provides high-level guidance to large language models (LLMs) on where to find relevant content for understanding the repository's purpose and specifications.
|
||||
|
||||
**Instructions:**
|
||||
## Primary Directive
|
||||
|
||||
- Ensure the `llms.txt` file accurately references all folders and files that are important for LLM comprehension, including the `specs/` folder (for machine-readable specifications) and the `docs/` folder (for developer and user documentation).
|
||||
- If new documentation or specification folders/files are added, update `llms.txt` accordingly.
|
||||
- Use clear, concise language and structured formatting for easy parsing by LLMs.
|
||||
- Do not include implementation details or code—focus on navigation and content discovery.
|
||||
Update the existing `llms.txt` file to maintain accuracy and compliance with the llms.txt specification while reflecting current repository structure and content. The file must remain optimized for LLM consumption while staying human-readable.
|
||||
|
||||
## Analysis and Planning Phase
|
||||
|
||||
Before updating the `llms.txt` file, you must complete a thorough analysis:
|
||||
|
||||
### Step 1: Review Current File and Specification
|
||||
- Read the existing `llms.txt` file to understand current structure
|
||||
- Review the official specification at https://llmstxt.org/ to ensure continued compliance
|
||||
- Identify areas that may need updates based on repository changes
|
||||
|
||||
### Step 2: Repository Structure Analysis
|
||||
- Examine the current repository structure using appropriate tools
|
||||
- Compare current structure with what's documented in existing `llms.txt`
|
||||
- Identify new directories, files, or documentation that should be included
|
||||
- Note any removed or relocated files that need to be updated
|
||||
|
||||
### Step 3: Content Discovery and Change Detection
|
||||
- Identify new README files and their locations
|
||||
- Find new documentation files (`.md` files in `/docs/`, `/spec/`, etc.)
|
||||
- Locate new specification files and their purposes
|
||||
- Discover new configuration files and their relevance
|
||||
- Find new example files and code samples
|
||||
- Identify any changes to existing documentation structure
|
||||
|
||||
### Step 4: Create Update Plan
|
||||
Based on your analysis, create a structured plan that includes:
|
||||
- Changes needed to maintain accuracy
|
||||
- New files to be added to the llms.txt
|
||||
- Outdated references to be removed or updated
|
||||
- Organizational improvements to maintain clarity
|
||||
|
||||
## Implementation Requirements
|
||||
|
||||
### Format Compliance
|
||||
The updated `llms.txt` file must maintain this exact structure per the specification:
|
||||
|
||||
1. **H1 Header**: Single line with repository/project name (required)
|
||||
2. **Blockquote Summary**: Brief description in blockquote format (optional but recommended)
|
||||
3. **Additional Details**: Zero or more markdown sections without headings for context
|
||||
4. **File List Sections**: Zero or more H2 sections containing markdown lists of links
|
||||
|
||||
### Content Requirements
|
||||
|
||||
#### Required Elements
|
||||
- **Project Name**: Clear, descriptive title as H1
|
||||
- **Summary**: Concise blockquote explaining the repository's purpose
|
||||
- **Key Files**: Essential files organized by category (H2 sections)
|
||||
|
||||
#### File Link Format
|
||||
Each file link must follow: `[descriptive-name](relative-url): optional description`
|
||||
|
||||
#### Section Organization
|
||||
Organize files into logical H2 sections such as:
|
||||
- **Documentation**: Core documentation files
|
||||
- **Specifications**: Technical specifications and requirements
|
||||
- **Examples**: Sample code and usage examples
|
||||
- **Configuration**: Setup and configuration files
|
||||
- **Optional**: Secondary files (special meaning - can be skipped for shorter context)
|
||||
|
||||
### Content Guidelines
|
||||
|
||||
#### Language and Style
|
||||
- Use concise, clear, unambiguous language
|
||||
- Avoid jargon without explanation
|
||||
- Write for both human and LLM readers
|
||||
- Be specific and informative in descriptions
|
||||
|
||||
#### File Selection Criteria
|
||||
Include files that:
|
||||
- Explain the repository's purpose and scope
|
||||
- Provide essential technical documentation
|
||||
- Show usage examples and patterns
|
||||
- Define interfaces and specifications
|
||||
- Contain configuration and setup instructions
|
||||
|
||||
Exclude files that:
|
||||
- Are purely implementation details
|
||||
- Contain redundant information
|
||||
- Are build artifacts or generated content
|
||||
- Are not relevant to understanding the project
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Current State Analysis
|
||||
1. Read the existing `llms.txt` file thoroughly
|
||||
2. Examine the current repository structure completely
|
||||
3. Compare existing file references with actual repository content
|
||||
4. Identify outdated, missing, or incorrect references
|
||||
5. Note any structural issues with the current file
|
||||
|
||||
### Step 2: Content Planning
|
||||
1. Determine if the primary purpose statement needs updates
|
||||
2. Review and update the summary blockquote if needed
|
||||
3. Plan additions for new files and directories
|
||||
4. Plan removals for outdated or moved content
|
||||
5. Reorganize sections if needed for better clarity
|
||||
|
||||
### Step 3: File Updates
|
||||
1. Update the existing `llms.txt` file in the repository root
|
||||
2. Maintain compliance with the exact format specification
|
||||
3. Add new file references with appropriate descriptions
|
||||
4. Remove or update outdated references
|
||||
5. Ensure all links are valid relative paths
|
||||
|
||||
### Step 4: Validation
|
||||
1. Verify continued compliance with https://llmstxt.org/ specification
|
||||
2. Check that all links are valid and accessible
|
||||
3. Ensure the file still serves as an effective LLM navigation tool
|
||||
4. Confirm the file remains both human and machine readable
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Format Validation
|
||||
- ✅ H1 header with project name
|
||||
- ✅ Blockquote summary (if included)
|
||||
- ✅ H2 sections for file lists
|
||||
- ✅ Proper markdown link format
|
||||
- ✅ No broken or invalid links
|
||||
- ✅ Consistent formatting throughout
|
||||
|
||||
### Content Validation
|
||||
- ✅ Clear, unambiguous language
|
||||
- ✅ Comprehensive coverage of essential files
|
||||
- ✅ Logical organization of content
|
||||
- ✅ Appropriate file descriptions
|
||||
- ✅ Serves as effective LLM navigation tool
|
||||
|
||||
### Specification Compliance
|
||||
- ✅ Follows https://llmstxt.org/ format exactly
|
||||
- ✅ Uses required markdown structure
|
||||
- ✅ Implements optional sections appropriately
|
||||
- ✅ File located at repository root (`/llms.txt`)
|
||||
|
||||
## Update Strategy
|
||||
|
||||
### Addition Process
|
||||
When adding new content:
|
||||
1. Identify the appropriate section for new files
|
||||
2. Create clear, descriptive names for links
|
||||
3. Write concise but informative descriptions
|
||||
4. Maintain alphabetical or logical ordering within sections
|
||||
5. Consider if new sections are needed for new content types
|
||||
|
||||
### Removal Process
|
||||
When removing outdated content:
|
||||
1. Verify files are actually removed or relocated
|
||||
2. Check if relocated files should be updated rather than removed
|
||||
3. Remove entire sections if they become empty
|
||||
4. Update cross-references if needed
|
||||
|
||||
### Reorganization Process
|
||||
When restructuring content:
|
||||
1. Maintain logical flow from general to specific
|
||||
2. Keep essential documentation in primary sections
|
||||
3. Move secondary content to "Optional" section if appropriate
|
||||
4. Ensure new organization improves LLM navigation
|
||||
|
||||
Example structure for `llms.txt`:
|
||||
|
||||
```txt
|
||||
# Solution: [Concise Title Describing the Solution's Purpose]
|
||||
# [Repository Name]
|
||||
|
||||
**Version:** [Optional: e.g., 1.0, Date]
|
||||
**Last Updated:** [Optional: YYYY-MM-DD]
|
||||
**Owner:** [Optional: Team/Individual responsible for this solution]
|
||||
**GitHub Repository:** https://github.com/PlagueHO/azure-ai-foundry-jumpstart
|
||||
> [Concise description of the repository's purpose and scope]
|
||||
|
||||
## 1. Purpose & Scope
|
||||
[Optional additional context paragraphs without headings]
|
||||
|
||||
[Provide a clear, concise description of the purpose of this repository and scope of its solution. State the intended audience and any assumptions.]
|
||||
## Documentation
|
||||
|
||||
## 2. Folder Structure
|
||||
- [Main README](README.md): Primary project documentation and getting started guide
|
||||
- [Contributing Guide](CONTRIBUTING.md): Guidelines for contributing to the project
|
||||
- [Code of Conduct](CODE_OF_CONDUCT.md): Community guidelines and expectations
|
||||
|
||||
[Describe the structure of the repository, including the purpose of each folder and file. Use visual folder structure. Include subfolders where applicable.]
|
||||
## Specifications
|
||||
|
||||
## 3. Important Files
|
||||
- [Technical Specification](spec/technical-spec.md): Detailed technical requirements and constraints
|
||||
- [API Specification](spec/api-spec.md): Interface definitions and data contracts
|
||||
|
||||
[Explicitly list all important files, their purpose, and how they relate to the solution. Use bullet points or tables for clarity.]
|
||||
## Examples
|
||||
|
||||
- [Basic Example](examples/basic-usage.md): Simple usage demonstration
|
||||
- [Advanced Example](examples/advanced-usage.md): Complex implementation patterns
|
||||
|
||||
## Configuration
|
||||
|
||||
- [Setup Guide](docs/setup.md): Installation and configuration instructions
|
||||
- [Deployment Guide](docs/deployment.md): Production deployment guidelines
|
||||
|
||||
## Optional
|
||||
|
||||
- [Architecture Documentation](docs/architecture.md): Detailed system architecture
|
||||
- [Design Decisions](docs/decisions.md): Historical design decision records
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The updated `llms.txt` file should:
|
||||
1. Accurately reflect the current repository structure and content
|
||||
2. Maintain compliance with the llms.txt specification
|
||||
3. Provide clear navigation to essential documentation
|
||||
4. Remove outdated or incorrect references
|
||||
5. Include new important files and documentation
|
||||
6. Maintain logical organization for easy LLM consumption
|
||||
7. Use clear, unambiguous language throughout
|
||||
8. Continue to serve both human and machine readers effectively
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Update a markdown file section with an index/table of files from a specified folder.'
|
||||
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'openSimpleBrowser', 'problems', 'runCommands', 'runTasks', 'runTests', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'updateUserPreferences', 'usages', 'vscodeAPI', 'ado']
|
||||
description: Update a markdown file section with an index/table of files from a specified folder.
|
||||
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'openSimpleBrowser', 'problems', 'runCommands', 'runTasks', 'runTests', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||
---
|
||||
# Update Markdown File Index
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Update existing object-oriented component documentation following industry best practices and architectural documentation standards.'
|
||||
description: Update existing object-oriented component documentation following industry best practices and architectural documentation standards.
|
||||
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||
---
|
||||
# Update Standard OO Component Documentation
|
||||
|
||||
@ -9,7 +9,7 @@ Your goal is to update the existing specification file `${file}` based on new re
|
||||
|
||||
The specification file must define the requirements, constraints, and interfaces for the solution components in a manner that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and ensure the content is machine-readable and self-contained.
|
||||
|
||||
**Best Practices for AI-Ready Specifications:**
|
||||
## Best Practices for AI-Ready Specifications
|
||||
|
||||
- Use precise, explicit, and unambiguous language.
|
||||
- Clearly distinguish between requirements, constraints, and recommendations.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user