@mark-gozner/aigile-method 0.4.5

package/core/prompts/architecture-blueprint-generator.prompt.md

@@ -0,0 +1,322 @@
+---
+description: 'Comprehensive project architecture blueprint generator that analyzes codebases to create detailed architectural documentation. Automatically detects technology stacks and architectural patterns, generates visual diagrams, documents implementation patterns, and provides extensible blueprints for maintaining architectural consistency and guiding new development.'
+mode: 'agent'
+---
+
+# Comprehensive Project Architecture Blueprint Generator
+
+## Configuration Variables
+${PROJECT_TYPE="Auto-detect|.NET|Java|React|Angular|Python|Node.js|Flutter|Other"} <!-- Primary technology -->
+${ARCHITECTURE_PATTERN="Auto-detect|Clean Architecture|Microservices|Layered|MVVM|MVC|Hexagonal|Event-Driven|Serverless|Monolithic|Other"} <!-- Primary architectural pattern -->
+${DIAGRAM_TYPE="C4|UML|Flow|Component|None"} <!-- Architecture diagram type -->
+${DETAIL_LEVEL="High-level|Detailed|Comprehensive|Implementation-Ready"} <!-- Level of detail to include -->
+${INCLUDES_CODE_EXAMPLES=true|false} <!-- Include sample code to illustrate patterns -->
+${INCLUDES_IMPLEMENTATION_PATTERNS=true|false} <!-- Include detailed implementation patterns -->
+${INCLUDES_DECISION_RECORDS=true|false} <!-- Include architectural decision records -->
+${FOCUS_ON_EXTENSIBILITY=true|false} <!-- Emphasize extension points and patterns -->
+
+## Generated Prompt
+
+"Create a comprehensive 'Project_Architecture_Blueprint.md' document that thoroughly analyzes the architectural patterns in the codebase to serve as a definitive reference for maintaining architectural consistency. Use the following approach:
+
+### 1. Architecture Detection and Analysis
+- ${PROJECT_TYPE == "Auto-detect" ? "Analyze the project structure to identify all technology stacks and frameworks in use by examining:
+  - Project and configuration files
+  - Package dependencies and import statements
+  - Framework-specific patterns and conventions
+  - Build and deployment configurations" : "Focus on ${PROJECT_TYPE} specific patterns and practices"}
+  
+- ${ARCHITECTURE_PATTERN == "Auto-detect" ? "Determine the architectural pattern(s) by analyzing:
+  - Folder organization and namespacing
+  - Dependency flow and component boundaries
+  - Interface segregation and abstraction patterns
+  - Communication mechanisms between components" : "Document how the ${ARCHITECTURE_PATTERN} architecture is implemented"}
+
+### 2. Architectural Overview
+- Provide a clear, concise explanation of the overall architectural approach
+- Document the guiding principles evident in the architectural choices
+- Identify architectural boundaries and how they're enforced
+- Note any hybrid architectural patterns or adaptations of standard patterns
+
+### 3. Architecture Visualization
+${DIAGRAM_TYPE != "None" ? `Create ${DIAGRAM_TYPE} diagrams at multiple levels of abstraction:
+- High-level architectural overview showing major subsystems
+- Component interaction diagrams showing relationships and dependencies
+- Data flow diagrams showing how information moves through the system
+- Ensure diagrams accurately reflect the actual implementation, not theoretical patterns` : "Describe the component relationships based on actual code dependencies, providing clear textual explanations of:
+- Subsystem organization and boundaries
+- Dependency directions and component interactions
+- Data flow and process sequences"}
+
+### 4. Core Architectural Components
+For each architectural component discovered in the codebase:
+
+- **Purpose and Responsibility**:
+  - Primary function within the architecture
+  - Business domains or technical concerns addressed
+  - Boundaries and scope limitations
+
+- **Internal Structure**:
+  - Organization of classes/modules within the component
+  - Key abstractions and their implementations
+  - Design patterns utilized
+
+- **Interaction Patterns**:
+  - How the component communicates with others
+  - Interfaces exposed and consumed
+  - Dependency injection patterns
+  - Event publishing/subscription mechanisms
+
+- **Evolution Patterns**:
+  - How the component can be extended
+  - Variation points and plugin mechanisms
+  - Configuration and customization approaches
+
+### 5. Architectural Layers and Dependencies
+- Map the layer structure as implemented in the codebase
+- Document the dependency rules between layers
+- Identify abstraction mechanisms that enable layer separation
+- Note any circular dependencies or layer violations
+- Document dependency injection patterns used to maintain separation
+
+### 6. Data Architecture
+- Document domain model structure and organization
+- Map entity relationships and aggregation patterns
+- Identify data access patterns (repositories, data mappers, etc.)
+- Document data transformation and mapping approaches
+- Note caching strategies and implementations
+- Document data validation patterns
+
+### 7. Cross-Cutting Concerns Implementation
+Document implementation patterns for cross-cutting concerns:
+
+- **Authentication & Authorization**:
+  - Security model implementation
+  - Permission enforcement patterns
+  - Identity management approach
+  - Security boundary patterns
+
+- **Error Handling & Resilience**:
+  - Exception handling patterns
+  - Retry and circuit breaker implementations
+  - Fallback and graceful degradation strategies
+  - Error reporting and monitoring approaches
+
+- **Logging & Monitoring**:
+  - Instrumentation patterns
+  - Observability implementation
+  - Diagnostic information flow
+  - Performance monitoring approach
+
+- **Validation**:
+  - Input validation strategies
+  - Business rule validation implementation
+  - Validation responsibility distribution
+  - Error reporting patterns
+
+- **Configuration Management**:
+  - Configuration source patterns
+  - Environment-specific configuration strategies
+  - Secret management approach
+  - Feature flag implementation
+
+### 8. Service Communication Patterns
+- Document service boundary definitions
+- Identify communication protocols and formats
+- Map synchronous vs. asynchronous communication patterns
+- Document API versioning strategies
+- Identify service discovery mechanisms
+- Note resilience patterns in service communication
+
+### 9. Technology-Specific Architectural Patterns
+${PROJECT_TYPE == "Auto-detect" ? "For each detected technology stack, document specific architectural patterns:" : `Document ${PROJECT_TYPE}-specific architectural patterns:`}
+
+${(PROJECT_TYPE == ".NET" || PROJECT_TYPE == "Auto-detect") ? 
+"#### .NET Architectural Patterns (if detected)
+- Host and application model implementation
+- Middleware pipeline organization
+- Framework service integration patterns
+- ORM and data access approaches
+- API implementation patterns (controllers, minimal APIs, etc.)
+- Dependency injection container configuration" : ""}
+
+${(PROJECT_TYPE == "Java" || PROJECT_TYPE == "Auto-detect") ? 
+"#### Java Architectural Patterns (if detected)
+- Application container and bootstrap process
+- Dependency injection framework usage (Spring, CDI, etc.)
+- AOP implementation patterns
+- Transaction boundary management
+- ORM configuration and usage patterns
+- Service implementation patterns" : ""}
+
+${(PROJECT_TYPE == "React" || PROJECT_TYPE == "Auto-detect") ? 
+"#### React Architectural Patterns (if detected)
+- Component composition and reuse strategies
+- State management architecture
+- Side effect handling patterns
+- Routing and navigation approach
+- Data fetching and caching patterns
+- Rendering optimization strategies" : ""}
+
+${(PROJECT_TYPE == "Angular" || PROJECT_TYPE == "Auto-detect") ? 
+"#### Angular Architectural Patterns (if detected)
+- Module organization strategy
+- Component hierarchy design
+- Service and dependency injection patterns
+- State management approach
+- Reactive programming patterns
+- Route guard implementation" : ""}
+
+${(PROJECT_TYPE == "Python" || PROJECT_TYPE == "Auto-detect") ? 
+"#### Python Architectural Patterns (if detected)
+- Module organization approach
+- Dependency management strategy
+- OOP vs. functional implementation patterns
+- Framework integration patterns
+- Asynchronous programming approach" : ""}
+
+### 10. Implementation Patterns
+${INCLUDES_IMPLEMENTATION_PATTERNS ? 
+"Document concrete implementation patterns for key architectural components:
+
+- **Interface Design Patterns**:
+  - Interface segregation approaches
+  - Abstraction level decisions
+  - Generic vs. specific interface patterns
+  - Default implementation patterns
+
+- **Service Implementation Patterns**:
+  - Service lifetime management
+  - Service composition patterns
+  - Operation implementation templates
+  - Error handling within services
+
+- **Repository Implementation Patterns**:
+  - Query pattern implementations
+  - Transaction management
+  - Concurrency handling
+  - Bulk operation patterns
+
+- **Controller/API Implementation Patterns**:
+  - Request handling patterns
+  - Response formatting approaches
+  - Parameter validation
+  - API versioning implementation
+
+- **Domain Model Implementation**:
+  - Entity implementation patterns
+  - Value object patterns
+  - Domain event implementation
+  - Business rule enforcement" : "Mention that detailed implementation patterns vary across the codebase."}
+
+### 11. Testing Architecture
+- Document testing strategies aligned with the architecture
+- Identify test boundary patterns (unit, integration, system)
+- Map test doubles and mocking approaches
+- Document test data strategies
+- Note testing tools and frameworks integration
+
+### 12. Deployment Architecture
+- Document deployment topology derived from configuration
+- Identify environment-specific architectural adaptations
+- Map runtime dependency resolution patterns
+- Document configuration management across environments
+- Identify containerization and orchestration approaches
+- Note cloud service integration patterns
+
+### 13. Extension and Evolution Patterns
+${FOCUS_ON_EXTENSIBILITY ? 
+"Provide detailed guidance for extending the architecture:
+
+- **Feature Addition Patterns**:
+  - How to add new features while preserving architectural integrity
+  - Where to place new components by type
+  - Dependency introduction guidelines
+  - Configuration extension patterns
+
+- **Modification Patterns**:
+  - How to safely modify existing components
+  - Strategies for maintaining backward compatibility
+  - Deprecation patterns
+  - Migration approaches
+
+- **Integration Patterns**:
+  - How to integrate new external systems
+  - Adapter implementation patterns
+  - Anti-corruption layer patterns
+  - Service facade implementation" : "Document key extension points in the architecture."}
+
+${INCLUDES_CODE_EXAMPLES ? 
+"### 14. Architectural Pattern Examples
+Extract representative code examples that illustrate key architectural patterns:
+
+- **Layer Separation Examples**:
+  - Interface definition and implementation separation
+  - Cross-layer communication patterns
+  - Dependency injection examples
+
+- **Component Communication Examples**:
+  - Service invocation patterns
+  - Event publication and handling
+  - Message passing implementation
+
+- **Extension Point Examples**:
+  - Plugin registration and discovery
+  - Extension interface implementations
+  - Configuration-driven extension patterns
+
+Include enough context with each example to show the pattern clearly, but keep examples concise and focused on architectural concepts." : ""}
+
+${INCLUDES_DECISION_RECORDS ? 
+"### 15. Architectural Decision Records
+Document key architectural decisions evident in the codebase:
+
+- **Architectural Style Decisions**:
+  - Why the current architectural pattern was chosen
+  - Alternatives considered (based on code evolution)
+  - Constraints that influenced the decision
+
+- **Technology Selection Decisions**:
+  - Key technology choices and their architectural impact
+  - Framework selection rationales
+  - Custom vs. off-the-shelf component decisions
+
+- **Implementation Approach Decisions**:
+  - Specific implementation patterns chosen
+  - Standard pattern adaptations
+  - Performance vs. maintainability tradeoffs
+
+For each decision, note:
+- Context that made the decision necessary
+- Factors considered in making the decision
+- Resulting consequences (positive and negative)
+- Future flexibility or limitations introduced" : ""}
+
+### ${INCLUDES_DECISION_RECORDS ? "16" : INCLUDES_CODE_EXAMPLES ? "15" : "14"}. Architecture Governance
+- Document how architectural consistency is maintained
+- Identify automated checks for architectural compliance
+- Note architectural review processes evident in the codebase
+- Document architectural documentation practices
+
+### ${INCLUDES_DECISION_RECORDS ? "17" : INCLUDES_CODE_EXAMPLES ? "16" : "15"}. Blueprint for New Development
+Create a clear architectural guide for implementing new features:
+
+- **Development Workflow**:
+  - Starting points for different feature types
+  - Component creation sequence
+  - Integration steps with existing architecture
+  - Testing approach by architectural layer
+
+- **Implementation Templates**:
+  - Base class/interface templates for key architectural components
+  - Standard file organization for new components
+  - Dependency declaration patterns
+  - Documentation requirements
+
+- **Common Pitfalls**:
+  - Architecture violations to avoid
+  - Common architectural mistakes
+  - Performance considerations
+  - Testing blind spots
+
+Include information about when this blueprint was generated and recommendations for keeping it updated as the architecture evolves."

package/core/prompts/architecture-validation.prompt.md

@@ -0,0 +1,71 @@
+---
+description: 'Validate and document the repository architecture and technology consistency.'
+mode: 'agent'
+---
+
+Validate and document the repository architecture and technology consistency across the entire project.
+
+Purpose
+- Auto-detect technologies, manifests, and architectural patterns in the repository.
+- Run deterministic checks for consistency, missing artifacts, and obvious risks.
+- Produce both machine-readable findings (JSON) and a concise human-readable report (Markdown).
+
+Constraints
+- Only read repository files; do not perform network calls or modify files.
+- If information is missing, mark it as unknown with low confidence and suggest exact local commands to run to resolve it.
+- Be deterministic: same input repo must produce the same output.
+
+Steps (agent must follow)
+1. Walk the repository and collect files and metadata (path, size, file type, and first 20 lines where helpful).
+2. Group files into components by folder/manifests.
+3. For each component, infer language, package manager, build and test commands, runtime versions (if present), and whether CI is configured.
+4. Run consistency checks (see below) and assign confidence scores (0.0-1.0) to inferred items.
+5. Produce JSON findings and a Markdown summary as described in Output Format.
+
+Checks to run per component (examples)
+- Manifest presence: expected manifest exists (e.g., package.json for Node, pom.xml for Maven).
+- Lockfile presence when expected (e.g., package-lock.json, yarn.lock, poetry.lock).
+- Version coherence: runtime version declared in manifest matches other artifacts (e.g., Dockerfile FROM image tag).
+- CI presence: workflow or pipeline config exists that builds/tests the component.
+- Test presence: test folders or test dependencies are present.
+- Mixed package managers in same component (flag as issue).
+- Broken path references in docs/prompts (report path, line snippet).
+- Potential secrets/secrets placeholders: detect obvious token patterns or files under mcp/ that reference tokens (do not show values).
+
+Output Format (required)
+1) JSON findings (single JSON object) with these top-level keys:
+	- repo: { name, path }
+	- summary: { components, languages, total_files, confidence }
+	- components: [
+			{ id, path, type, language, package_manager, manifests, inferred_runtime_versions, build_commands, test_commands, has_ci, checks, recommendations }
+		]
+	- global_checks: [ { id, description, pass, confidence, details } ]
+	- recommendations: [ { id, description, priority, effort, affected_components } ]
+	- metadata: { generated_at (ISO8601), tool, version }
+
+Notes for JSON
+- Use numeric confidence (0.0-1.0).
+- Keep identifiers deterministic and stable (use normalized path strings).
+
+2) Markdown summary (max ~1200 words):
+- Title: "Architecture Validation — <repo name>"
+- One-paragraph overview of inferred architecture and primary technologies.
+- Bullet list of components: path, language, main status (OK / Issues).
+- Top 5 prioritized recommendations (one line each).
+- Checklist of failing high-severity checks.
+- "How I inferred" short heuristics list.
+- Minimal examples of how to fix the top 2 issues with PowerShell-compatible commands.
+- Quality gates: Build, Lint/Typecheck, Tests (PASS/FAIL).
+
+Quality gates
+- Build: each code component must have at least one build command or CI pipeline (PASS/FAIL).
+- Lint/Typecheck: evidence of lint or typecheck config for major languages (PASS/FAIL).
+- Tests: presence of test folders or test manifests (PASS/FAIL).
+
+Behavior
+- Be concise. Use bullets and short sentences.
+- Prioritize actionable remediation steps with estimated effort (Low/Medium/High).
+- When recommending commands, use PowerShell-safe commands in fenced blocks.
+
+Begin by listing detected top-level manifests and components (one-line each), then provide the full JSON findings object, followed by the Markdown summary and a final 3-step next-action plan.
+

package/core/prompts/code-review.prompt.md

@@ -0,0 +1,107 @@
+---
+description: "Perform a code review"
+mode : 'ask'
+---
+
+## Code Review Expert: Detailed Analysis and Best Practices
+
+As a senior software engineer with expertise in code quality, security, and performance optimization, perform a code review of the provided git diff.
+
+Focus on delivering actionable feedback in the following areas:
+
+Critical Issues:
+- Security vulnerabilities and potential exploits
+- Runtime errors and logic bugs
+- Performance bottlenecks and optimization opportunities
+- Memory management and resource utilization
+- Threading and concurrency issues
+- Input validation and error handling 
+
+Code Quality:
+- Adherence to language-specific conventions and best practices
+- Design patterns and architectural considerations
+- Code organization and modularity
+- Naming conventions and code readability
+- Documentation completeness and clarity
+- Test coverage and testing approach
+
+Maintainability:
+- Code duplication and reusability
+- Complexity metrics (cyclomatic complexity, cognitive complexity)
+- Dependencies and coupling
+- Extensibility and future-proofing
+- Technical debt implications
+
+Provide specific recommendations with:
+- Code examples for suggested improvements
+- References to relevant documentation or standards
+- Rationale for suggested changes
+- Impact assessment of proposed modifications
+
+Format your review using clear sections and bullet points. Include inline code references where applicable.
+
+Note: This review should comply with the project's established coding standards and architectural guidelines.
+
+## Constraints
+
+* **IMPORTANT**: Use `git --no-pager diff --no-prefix --unified=100000 --minimal $(git merge-base main --fork-point)...head` to get the diff for code review.
+* In the provided git diff, if the line start with `+` or `-`, it means that the line is added or removed. If the line starts with a space, it means that the line is unchanged. If the line starts with `@@`, it means that the line is a hunk header.
+
+* Avoid overwhelming the developer with too many suggestions at once.
+* Use clear and concise language to ensure understanding.
+
+* Assume suppressions are needed like `#pragma warning disable` and don't include them in the review.
+* If there are any TODO comments, make sure to address them in the review.
+
+* Use markdown for each suggestion, like
+    ```
+    # Code Review for ${feature_description}
+
+    Overview of the code changes, including the purpose of the feature, any relevant context, and the files involved.
+
+    # Suggestions
+
+    ## ${code_review_emoji} ${Summary of the suggestion, include necessary context to understand suggestion}
+    * **Priority**: ${priority: (🔥/⚠️/🟡/🟢)}
+    * **File**: ${relative/path/to/file}
+    * **Details**: ...
+    * **Example** (if applicable): ...
+    * **Suggested Change** (if applicable): (code snippet...)
+    
+    ## (other suggestions...)
+    ...
+
+    # Summary
+    ```
+* Use the following emojis to indicate the priority of the suggestions:
+    * 🔥 Critical
+    * ⚠️ High
+    * 🟡 Medium
+    * 🟢 Low
+* Each suggestion should be prefixed with an emoji to indicate the type of suggestion:
+    * 🔧 Change request
+    * ❓ Question
+    * ⛏️ Nitpick
+    * ♻️ Refactor suggestion
+    * 💭 Thought process or concern
+    * 👍 Positive feedback
+    * 📝 Explanatory note or fun fact
+    * 🌱 Observation for future consideration
+* Always use file paths
+
+### Use Code Review Emojis
+
+Use code review emojis. Give the reviewee added context and clarity to follow up on code review. For example, knowing whether something really requires action (🔧), highlighting nit-picky comments (⛏), flagging out of scope items for follow-up (📌) and clarifying items that don’t necessarily require action but are worth saying ( 👍, 📝, 🤔 )
+
+#### Emoji Legend
+
+|       |      `:code:`       | Meaning                                                                                                                                                                                                                            |
+| :---: | :-----------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|   🔧   |     `:wrench:`      | Use when this needs to be changed. This is a concern or suggested change/refactor that I feel is worth addressing.                                                                                                                 |
+|   ❓   |    `:question:`     | Use when you have a question. This should be a fully formed question with sufficient information and context that requires a response.                                                                                             |
+|   ⛏   |      `:pick:`       | This is a nitpick. This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter |
+|   ♻️   |     `:recycle:`     | Suggestion for refactoring. Should include enough context to be actionable and not be considered a nitpick.                                                                                                                        |
+|   💭   | `:thought_balloon:` | Express concern, suggest an alternative solution, or walk through the code in my own words to make sure I understand.                                                                                                              |
+|   👍   |       `:+1:`        | Let the author know that you really liked something! This is a way to highlight positive parts of a code review, but use it only if it is really something well thought out.                                                       |
+|   📝   |      `:memo:`       | This is an explanatory note, fun fact, or relevant commentary that does not require any action.                                                                                                                                    |
+|   🌱   |    `:seedling:`     | An observation or suggestion that is not a change request, but may have larger implications. Generally something to keep in mind for the future.                                                                                   |

package/core/prompts/confluence-in-md.prompt.md

@@ -0,0 +1,167 @@
+---
+description: 'Prompt for generating Confluence documentation in Markdown format.'
+mode: 'agent'
+---
+
+Important: This prompt expects the host environment to provide a tool named `confluence_get_page` (an Atlassian MCP integration) that accepts a Confluence space key and page title or page id and returns the page content and metadata. If `confluence_get_page` is not available in the execution environment, STOP and report to the user that the tool is unavailable and that network/MCP access is required.
+
+When a user provides a Confluence URL (for example: `https://your-company.atlassian.net/wiki/display/PROJ/Page+Title`), you MUST do the following before fetching content:
+
+- Parse the URL and extract the space key and page title (or page id if the URL contains `pages/<id>`). Rules:
+	- If the URL contains `/display/{SPACE}/{Page+Title}`, then `SPACE` is the space key and the page title is the portion after the space, with `+` decoded to spaces.
+	- If the URL contains `/pages/{id}`, extract the numeric page id.
+	- Normalize the page title by URL-decoding and trimming leading/trailing whitespace.
+
+- Confirm back to the user the extracted values in one short line, for example: `Extracted space key: INV, page title: Flows for instruments` and then proceed.
+
+- Use the `confluence_get_page` tool with the extracted identifiers. The call should request the page in Storage (HTML) format along with full metadata (title, id, space, url, version, created/updated timestamps, author, labels, attachments list).
+
+- If the `confluence_get_page` tool returns an error indicating the page is restricted or inaccessible, report that to the user and do not attempt further fetches for that page unless explicit permission is granted.
+
+- If the `confluence_get_page` tool is not available, do NOT attempt to call Confluence APIs directly. Immediately inform the user: "The required `confluence_get_page` tool is not available in this environment. I cannot fetch Confluence pages without MCP access. Please provide the page content or enable the tool."
+
+Additional details:
+- Assumptions the agent can rely on (must verify before running):
+	- You have valid Confluence access and appropriate permissions to read pages and attachments.
+	- The Confluence content format can be either Storage (HTML-like) or WYSIWYG; the agent must detect and handle both.
+	- The user will provide either a page ID or space key + title
+	- Network rate limits and transient HTTP errors can occur; implement retries with exponential backoff (3 attempts default).
+
+1) Reasoning / Plan (required): 
+	 - For each run, produce a 3–6 sentence plan describing inputs, scope, number of pages estimated, attachments expected, and any ambiguous items that require user confirmation. Wait for confirmation when key inputs are missing or ambiguous (e.g., both space_keys and page_ids absent).
+
+2) Discovery:
+	 - Resolve the list of pages to export based on scope.
+	 - For space_keys: list pages via Confluence API (paginate). Respect include/exclude label filters.
+	 - For root_page_id: traverse children up to configured depth.
+	 - For page_ids: validate each id exists and record metadata.
+
+3) Fetch content:
+	 - For each resolved page id, fetch storage-format content (prefer Storage format via API).
+	 - Also fetch page metadata: title, id, space, url, version, created/updated timestamps, author, labels, and list of attachments (name, id, mediaType, download link).
+
+4) Conversion rules:
+	 - Convert Storage/HTML content to GitHub-flavored Markdown.
+	 - Preserve headings, lists, tables, code blocks, blockquotes.
+	 - Convert Confluence-specific macros:
+		 - Jira macros: replace with a short link or a placeholder with the referenced issue keys.
+		 - Include/excerpt macros: inline the fetched content where possible; otherwise insert a clear placeholder with the source page id and URL.
+		 - Other unsupported macros: insert a markdown placeholder with macro name and parameters.
+	 - Convert internal Confluence links:
+		 - If link_style == "relative": map to local markdown filenames using `page_name_template` and make links relative.
+		 - If absolute: keep original Confluence URLs.
+		 - Record broken or unresolvable links in a `links-report.json`.
+	 - Images and attachments:
+		 - If attachments==true and image_handling=="save_and_link": download attachments to `output_dir/assets/<page-id>/` and replace src with relative path.
+		 - If "embed_base64": embed small images as data URIs (limit configurable; default 100KB).
+		 - For attachments that are not images (PDFs, etc.), download and place in assets folder and link to them from the markdown.
+
+5) Output file format per page:
+	 - Each page must become one markdown file named per `page_name_template`. Filenames must be sanitized for filesystem compatibility.
+	 - Prepend YAML frontmatter with the following fields:
+		 - title: original page title
+		 - confluence_id: page id
+		 - space: space key
+		 - confluence_url: canonical URL
+		 - version: version number
+		 - created_at: ISO timestamp
+		 - updated_at: ISO timestamp
+		 - author: name or account id
+		 - labels: [list]
+		 - attachments: [{ name, path_relative, mediaType }]
+	 - After frontmatter, include a "source" section that contains a short provenance line: "Exported from Confluence space {space} page {id} on {export_date}".
+	 - Then the converted markdown content.
+
+6) Manifest and reports:
+	 - Write `export-manifest.json` in `output_dir` listing all exported pages with metadata and file paths.
+	 - Write `links-report.json` with unresolved links, mapped links, and any conversion warnings.
+	 - Write `errors.log` with any pages skipped and error reasons.
+
+7) Idempotency & safe runs:
+	 - If a file already exists, compare Confluence page updated_at with a stored manifest_version; skip or overwrite based on `--force` flag (agent must ask the user if overwrite policy is not provided).
+	 - Maintain a lightweight cache of page ids and etags to speed repeated runs.
+
+8) Error handling:
+	 - Retry HTTP requests up to 3 times with exponential backoff for 5xx errors and transient network failures.
+	 - For 401/403, report authentication failure and stop.
+	 - For rate limiting (429), honor Retry-After header.
+
+Output Format (explicit):
+- A directory at `output_dir` containing:
+	- For each page: `{sanitized-filename}.md` with YAML frontmatter + content.
+	- `assets/` subfolders organizing attachments by page id: `assets/<page-id>/...`
+	- `export-manifest.json` (JSON array of page metadata and file paths)
+	- `links-report.json` (JSON detailing internal link mappings and broken links)
+	- `errors.log` (text log)
+- All JSON outputs must be machine-parseable (UTF-8, newline-delimited pretty-print).
+
+Examples (start and end markers; placeholders MUST be used):
+- Example Input (placeholder):
+	- confluence_base_url: [https://yourcompany.atlassian.net/wiki]
+	- auth_method: [mcp_credential]
+	- scope: { space_keys: ["REQ"], include_labels: ["requirements"], depth: 2 }
+	- output_dir: [/tmp/confluence-requirements-export]
+- Example Output (one per page):
+	- File: `REQ-User-Login-12345.md`
+	- YAML frontmatter:
+		---
+		title: "User Login"
+		confluence_id: "12345"
+		space: "REQ"
+		confluence_url: "https://yourcompany.atlassian.net/wiki/spaces/REQ/pages/12345"
+		version: 4
+		created_at: "2023-05-01T12:00:00Z"
+		updated_at: "2024-02-10T09:30:00Z"
+		author: "Jane Doe"
+		labels: ["requirements","auth"]
+		attachments:
+			- name: "login-flow.png"
+				path_relative: "assets/12345/login-flow.png"
+				mediaType: "image/png"
+		---
+		Exported from Confluence space REQ page 12345 on 2025-10-28T12:00:00Z
+		# User Login
+		...
+
+Notes / Edge cases:
+- Large pages: if converted markdown exceeds filesystem limits, warn and truncate title-based filename using `{id}` fallback.
+- Attachment name collisions: deduplicate by appending numeric suffixes or use UUIDs; record original names in manifest.
+- Confluence macros that render dynamic content (e.g., reports): include a placeholder and, when possible, fetch underlying data (e.g., Jira issue keys) to provide stable references.
+- If conversion of complex tables or diagrams fails, include both a markdown placeholder and save the original HTML snippet into `assets/<page-id>/raw-<id>.html`.
+
+User prompts & confirmations:
+- If required inputs are missing, ask succinct clarifying questions before proceeding (e.g., "Provide Confluence base URL and either page_ids, space_keys, or root_page_id+depth.").
+- If overwrite policy is not set and existing files are present, ask: "Existing files detected in {output_dir}. Overwrite? [yes/no/skip/backup]" and wait for explicit confirmation.
+
+Success criteria (how to verify):
+- Every requested page produces a `.md` file with YAML frontmatter and valid Markdown body.
+- All in-page images and attachments referenced when attachments==true are downloaded into `assets/` and linked relative.
+- `export-manifest.json` lists all pages and their output paths.
+- `links-report.json` contains zero unresolved internal links (or a clear list if unresolved).
+- No unhandled exceptions; all failures logged in `errors.log`.
+
+Performance / Rate-limiting guidance:
+- Use pagination and parallelize content fetches moderately (max 5 concurrent requests by default) to avoid rate limits; expose concurrency setting to the caller.
+
+Security:
+- Never print or include `auth_credentials` in the exported files or logs.
+- Respect any data retention/export policies; if a page is marked restricted, do not export it unless explicit permission is confirmed.
+
+# Output Format
+- The agent must return JSON summarizing the run when finished (in addition to writing files). The JSON must include:
+	{
+		"exported_pages": N,
+		"skipped_pages": [ { "id": "...", "reason":"..." } ],
+		"output_dir": "[path]",
+		"manifest_path": "output_dir/export-manifest.json",
+		"links_report_path": "output_dir/links-report.json",
+		"errors_log": "output_dir/errors.log",
+		"warnings": [ ... ]
+	}
+- After the JSON summary, print a one-line human-friendly summary.
+
+# Notes
+- Always require explicit confirmation before performing write/overwrite actions on the filesystem.
+- Favor fidelity of content and provenance over cosmetic formatting changes.
+- If the agent cannot perform network calls (no MCP access), it must stop and clearly report that network access is unavailable and list the minimal manual steps to run the export offline (e.g., provide HTML exports to be converted).
+- Keep logs structured and machine-readable where possible.