workspace-architect 1.3.0

package/assets/prompts/create-agentsmd.prompt.md

@@ -0,0 +1,249 @@
+---
+description: "Prompt for generating an AGENTS.md file for a repository"
+mode: "agent"
+---
+
+# Create high‑quality AGENTS.md file
+
+You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/.
+
+AGENTS.md is an open format designed to provide coding agents with the context and instructions they need to work effectively on a project.
+
+## What is AGENTS.md?
+
+AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It complements README.md by containing detailed technical context that coding agents need but might clutter a human-focused README.
+
+## Key Principles
+
+- **Agent-focused**: Contains detailed technical instructions for automated tools
+- **Complements README.md**: Doesn't replace human documentation but adds agent-specific context
+- **Standardized location**: Placed at repository root (or subproject roots for monorepos)
+- **Open format**: Uses standard Markdown with flexible structure
+- **Ecosystem compatibility**: Works across 20+ different AI coding tools and agents
+
+## File Structure and Content Guidelines
+
+### 1. Required Setup
+
+- Create the file as `AGENTS.md` in the repository root
+- Use standard Markdown formatting
+- No required fields - flexible structure based on project needs
+
+### 2. Essential Sections to Include
+
+#### Project Overview
+
+- Brief description of what the project does
+- Architecture overview if complex
+- Key technologies and frameworks used
+
+#### Setup Commands
+
+- Installation instructions
+- Environment setup steps
+- Dependency management commands
+- Database setup if applicable
+
+#### Development Workflow
+
+- How to start development server
+- Build commands
+- Watch/hot-reload setup
+- Package manager specifics (npm, pnpm, yarn, etc.)
+
+#### Testing Instructions
+
+- How to run tests (unit, integration, e2e)
+- Test file locations and naming conventions
+- Coverage requirements
+- Specific test patterns or frameworks used
+- How to run subset of tests or focus on specific areas
+
+#### Code Style Guidelines
+
+- Language-specific conventions
+- Linting and formatting rules
+- File organization patterns
+- Naming conventions
+- Import/export patterns
+
+#### Build and Deployment
+
+- Build commands and outputs
+- Environment configurations
+- Deployment steps and requirements
+- CI/CD pipeline information
+
+### 3. Optional but Recommended Sections
+
+#### Security Considerations
+
+- Security testing requirements
+- Secrets management
+- Authentication patterns
+- Permission models
+
+#### Monorepo Instructions (if applicable)
+
+- How to work with multiple packages
+- Cross-package dependencies
+- Selective building/testing
+- Package-specific commands
+
+#### Pull Request Guidelines
+
+- Title format requirements
+- Required checks before submission
+- Review process
+- Commit message conventions
+
+#### Debugging and Troubleshooting
+
+- Common issues and solutions
+- Logging patterns
+- Debug configuration
+- Performance considerations
+
+## Example Template
+
+Use this as a starting template and customize based on the specific project:
+
+```markdown
+# AGENTS.md
+
+## Project Overview
+
+[Brief description of the project, its purpose, and key technologies]
+
+## Setup Commands
+
+- Install dependencies: `[package manager] install`
+- Start development server: `[command]`
+- Build for production: `[command]`
+
+## Development Workflow
+
+- [Development server startup instructions]
+- [Hot reload/watch mode information]
+- [Environment variable setup]
+
+## Testing Instructions
+
+- Run all tests: `[command]`
+- Run unit tests: `[command]`
+- Run integration tests: `[command]`
+- Test coverage: `[command]`
+- [Specific testing patterns or requirements]
+
+## Code Style
+
+- [Language and framework conventions]
+- [Linting rules and commands]
+- [Formatting requirements]
+- [File organization patterns]
+
+## Build and Deployment
+
+- [Build process details]
+- [Output directories]
+- [Environment-specific builds]
+- [Deployment commands]
+
+## Pull Request Guidelines
+
+- Title format: [component] Brief description
+- Required checks: `[lint command]`, `[test command]`
+- [Review requirements]
+
+## Additional Notes
+
+- [Any project-specific context]
+- [Common gotchas or troubleshooting tips]
+- [Performance considerations]
+```
+
+## Working Example from agents.md
+
+Here's a real example from the agents.md website:
+
+```markdown
+# Sample AGENTS.md file
+
+## Dev environment tips
+
+- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
+- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
+- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
+- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
+
+## Testing instructions
+
+- Find the CI plan in the .github/workflows folder.
+- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
+- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
+- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
+- Fix any test or type errors until the whole suite is green.
+- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
+- Add or update tests for the code you change, even if nobody asked.
+
+## PR instructions
+
+- Title format: [<project_name>] <Title>
+- Always run `pnpm lint` and `pnpm test` before committing.
+```
+
+## Implementation Steps
+
+1. **Analyze the project structure** to understand:
+
+   - Programming languages and frameworks used
+   - Package managers and build tools
+   - Testing frameworks
+   - Project architecture (monorepo, single package, etc.)
+
+2. **Identify key workflows** by examining:
+
+   - package.json scripts
+   - Makefile or other build files
+   - CI/CD configuration files
+   - Documentation files
+
+3. **Create comprehensive sections** covering:
+
+   - All essential setup and development commands
+   - Testing strategies and commands
+   - Code style and conventions
+   - Build and deployment processes
+
+4. **Include specific, actionable commands** that agents can execute directly
+
+5. **Test the instructions** by ensuring all commands work as documented
+
+6. **Keep it focused** on what agents need to know, not general project information
+
+## Best Practices
+
+- **Be specific**: Include exact commands, not vague descriptions
+- **Use code blocks**: Wrap commands in backticks for clarity
+- **Include context**: Explain why certain steps are needed
+- **Stay current**: Update as the project evolves
+- **Test commands**: Ensure all listed commands actually work
+- **Consider nested files**: For monorepos, create AGENTS.md files in subprojects as needed
+
+## Monorepo Considerations
+
+For large monorepos:
+
+- Place a main AGENTS.md at the repository root
+- Create additional AGENTS.md files in subproject directories
+- The closest AGENTS.md file takes precedence for any given location
+- Include navigation tips between packages/projects
+
+## Final Notes
+
+- AGENTS.md works with 20+ AI coding tools including Cursor, Aider, Gemini CLI, and many others
+- The format is intentionally flexible - adapt it to your project's needs
+- Focus on actionable instructions that help agents understand and work with your codebase
+- This is living documentation - update it as your project evolves
+
+When creating the AGENTS.md file, prioritize clarity, completeness, and actionability. The goal is to give any coding agent enough context to effectively contribute to the project without requiring additional human guidance.

package/assets/prompts/create-architectural-decision-record.prompt.md

@@ -0,0 +1,97 @@
+---
+mode: 'agent'
+description: 'Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.'
+tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
+---
+# Create Architectural Decision Record
+
+Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability.
+
+## Inputs
+
+- **Context**: `${input:Context}`
+- **Decision**: `${input:Decision}`
+- **Alternatives**: `${input:Alternatives}`
+- **Stakeholders**: `${input:Stakeholders}`
+
+## 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
+
+- Use precise, unambiguous language
+- Follow standardized ADR format with front matter
+- Include both positive and negative consequences
+- Document alternatives with rejection rationale
+- Structure for machine parsing and human reference
+- Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections
+
+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
+
+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:
+
+```md
+---
+title: "ADR-NNNN: [Decision Title]"
+status: "Proposed"
+date: "YYYY-MM-DD"
+authors: "[Stakeholder Names/Roles]"
+tags: ["architecture", "decision"]
+supersedes: ""
+superseded_by: ""
+---
+
+# ADR-NNNN: [Decision Title]
+
+## Status
+
+**Proposed** | Accepted | Rejected | Superseded | Deprecated
+
+## Context
+
+[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]
+
+## Decision
+
+[Chosen solution with clear rationale for selection.]
+
+## Consequences
+
+### Positive
+
+- **POS-001**: [Beneficial outcomes and advantages]
+- **POS-002**: [Performance, maintainability, scalability improvements]
+- **POS-003**: [Alignment with architectural principles]
+
+### Negative
+
+- **NEG-001**: [Trade-offs, limitations, drawbacks]
+- **NEG-002**: [Technical debt or complexity introduced]
+- **NEG-003**: [Risks and future challenges]
+
+## Alternatives Considered
+
+### [Alternative 1 Name]
+
+- **ALT-001**: **Description**: [Brief technical description]
+- **ALT-002**: **Rejection Reason**: [Why this option was not selected]
+
+### [Alternative 2 Name]
+
+- **ALT-003**: **Description**: [Brief technical description]
+- **ALT-004**: **Rejection Reason**: [Why this option was not selected]
+
+## Implementation Notes
+
+- **IMP-001**: [Key implementation considerations]
+- **IMP-002**: [Migration or rollout strategy if applicable]
+- **IMP-003**: [Monitoring and success criteria]
+
+## References
+
+- **REF-001**: [Related ADRs]
+- **REF-002**: [External documentation]
+- **REF-003**: [Standards or frameworks referenced]
+```

package/assets/prompts/create-github-action-workflow-specification.prompt.md

@@ -0,0 +1,276 @@
+---
+mode: 'agent'
+description: 'Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.'
+tools: ['changes', 'search/codebase', 'edit/editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'new', 'openSimpleBrowser', 'problems', 'runCommands', 'runInTerminal2', 'runNotebooks', 'runTasks', 'runTests', 'search', 'search/searchResults', 'runCommands/terminalLastCommand', 'runCommands/terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'microsoft.docs.mcp', 'github', 'Microsoft Docs']
+---
+# Create GitHub Actions Workflow Specification
+
+Create a comprehensive specification for the GitHub Actions workflow: `${input:WorkflowFile}`.
+
+This specification serves as a specification for the workflow's behavior, requirements, and constraints. It must be implementation-agnostic, focusing on **what** the workflow accomplishes rather than **how** it's implemented.
+
+## AI-Optimized Requirements
+
+- **Token Efficiency**: Use concise language without sacrificing clarity
+- **Structured Data**: Leverage tables, lists, and diagrams for dense information
+- **Semantic Clarity**: Use precise terminology consistently throughout
+- **Implementation Abstraction**: Avoid specific syntax, commands, or tool versions
+- **Maintainability**: Design for easy updates as workflow evolves
+
+## Specification Template
+
+Save as: `/spec/spec-process-cicd-[workflow-name].md`
+
+```md
+---
+title: CI/CD Workflow Specification - [Workflow Name]
+version: 1.0
+date_created: [YYYY-MM-DD]
+last_updated: [YYYY-MM-DD]
+owner: DevOps Team
+tags: [process, cicd, github-actions, automation, [domain-specific-tags]]
+---
+
+## Workflow Overview
+
+**Purpose**: [One sentence describing workflow's primary goal]
+**Trigger Events**: [List trigger conditions]
+**Target Environments**: [Environment scope]
+
+## Execution Flow Diagram
+
+```mermaid
+graph TD
+    A[Trigger Event] --> B[Job 1]
+    B --> C[Job 2]
+    C --> D[Job 3]
+    D --> E[End]
+    
+    B --> F[Parallel Job]
+    F --> D
+    
+    style A fill:#e1f5fe
+    style E fill:#e8f5e8
+```
+
+## Jobs & Dependencies
+
+| Job Name | Purpose | Dependencies | Execution Context |
+|----------|---------|--------------|-------------------|
+| job-1 | [Purpose] | [Prerequisites] | [Runner/Environment] |
+| job-2 | [Purpose] | job-1 | [Runner/Environment] |
+
+## Requirements Matrix
+
+### Functional Requirements
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|-------------------|
+| REQ-001 | [Requirement] | High | [Testable criteria] |
+| REQ-002 | [Requirement] | Medium | [Testable criteria] |
+
+### Security Requirements
+| ID | Requirement | Implementation Constraint |
+|----|-------------|---------------------------|
+| SEC-001 | [Security requirement] | [Constraint description] |
+
+### Performance Requirements
+| ID | Metric | Target | Measurement Method |
+|----|-------|--------|-------------------|
+| PERF-001 | [Metric] | [Target value] | [How measured] |
+
+## Input/Output Contracts
+
+### Inputs
+
+```yaml
+# Environment Variables
+ENV_VAR_1: string  # Purpose: [description]
+ENV_VAR_2: secret  # Purpose: [description]
+
+# Repository Triggers
+paths: [list of path filters]
+branches: [list of branch patterns]
+```
+
+### Outputs
+
+```yaml
+# Job Outputs
+job_1_output: string  # Description: [purpose]
+build_artifact: file  # Description: [content type]
+```
+
+### Secrets & Variables
+
+| Type | Name | Purpose | Scope |
+|------|------|---------|-------|
+| Secret | SECRET_1 | [Purpose] | Workflow |
+| Variable | VAR_1 | [Purpose] | Repository |
+
+## Execution Constraints
+
+### Runtime Constraints
+
+- **Timeout**: [Maximum execution time]
+- **Concurrency**: [Parallel execution limits]
+- **Resource Limits**: [Memory/CPU constraints]
+
+### Environmental Constraints
+
+- **Runner Requirements**: [OS/hardware needs]
+- **Network Access**: [External connectivity needs]
+- **Permissions**: [Required access levels]
+
+## Error Handling Strategy
+
+| Error Type | Response | Recovery Action |
+|------------|----------|-----------------|
+| Build Failure | [Response] | [Recovery steps] |
+| Test Failure | [Response] | [Recovery steps] |
+| Deployment Failure | [Response] | [Recovery steps] |
+
+## Quality Gates
+
+### Gate Definitions
+
+| Gate | Criteria | Bypass Conditions |
+|------|----------|-------------------|
+| Code Quality | [Standards] | [When allowed] |
+| Security Scan | [Thresholds] | [When allowed] |
+| Test Coverage | [Percentage] | [When allowed] |
+
+## Monitoring & Observability
+
+### Key Metrics
+
+- **Success Rate**: [Target percentage]
+- **Execution Time**: [Target duration]
+- **Resource Usage**: [Monitoring approach]
+
+### Alerting
+
+| Condition | Severity | Notification Target |
+|-----------|----------|-------------------|
+| [Condition] | [Level] | [Who/Where] |
+
+## Integration Points
+
+### External Systems
+
+| System | Integration Type | Data Exchange | SLA Requirements |
+|--------|------------------|---------------|------------------|
+| [System] | [Type] | [Data format] | [Requirements] |
+
+### Dependent Workflows
+
+| Workflow | Relationship | Trigger Mechanism |
+|----------|--------------|-------------------|
+| [Workflow] | [Type] | [How triggered] |
+
+## Compliance & Governance
+
+### Audit Requirements
+
+- **Execution Logs**: [Retention policy]
+- **Approval Gates**: [Required approvals]
+- **Change Control**: [Update process]
+
+### Security Controls
+
+- **Access Control**: [Permission model]
+- **Secret Management**: [Rotation policy]
+- **Vulnerability Scanning**: [Scan frequency]
+
+## Edge Cases & Exceptions
+
+### Scenario Matrix
+
+| Scenario | Expected Behavior | Validation Method |
+|----------|-------------------|-------------------|
+| [Edge case] | [Behavior] | [How to verify] |
+
+## Validation Criteria
+
+### Workflow Validation
+
+- **VLD-001**: [Validation rule]
+- **VLD-002**: [Validation rule]
+
+### Performance Benchmarks
+
+- **PERF-001**: [Benchmark criteria]
+- **PERF-002**: [Benchmark criteria]
+
+## Change Management
+
+### Update Process
+
+1. **Specification Update**: Modify this document first
+2. **Review & Approval**: [Approval process]
+3. **Implementation**: Apply changes to workflow
+4. **Testing**: [Validation approach]
+5. **Deployment**: [Release process]
+
+### Version History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|--------|
+| 1.0 | [Date] | Initial specification | [Author] |
+
+## Related Specifications
+
+- [Link to related workflow specs]
+- [Link to infrastructure specs]
+- [Link to deployment specs]
+
+```
+
+## Analysis Instructions
+
+When analyzing the workflow file:
+
+1. **Extract Core Purpose**: Identify the primary business objective
+2. **Map Job Flow**: Create dependency graph showing execution order
+3. **Identify Contracts**: Document inputs, outputs, and interfaces
+4. **Capture Constraints**: Extract timeouts, permissions, and limits
+5. **Define Quality Gates**: Identify validation and approval points
+6. **Document Error Paths**: Map failure scenarios and recovery
+7. **Abstract Implementation**: Focus on behavior, not syntax
+
+## Mermaid Diagram Guidelines
+
+### Flow Types
+- **Sequential**: `A --> B --> C`
+- **Parallel**: `A --> B & A --> C; B --> D & C --> D`
+- **Conditional**: `A --> B{Decision}; B -->|Yes| C; B -->|No| D`
+
+### Styling
+```mermaid
+style TriggerNode fill:#e1f5fe
+style SuccessNode fill:#e8f5e8
+style FailureNode fill:#ffebee
+style ProcessNode fill:#f3e5f5
+```
+
+### Complex Workflows
+For workflows with 5+ jobs, use subgraphs:
+```mermaid
+graph TD
+    subgraph "Build Phase"
+        A[Lint] --> B[Test] --> C[Build]
+    end
+    subgraph "Deploy Phase"  
+        D[Staging] --> E[Production]
+    end
+    C --> D
+```
+
+## Token Optimization Strategies
+
+1. **Use Tables**: Dense information in structured format
+2. **Abbreviate Consistently**: Define once, use throughout
+3. **Bullet Points**: Avoid prose paragraphs
+4. **Code Blocks**: Structured data over narrative
+5. **Cross-Reference**: Link instead of repeat information
+
+Focus on creating a specification that serves as both documentation and a template for workflow updates.

package/assets/prompts/create-github-issue-feature-from-specification.prompt.md

@@ -0,0 +1,28 @@
+---
+mode: 'agent'
+description: 'Create GitHub Issue for feature request from specification file using feature_request.yml template.'
+tools: ['search/codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
+---
+# Create GitHub Issue from Specification
+
+Create GitHub Issue for the specification at `${file}`.
+
+## 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
+
+- 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
+
+- Title: Feature name from specification
+- Description: Problem statement, proposed solution, and context
+- Labels: feature, enhancement (as appropriate)

package/assets/prompts/create-github-issues-feature-from-implementation-plan.prompt.md

@@ -0,0 +1,28 @@
+---
+mode: 'agent'
+description: 'Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates.'
+tools: ['search/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
+
+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
+
+- 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
+
+- Title: Phase name from implementation plan
+- Description: Phase details, requirements, and context
+- Labels: Appropriate for issue type (feature/chore)