@silverassist/agents-toolkit 2.0.0

package/templates/shared/prompts/README.md

@@ -0,0 +1,129 @@
+# Prompts / Commands
+
+Reusable prompt templates for AI agent workflows — compatible with **GitHub Copilot** (VS Code), **Claude Code**, and **Codex**.
+
+## Overview
+
+This package provides a collection of modular, reusable prompts for common development workflows. Each prompt integrates with Jira via the Atlassian MCP.
+
+- **GitHub Copilot**: files live in `.github/prompts/` with `.prompt.md` extension
+- **Claude Code**: files live in `.claude/commands/` with `.md` extension (auto-converted by the CLI)
+- **Codex**: prompts live in `.github/prompts/` as reusable workflow references
+
+## Structure
+
+```
+prompts/
+├── README.md                    # This documentation
+├── _partials/                   # Shared prompt fragments
+│   ├── README.md               # Partials documentation
+│   ├── validations.md          # Code quality validation steps
+│   ├── git-operations.md       # Git workflow operations
+│   ├── jira-integration.md     # Jira/Atlassian MCP operations
+│   ├── documentation.md        # Documentation standards
+│   └── pr-template.md          # Pull request templates
+│
+├── # Workflow Prompts (Main Flow)
+├── analyze-ticket.prompt.md    # 1. Analyze a Jira ticket
+├── create-plan.prompt.md       # 2. Create implementation plan
+├── work-ticket.prompt.md       # 3. Start working on a ticket
+├── prepare-pr.prompt.md        # 4. Prepare code for PR
+├── create-pr.prompt.md         # 5. Create a pull request
+├── finalize-pr.prompt.md       # 6. Finalize and merge PR
+│
+├── # Utility Prompts
+├── review-code.prompt.md       # Quick code review
+├── fix-issues.prompt.md        # Fix lint/type/test errors
+└── add-tests.prompt.md         # Add tests for components
+```
+
+## Workflow Stages
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  1. Analyze     │────▶│  2. Plan        │────▶│  3. Work        │
+│  analyze-ticket │     │  create-plan    │     │  work-ticket    │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+                                                        │
+                                                        ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  6. Finalize    │◀────│  5. Create PR   │◀────│  4. Prepare     │
+│  finalize-pr    │     │  create-pr      │     │  prepare-pr     │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+## Usage
+
+### GitHub Copilot (VS Code)
+
+1. Open the Command Palette (`Cmd+Shift+P`)
+2. Search for "GitHub Copilot: Run Prompt"
+3. Select the desired prompt
+4. Fill in the required variables (e.g., `{ticket-id}`)
+
+### Claude Code
+
+Type `/` in the chat to open the command palette and select the desired command:
+
+```
+/analyze-ticket
+/work-ticket
+/create-pr
+```
+
+### Codex
+
+Run Codex from the project root after installing with `--codex`. Use prompts in `.github/prompts/` as workflow templates and task checklists.
+
+### Variables
+
+Each prompt may require input variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{ticket-id}` | Jira ticket identifier | `WEB-726` |
+| `{feature-description}` | Brief feature description | `Add font size controls` |
+| `{feature-name}` | Kebab-case feature name | `font-accessibility` |
+
+## Customization
+
+### Adding Custom Prompts
+
+1. Create a new `.prompt.md` file
+2. Use the frontmatter format:
+
+   ```markdown
+   ---
+   agent: agent
+   description: Brief description of the prompt
+   ---
+   
+   Your prompt content here...
+   ```
+
+### Frontmatter Options
+
+| Field | Description |
+|-------|-------------|
+| `description` | A short description of the prompt |
+| `name` | The name shown after typing `/` in chat (defaults to filename) |
+| `agent` | The agent to use: `ask`, `edit`, `agent`, or custom agent name |
+| `model` | Language model to use (defaults to selected model) |
+| `tools` | List of tools available for this prompt |
+
+### Using Partials
+
+Reference shared fragments in your prompts:
+
+```markdown
+## Prerequisites
+- Reference: `.github/prompts/_partials/validations.md`
+```
+
+## Integration
+
+### Required Tools/MCPs
+
+- **Atlassian MCP**: For Jira ticket operations
+- **Git**: For version control operations
+- **npm/Node.js**: For running validations

package/templates/shared/prompts/_partials/README.md

@@ -0,0 +1,57 @@
+# Prompts Partials Index
+
+This directory contains reusable prompt fragments that can be referenced in main prompts.
+
+## Available Partials
+
+| Partial | Description | Use Case |
+|---------|-------------|----------|
+| `validations.md` | Code quality validation steps | Pre-PR checks, CI validation |
+| `git-operations.md` | Git workflow operations | Branch management, commits |
+| `jira-integration.md` | Jira/Atlassian MCP operations | Ticket reading, updates |
+| `documentation.md` | Documentation standards | JSDoc, README, planning docs |
+| `pr-template.md` | Pull request templates | PR creation, review |
+
+## How to Reference
+
+In your prompt files, reference partials like this:
+
+```markdown
+## Prerequisites
+- Reference: `.github/prompts/_partials/validations.md`
+```
+
+The agent will read the referenced partial when needed.
+
+## Creating New Partials
+
+1. Create a new `.md` file in this directory
+2. Use clear section headings with `###`
+3. Include reusable steps with `Step:` prefix
+4. Add this file to the README table
+5. Reference from main prompts as needed
+
+## Partial Structure
+
+```markdown
+# Partial Name
+
+Description of what this partial provides.
+
+## Usage
+When and how to use this partial.
+
+---
+
+## Section 1
+
+### Step: Step Name
+1. First action
+2. Second action
+3. Third action
+
+---
+
+## Section 2
+...
+```

package/templates/shared/prompts/_partials/documentation.md

@@ -0,0 +1,203 @@
+# Documentation Partial
+
+Reusable documentation standards and steps for prompts.
+
+## Usage
+
+Include these steps in prompts that require documentation checks or creation.
+
+---
+
+## Documentation Standards
+
+### Step: Verify Documentation
+
+1. **Check JSDoc comments**:
+   - All new/modified functions have JSDoc
+   - Include `@param`, `@returns`, `@example` where applicable
+   - Write in English
+
+2. **Check component documentation**:
+   - Props interfaces are defined and documented
+   - Complex logic has inline comments
+   - Component usage examples exist
+
+3. **Check README updates**:
+   - New features documented if user-facing
+   - Configuration changes noted
+   - Breaking changes highlighted
+
+---
+
+## JSDoc Standards
+
+### Function Documentation
+
+```typescript
+/**
+ * Formats a date string for display.
+ * 
+ * @param date - The date to format (ISO string or Date object)
+ * @param locale - The locale for formatting (default: 'en-US')
+ * @returns Formatted date string
+ * @example
+ * formatDate('2024-01-15') // 'January 15, 2024'
+ * formatDate('2024-01-15', 'es-ES') // '15 de enero de 2024'
+ */
+export function formatDate(date: string | Date, locale = 'en-US'): string {
+  // implementation
+}
+```
+
+### Component Documentation
+
+```typescript
+/**
+ * User profile card displaying avatar and basic information.
+ * 
+ * @example
+ * <UserCard 
+ *   user={{ name: 'John Doe', email: 'john@example.com' }}
+ *   showEmail={true}
+ * />
+ */
+export default function UserCard({ user, showEmail }: UserCardProps) {
+  // implementation
+}
+```
+
+---
+
+## Documentation Files
+
+### Planning Documents
+
+Location: `docs/{feature-name}-plan.md`
+
+Template:
+```markdown
+# {Feature Name} Implementation Plan
+
+## Problem Statement
+What problem are we solving?
+
+## Current Architecture
+How does it work now?
+
+## Proposed Changes
+What needs to change?
+
+## Risk Assessment
+- Risk 1: Description
+- Mitigation: Solution
+
+## Phase Breakdown
+
+### Phase 1: {Name}
+- [ ] Task 1
+- [ ] Task 2
+
+### Phase 2: {Name}
+- [ ] Task 1
+- [ ] Task 2
+
+## Testing Strategy
+How will we validate this works?
+
+## Rollback Plan
+How to revert if issues arise?
+```
+
+---
+
+### Feature Documentation
+
+Location: `docs/{feature-name}.md`
+
+Template:
+```markdown
+# {Feature Name}
+
+## Overview
+Brief description of the feature.
+
+## Usage
+
+### Basic Usage
+```typescript
+// Example code
+```
+
+### Advanced Usage
+```typescript
+// More complex example
+```
+
+## Configuration
+Any configuration options.
+
+## API Reference
+If applicable, API details.
+
+## Troubleshooting
+Common issues and solutions.
+```
+
+---
+
+## Step: Create Planning Document
+
+1. **Determine file name**:
+   - Convert feature to kebab-case
+   - Pattern: `docs/{feature-name}-plan.md`
+
+2. **Include sections**:
+   - Problem Statement
+   - Current Architecture
+   - Proposed Changes
+   - Risk Assessment
+   - Phase Breakdown
+   - Testing Strategy
+
+3. **Commit document**:
+   ```bash
+   git add docs/{feature-name}-plan.md
+   git commit -m "TICKET-ID: Add {feature} implementation plan"
+   ```
+
+---
+
+## Step: Create Final Documentation
+
+1. **After implementation complete**:
+   - Create `docs/{feature-name}.md` with usage guide
+   - Update any related documentation
+   - Delete planning document if no longer needed
+
+2. **Commit documentation**:
+   ```bash
+   git add docs/
+   git commit -m "TICKET-ID: Add {feature} documentation"
+   ```
+
+---
+
+## Documentation Checklist
+
+### Code Documentation
+- [ ] JSDoc on all public functions
+- [ ] Props interfaces documented
+- [ ] Complex logic has comments
+- [ ] Type definitions have descriptions
+
+### Project Documentation
+- [ ] Feature documented in `docs/`
+- [ ] README updated if needed
+- [ ] CHANGELOG updated
+- [ ] Migration guide if breaking changes
+
+### PR Documentation
+- [ ] Clear PR title with ticket ID
+- [ ] Description explains changes
+- [ ] Testing notes included
+- [ ] Screenshots for UI changes

package/templates/shared/prompts/_partials/git-operations.md

@@ -0,0 +1,171 @@
+# Git Operations Partial
+
+Reusable Git workflow operations for prompts.
+
+## Usage
+
+Include these steps in prompts that require Git operations.
+
+---
+
+## Branch Operations
+
+### Step: Resolve Base Branch
+
+1. **Read base branch from config**:
+   ```bash
+   BASE_BRANCH=$(node -e "try{const c=require('./.agents-toolkit.json');console.log(c.pr?.targetBranch||c.git?.defaultBranch||'main')}catch{console.log('main')}")
+   echo "$BASE_BRANCH"
+   ```
+
+2. **Fallback behavior**:
+   - If config is missing or invalid, default to `main`
+
+---
+
+### Step: Verify Branch Status
+
+1. **Check current branch**:
+   - Run `git branch --show-current` to get current branch name
+   - Ensure not on protected branches: `main`, `dev`, `stg`, `master`, and `${BASE_BRANCH}`
+
+2. **Check branch naming**:
+   - Verify branch follows convention:
+     - `feature/[TICKET-ID]-short-description`
+     - `bugfix/[TICKET-ID]-short-description`
+
+3. **Check uncommitted changes**:
+   - Run `git status` to see working directory state
+   - Ensure all changes are committed before proceeding
+
+---
+
+### Step: Create Working Branch
+
+1. **Ensure on latest base branch**:
+   ```bash
+   git checkout "$BASE_BRANCH"
+   git pull origin "$BASE_BRANCH"
+   ```
+
+2. **Create new branch**:
+   ```bash
+   git checkout -b feature/[TICKET-ID]-short-description
+   # or
+   git checkout -b bugfix/[TICKET-ID]-short-description
+   ```
+
+---
+
+### Step: Push Branch
+
+1. **Push to remote**:
+   ```bash
+   git push -u origin <branch-name>
+   ```
+
+2. **Verify push**:
+   - Confirm branch appears in remote repository
+
+---
+
+## Sync Operations
+
+### Step: Sync with Base Branch
+
+1. **Fetch latest**:
+   ```bash
+   git fetch origin
+   ```
+
+2. **Rebase on base branch**:
+   ```bash
+   git rebase "origin/${BASE_BRANCH}"
+   ```
+
+3. **Handle conflicts** (if any):
+   - Resolve each conflict file
+   - Stage resolved files: `git add <file>`
+   - Continue rebase: `git rebase --continue`
+
+4. **Push updated branch**:
+   ```bash
+   git push --force-with-lease
+   ```
+
+---
+
+## Commit Operations
+
+### Step: Review Commits
+
+1. **View recent commits**:
+   ```bash
+   git log --oneline -5
+   ```
+
+2. **Verify commit messages**:
+   - Follow format: `TICKET-ID: Short description`
+   - Use present tense, imperative mood
+   - Example: `WEB-726: Add font size accessibility controls`
+
+3. **If history is noisy**:
+   - Prefer squash merge in the PR platform instead of interactive rebases
+
+---
+
+### Step: View Changes
+
+1. **Summary of changes**:
+   ```bash
+   git diff --stat
+   ```
+
+2. **List changed files**:
+   ```bash
+   git diff "$BASE_BRANCH" --name-only
+   ```
+
+3. **Detailed diff**:
+   ```bash
+   git diff "$BASE_BRANCH"
+   ```
+
+---
+
+## Cleanup Operations
+
+### Step: Post-Merge Cleanup
+
+1. **Delete local branch**:
+   ```bash
+   git branch -d <branch-name>
+   ```
+
+2. **Delete remote branch**:
+   ```bash
+   git push origin --delete <branch-name>
+   ```
+
+3. **Prune stale branches**:
+   ```bash
+   git remote prune origin
+   ```
+
+---
+
+## Branch Naming Convention
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature | `feature/[TICKET-ID]-description` | `feature/WEB-726-font-controls` |
+| Bugfix | `bugfix/[TICKET-ID]-description` | `bugfix/WEB-734-logo-sizing` |
+| Hotfix | `hotfix/[TICKET-ID]-description` | `hotfix/WEB-800-critical-fix` |
+
+## Protected Branches
+
+These branches require PRs and cannot receive direct commits:
+- `main` - Production
+- `dev` - Development
+- `stg` - Staging
+- `master` - Legacy (if exists)

package/templates/shared/prompts/_partials/github-integration.md

@@ -0,0 +1,100 @@
+# GitHub Integration Partial
+
+Reusable GitHub issue and PR operations for prompts.
+
+## Usage
+
+Include these steps in prompts that require GitHub integration.
+
+---
+
+## Issue Operations
+
+### Step: Read GitHub Issue
+
+1. **Fetch issue details**:
+   - Use `mcp_github_github_issue_read` with owner, repo, and issue number
+   - Or use `gh issue view <number> | cat` via terminal
+
+2. **Extract key information**:
+   - **Title**: Issue title
+   - **Body**: Full description and context
+   - **Labels**: Category and priority labels
+   - **Assignees**: Who is responsible
+   - **Milestone**: Target milestone if set
+   - **State**: Open / Closed
+
+3. **Read issue comments**:
+   - Fetch all comments for additional context
+   - Note any clarifications or updates from maintainers
+
+4. **Identify acceptance criteria**:
+   - Look in body for "Acceptance Criteria" section
+   - List all checkable requirements
+
+---
+
+### Step: Search Related Issues
+
+1. **Search by label**:
+   - Use `gh issue list --label "<label>" | cat`
+   - Find related issues in the same phase or category
+
+2. **Search by keyword**:
+   - Use `gh search issues "<keyword>" --repo owner/repo | cat`
+   - Find duplicates or related work
+
+---
+
+## Issue Update Operations
+
+### Step: Add Comment to Issue
+
+1. **Add progress comment**:
+   - Use `gh issue comment <number> --body "message" | cat`
+   - Include relevant links (PR, branch, etc.)
+   - Use Markdown formatting for readability
+
+2. **Comment templates**:
+   ```markdown
+   ## Development Started
+   - Branch: `feature/<number>-description`
+   - PR: [Link to PR]
+
+   ## Progress
+   - [x] Initial implementation
+   - [ ] Tests
+   - [ ] Documentation
+   ```
+
+---
+
+### Step: Close Issue
+
+1. **Close with comment**:
+   - Use `gh issue close <number> --comment "Completed in PR #XX" | cat`
+
+2. **Close as not planned**:
+   - Use `gh issue close <number> --reason "not planned" --comment "Reason" | cat`
+
+---
+
+## Issue Analysis
+
+### Step: Analyze Issue Impact
+
+1. **Identify affected areas**:
+   - Components that need changes
+   - Files likely to be modified
+   - Dependencies and integrations
+
+2. **Estimate complexity**:
+   - **Simple**: 1-2 files, straightforward change
+   - **Medium**: 3-5 files, some logic changes
+   - **Complex**: 6+ files, architectural changes
+
+3. **Identify risks**:
+   - Breaking changes
+   - Migration requirements
+   - External dependencies
+   - Testing complexity