zhongwei/gh-taylorhuston-ai-toolkit-plugins-ai-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:00:21 +08:00
commit f5496428cd
50 changed files with 10011 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
commands/adr.md Normal file
View File

@@ -0,0 +1,146 @@
---
tags: ["workflow", "architecture", "decisions", "adr"]
description: "Create Architecture Decision Records through interactive conversation"
argument-hint: "[\"optional context or topic\"]"
allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob", "TodoWrite", "Task"]
model: claude-opus-4-5
references_guidelines:
- docs/development/conventions/architectural-principles.md # Design principles and patterns to consider
- docs/development/templates/adr-template.md # ADR template structure
- docs/development/templates/architecture-overview-template.md # Architecture overview template structure
---
# /adr Command
**WHAT**: Create Architecture Decision Records through interactive conversation.
**WHY**: Document significant architectural decisions with context, alternatives, and rationale for future reference.
**HOW**: See architectural-principles.md for design principles and patterns. Interactive 8-step process gathers context and creates ADR.
**IMPORTANT**: Architecture decisions have long-term consequences. Take time to think thoroughly - quality > speed.
## Usage
```bash
/adr # Start conversation
/adr "database selection" # Provide context
/adr "authentication approach"
/adr "frontend framework"
```
## Process (8 Steps)
1. **Read Context** - Load best practices, template, existing ADRs, architecture overview
2. **Understand Decision** - Read project context, clarify topic
3. **Ask Questions** - ONE at a time, build understanding progressively
4. **Present Options** - 2-3 viable options with trade-offs
5. **Discuss Deeply** - Leverage specialist agents, explore implications
6. **Get Confirmation** - Ensure user understands trade-offs
7. **Create ADR** - Document decision following template
8. **Update Architecture Overview** - Reflect decision in `architecture-overview.md`
## Example Flow
```
User: /adr "database selection"
AI: [Reads best practices, template, existing ADRs, architecture overview]
Looking at your project brief - quotation management app, monolithic, no database yet.
Previous decisions: ADR-002 (auth), ADR-003 (API design).
Data structure needs? (relational/flexible/mix)
User: Primarily relational
Expected scale? (<10k/10k-100k/100k+)
User: <10k users first year
Team experience? (SQL/ORM/NoSQL)
User: SQL + ORM
Hosting? (managed/self-hosted)
User: Managed, minimize ops
Options:
- PostgreSQL (Supabase) - Managed, built-in auth, relational
- PostgreSQL (Self-hosted) - Full control, no vendor lock-in
- MongoDB Atlas - Flexible schema, horizontal scaling
[Consults database-specialist, security-auditor for expert analysis]
AI: Great! Creating ADR-001-use-postgresql-supabase.md
Updating architecture-overview.md
✓ ADR-001 created and architecture overview updated
```
## Files Read Before Conversation
- `docs/project/adrs/README.md` - Best practices, quality standards
- `docs/development/templates/adr-template.md` - Template structure (YAML frontmatter)
- `docs/project/adrs/ADR-*.md` - Existing ADRs (decision history, patterns, conflicts)
- `docs/project/conventions/*.md` - Codebase conventions
- `docs/project/architecture-overview.md` - Current architecture state
- `docs/project-brief.md`, `CLAUDE.md` - Project context
**Why read existing ADRs**: Understand history, avoid conflicts, reference related decisions, build on previous choices
## Agent Coordination
**Primary**: `code-architect` (leads conversation, creates ADR)
**Specialists** (consulted via Task tool during step 5):
- `database-specialist` - DB selection, data modeling, scaling
- `devops-engineer` - Infrastructure, deployment, CI/CD
- `security-auditor` - Security architecture, auth, compliance
- `frontend-specialist` - Frontend frameworks, state management
- `backend-specialist` - Backend frameworks, API design
- `performance-optimizer` - Performance, scalability, caching
- `ui-ux-designer` - UX architecture, design systems
**Example**: Database decision → consult database-specialist + security-auditor + performance-optimizer + devops-engineer
## Command Instructions
```
Task: "Create ADR for [topic] through interactive conversation.
CRITICAL MINDSET:
- Architecture decisions have long-term consequences
- Take time - quality > speed
- Consider implications 1/3/5 years out
- Explore edge cases before committing
PROCESS:
1. BEFORE: Read docs/project/adrs/README.md, docs/development/templates/adr-template.md,
ALL docs/project/adrs/ADR-*.md, docs/project/architecture-overview.md,
docs/project-brief.md, CLAUDE.md
2. DURING: Ask ONE question at a time, wait for answer, leverage specialist agents
via Task tool
3. AFTER: Determine ADR number, create docs/project/adrs/ADR-###-<kebab-case>.md, update
docs/project/architecture-overview.md, link from epic if relevant
ADR CONTENT:
- Context: Why matters, forces at play, honest problem framing
- Decision: Definitive ("We will use X"), clear rationale
- Alternatives: Options considered, why rejected
- Consequences: Honest trade-offs, negative consequences, long-term impact
- References: Related ADRs, epics, docs
Output ADR documenting conversation and decision."
```
## ADR Content Guidelines
- **Context**: Why this decision matters, forces at play, honest problem framing
- **Decision**: Definitive ("We will use X"), clear rationale, active voice
- **Alternatives**: Real options considered, why each was rejected
- **Consequences**: Honest trade-offs, negative consequences, long-term impact (1/3/5 years)
- **References**: Related ADRs, epics, documentation
## ADR Location & Naming
**Location**: `docs/project/adrs/ADR-###-<kebab-case-title>.md`
**Numbering**: Sequential (scan existing ADR-*.md files for next number)
**Architecture Overview**: Living document - read at start, updated at end

80
commands/advise.md Normal file
View File

@@ -0,0 +1,80 @@
---
tags: ["workflow", "development", "collaborative"]
description: "Get implementation guidance for a phase without automated code generation - user implements manually"
argument-hint: "TASK-### PHASE | TASK-### --next | --next"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/pm-workflows.md # Phase structure, quality gates, completion protocol
- docs/development/workflows/worklog-format.md # ADVICE entry format
- docs/development/workflows/task-workflow.md # Quality gates, collaborative mode
- docs/development/workflows/agent-coordination.md # Advisory mode agent coordination
---
# /advise Command
**WHAT**: Provide structured implementation guidance for a phase WITHOUT writing code - user implements manually following advice.
**WHY**: Collaborative mode enables hands-on learning, full control over implementation, and balance between automation and manual coding.
**HOW**: See pm-guide.md for phase requirements and completion protocol. See task-workflow.md for collaborative implementation mode. See agent-coordination.md for advisory mode patterns.
## Usage
```bash
/advise TASK-001 1.2 # Get guidance for Phase 1.2
/advise TASK-001 --next # Smart: find and advise on next uncompleted phase
/advise --next # Auto-detect current task, advise next phase
```
## Execution Flow
**Before you start**: Read pm-guide.md for phase requirements and completion protocol. Read task-workflow.md for collaborative implementation mode. Read agent-coordination.md for advisory mode patterns.
### High-Level Steps
1. **Parse & Locate**
- Parse issue ID and phase number (or auto-detect next)
- Locate issue directory: pm/issues/{ISSUE-ID}-*/
- Read TASK.md/BUG.md, PLAN.md
2. **Analyze Context**
- Read CLAUDE.md, coding-standards.md, architecture-overview.md
- Grep existing code patterns in codebase
- Understand phase requirements and project constraints
3. **Invoke Advisory Agents**
- code-architect: Architectural approach, patterns, integration points
- security-auditor: Security considerations (if applicable)
- test-engineer: Test strategy and scenarios
- **All agents in advisory mode**: No code generation, guidance only
4. **Compile Guidance Document**
- Suggested approach (high-level strategy)
- Implementation details (signatures, types, patterns)
- Files to create/modify
- Security considerations (if applicable)
- Testing strategy
- Code examples (minimal scaffolding)
5. **Create WORKLOG Entry**
- Write ADVICE entry per worklog-format.md
- Document guidance provided
- Mark phase as advised
6. **Present to User**
- Output structured advice for manual implementation
- User implements following guidance
- User marks phase complete in PLAN.md
- Same quality gates apply as /implement
**See task-workflow.md "Collaborative Implementation Mode" for complete workflow and examples.**
## Mode Comparison
**`/implement`** (Automated): AI writes code, fast, best for boilerplate/standard patterns
**`/advise`** (Collaborative): User writes code with AI guidance, hands-on learning, best for complex logic
**Hybrid approach** (recommended): `/implement` for boilerplate → `/advise` for complex logic → `/implement` for tests
See task-workflow.md for complete workflow patterns and examples.

125
commands/branch.md Normal file
View File

@@ -0,0 +1,125 @@
---
tags: ["workflow", "git", "branching"]
description: "Unified branch operations with git-workflow enforcement"
argument-hint: "create ISSUE-ID | merge [target] | delete branch-name | switch branch-name | status | \"natural language\""
allowed-tools: ["Bash", "Read", "Edit", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/git-workflow.md # Source of truth for branching rules, merge validation, naming patterns
---
# /branch Command
**WHAT**: Unified branch operations (create, merge, delete, switch, status) with git-workflow enforcement.
**WHY**: Ensure consistent branch naming, enforce quality gates on merge, prevent workflow violations.
**HOW**: See git-workflow.md for branching rules, merge validation requirements, and naming patterns.
**CRITICAL**: Always read `docs/development/workflows/git-workflow.md` FIRST for project-specific rules.
## Usage
```bash
/branch create TASK-001 # Create work branch
/branch merge [develop|main] # Merge with validation
/branch delete feature/TASK-001 # Delete merged branch
/branch switch develop # Switch branches
/branch status # Show workflow state
# Natural language
/branch "merge to develop"
/branch "create for TASK-001"
```
## Operations
### Create
1. Read git-workflow.md for branching pattern and base branch
2. Parse issue ID → determine type (TASK → feature, BUG → bugfix)
3. Create branch following pattern (e.g., `feature/TASK-001` from `develop`)
4. Switch to new branch
### Merge
1. Read git-workflow.md for merge rules
2. Apply validation based on target:
- **To develop**: Run tests (BLOCK if fail)
- **To main**:
- Verify source is `develop` (BLOCK if feature/bugfix)
- Run staging health checks (BLOCK if fail)
- Hotfixes require explicit justification
3. If pass: merge and push
4. If fail: block with clear error
### Delete
1. Check if fully merged
2. Confirm with user
3. Delete local and remote
### Switch
1. Check uncommitted changes (offer stash)
2. Switch to target
3. Pull latest
### Status
1. Show current branch and issue context
2. Check test/validation status
3. Show merge requirements
## Configuration
Reads `docs/development/workflows/git-workflow.md` YAML frontmatter:
```yaml
---
branching_strategy: "three-branch"
main_branch: "main"
develop_branch: "develop"
work_branch_pattern: "type/ISSUE-ID"
merge_rules:
to_develop: "tests_pass"
to_main: "staging_validated"
---
```
**If missing**: Use defaults (three-branch: main ← develop ← work branches)
## Agent Coordination
- **devops-engineer** - Health checks, deployment validation
- **test-engineer** - Test execution, result parsing
## Command Instructions
```
Task: "Execute Git branch operation following project workflow rules.
CRITICAL:
1. FIRST: Read docs/development/workflows/git-workflow.md
- Extract YAML frontmatter
- Understand strategy, patterns, merge rules
- Use as source of truth
2. Execute operation:
- create: Follow pattern, create from base
- merge: Apply validation, block if fail
- delete: Check merge status, confirm, delete
- switch: Handle uncommitted, switch, pull
- status: Show state and readiness
3. Validation enforcement:
- Merge to develop: Run tests (auto-detect)
- Merge to main: Verify source=develop, check staging
- Block if fail, show clear errors
4. Git commands:
- git checkout, branch, merge, push
- Parse output, handle conflicts
5. Natural language:
- Parse intent from quoted string
- Map to structured operation
- Execute with same validation
All rules defined in git-workflow.md - this command enforces them."
```

152
commands/changelog.md Normal file
View File

@@ -0,0 +1,152 @@
---
tags: ["documentation", "versioning", "changelog", "maintenance"]
description: "Check if CHANGELOG is up to date and update as necessary"
aliases: ["update-changelog"]
allowed-tools: ["Read", "Edit", "Bash", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/conventions/versioning-and-releases.md # CHANGELOG format, categories, writing style
---
# /changelog Command
**WHAT**: Update CHANGELOG.md with undocumented changes from git history.
**WHY**: Keep CHANGELOG accurate and reduce pre-release work.
**HOW**: See `docs/development/conventions/versioning-and-releases.md` for format, categories, and writing style guidelines.
## Usage
```bash
/changelog # Check and update CHANGELOG
```
## Execution Steps
### 1. Read Current State
```bash
# Parse CHANGELOG.md
Grep: "^## \[" CHANGELOG.md # Last release version
Read: CHANGELOG.md # [Unreleased] section
# Get last release tag
Bash: git describe --tags --abbrev=0
```
### 2. Analyze Git History
```bash
# Commits since last release (e.g., v0.12.0)
Bash: git log v0.12.0..HEAD --oneline --no-merges
Bash: git diff --name-only v0.12.0..HEAD
```
### 3. Detect Undocumented Changes
**Change types:**
- **Added**: New commands, agents, templates
- **Changed**: Modified functionality, improvements
- **Fixed**: Bug fixes (commits with "fix", "bug", "issue")
- **Removed**: Deleted files (BREAKING if user-facing)
**Compare to CHANGELOG [Unreleased]** - Flag missing entries.
### 4. Draft Suggestions
**Format** (per versioning-and-releases.md):
```markdown
## [Unreleased]
### Added
- **Feature Name**: User-facing description
- Benefit 1
- Benefit 2
### Changed
- **Improvement**: What changed and impact
### Fixed
- **Bug Fix**: What was broken and how fixed
```
**Writing style**:
- ✅ "Added `/changelog` command to update CHANGELOG automatically"
- ❌ "Added changelog.md file to commands directory"
### 5. Update CHANGELOG
Ask user confirmation:
```
Update CHANGELOG.md with these entries? (yes/no/edit)
```
If yes:
- Add entries to `[Unreleased]` section
- Maintain alphabetical order within categories
- Preserve existing content
## Example Output
```
Checking CHANGELOG.md...
Last release: [0.12.0] - 2025-11-03
Commits since v0.12.0: 8 commits, 15 files changed
Undocumented changes:
1. NEW: commands/changelog.md
2. NEW: commands/release.md
3. MODIFIED: commands/ui-design.md (Playwright review)
Suggested entries:
### Added
- `/changelog` command - Auto-update CHANGELOG from git history
- `/release` command - Release versions with semantic versioning
### Changed
- `/ui-design` validates mockups in browser before presenting
Update CHANGELOG? (yes/no)
```
## When to Use
**Run when:**
- Before creating PR
- After completing feature
- Before release
- Periodically to stay current
**Skip when:**
- No user-facing changes
- Already documented
- Work in progress
## Integration
```
/implement → /changelog → /commit → PR
↑
Update before commit
```
## Error Handling
- **No commits**: "CHANGELOG up to date - no commits since v0.12.0"
- **Already complete**: "All changes documented in [Unreleased]"
- **No CHANGELOG**: Create with versioning-and-releases.md format
## Related Commands
- `/release` - Release version (uses CHANGELOG)
- `/commit` - Create commit (may update CHANGELOG)
## Notes
- User approval required before updating
- Follows Keep a Changelog format
- Focus on user impact, not implementation
- Source of truth: versioning-and-releases.md

112
commands/commit.md Normal file
View File

@@ -0,0 +1,112 @@
---
tags: ["workflow", "git", "commit", "quality"]
description: "Create a proper git commit with quality checks and conventional message"
argument-hint: "[message] [--files FILES] [--amend] [--no-verify] [--interactive]"
allowed-tools: ["Bash", "Read", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/git-workflow.md # Commit conventions, type inference, branch naming
---
# /commit Command
**WHAT**: Create git commit with quality checks and conventional message formatting.
**WHY**: Ensure consistent commit messages, enforce quality gates, enable semantic versioning and automated changelogs.
**HOW**: See git-workflow.md for commit conventions, type inference rules, and branch-based message generation.
## Usage
```bash
# Basic
/commit # Interactive with quality checks
/commit "feat: add user auth" # Direct with message
/commit --files "src/auth.js" # Commit specific files
# Advanced
/commit --amend # Amend last (safety checks)
/commit "fix: typo" --no-verify # Skip hooks
/commit --interactive # Interactive staging + commit
/commit "docs: update" --amend --no-verify # Combine flags
```
## Process
**Argument Parsing**:
- `--amend`: Amend mode with safety checks
- `--no-verify`: Skip pre-commit hooks
- `--interactive`: Interactive staging first
- `--files`: Stage only specified files
**Branch-Aware Message Generation**:
1. Get branch: `git branch --show-current`
2. Read `git-workflow.md` for branch naming pattern
3. Extract issue ID from branch (feature/TASK-001 → TASK-001)
4. Determine commit type from staged changes using `commit_type_inference` config
- Analyzes file patterns (tests, docs, config, source)
- Checks message keywords (fix, feature, refactor)
- See git-workflow.md "Commit Type Inference" for customization
5. If issue ID extracted and not in message: `type(ISSUE-ID): description`
6. Follow conventional commits format from git-workflow.md
**Standard Flow**:
1. Run pre-commit checks (tests, lint, type-check) unless `--no-verify`
2. Review staged changes
3. Draft message (branch-aware, with issue reference)
4. Ask confirmation
**Amend Mode** (`--amend`):
1. Safety: Verify not pushed (`git log @{u}..HEAD`)
2. Authorship: Verify author matches user
3. Warning: If different author, warn and require confirmation
4. Proceed: Allow amending if safe
**No-Verify Mode** (`--no-verify`):
1. Display warning (checks skipped)
2. Explain use cases (emergency fixes, WIP)
3. Note quality checks won't run
4. Execute with `--no-verify`
**Interactive Mode** (`--interactive`):
1. Run `git add -i` or `git add -p`
2. Review selected changes
3. Proceed with standard flow
## Agent Coordination
**Primary**: code-reviewer (change assessment, quality validation)
**Supporting**: test-engineer (test validation), security-auditor (security-sensitive changes)
## Branch-Aware Messages
Auto-includes issue references from branch:
```bash
# On feature/TASK-001
/commit "add user authentication"
# → feat(TASK-001): add user authentication
# On bugfix/BUG-003
/commit "fix login timeout"
# → fix(BUG-003): fix login timeout
# On develop (no issue)
/commit "refactor database connection"
# → refactor: refactor database connection
# Manual override
/commit "feat(TASK-001): add user auth"
# → Uses as-is: feat(TASK-001): add user auth
```
**Benefits**: Auto issue tracking, no need to remember IDs, links commits to tasks
## Examples
**Interactive**: `/commit` → Review → Generate message → Confirm
**Direct**: `/commit "add auth"` → Adds issue → Quality checks → Commit
**Selective**: `/commit --files "src/auth.js"` → Specific files with issue
**Amend**: `/commit --amend` → Safety checks → Amend
**Skip hooks**: `/commit "fix typo" --no-verify` → Fast commit
**Interactive staging**: `/commit --interactive` → Choose hunks → Commit

242
commands/complete.md Normal file
View File

@@ -0,0 +1,242 @@
---
tags: ["workflow", "completion", "task", "bug", "spike"]
description: "Complete any issue type per its workflow requirements"
argument-hint: "### | PROJ-###"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "TodoWrite", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/task-workflow.md # Task completion requirements
- docs/development/workflows/bug-workflow.md # Bug completion requirements
- docs/development/workflows/spike-workflow.md # Spike completion requirements
---
# /complete Command
**WHAT**: Complete any issue type by validating and executing its workflow's completion requirements.
**WHY**: Each issue type has different completion criteria. This command ensures all requirements are met before marking work as done.
**HOW**: Detect issue type, read its workflow's Completion section, validate/execute requirements, mark complete.
## Usage
```bash
/complete 001 # Detects type from file, runs completion workflow
/complete 002 # If BUG.md exists → bug completion
/complete 005 # If SPIKE.md exists → spike completion
/complete PROJ-123 # Jira issue completion
```
## Execution Flow
### 1. Detect Issue Type
Read issue file to determine type:
```bash
# In pm/issues/###-name/ directory:
if [ -f "TASK.md" ]; then type="task"
elif [ -f "BUG.md" ]; then type="bug"
elif [ -f "SPIKE.md" ]; then type="spike"
fi
```
### 2. Execute Type-Specific Completion
---
## Task Completion
**Reference:** task-workflow.md Completion section
### Validation Checklist
1. **All phases complete** - Every checkbox in PLAN.md checked
2. **Tests passing** - Run test suite, all green
3. **Code review ≥90** - Final phase achieved review threshold
4. **Acceptance criteria met** - All criteria in TASK.md satisfied
5. **WORKLOG updated** - Final entry documents completion
### Execution
```
Completing issue 001 (task)...
✓ PLAN.md: All phases checked (5/5)
✓ Tests: 47/47 passing
✓ Code review: 92/100 on final phase
✓ Acceptance criteria: 4/4 met
✓ WORKLOG: Final entry present
Task ready for merge. Update status? (yes/no)
```
If validation fails, report what's missing and suggest next steps.
### Final Actions
- Update TASK.md status to `done`
- Suggest: "Ready for PR. Run `/branch merge develop`"
---
## Bug Completion
**Reference:** bug-workflow.md Completion section
### Validation Checklist
1. **Reproduction test exists** - Test that fails without fix
2. **Fix implemented** - Code changes complete
3. **Reproduction test passes** - Fix resolves the issue
4. **No regressions** - All existing tests still pass
5. **Root cause documented** - WORKLOG explains why bug occurred
### Execution
```
Completing issue 002 (bug)...
✓ Reproduction test: tests/auth/login-safari.test.ts
✓ Fix implemented: src/auth/login.ts
✓ Reproduction test: PASSES with fix
✓ Regression tests: 156/156 passing
✓ Root cause: Documented in WORKLOG.md
Bug fix ready for merge. Update status? (yes/no)
```
### Final Actions
- Update BUG.md status to `done`
- Suggest: "Ready for PR. Run `/branch merge develop`"
---
## Spike Completion
**Reference:** spike-workflow.md Completion section
### Process
Unlike TASK/BUG, spike completion involves active work:
1. **Collect WORKLOGs from branches**
2. **Generate SPIKE-SUMMARY.md**
3. **Commit documentation to develop**
4. **Create follow-up actions**
5. **Clean up spike branches**
### Execution
```
Completing issue 005 (spike)...
Step 1: Collecting findings from spike branches...
→ Checking out WORKLOG-1.md from spike/005/plan-1
→ Checking out WORKLOG-2.md from spike/005/plan-2
Step 2: Generating SPIKE-SUMMARY.md...
[Draft summary presented for review]
Step 3: Review summary
Edit summary? (yes/no)
Step 4: Follow-up actions
Create ADR from findings? (yes/no)
Update related spec? (yes/no)
Create implementation tasks? (yes/no)
Step 5: Commit to develop
→ git add pm/issues/005-*/
→ git commit -m "docs: 005 spike findings - recommend REST"
Step 6: Cleanup
Delete spike branches? (yes/keep)
→ spike/005/plan-1
→ spike/005/plan-2
```
### Git Operations for Spike
```bash
# Ensure on develop branch
git checkout develop
# Pull WORKLOG files from spike branches
git checkout spike/005/plan-1 -- pm/issues/005-*/WORKLOG-1.md
git checkout spike/005/plan-2 -- pm/issues/005-*/WORKLOG-2.md
# Commit documentation
git add pm/issues/005-*/
git commit -m "docs: 005 spike findings - [recommendation]"
# Optional: delete spike branches
git branch -D spike/005/plan-1
git branch -D spike/005/plan-2
```
### SPIKE-SUMMARY.md Generation
Generate from WORKLOG files:
```markdown
# 005 Spike Summary: [Title]
## Executive Summary
**Recommendation: [Approach N]** - [One-line rationale]
## Questions Answered
### 1. [Question from SPIKE.md]
[Finding from WORKLOGs]
## Comparison
| Criteria | Approach 1 | Approach 2 | Winner |
|----------|------------|------------|--------|
| [metric] | [value] | [value] | [1/2] |
## Recommendation Rationale
[Why this approach was chosen]
## Next Steps
- [ ] Create ADR documenting decision
- [ ] Create task for implementing chosen approach
```
### Follow-up Actions
**Create ADR:**
- Run `/adr` with spike findings as evidence
- Reference spike issue in ADR context
**Update Spec:**
- Add Technical Approach section to related SPEC.md
- Reference spike findings
**Create Tasks:**
- Run `/issue` to create implementation task
- Link to spike for context
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Issue not found | Check `pm/issues/{ID}-*/` exists |
| Unknown type | Verify issue file exists (TASK.md/BUG.md/SPIKE.md) |
| Incomplete phases | List remaining phases, suggest `/implement {ID} --next` |
| Tests failing | Show failures, suggest fixing before completion |
| Spike branches missing | Check branch names, may need manual recovery |
## Integration
**Workflow position:**
```
/issue → /plan ### → /implement ### → /complete ### → /branch merge
```
**Related commands:**
- `/issue` - Create work items
- `/implement ###` - Execute plan phases
- `/branch merge` - Merge completed work to develop

145
commands/docs.md Normal file
View File

@@ -0,0 +1,145 @@
---
tags: ["documentation", "generation", "validation", "synchronization", "health"]
description: "Unified documentation management - generate, validate, sync, update, and analyze documentation"
argument-hint: "--sync | --validate | --health | --update | --generate TARGET | \"natural language\""
allowed-tools: ["Read", "Write", "Edit", "MultiEdit", "Bash", "Grep", "Glob", "TodoWrite", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/README.md # Documentation structure and organization
---
# /docs Command
**WHAT**: Unified documentation management - generate, validate, sync, update, and analyze documentation.
**WHY**: Maintain documentation accuracy, completeness, and freshness alongside code evolution.
**HOW**: Use flags for common operations, or natural language for specific requests.
## Usage
```bash
# Quick flags for common operations
/docs --sync # Sync docs with recent code changes
/docs --validate # Check links and references
/docs --health # Documentation coverage and quality metrics
/docs --update # Update stale information across all docs
/docs --generate "auth system" # Generate docs for specific target
# Natural language for specific requests
/docs "generate API documentation for the user service"
/docs "sync API docs with latest endpoint changes"
```
## Flags
| Flag | Purpose |
|------|---------|
| `--sync` | Analyze recent git changes, update affected documentation |
| `--validate` | Check all links, references, and code examples for accuracy |
| `--health` | Generate coverage metrics, quality scores, freshness report |
| `--update` | Review all docs, fix stale information and broken references |
| `--generate TARGET` | Generate documentation for specified target (module, API, feature) |
## Natural Language
For more specific requests, use natural language:
```bash
/docs "generate database schema documentation with ER diagrams"
/docs "validate only the API documentation"
/docs "sync docs with changes from the last 5 commits"
```
## How It Works
AI analyzes natural language and executes appropriate action:
**Generation**: Creates new documentation
- Analyzes codebase structure
- Generates appropriate format
- Follows project standards
- Creates comprehensive content
**Validation**: Checks quality and accuracy
- Validates internal/external links
- Checks code examples and references
- Verifies freshness
- Identifies outdated/missing content
**Synchronization**: Keeps docs aligned with code
- Analyzes recent code changes
- Updates affected documentation
- Maintains consistency
- Preserves structure
**Update**: Maintains accuracy
- Reviews documentation tree
- Updates stale information
- Fixes broken references
- Ensures current state reflected
**Health Analysis**: Provides metrics
- Coverage analysis
- Quality scoring
- Freshness metrics
- Completeness assessment
- Actionable recommendations
## Agent Coordination
**Primary**: technical-writer (documentation creation/maintenance)
**Supporting**: code-reviewer (accuracy validation)
**Domain**: Frontend/backend specialists (technical accuracy)
**Security**: security-auditor (validates security docs, threat models, auth flows)
## Output Locations
- **Project docs**: `docs/project/` - Architecture, decisions, features
- **Development docs**: `docs/development/` - Guidelines, standards, setup
## Examples
**Generation:**
```bash
/docs "generate complete API reference documentation"
/docs "create ADR for new caching layer"
/docs "generate database schema documentation with ER diagrams"
```
**Validation:**
```bash
/docs "validate all markdown links in docs/"
/docs "check for broken code examples"
/docs "verify all external references still valid"
```
**Synchronization:**
```bash
/docs "sync docs with code changes from last week"
/docs "update API docs after refactoring user service"
/docs "align architecture docs with current design"
```
**Update:**
```bash
/docs "update all outdated version numbers"
/docs "refresh technology stack documentation"
/docs "comprehensive documentation accuracy review"
```
**Health Analysis:**
```bash
/docs "analyze documentation coverage and quality"
/docs "identify documentation gaps and missing content"
/docs "create documentation metrics report"
```
## Quality Standards
- **Accuracy**: Reflects actual code behavior
- **Completeness**: All public APIs/features documented
- **Freshness**: Updated with code changes
- **Clarity**: Clear, concise, well-structured
- **Examples**: Code examples tested and accurate
- **Links**: All references valid and current

245
commands/implement.md Normal file
View File

@@ -0,0 +1,245 @@
---
tags: ["workflow", "development", "execution"]
description: "Execute specific implementation phases from task plans with test-first enforcement"
argument-hint: "### PHASE | ### --next | --next | ### --full | --full"
allowed-tools: ["Read", "Write", "Edit", "MultiEdit", "Bash", "Grep", "Glob", "TodoWrite", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/pm-workflows.md # Phase execution protocol
- docs/development/workflows/task-workflow.md # TDD phases, quality gates
- docs/development/workflows/bug-workflow.md # Reproduction-first phases
- docs/development/workflows/spike-workflow.md # Spike exploration with branches
- docs/development/workflows/worklog-format.md # WORKLOG entry formats
- docs/development/workflows/git-workflow.md # Branch creation and verification
- docs/development/workflows/agent-coordination.md # Agent handoff patterns
---
# /implement Command
**WHAT**: Execute implementation phases with test-first enforcement and agent coordination.
**HOW**: Detects issue type, follows its workflow, enforces quality gates.
## Usage
```bash
/implement 001 1.1 # Execute specific phase (detects type from file)
/implement 003 2.2 # Execute bug fix phase
/implement 005 # Spike: asks which plan, creates spike branch
/implement 001 --next # Auto-find next uncompleted phase
/implement --next # Auto-detect issue + next phase
/implement 001 --full # Execute all remaining phases
/implement PROJ-123 --next # Jira issue
```
## Issue Type Detection
**Reads issue file to determine type and workflow:**
```bash
# In pm/issues/###-name/ directory:
if [ -f "TASK.md" ]; then type="task" # TDD phases
elif [ -f "BUG.md" ]; then type="bug" # Reproduction-first
elif [ -f "SPIKE.md" ]; then type="spike" # Exploration plans
fi
```
| Issue File | Workflow | Branch Pattern |
|------------|----------|----------------|
| TASK.md | TDD (RED/GREEN/REFACTOR) | `feature/###` |
| BUG.md | Reproduction-first | `bugfix/###` |
| SPIKE.md | Exploration (per plan) | `spike/###/plan-N` |
## Execution Flow
### 1. Parse & Validate
- Parse issue ID and phase (or auto-detect)
- Locate issue directory: `pm/issues/{ID}-*/`
- Read issue file (TASK.md/BUG.md/SPIKE.md)
- Read PLAN.md (or PLAN-N.md for spikes)
- Create WORKLOG.md if missing (with Phase Commits header)
### 2. Type-Specific Handling
**For TASK/BUG:**
- Create feature/bugfix branch if needed
- Execute phase with TDD checkpoints
- Follow quality gates per workflow
**For SPIKE (see below):**
- Ask which plan to explore
- Create spike branch
- Execute without quality gates
### 3. Agent Coordination
Select agent based on phase domain:
- `frontend-specialist`, `backend-specialist`, `database-specialist`
- `test-engineer` for RED phases
- `code-reviewer` for REFACTOR phases
### 4. TDD Checkpoints (TASK/BUG)
- **RED**: Tests FAIL before implementation
- **GREEN**: Tests PASS after implementation
- **REFACTOR**: Review ≥90 to complete
### 5. Track Progress
- Write WORKLOG entry
- Update Phase Commits section
- Check off PLAN.md checkbox
- Commit changes
---
## SPIKE Implementation
**When issue type is SPIKE, behavior changes significantly.**
### Step 1: Select Plan
```
Which plan do you want to explore?
Available plans:
1. PLAN-1.md: GraphQL with Apollo Server
2. PLAN-2.md: REST with Express
Enter plan number: _
```
### Step 2: Create Spike Branch
```bash
# From current branch (usually develop)
git checkout -b spike/005/plan-1
```
### Step 3: Execute Exploration
**Differences from TASK/BUG:**
| Aspect | TASK/BUG | SPIKE |
|--------|----------|-------|
| TDD checkpoints | Required | Not enforced |
| Code review | Required (≥90) | Not required |
| Commits | To feature branch | To spike branch |
| WORKLOG | WORKLOG.md | WORKLOG-N.md |
| Branch merge | Yes (to develop) | Never |
### Step 4: Track Findings
- Update WORKLOG-N.md on spike branch
- Document discoveries, surprises, benchmarks
- Track time spent vs time box
### Example SPIKE Flow
```
User: /implement 005
AI: Issue 005 (spike): "GraphQL vs REST for our API?"
Which plan do you want to explore?
1. PLAN-1.md: GraphQL with Apollo Server
2. PLAN-2.md: REST with Express
User: 1
AI: Creating branch spike/005/plan-1...
> ⚠️ SPIKE EXPLORATION
> Code will be committed to spike branch, not merged to main.
> Track discoveries in WORKLOG-1.md.
Executing PLAN-1.md Phase 1: Setup
→ Installing Apollo Server...
→ Creating basic schema...
→ Updating WORKLOG-1.md
✓ Phase 1 complete (1.5 hours spent, 6.5 remaining)
Continue to Phase 2? (yes/no/stop)
```
---
## Task-Specific Scripts
**Temporary scripts go in task directory:**
```
pm/issues/001-user-auth/
├── TASK.md
├── PLAN.md
├── WORKLOG.md
└── scripts/
├── generate-test-users.sh
├── migrate-passwords.js
└── debug-jwt-validation.js
```
**Why:** Easy cleanup, clear context, no root clutter.
**Root `scripts/`:** Only for universal utilities used across tasks.
---
## Modes
| Mode | Command | Behavior |
|------|---------|----------|
| Specific | `/implement 001 1.1` | Execute single phase |
| Next | `/implement 001 --next` | Find first uncompleted |
| Full | `/implement 001 --full` | Execute all remaining |
| Auto | `/implement --next` | Auto-detect issue + next |
---
## Example (TASK)
```
User: /implement 001 --next
AI: Next: 1.RED - Write failing tests for user login
Proceed? (yes/no)
User: yes
AI: Spawning test-engineer...
→ Tests written (8 test cases)
→ Running tests...
→ [RED CHECKPOINT] 8 tests FAILED ✓
✓ Phase 1.RED complete
Next: /implement 001 --next
```
---
## Error Handling
| Error | Resolution |
|-------|------------|
| Issue not found | Check `pm/issues/{ID}-*/` exists |
| PLAN.md missing | Run `/plan {ID}` first |
| Unknown type | Verify TASK.md/BUG.md/SPIKE.md exists |
| Spike no plans | Run `/plan ###` to create plans |
| Phase complete | Use `--next` for next phase |
## Integration
```
/issue → /plan ### → /implement ### → /complete ### → /branch merge
```
**SPIKE flow:**
```
/issue → /plan ### → /implement ### → /complete ###
↓
(creates spike branch)
↓
(never merges to develop)
```

223
commands/issue.md Normal file
View File

@@ -0,0 +1,223 @@
---
tags: ["workflow", "issue", "task", "bug", "spike", "conversational"]
description: "Create standalone work items (TASK, BUG, or SPIKE) with AI-assisted type detection"
argument-hint: "[\"description\"]"
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "TodoWrite"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/task-workflow.md # Task implementation workflow
- docs/development/workflows/bug-workflow.md # Bug fix workflow
- docs/development/workflows/spike-workflow.md # Spike exploration workflow
- docs/development/workflows/pm-workflows.md # PM artifact hierarchy
---
# /issue Command
**WHAT**: Create standalone work items (TASK, BUG, or SPIKE) through natural conversation.
**WHY**: Single entry point for all standalone work items with AI-assisted type detection and optional spec linkage.
**HOW**: Describe what you need, AI detects type, confirms with you, optionally links to spec, creates issue directory and skeleton file.
## Usage
```bash
/issue # Start conversation
/issue "Login crashes on Safari" # AI detects: BUG
/issue "Add CSV export feature" # AI detects: TASK
/issue "GraphQL vs REST?" # AI detects: SPIKE
```
## ID Format
**All issues use numeric IDs.** Type is determined by which file exists in the directory:
```
pm/issues/001-feature-name/TASK.md → Task (type from file)
pm/issues/002-bug-name/BUG.md → Bug (type from file)
pm/issues/003-spike-name/SPIKE.md → Spike (type from file)
pm/issues/PROJ-123-name/TASK.md → External (Jira) task
```
This unified scheme:
- Single counter for all local issues
- External IDs (PROJ-123) work seamlessly
- Type always determined from file, not ID prefix
## Type Detection
AI detects issue type from description keywords:
| Type | Keywords | Purpose |
|------|----------|---------|
| **BUG** | fix, broken, crash, error, regression, doesn't work, fails | Something is broken |
| **SPIKE** | should we, which, can we, explore, vs, compare, evaluate, feasibility | Technical exploration |
| **TASK** | add, implement, create, build, enhance (default) | New feature or enhancement |
User can always override the detected type.
## Execution Flow
### 1. Gather Description
If no description provided, ask:
> "What do you need to do? Describe the work item."
### 2. Detect Type
Analyze description for keywords:
- BUG indicators: "fix", "broken", "crash", "error", "regression", "fails", "doesn't work"
- SPIKE indicators: "should we", "which", "can we", "explore", "vs", "compare", "feasibility"
- TASK: default if no BUG/SPIKE indicators
Present detection:
> "This sounds like a **BUG**. Create as issue 001? (yes / task / spike)"
### 3. Determine Next Issue Number
```bash
# Count ALL existing issues (single counter)
ls pm/issues/ | grep -E '^[0-9]{3}-' | sort -n | tail -1
# Extract number, increment for next ID
# Format: 001, 002, 003, ...
```
### 4. Ask About Spec Linkage
> "Link to an existing spec? (no / SPEC-001 / SPEC-002 / ...)"
If specs exist, list them. If user selects one, add `spec: SPEC-###` to frontmatter.
### 5. Conversational Details
Based on type, gather required information using the appropriate template:
**For TASK** (templates/task-template.md):
- Description (already have from initial input)
- Acceptance criteria
- Technical notes (optional)
**For BUG** (templates/bug-template.md):
- Description (already have)
- Steps to reproduce
- Expected vs actual behavior
- Severity (critical/high/medium/low)
**For SPIKE** (templates/spike-template.md):
- Questions to answer
- Time box (max hours)
- Deadline (optional)
- Number of approaches to explore
### 6. Create Issue
Create directory and file:
```
pm/issues/###-{slug}/
└── {TYPE}.md # TASK.md, BUG.md, or SPIKE.md (determines type)
```
**ID format**: 3-digit zero-padded number (001, 002, ...)
**Slug**: kebab-case from description (max 50 chars)
### 7. Next Steps
**For TASK/BUG:**
> "Created issue 001 (task). Next: `/plan 001` to create implementation plan."
**For SPIKE:**
> "Created issue 001 (spike). Next: `/plan 001` to create exploration plans."
If linked to spec, also update SPEC.md Tasks section.
## Example
```
User: /issue "Login page crashes when clicking submit on Safari mobile"
AI: This sounds like a **BUG** - a crash that needs fixing.
Create as issue 001? (yes / task / spike)
User: yes
AI: Link to an existing spec?
- SPEC-001: User Authentication
- SPEC-002: Mobile Experience
- no (standalone)
User: SPEC-001
AI: Let me gather a few more details for the bug report.
Steps to reproduce?
User: 1. Open login page on Safari iOS
2. Enter valid credentials
3. Click Submit button
4. Page crashes
AI: Expected vs actual behavior?
User: Expected: Login succeeds. Actual: White screen crash.
AI: Severity? (critical / high / medium / low)
User: high
AI: Created issue 001 (bug): Login Safari Crash
📁 pm/issues/001-login-safari-crash/BUG.md
🔗 Linked to SPEC-001: User Authentication
Next: /plan 001
```
## File Structure
```
pm/issues/
├── 001-csv-export/
│ └── TASK.md # Type = task (from file)
├── 002-login-safari-crash/
│ └── BUG.md # Type = bug (from file)
├── 003-graphql-vs-rest/
│ └── SPIKE.md # Type = spike (from file)
└── PROJ-123-oauth/
└── TASK.md # External Jira task
```
## Type Detection from Files
Commands detect issue type by which file exists:
```bash
# In pm/issues/###-name/ directory:
if [ -f "TASK.md" ]; then type="task"
elif [ -f "BUG.md" ]; then type="bug"
elif [ -f "SPIKE.md" ]; then type="spike"
fi
```
This enables:
- Numeric IDs for all local issues
- External IDs (PROJ-123) work without modification
- Type always authoritative from file content
## Integration
**Workflow position:**
```
/issue → /plan {ID} → /implement {ID} → /complete {ID}
```
**Spec linkage:**
- Standalone issues work without a spec
- Linked issues appear in SPEC.md Tasks section
- `spec: SPEC-###` in issue frontmatter enables traceability
**Related commands:**
- `/spec` - Create feature specs with multiple tasks (top-down)
- `/plan` - Create implementation plan for any issue type
- `/implement` - Execute plan phases
- `/complete` - Complete issue per workflow requirements

189
commands/jira-comment.md Normal file
View File

@@ -0,0 +1,189 @@
---
tags: ["jira", "integration", "collaboration", "workflow"]
description: "Add AI-suggested comments to external Jira issues based on work context"
argument-hint: "PROJ-###"
allowed-tools: ["Read", "Write", "Bash", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/misc/jira-integration.md # Jira integration patterns
- docs/development/workflows/worklog-format.md # WORKLOG format for context gathering
---
# /jira-comment Command
## WHAT
Add AI-suggested comments to external Jira issues by analyzing local work context (WORKLOG, commits, existing comments).
## WHY
Keeps stakeholders informed with professional progress updates synthesized from actual work, without manual comment composition.
**Scope:** External issues only (PROJ-###). Use `/worklog` for local issues (TASK-###, BUG-###).
## HOW
### Usage
```bash
/jira-comment PROJ-123 # AI suggests comment based on context
/jira-comment PROJ-123 "text" # Add specific comment text
```
### Pre-Execution Context
**Validate prerequisites:**
- CLAUDE.md: `jira.enabled: true`
- Atlassian Remote MCP: Available
- Issue ID: External format (PROJ-###, not TASK-###)
- Jira access: Issue exists and accessible
**Gather context (interactive mode only):**
- WORKLOG: `pm/issues/PROJ-123-*/WORKLOG.md` (last 5-10 entries)
- Git commits: Last 10 mentioning issue ID
- Jira comments: Existing comments (avoid duplication)
### Execution Steps
**1. Validate:**
```bash
# Read CLAUDE.md jira config
# Check issue ID format (must be PROJ-###)
# Verify Atlassian MCP available
# Confirm issue exists in Jira
```
**2. Interactive mode (no text provided):**
```bash
# Find issue directory
glob pm/issues/PROJ-###-*/
# Read WORKLOG
# Get recent commits: git log -10 --grep="PROJ-###"
# Fetch Jira comments (optional, for context)
# AI synthesizes comment:
# Format:
# [Summary sentence]
#
# Work completed:
# - [Accomplishment 1]
# - [Accomplishment 2]
#
# Files changed:
# - path/to/file (new/modified)
#
# Next steps:
# - [Action 1]
# - [Action 2]
# Show preview
# Ask: "Post this comment? (yes/edit/cancel)"
```
**3. Direct mode (text provided):**
```bash
# Show preview of provided text
# Ask: "Post to Jira? (yes/cancel)"
```
**4. Handle user approval:**
- `yes`: Post comment via Atlassian MCP
- `edit`: Allow modification, then confirm
- `cancel`: Exit without posting
**5. Post to Jira:**
```bash
# Use Atlassian MCP to add comment
# Get confirmation and URL
# Optionally log to WORKLOG: "Posted update to Jira"
# Display: "✓ Comment posted to PROJ-###"
```
### Comment Format Guidelines
**Template:**
```
[Summary sentence]
Work completed:
- [Accomplishment 1]
- [Accomplishment 2]
Files changed:
- path/to/file (new/modified)
Next steps:
- [Action 1]
```
**Characteristics:**
- Concise: 5-10 lines total
- Actionable: Focus on stakeholder needs
- Specific: Include file paths, metrics
- Forward-looking: Always suggest next steps
- Professional: Assumes PM/stakeholder audience
### Error Handling
**Local issue provided:**
```
Error: TASK-001 is a local issue.
Use /comment for local issues.
/jira-comment only works with PROJ-###.
```
**Jira not enabled:**
```
Error: Jira integration not enabled.
Add to CLAUDE.md:
jira.enabled: true
jira.project_key: PROJ
Configure Atlassian Remote MCP.
```
**MCP unavailable:**
```
Error: Atlassian Remote MCP not configured.
Setup guide: https://www.atlassian.com/blog/announcements/remote-mcp-server
```
**No context found:**
```
Warning: No local work context for PROJ-456.
- No WORKLOG entries
- No git commits mentioning issue
Use direct mode: /jira-comment PROJ-456 "text"
Or start working: /plan PROJ-456
```
**Permission denied:**
```
Error: Failed to add comment (403 Forbidden).
Possible: No permission, issue locked, credentials expired.
Check: {jira_url}
```
**Issue not found:**
```
Error: PROJ-456 not found in Jira.
Possible: Doesn't exist, no permission, wrong project key.
```
### Integration
**Workflow position:**
```
/implement PROJ-456 1.2 → /jira-comment PROJ-456 → /implement PROJ-456 1.3
```
**When to use:**
- After significant work
- End of day updates
- When blocked
- Stakeholder requests
- Not for every commit (too frequent)
### Related
- `/worklog` - Local WORKLOG entry (not Jira)
- `/import-issue` - Import Jira issue to local
- `/plan PROJ-###` - Create implementation plan
- `/implement PROJ-### 1.1` - Execute work

141
commands/jira-epic.md Normal file
View File

@@ -0,0 +1,141 @@
---
tags: ["workflow", "epic", "jira", "project-management", "conversational"]
description: "Create Jira epics through natural language conversation (requires Jira integration)"
argument-hint: "[PROJ-### | --spec SPEC-###]"
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Task", "TodoWrite"]
model: claude-opus-4-5
references_guidelines:
- docs/development/misc/jira-integration.md # Jira setup, field discovery, epic creation workflow
- docs/development/workflows/pm-workflows.md # Core PM workflows and epic structure
---
# /jira-epic Command
**WHAT**: Create/refine Jira epics through conversational interaction.
**WHY**: Natural conversation for creating PM tracking containers in Jira. Epics organize work at the PM tool level.
**HOW**: See jira-integration.md for Jira integration patterns, field discovery, and epic creation workflow.
**REQUIRES**: Jira integration enabled in CLAUDE.md (see jira-integration.md for setup)
## Usage
```bash
/jira-epic # Create new Jira epic
/jira-epic PROJ-### # Refine existing Jira epic
/jira-epic --spec SPEC-### # Create Jira epic from local spec
```
## Execution Flow
**Before you start**: Read jira-integration.md for Jira requirements, field discovery, and conversational creation patterns.
### High-Level Steps
1. **Verify Jira Integration**
- Check CLAUDE.md jira.enabled = true
- If disabled: Error with setup instructions
2. **Load Context**
- If --spec: Read local spec for pre-population
- If PROJ-###: Fetch existing epic from Jira
- Load field requirements from cache
3. **Conversational Creation/Refinement**
- Ask for required fields (summary, description, epic name)
- Discover custom fields per jira-integration.md
- Create/update via Atlassian MCP
4. **Optional Issue Suggestions**
- Suggest initial issues based on epic scope
- Interactive: Create selected issues
- Per jira-integration.md task suggestion strategy
5. **Optional Spec Creation**
- Offer to create local spec from epic
- Run /spec --jira-epic PROJ-### if accepted
**See jira-integration.md "Epic Creation Workflow" for complete conversational flow details.**
## Local vs Jira
**Local Specs** (`/spec`): Document WHAT to build, version controlled
**Jira Epics** (this command): PM tracking container, network required
See jira-integration.md for semantic mapping and workflow patterns.
## Example
```
User: /jira-epic --spec SPEC-001
AI: Creating Jira epic from SPEC-001: User Authentication
✓ Loaded spec content for pre-population
Summary: User Authentication
Epic Name: user-authentication
Customize? (yes/no)
User: no
AI: ✓ Created PROJ-100: User Authentication
🔗 https://company.atlassian.net/browse/PROJ-100
Add initial issues? (yes/no)
User: yes
AI: Suggested:
1. User Registration (Story)
2. Login Flow (Story)
3. Database Schema (Task)
Create which? (1,2,3/all/none)
User: all
AI: ✓ PROJ-101: User Registration
✓ PROJ-102: Login Flow
✓ PROJ-103: Database Schema
Next: /jira-import PROJ-101
```
## Workflow Patterns
**Spec-first** (recommended):
```
/spec → /jira-epic --spec SPEC-### → /jira-import PROJ-###
```
**Epic-first**:
```
/jira-epic → /spec --jira-epic PROJ-### → /jira-import PROJ-###
```
**Epic-only** (no local spec):
```
/jira-epic → /jira-import PROJ-###
```
## Agent Coordination
**Primary**: project-manager (conversation, Jira interaction)
**Supporting**: Domain specialists (field suggestions), test-engineer (acceptance criteria)
## Error Handling
- **Jira not enabled**: Show setup instructions from jira-integration.md
- **MCP unavailable**: Check Atlassian MCP configuration
- **Spec not found**: Verify path and spec number
- **Field discovery fails**: Run /refresh-schema
See jira-integration.md for complete error scenarios and solutions.
## Integration
**Creates**: Jira epic (PROJ-###)
**Next step**: `/jira-import PROJ-###` or `/spec --jira-epic PROJ-###`
See jira-integration.md for complete workflow integration.

168
commands/jira-import.md Normal file
View File

@@ -0,0 +1,168 @@
---
tags: ["jira", "integration", "import", "workflow"]
description: "Import Jira issue for local work with PLAN.md creation"
argument-hint: "PROJ-###"
allowed-tools: ["Read", "Write", "Bash", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/misc/jira-integration.md # Jira integration and import workflow
- docs/development/workflows/pm-workflows.md # Core PM workflows and file formats
---
# /jira-import Command
## WHAT
Import Jira issue into local structure, creating directory for implementation artifacts and displaying requirements.
## WHY
Enables AI-assisted implementation of PM/stakeholder-created issues with local artifact management.
**Note:** Not required - `/plan PROJ-123` auto-imports. Use this to preview before planning or verify access.
## HOW
### Usage
```bash
/jira-import PROJ-123 # Import specific Jira issue (or epic with bulk import)
```
### Pre-Execution Context
**Validate prerequisites:**
- CLAUDE.md: `jira.enabled: true`
- Atlassian Remote MCP: Available
- Issue ID: Valid format (PROJ-###)
- Jira access: Issue exists and accessible
### Execution Steps
**1. Fetch from Jira:**
```bash
# Use Atlassian MCP to get issue
# Fields: key, summary, description, type, status, epic_link, reporter, assignee
# If type = Epic: Fetch all child issues in epic
```
**2. Create local directory:**
```bash
# Convert summary to kebab-case
# If regular issue (Story/Task/Bug):
# mkdir pm/issues/PROJ-123-{kebab-case-summary}/
# If Epic:
# mkdir pm/epics/PROJ-123-{kebab-case-name}/
# No TASK.md created (Jira is source of truth)
```
**3. Display issue details:**
```
Issue: PROJ-123
Summary: {summary}
Type: {type}
Status: {status}
Epic: {epic_link} (if present)
Description:
{description}
Acceptance Criteria:
{parsed from description or custom field}
Local: pm/issues/PROJ-123-{name}/
Next: /plan PROJ-123
View: {jira_url}
```
**4. Bulk import (Epics only):**
```bash
# If issue type is Epic:
# Show child issues (key, summary, type, status)
# Ask: "Import all N child issues? (yes/no)"
# If yes:
# For each child:
# - Check if already imported (directory exists)
# - Fetch and create directory if new
# - Display progress
# Show summary (new, skipped, total)
```
**5. Ready for work:**
- `/plan PROJ-123` - Create implementation plan
- `/implement PROJ-123 1.1` - Start work
### Directory Structure
**Regular issues:**
```
pm/issues/PROJ-456-api-rate-limiting/
└── (empty - ready for PLAN.md, WORKLOG.md, RESEARCH.md)
```
**Epics:**
```
pm/epics/PROJ-400-api-infrastructure/
└── (empty - epic metadata, Jira is source)
```
**Naming:** kebab-case, strip special chars, max 50 chars
### Error Handling
**Issue not found:**
```
Error: PROJ-456 not found in Jira.
Possible: Doesn't exist, no permission, wrong project key.
Check: {jira_url}
```
**Jira not enabled:**
```
Error: Jira integration not enabled.
Add to CLAUDE.md:
jira.enabled: true
jira.project_key: PROJ
Configure Atlassian Remote MCP.
Or work locally: /plan TASK-001
```
**MCP unavailable:**
```
Error: Atlassian Remote MCP not configured.
Setup guide: https://www.atlassian.com/blog/announcements/remote-mcp-server
```
**Directory exists:**
```
Warning: pm/issues/PROJ-456-{name}/ already exists.
Previously imported. Contents: PLAN.md, WORKLOG.md
Issue details (refreshed from Jira): {details}
Continue: /plan PROJ-456 or /implement PROJ-456 1.1
```
### Integration
**Workflow position:**
```
Jira (PM creates) → /jira-import PROJ-456 → /plan PROJ-456 → /implement
```
**Alternative (auto-import):**
```
Jira (PM creates) → /plan PROJ-456 (auto-imports) → /implement
```
**Use /jira-import when:**
- Preview before planning
- Verify access/existence
- See acceptance criteria upfront
- Import epic with bulk child import
**Skip when:**
- Ready to plan: `/plan PROJ-456` auto-imports
- Trust issue exists
### Related
- `/plan PROJ-123` - Create plan (auto-imports)
- `/implement PROJ-123 1.1` - Execute phase
- `/project-status` - View all imported issues
- `/promote TASK-001` - Convert local to Jira

76
commands/jira-promote.md Normal file
View File

@@ -0,0 +1,76 @@
---
tags: ["jira", "integration", "promote", "workflow"]
description: "Promote local exploration issue to Jira for team visibility"
argument-hint: "TASK-### | BUG-###"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/misc/jira-integration.md # Jira integration and promotion workflow
- docs/development/workflows/pm-workflows.md # Core PM workflows and file formats
---
# /jira-promote Command
**WHAT**: Promote local exploration issue to Jira for team collaboration.
**WHY**: Convert validated prototypes to production-tracked work.
**HOW**: Migrate TASK-###/BUG-### to Jira, preserve all artifacts, update branch.
## Usage
```bash
/jira-promote TASK-001 # Promote local task to Jira
/jira-promote BUG-003 # Promote local bug to Jira
```
## Execution Flow
**Before you start**: Read jira-integration.md for Jira integration patterns, field discovery, and promotion workflow.
### High-Level Steps
1. **Validate Prerequisites**
- Check Jira enabled in CLAUDE.md
- Verify Atlassian MCP accessible
- Confirm local issue exists (TASK.md or BUG.md)
2. **Load Local Artifacts**
- Read TASK.md/BUG.md, PLAN.md, WORKLOG.md, RESEARCH.md
- Extract summary, description, acceptance criteria
3. **Field Discovery & Collection**
- Load field cache (.ai-toolkit/jira-field-cache.json)
- Map local → Jira (summary, description, issue type)
- Prompt for custom fields conversationally
4. **Create Jira Issue**
- Use Atlassian MCP to create issue
- Get PROJ-### issue key and URL
- Display Jira link
5. **Migrate Artifacts**
- Create pm/issues/PROJ-###-{name}/
- Copy PLAN.md, WORKLOG.md, RESEARCH.md, resources/
- Add promotion note to WORKLOG
6. **Cleanup & Branch Update**
- Ask: Delete original directory?
- If yes: Remove pm/issues/TASK-###-*/
- Rename branch: feature/TASK-### → feature/PROJ-###
**See jira-integration.md "Promotion Workflow" for complete artifact migration and field mapping details.**
## When to Promote
**Promote when**: Prototype validated, ready for production, needs team collaboration
**Don't promote when**: Still exploring, throwaway spike, personal learning, already complete
## Error Handling
**Jira not enabled**: Enable in CLAUDE.md with `jira.enabled: true`
**Issue not found**: Verify local issue exists in pm/issues/
**Field discovery fails**: Field cache will auto-refresh on failure
**MCP unavailable**: Install and configure Atlassian MCP server
See jira-integration.md for complete error scenarios and solutions.

192
commands/plan.md Normal file
View File

@@ -0,0 +1,192 @@
---
tags: ["workflow", "planning", "implementation"]
description: "Create PLAN.md file with phase-based breakdown for tasks, bugs, and spikes"
argument-hint: "### | PROJ-###"
allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob", "TodoWrite", "Task", "mcp__plugin_ai-toolkit_sequential-thinking__sequentialthinking", "mcp__plugin_ai-toolkit_context7__resolve-library-id", "mcp__plugin_ai-toolkit_context7__get-library-docs", "WebSearch", "WebFetch"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/pm-workflows.md # Plan methodology, phase structure, complexity scoring
- docs/development/workflows/task-workflow.md # Task TDD phases
- docs/development/workflows/bug-workflow.md # Bug reproduction-first phases
- docs/development/workflows/spike-workflow.md # Spike exploration planning
- docs/development/templates/plan-template.md # Plan file structure
---
# /plan Command
**WHAT**: Create PLAN.md with phase-based breakdown through analysis and research.
**HOW**: Detects issue type from file (TASK.md/BUG.md/SPIKE.md) and generates appropriate plan structure.
## Usage
```bash
/plan 001 # Detects type from file, creates appropriate PLAN.md
/plan 003 # If SPIKE.md exists → creates PLAN-1.md, PLAN-2.md
/plan PROJ-123 # Jira: Fetches issue, creates PLAN.md locally
```
## Issue Type Detection
**Reads issue file to determine type (not ID prefix):**
```bash
# In pm/issues/###-name/ directory:
if [ -f "TASK.md" ]; then type="task" # TDD phases
elif [ -f "BUG.md" ]; then type="bug" # Reproduction-first
elif [ -f "SPIKE.md" ]; then type="spike" # Exploration plans
fi
```
| Issue Type | Plan Structure | File Created |
|------------|---------------|--------------|
| Task (TASK.md) | TDD phases (RED/GREEN/REFACTOR) | PLAN.md |
| Bug (BUG.md) | Reproduction-first phases | PLAN.md |
| Spike (SPIKE.md) | Exploration phases per approach | PLAN-1.md, PLAN-2.md, ... |
## Process
### For Task/Bug
1. **Load**: Read TASK.md/BUG.md, parent SPEC (if exists), similar WORKLOGs
2. **Analyze**: Sequential thinking, research via Context7/web search
3. **Generate**: Phase breakdown per workflow guidelines
- **Task**: TDD phases (X.RED/X.GREEN/X.REFACTOR) per task-workflow.md
- **Bug**: Reproduction → Fix → Harden phases per bug-workflow.md
4. **Review**: code-architect (always), security-auditor (if security-relevant)
5. **Present**: Phases, scenario coverage, complexity score, research summary
### For Spike (Exploration)
1. **Load**: Read SPIKE.md (questions, success criteria)
2. **Ask**: "How many approaches do you want to explore?" → N
3. **Gather**: For each approach:
- "Describe approach N?" → User describes
- "What aspects to evaluate?" → Performance, complexity, etc.
4. **Generate**: Create PLAN-N.md for each approach
- Exploration phases (not TDD)
- Focus on answering questions
- Include spike reminder banner and branch reference
5. **Present**: Summary of all exploration plans
## Task Plan Example
```markdown
# Implementation Plan: 001 User Login Flow
## Phase 1 - User can log in
### 1.RED - Write Failing Tests
- [ ] 1.1 Write login tests (valid credentials, invalid, locked account)
- [ ] 1.2 [CHECKPOINT] Tests FAIL
### 1.GREEN - Implement
- [ ] 1.3 Implement login endpoint
- [ ] 1.4 [CHECKPOINT] Tests PASS
### 1.REFACTOR - Clean Up
- [ ] 1.5 Refactor, review >= 90
- [ ] 1.6 Commit phase
## Scenario Coverage
✓ SPEC-001 Scenario 1: "User logs in" → Phase 1
Complexity: 8 points (Medium)
```
## Bug Plan Example
```markdown
# Implementation Plan: 002 Login Safari Crash
## Phase 1 - Reproduce Failure
### 1.RED - Write Reproduction Test
- [ ] 1.1 Create Safari-specific test
- [ ] 1.2 [CHECKPOINT] Test FAILS (proves bug exists)
## Phase 2 - Implement Fix
### 2.GREEN - Fix the Bug
- [ ] 2.1 Investigate root cause
- [ ] 2.2 Implement fix
- [ ] 2.3 [CHECKPOINT] Reproduction test PASSES
- [ ] 2.4 [CHECKPOINT] No regressions
### 2.REFACTOR - Clean Up
- [ ] 2.5 Refactor, review >= 90
- [ ] 2.6 Commit fix
```
## Spike Plan Example
Creates multiple files with branch references:
**PLAN-1.md:**
```markdown
# 003 Exploration Plan 1: GraphQL
> **⚠️ SPIKE EXPLORATION**
> Code will be committed to spike branch, not merged to main.
> Track discoveries in WORKLOG-1.md.
> Branch: spike/003/plan-1
## Exploration Goal
Evaluate GraphQL for our API needs.
## Phase 1: Setup (1 hour)
- [ ] Install dependencies
- [ ] Create basic schema
## Phase 2: Performance Testing (2 hours)
- [ ] Run benchmarks
- [ ] Document in WORKLOG-1.md
```
## Spike Interaction Example
```
User: /plan 003
AI: Issue 003 (spike): "GraphQL vs REST for our API?"
How many approaches do you want to explore?
User: 2
AI: Describe approach 1:
User: GraphQL with Apollo Server - evaluate schema design,
query flexibility, and caching
AI: Describe approach 2:
User: REST with Express - compare setup simplicity,
HTTP caching, and team familiarity
AI: Creating exploration plans...
✓ PLAN-1.md: GraphQL with Apollo Server
Branch: spike/003/plan-1
- Phase 1: Setup (1h)
- Phase 2: Query implementation (2h)
- Phase 3: Performance testing (1h)
✓ PLAN-2.md: REST with Express
Branch: spike/003/plan-2
- Phase 1: Setup (30min)
- Phase 2: Endpoint implementation (2h)
- Phase 3: Performance testing (1h)
Next: /implement 003 (will ask which plan)
```
## Integration
```
/issue → /plan {ID} → /implement {ID} → /complete {ID}
```
**Creates:**
- Task/Bug: `pm/issues/###-*/PLAN.md`
- Spike: `pm/issues/###-*/PLAN-1.md`, `PLAN-2.md`, etc.

153
commands/project-brief.md Normal file
View File

@@ -0,0 +1,153 @@
---
tags: ["workflow", "strategy", "project-brief", "vision", "planning", "collaboration"]
description: "Fill and improve project brief through gap-driven conversation"
argument-hint: "[--review] [--force]"
allowed-tools: ["Read", "Write", "Edit", "Task", "TodoWrite"]
model: claude-opus-4-5
references_guidelines:
- docs/development/templates/project-brief-template.md # Template structure
---
# /project-brief Command
## WHAT
Fill in and improve project brief through natural, gap-driven conversation - one section at a time, focusing on product vision.
## WHY
Establishes clear product vision and strategy as foundation for feature planning, using conversational approach instead of upfront interrogation.
## HOW
### Usage
```bash
/project-brief # Gap-driven conversation to fill missing sections
/project-brief --review # Analyze brief, suggest improvements (no edits)
/project-brief --force # Start from scratch (recreate brief)
```
### Pre-Execution Context
**Read existing brief:**
- Project brief lives at: `docs/project-brief.md`
- Template structure at: `docs/development/templates/project-brief-template.md`
- 6 sections: Overview, Problem, Solution, Target Audience, Key Features, Success Metrics
- Analyze completeness: empty (<10 chars), weak (<50 chars), needs_detail (vague), complete
- Identify gaps to fill
**Modes:**
- Default: Fill gaps conversationally
- `--review`: Analysis only, no edits
- `--force`: Recreate from scratch
### Execution Steps
**1. File check and creation:**
```bash
# Check if docs/project-brief.md exists
if not exists "docs/project-brief.md":
# Create from template
cp docs/development/templates/project-brief-template.md docs/project-brief.md
# Inform user: "Created docs/project-brief.md from template"
```
**2. Gap analysis:**
```bash
# Parse sections
# Categorize each: empty, weak, needs_detail, complete
# Section order: Problem → Solution → Target Audience → Key Features → Success Metrics
# Show status summary
```
**3. Invoke brief-strategist agent:**
```
Task: "Complete project brief through gap-driven conversation.
1. Read project brief at docs/project-brief.md
- Reference template structure from docs/development/templates/project-brief-template.md if needed
2. For each incomplete section (in order):
- Ask open question about topic
- Listen, ask clarifying question
- Generate section content from answers
- Show proposed content
- Get confirmation (yes/edit/skip)
- Update docs/project-brief.md if approved
- Ask: Continue to next? (yes/no)
3. Provide progress summary
Be conversational, not formal. User controls pace."
```
**4. Conversational flow per section:**
```
{Section Name}
[Primary question based on section]
> [User answer]
[Clarifying question based on answer]
> [User answer]
Generated content:
---
{AI-generated section content}
---
Does this capture it? (yes/edit/skip)
> [User choice]
# If yes: Update file, move to next
# If edit: Refine content, confirm again
# If skip: Leave as-is, move to next
Continue to {next_section}? (yes/no)
```
**5. Progress tracking:**
- Use TodoWrite for section completion
- Allow stop/resume anytime
- Respect user pace
### Review Mode
**When `--review` flag:**
```bash
# Read brief
# Analyze each section: strengths, weaknesses
# Provide suggestions (specific, actionable)
# No edits made
# Suggest: "Run /project-brief to fill gaps"
```
### Agent Coordination
**Primary agent:** brief-strategist
- Gap-driven conversation
- Section content generation
- User-paced Q&A
- Natural dialogue (not interrogation)
**Living document:** Can stop/resume anytime
### Error Handling
**Brief doesn't exist:**
```
Error: No project brief found.
Run /toolkit-init first to create initial structure.
```
**Force mode confirmation:**
```
Warning: This will recreate brief from scratch.
Existing content will be lost.
Continue? (yes/no)
```
### Integration
**Workflow position:**
```
/toolkit-init → /project-brief → /jira-epic → /plan
```
**Purpose:** Foundation for feature planning, no tech stack (product vision only)

158
commands/project-status.md Normal file
View File

@@ -0,0 +1,158 @@
---
tags: ["workflow", "project-status", "analysis", "context", "dashboard"]
description: "Enhanced project status dashboard with intelligent context analysis"
argument-hint: "[--ai-format] [--detailed]"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "TodoWrite", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- pm/README.md
---
# /project-status Command
## WHAT
Enhanced project status dashboard with intelligent analysis - git state, project health, workflow progress, environment consistency, and Jira integration.
## WHY
Provides comprehensive project context through intelligent agent analysis, enabling informed decisions and workflow continuity.
## HOW
### Usage
```bash
/project-status # Standard human-readable report
/project-status --ai-format # AI-optimized format
/project-status --detailed # Comprehensive analysis
```
### Pre-Execution Context
**Gather project state:**
- Git: Branch, status, recent commits, remotes
- PM structure: Parse `pm/epics/`, `pm/issues/` for progress
- CLAUDE.md: Jira integration settings, project context
- Environment: Tools, dependencies, versions
- Recent changes: Modified files, active work
**Check Jira integration:**
- Read CLAUDE.md `jira.enabled` flag
- If enabled: Query Jira via Atlassian MCP
- Match Jira issues with local directories
### Execution Steps
**1. Collect status data:**
```bash
# Git
git branch --show-current
git status --porcelain
git log -10 --oneline
git remote -v
# PM structure
glob: pm/specs/*/
glob: pm/issues/*/
# Parse PLAN.md phases, WORKLOG.md entries
# Environment
# Detect: package.json, requirements.txt, Cargo.toml, etc.
# Check versions, outdated deps
# Jira (if enabled)
# Use Atlassian MCP to query project issues
# Match with local directories
```
**3. Jira hybrid display (if enabled):**
```
## Epics (from Jira)
- PROJ-100: Feature Name (Jira: In Progress)
- 4/6 issues complete locally (66%)
## Issues
Jira Issues:
- PROJ-123: Task Name [IN PROGRESS] (Jira: In Progress)
- PROJ-124: Bug Fix [COMPLETED] (Jira: In Progress)
⚠️ Local complete, update Jira status
Local Exploration:
- TASK-001: Spike [COMPLETED]
- TASK-002: Experiment [IN PROGRESS]
Legend:
- [PLANNED] = PLAN.md exists
- [IN PROGRESS] = WORKLOG.md exists
- [COMPLETED] = All PLAN.md phases checked
- (Jira: X) = Current Jira status (read-only)
```
**3. Intelligent analysis:**
- Branch strategy assessment
- Commit pattern insights
- Technical debt identification
- Workflow phase analysis
- Blocker identification
- Risk assessment
- Actionable recommendations
**4. Format output:**
- Standard: Human-readable with visual indicators
- AI-format: Structured for AI consumption
- Detailed: Comprehensive with trends and rationale
- JSON: Programmatic access
### Status Dimensions
**Git Intelligence:**
- Branch, commits, status (basic)
- Branch strategy, commit patterns, merge readiness (enhanced)
**Project Health:**
- File counts, structure (basic)
- Code quality trends, technical debt, architecture health (enhanced)
**Workflow State:**
- Current files, recent changes (basic)
- Workflow phase, task progress, blockers (enhanced)
**Environment Analysis:**
- Tools, dependencies (basic)
- Consistency, vulnerabilities, optimization (enhanced)
### Agent Coordination
**Primary:** project-manager (orchestration and analysis)
**Supporting:** technical-writer (formatting)
### Error Handling
**Jira MCP unavailable:**
```
Warning: Jira enabled but Atlassian MCP unavailable.
Showing local issues only.
```
**Jira query failure:**
```
Warning: Could not fetch Jira issues.
Reason: {error}
Showing local issues only.
```
**No PM structure:**
```
Info: No pm/ directory found.
Project not using PM workflow.
Showing git and environment status only.
```
### Integration
**Workflow position:** Context refresh for any command
**Use cases:**
- Session start: Get project overview
- Before planning: Assess readiness
- During implementation: Check progress
- Before commit: Validate state
- AI context refresh: Preserve continuity

124
commands/quality.md Normal file
View File

@@ -0,0 +1,124 @@
---
tags: ["workflow", "quality", "assessment", "validation"]
description: "Comprehensive quality assessment with multi-agent coordination"
argument-hint: "[--focus AREA]"
allowed-tools: ["Read", "Write", "Edit", "MultiEdit", "Bash", "Grep", "Glob", "TodoWrite", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/quality-gates.md # Quality dimensions, thresholds, validation rules
---
# /quality Command
**WHAT**: Comprehensive quality assessment across code quality, security, performance, testing, and documentation.
**WHY**: Ensure consistent quality standards throughout development with multi-agent analysis and actionable recommendations.
**HOW**: Coordinate specialized agents (code-reviewer, security-auditor, performance-optimizer, test-engineer) to analyze the codebase and provide improvement recommendations.
## Usage
```bash
/quality # Comprehensive quality assessment (all dimensions)
/quality --focus security # Focus on security analysis
/quality --focus performance # Focus on performance analysis
/quality --focus testing # Focus on test coverage and quality
```
## How It Works
1. **Read Quality Configuration** - Load quality dimensions and thresholds from `docs/development/workflows/quality-gates.md`
2. **Analyze Codebase** - Coordinate specialized agents based on focus area or run comprehensive analysis
3. **Generate Report** - Provide actionable recommendations with priority levels
4. **Suggest Improvements** - Offer specific fixes and refactoring suggestions
## Quality Dimensions
**Default dimensions** (configured in `quality-gates.md`):
- **Code Quality** - Maintainability, complexity, best practices (code-reviewer)
- **Security** - Vulnerabilities, OWASP compliance (security-auditor)
- **Performance** - Bottlenecks, optimization opportunities (performance-optimizer)
- **Testing** - Coverage, test quality, effectiveness (test-engineer)
- **Documentation** - Completeness, accuracy (technical-writer)
## Focus Areas
Use `--focus` to target specific quality dimensions:
- `security` - OWASP Top 10, vulnerabilities, auth/data protection
- `performance` - N+1 queries, inefficient algorithms, bottlenecks
- `testing` - Coverage analysis, test quality, missing tests
- `code` - Code quality, complexity, maintainability
- `docs` - Documentation completeness and accuracy
**No flag = Comprehensive analysis across all dimensions**
## When to Use
**During Development:**
- Before merging to staging/production
- After completing a task
- When quality concerns arise
**Regular Checks:**
- Weekly quality reviews
- Pre-release validation
- After major refactoring
**Targeted Analysis:**
- Security review before auth changes
- Performance check after data layer changes
- Test coverage validation after feature addition
## Example Output
```
Quality Assessment Report
=========================
Code Quality: 87/100 ✅
- 3 high-complexity functions identified
- Recommendation: Refactor UserService.validateCredentials()
Security: 92/100 ✅
- 1 medium-severity issue: SQL injection risk in search endpoint
- Recommendation: Use parameterized queries
Performance: 78/100 ⚠️
- N+1 query detected in /api/users endpoint
- Recommendation: Add eager loading for user.posts
Testing: 85/100 ✅
- Coverage: 82% (target: 80%)
- 12 untested edge cases identified
Documentation: 90/100 ✅
- API endpoints documented
- Missing: Error response examples
Overall: 86/100 ✅
Priority Actions:
1. Fix SQL injection in search (CRITICAL)
2. Optimize /api/users N+1 query (HIGH)
3. Refactor high-complexity functions (MEDIUM)
```
## Benefits
✅ **Single Command**: No complex subcommands or flags
✅ **Comprehensive by Default**: Analyzes all quality dimensions
✅ **Targeted When Needed**: Optional focus for specific concerns
✅ **Actionable Output**: Specific recommendations with priority
✅ **Multi-Agent Coordination**: Leverages specialized domain experts
✅ **Configuration-Driven**: Adapts to your quality standards via quality-gates.md
## Integration
**With `/implement`**: Quality checks run automatically during implementation phases
**With `/sanity-check`**: Use for quick quality validation mid-development
**With `/security-audit`**: For deeper OWASP compliance and penetration testing
**Before `/branch merge`**: Run comprehensive quality check before merging to staging/production

78
commands/refresh.md Normal file
View File

@@ -0,0 +1,78 @@
---
tags: ["context", "workflow", "optimization"]
description: "Silently refresh AI context by reading project configuration, guidelines, and recent commits"
argument-hint: ""
allowed-tools: ["Read", "Bash", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/task-workflow.md # Context refresh patterns in development workflow
---
# /refresh Command
**WHAT**: Silently reload project context by reading critical configuration files.
**WHY**: Use when starting a new conversation, after context loss, or before major tasks.
**HOW**: See workflow details in project guidelines (files are read, not explained).
## Usage
```bash
/refresh # Silent context reload
```
## Execution Steps
### 1. Read Project Configuration
```bash
Read: CLAUDE.md
```
If missing: Error "CLAUDE.md not found - run /toolkit-init first"
### 2. Read All Guidelines
```bash
Glob: docs/development/{conventions,workflows,misc,templates}/*.md
# Then read each file found
```
If no guidelines found: Skip silently, continue.
### 3. Read Project Documentation
```bash
Read: docs/project/*.md
```
If files missing: Skip silently, continue.
### 4. Get Recent Work Context
```bash
Bash: git log -3 --format="%h - %s%n%b%n---"
```
If git unavailable: Skip silently, continue.
### 5. Output
```
✓ Context refreshed
```
**Silent operation**: Do NOT summarize files, list what was read, or explain context.
## Error Handling
- **CLAUDE.md missing**: Fail with error message
- **Other files missing**: Skip silently
- **Git unavailable**: Skip git log, continue with files
## Notes
- **Read-only**: Never modifies files
- **Idempotent**: Safe to run multiple times
- **Focused**: Only reads critical context files, not task-specific files (PLAN.md, WORKLOG.md)

120
commands/release.md Normal file
View File

@@ -0,0 +1,120 @@
---
tags: ["versioning", "release", "deployment", "git", "tagging"]
description: "Release new version following semantic versioning guidelines"
aliases: ["version", "tag-release"]
allowed-tools: ["Read", "Edit", "Bash", "Grep", "AskUserQuestion"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/conventions/versioning-and-releases.md # Version bump rules, file update list, semver strategy
---
# /release Command
**WHAT**: Automate version releases with CHANGELOG updates, version file synchronization, and annotated git tags.
**WHY**: Ensure consistent version management across all project files following semantic versioning and project-specific guidelines.
**HOW**: Read versioning convention, analyze changes, suggest version bump, update files, create git tag.
## Usage
```bash
/release # Interactive: analyze changes and suggest version
/release 0.13.0 # Release specific version
/release patch # Release patch version (bug fixes only)
/release minor # Release minor version (new features)
/release major # Release major version (breaking changes)
```
## Workflow
1. **Read Convention** - Load version bump rules from `docs/development/conventions/versioning-and-releases.md`
2. **Validate Preconditions**
- Git working directory must be clean
- CHANGELOG.md [Unreleased] section must have content
- Must be on appropriate branch (defined in convention)
3. **Analyze Changes** - Parse CHANGELOG [Unreleased] to determine appropriate version bump
4. **Get Confirmation** - Show suggested version with rationale, ask user to proceed
5. **Update Files** - Synchronize version across all project files (list from convention)
6. **Create Git Tag** - Annotated tag with release notes from CHANGELOG
7. **Display Summary** - Show updated files, created tag, and next steps
## What Gets Updated
The command reads `versioning-and-releases.md` to determine:
- Which files contain version numbers
- Version bump rules (pre-1.0.0 vs post-1.0.0)
- Git tag format and content
- Branch requirements for releases
**Common version files:**
- CHANGELOG.md (transform [Unreleased] → [version] - date)
- package.json, pyproject.toml, Cargo.toml (language-specific)
- CLAUDE.md frontmatter (version, last_updated)
- Plugin metadata files (for plugin projects)
## Example Output
```
Release Analysis
================
Current version: 0.30.0
Changes in [Unreleased]:
- Added: 2 new features
- Changed: 1 breaking change
- Fixed: 1 bug fix
Suggested version: 0.31.0 (MINOR)
Reason: Breaking changes increment MINOR in pre-1.0.0
Proceed with v0.31.0? (yes/no/custom): yes
Updating files...
✓ CHANGELOG.md
✓ .claude-plugin/marketplace.json
✓ plugins/ai-toolkit/.claude-plugin/plugin.json
✓ CLAUDE.md
Creating git tag...
✓ Created annotated tag v0.31.0
Next steps:
git push origin main --tags
```
## Error Prevention
**Blocks release if:**
- Uncommitted changes exist → Suggests `/commit` first
- CHANGELOG.md [Unreleased] is empty → Suggests `/changelog` first
- Version already exists → Suggests next available versions
- Wrong branch for release type → Warns and asks for confirmation
## Integration
**Typical workflow:**
```bash
/implement TASK-001 --full # Complete implementation
/quality # Verify quality
/changelog # Document changes
/commit # Commit changes
/release # Create release
git push origin main --tags # Push to remote
```
**With CI/CD:**
Pushing the tag triggers automated deployment (if configured).
## Related Commands
- `/changelog` - Document changes before release
- `/commit` - Commit changes before release
- `/project-status` - Review overall project state
## Configuration
All release rules, version bump logic, and file lists are defined in:
`docs/development/conventions/versioning-and-releases.md`
Edit that file to customize your project's versioning strategy.

127
commands/sanity-check.md Normal file
View File

@@ -0,0 +1,127 @@
---
tags: ["workflow", "validation", "quality", "reflection"]
description: "Step back, reflect on current work, validate direction, and assess alignment with plan and architecture"
argument-hint: ""
allowed-tools: ["Read", "Grep", "Glob", "Bash", "mcp__plugin_ai-toolkit_sequential-thinking__sequentialthinking"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/task-workflow.md # Work standards, quality gates, agent coordination
---
# /sanity-check Command
**WHAT**: Mid-work validation using deep reflection to catch drift early.
**WHY**: Prevent expensive course corrections by validating direction while in progress.
**HOW**: Sequential thinking analysis + context validation + alignment check.
## Usage
```bash
/sanity-check # Pause, reflect, validate direction
```
**When**: Complexity increasing, feeling uncertain, before major decisions, after 30+ minutes work, something feels off.
**Not for**: Start of work (`/plan`), after completion (`/quality`), loading context (`/refresh`).
## Execution Steps
### 1. Sequential Thinking Reflection
**Use sequential thinking tool:**
- What are we trying to accomplish? (TASK.md/BUG.md goal)
- What have we done? (WORKLOG.md, completed phases)
- Current approach? (technical solution, assumptions)
- Architecture alignment? (ADRs, architecture-overview.md)
- Standards alignment? (task-workflow.md, test-first, quality gates)
- Concerns? (what feels wrong, risks, drift)
- **Decision**: Green (continue), Yellow (adjust), Red (course correct)
### 2. Read Context Files
```bash
# Work context
Read: pm/issues/TASK-###-*/[TASK|BUG].md
Read: PLAN.md
Read: WORKLOG.md
# Standards and architecture
Read: CLAUDE.md
Read: docs/development/workflows/task-workflow.md
Read: docs/project/architecture-overview.md
Read: docs/project/design-overview.md
# Recent history
Bash: git log -5 --format="%h - %s"
```
Skip missing files gracefully.
### 3. Analyze Alignment
**Compare reflection to reality:**
- **Plan**: Following PLAN.md phases? Deviations?
- **Standards**: Test-first? Quality gates per task-workflow.md?
- **Architecture**: ADR consistency? Approved patterns?
- **Design**: Design system usage? Accessibility?
**Categorize concerns:**
- ✅ Green: On track, continue
- ⚠️ Yellow: Minor issues, easy fixes
- 🚩 Red: Major drift, course correction needed
### 4. Provide Assessment
```markdown
## Sanity Check - TASK-###
### Current State
[What's done, current approach]
### Alignment
**Plan**: ✅ | ⚠️ | 🚩 [details]
**Standards**: ✅ | ⚠️ | 🚩 [details]
**Architecture**: ✅ | ⚠️ | 🚩 [details]
### Concerns
✅ What's Working: [positives]
⚠️ Minor Issues: [yellow flags + fixes]
🚩 Critical Issues: [red flags + actions]
### Recommendation
[Continue as-is | Minor adjustment | Course correction | Update plan]
### Next Steps
[Specific actions]
```
## Error Handling
- **Missing files**: Skip gracefully, note if critical file (PLAN.md) missing
- **No concerns**: Provide positive feedback, confirm alignment
- **Multiple red flags**: Prioritize by severity, clear action items
## Integration
**Workflow position**: Mid-work validation
```
/plan → /implement 1.1 → /implement 1.2 → /sanity-check → [adjust if needed] → /implement 1.3 → /quality
```
**Comparison**:
- `/refresh` - Conversation start (load context silently, no analysis)
- `/plan` - Before work (create execution plan, strategic thinking)
- `/sanity-check` - Mid-work (validate direction, **deep reflection**)
- `/implement` - During work (execute phases, tactical)
- `/quality` - After work (assess code quality, review)
## Notes
- **Sequential thinking required** - Key differentiator from `/refresh`
- **Mid-work focus** - For the messy middle, not start or end
- **Permission to pause** - Makes stepping back a workflow step
- **Catch drift early** - Course correction cheap at 45 min, expensive at 4 hours
- **Trust your gut** - If something feels off, run this command

181
commands/spec.md Normal file
View File

@@ -0,0 +1,181 @@
---
tags: ["workflow", "spec", "feature-spec", "project-management", "conversational"]
description: "Create local feature specifications through natural language conversation"
argument-hint: "[SPEC-### | --epic PROJ-### | --update SPEC-###]"
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Task", "TodoWrite"]
model: claude-opus-4-5
references_guidelines:
- docs/development/workflows/pm-workflows.md # Spec creation workflows and file formats
- docs/development/misc/jira-integration.md # Jira mode (if enabled in CLAUDE.md)
---
# /spec Command
**WHAT**: Create/refine local feature specifications through conversational interaction.
**WHY**: Natural conversation ensures complete spec structure without rigid forms. Specs document WHAT to build locally, separate from PM tool tracking.
**HOW**: See pm-guide.md for spec creation workflows, file formats, and task suggestion strategies. For Jira mode, see jira-integration.md.
## Usage
```bash
/spec # Start conversation (create new or work with existing)
/spec SPEC-### # Work with specific spec
/spec --epic PROJ-### # Create spec from Jira epic (requires Jira integration)
/spec --update SPEC-### # Review and update spec based on recent development (run after task completion)
```
## Execution Flow
**Before you start**: Read pm-guide.md for spec creation workflows, file formats, and task suggestion strategies. For Jira mode, read jira-integration.md.
### High-Level Steps
1. **Determine Mode**
- No arguments: Ask "Create new or work on existing?"
- SPEC-### provided: Refinement mode
- --epic PROJ-###: Fetch Jira epic and pre-populate
- --update SPEC-###: Review mode (analyze recent development and update spec)
2. **Load Context**
- Read docs/development/templates/spec-template.md for structure
- Glob pm/specs/SPEC-*.md for next number
- If --epic: Fetch from Jira via Atlassian MCP
3. **Conversational Creation**
- Main goal, primary users
- Acceptance scenarios (2-5 Given-When-Then)
- Success criteria, OUT of scope
- Follow spec-template.md structure
4. **Create Spec File**
- Write pm/specs/SPEC-###-<name>.md
- Mark Jira source if --epic used
5. **Task Creation** (interactive)
- Suggest 2-3 foundational tasks based on spec scope
- Interactive loop: Which to create? (yes/all/custom/stop)
- For each selected task:
- Create `pm/issues/TASK-###-name/` directory
- Create `TASK.md` from `templates/task-template.md` template
- Link task → spec (frontmatter: `spec: SPEC-###`)
- Update spec → task reference (Tasks section)
- Per pm-workflows.md task suggestion strategy
6. **Optional Jira Epic**
- Ask: Create corresponding Jira epic?
- If yes: Run /jira-epic --spec SPEC-###
**See pm-guide.md "Spec Creation Workflows" for complete conversational flow patterns.**
## Update Mode (`--update SPEC-###`)
**When to use:** After completing tasks to sync spec with implementation reality.
**Workflow:**
1. **Load Context**
- Read SPEC-###-<name>.md
- Read all linked TASK-###/TASK.md files
- Read all linked TASK-###/WORKLOG.md files (completed tasks)
- Read recent git commits for the spec's feature branch
2. **Analyze Development Activity**
- What was actually implemented vs planned?
- Were there scope changes during implementation?
- Did acceptance scenarios change?
- Were new edge cases discovered?
- Did any requirements change?
3. **Review Incomplete Tasks**
- Read all tasks with status: `todo` or `in_progress`
- Based on completed work, do these tasks still make sense?
- Should any be:
- Modified (scope changed based on discoveries)
- Removed (no longer needed)
- Split (too large based on actual complexity)
- Merged (smaller than expected)
- Suggest changes interactively
4. **Update Spec**
- Revise description if scope changed
- Update/add acceptance scenarios based on discoveries
- Update definition of done if needed
- Mark completed tasks as done
- Add new tasks if gaps discovered
- Update "Out of Scope" section if boundaries changed
5. **Document Changes**
- Add update note to spec with timestamp
- Summary of what changed and why
- Link to completed tasks that informed changes
**Example:**
```bash
# After completing TASK-001 and TASK-002 for SPEC-001
/spec --update SPEC-001
→ Reads SPEC-001-user-authentication.md
→ Reads completed TASK-001/WORKLOG.md, TASK-002/WORKLOG.md
→ Reviews remaining TASK-003, TASK-004, TASK-005
AI: "During TASK-001, you implemented OAuth in addition to email/password.
Should we update the spec to include OAuth in the description?"
User: "Yes"
AI: "TASK-004 was for 'password complexity rules', but you already
implemented basic validation in TASK-001. Should we:
1. Remove TASK-004 (no longer needed)
2. Modify TASK-004 to focus on advanced rules only
3. Keep as-is"
User: "2"
→ Updates SPEC-001 with OAuth in description
→ Updates TASK-004 description to "Advanced password rules (strength meter, common password detection)"
→ Adds update note with timestamp
```
**Integration with Workflow:**
```bash
/implement TASK-001 --full # Complete task
/quality # Verify quality
/spec --update SPEC-001 # Sync spec with reality
/plan TASK-002 # Plan next task with updated context
```
## Workflow Patterns
**Local-first** (recommended):
```
/spec → /jira-epic --spec SPEC-### → /plan TASK-### → /implement → /spec --update SPEC-###
```
**Jira-first**:
```
/spec --epic PROJ-### → /plan TASK-### → /implement → /spec --update SPEC-###
```
**Local-only**:
```
/spec → /plan TASK-### → /implement → /spec --update SPEC-###
```
**Iterative development cycle**:
```
/spec SPEC-001 # Create spec with tasks
/plan TASK-001 → /implement # Complete first task
/spec --update SPEC-001 # Review and adjust remaining work
/plan TASK-002 → /implement # Next task with updated context
/spec --update SPEC-001 # Continue iterating
```
## Error Handling
**--epic without Jira**: Enable Jira in CLAUDE.md or omit --epic flag
**Epic not found**: Verify epic exists and you have access
**MCP unavailable**: Fallback to manual creation
See jira-integration.md for complete error scenarios and solutions.

162
commands/sync-progress.md Normal file
View File

@@ -0,0 +1,162 @@
---
tags: ["workflow", "manual-changes", "planning"]
description: "Sync project state after manual changes via git diff analysis"
argument-hint: ""
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "TodoWrite"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/pm-workflows.md # Plan structure and phase management
- docs/development/workflows/worklog-format.md # WORKLOG entry formats
- docs/development/workflows/git-workflow.md # Git diff analysis
---
# /sync-progress Command
**WHAT**: Automatically sync project state when user makes manual changes.
**WHY**: Analyzes git diff, updates plan to reflect progress, and documents changes in WORKLOG without manual explanation.
**HOW**: See pm-guide.md for plan/phase management, worklog-format.md for entry structure, git-workflow.md for git analysis.
---
## Workflow
### 1. Analyze Changes
Run these commands to understand what changed:
```bash
# Check for uncommitted changes
git diff
# Check staged changes
git diff --staged
# Get summary of changed files
git status --short
```
### 2. Read Current State
Read the following files if they exist:
- `pm/active/PLAN.md` - Current task plan
- `pm/active/WORKLOG.md` - Work history
- `pm/active/spec.md` - Feature specification (if applicable)
### 3. Analyze and Update
**For each changed file in git diff**:
1. **Determine intent** - What was the user trying to accomplish?
- New feature implementation
- Bug fix
- Refactoring
- Configuration change
- Documentation update
2. **Compare to PLAN.md**:
- Which phase/task does this relate to?
- Is this planned work or new direction?
- Should any phases be marked complete?
- Are there new tasks to add?
3. **Update PLAN.md**:
- If there is ANY ambiguity clarify with user
- Mark completed phases as `[x] COMPLETED`
- Update phase descriptions if approach changed
- Add new phases if user took different direction
- Add notes about implementation decisions made
### 4. Document in WORKLOG
Write a WORKLOG entry with:
```markdown
## YYYY-MM-DD HH:MM - Manual Changes Synced
**Files Changed**: [list of changed files]
**Changes Made**:
- [Brief description of each major change]
- [Why it was done - inferred from code]
- [Any patterns or decisions observed]
**Plan Updates**:
- [Which phases marked complete]
- [Any new phases added]
- [Any direction changes noted]
**Status**: [Current project state after these changes]
**Next Steps**: [Suggested next actions based on plan]
```
### 5. Summary Report
Provide user with:
- **Changes detected**: Count and summary of modified files
- **Plan updates**: Which phases completed, which added
- **WORKLOG entry**: Confirmation of documentation
- **Next suggested action**: Based on remaining plan items
---
## Key Principles
1. **Infer intent from code** - Don't ask user to explain, analyze the diff
2. **Be accurate** - Only mark phases complete if truly done
3. **Preserve context** - Keep plan structure, don't overwrite unnecessarily
4. **Document decisions** - Note any technical choices made in code
5. **Suggest next steps** - Help user know what to work on next
---
## Example Usage
**Scenario**: User manually implemented authentication while AI was offline
**Command**: `/sync-progress`
**AI Actions**:
1. Runs `git diff` - sees new files: `auth/login.ts`, `auth/middleware.ts`, `db/users.sql`
2. Reads `pm/active/PLAN.md` - finds Phase 2: "Implement authentication system"
3. Updates PLAN.md:
- Marks Phase 2 as `[x] COMPLETED`
- Adds notes: "Used JWT tokens, bcrypt for passwords, PostgreSQL for users table"
4. Writes WORKLOG entry documenting authentication implementation
5. Reports: "Detected authentication implementation complete. Phase 2 marked done. Next: Phase 3 - API endpoint protection"
---
## Edge Cases
**No PLAN.md exists**:
- Create one based on git changes
- Infer project structure and goals
- Add phases for observed work
**Changes conflict with plan**:
- Note the deviation in WORKLOG
- Ask user if plan should be updated or reverted
- Suggest reconciliation approach
**Changes are exploratory/experimental**:
- Don't mark plan phases complete
- Add note to PLAN.md: "Exploration: [description]"
- Document in WORKLOG as research/spike
**Multiple unrelated changes**:
- Group by functional area
- Update multiple plan phases if applicable
- Create clear sections in WORKLOG entry
---
## Success Criteria
✅ All git changes analyzed and understood
✅ PLAN.md accurately reflects current state
✅ Completed work properly marked
✅ WORKLOG entry is clear and comprehensive
✅ User knows what to do next

261
commands/toolkit-init.md Normal file
View File

@@ -0,0 +1,261 @@
---
tags: ["workflow", "initialization", "setup", "scaffolding", "update", "sync"]
description: "Initialize project with ai-toolkit structure - minimal questions, fast setup"
argument-hint: "[--force | --dry-run]"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "AskUserQuestion"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/pm-workflows.md # PM structure and directory organization
- docs/development/workflows/task-workflow.md # Development workflow structure
---
# /toolkit-init
**WHAT**: Initialize project with complete ai-toolkit structure (54 files) or intelligently sync updates after plugin upgrades.
**WHY**: 30-second setup for new projects; preserve customizations while benefiting from template improvements in existing projects.
**HOW**: Smart mode detection (initial setup vs update/sync), minimal questions (2), comprehensive file copying with verification.
## Usage
```bash
/toolkit-init # Smart: Initial setup (new) or update/sync (existing)
/toolkit-init --force # Force: Overwrite all with templates (complete reset)
/toolkit-init --dry-run # Preview: Show changes without modifying files
```
## Execution Steps
### 1. Mode Detection
```bash
# Check for existing ai-toolkit structure
if pm/ AND docs/ exist:
if --force:
→ Force Reinit (skip to step 3)
else:
→ Update/Sync Mode (jump to Update Flow)
else:
→ Initial Setup (continue to step 2)
```
**Template verification**:
```bash
TEMPLATE_DIR="${CLAUDE_PLUGIN_ROOT}/templates/starter"
if not exists: ERROR "Template directory not found"
```
### 2. Initial Setup Questions (New Projects Only)
**Ask 2 questions**:
1. "What's your app called?" → {app-name}
2. "What does it do? (1-2 sentences)" → {description}
**No other questions**. Tech stack, links, infrastructure = filled in later.
### 3. Copy Template Files (51 Files)
**Copy all template files**:
```bash
TEMPLATE_DIR="${CLAUDE_PLUGIN_ROOT}/templates/starter"
# Use rsync if available (handles hidden files, nested dirs)
rsync -av "$TEMPLATE_DIR"/ . --exclude='.git'
# OR use cp with explicit hidden file handling
cp -r "$TEMPLATE_DIR"/* .
cp "$TEMPLATE_DIR"/.gitignore .
```
**CRITICAL**: Must copy ALL 51 template files including:
- `.gitkeep` files (preserve empty dirs in pm/specs/, pm/issues/, pm/notes/)
- `.gitignore` (hidden file)
- All nested subdirectories
### 4. Generate Project Docs from Templates
**Create 3 project-specific files from templates**:
| Generated File | Source Template | Customization |
|----------------|-----------------|---------------|
| `docs/project/architecture-overview.md` | `docs/development/templates/architecture-overview-template.md` | Copy as-is |
| `docs/project/design-overview.md` | `docs/development/templates/design-overview-template.md` | Copy as-is |
| `docs/project/writing-style.md` | `docs/development/templates/writing-style-template.md` | Copy as-is |
These provide starter structure for project-specific documentation that users fill in as the project develops.
**Note**: `docs/project-brief.md` is created by `/project-brief` command on first run, not by `/toolkit-init`.
### 5. Customize Existing Files
**Get plugin metadata**:
```bash
PLUGIN_VERSION=$(grep '"version"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" | sed 's/.*: *"\([^"]*\)".*/\1/')
CURRENT_DATE=$(date '+%Y-%m-%d')
```
**Update files with placeholders**:
- **CLAUDE.md**: Replace {app-name}, {description}, {toolkit-version}, {last-updated}
- **README.md**: Replace {app-name}, {description}
### 6. Verification
```bash
# Count files (should be 54: 51 template + 3 generated)
find . -type f | grep -v ".git" | wc -l
# Verify critical directories exist
[ -d "docs/development/conventions" ]
[ -d "docs/development/workflows" ]
[ -d "docs/development/templates" ]
[ -d "docs/project/adrs" ]
[ -d "docs/project/design-assets" ]
[ -d "pm/specs" ]
[ -d "pm/issues" ]
```
### 7. Success Output
```
✓ Created 54 files
Structure:
├── pm/ (4 files)
├── docs/development/ (34 files: conventions, workflows, templates, misc)
├── docs/project/ (6 files: READMEs + generated docs)
└── root (10 files: CLAUDE.md, README.md, etc.)
Generated from templates:
├── docs/project/architecture-overview.md
├── docs/project/design-overview.md
└── docs/project/writing-style.md
Next steps:
1. /project-brief (complete your project vision)
2. /spec (create your first feature spec)
```
## Update/Sync Flow (Existing Projects)
### 1. Version Detection
```bash
# Extract versions
PROJECT_VERSION=$(grep "Plugin Version" CLAUDE.md | sed 's/.*: *//')
PLUGIN_VERSION=$(grep '"version"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" | sed 's/.*: *"\([^"]*\)".*/\1/')
```
**Display version comparison**:
```
Your project: v0.37.0
Current plugin: v0.38.0
Checking for template changes...
```
### 2. Scan & Categorize Files
**Compare each template file with project file**:
| Status | Meaning |
|--------|---------|
| ✅ Identical | No changes needed |
| 🔧 Customized | User modified (offer merge options) |
| ❌ Missing | Template file not in project (will add) |
| ➕ New in Plugin | New template file (will add) |
**Example drift report**:
```
✅ Identical (40): .gitignore, most workflow files...
🔧 Customized (5): CLAUDE.md, README.md, docs/project-brief.md, testing-standards.md, git-workflow.md
❌ Missing (1): docs/development/workflows/spike-workflow.md
➕ New in Plugin (2): docs/development/misc/new-feature.md
```
### 3. Interactive Decisions
**For each customized file**:
```
CLAUDE.md is customized.
Options:
1. Keep your version (no changes)
2. Replace with template (lose customizations)
3. Smart merge (keep your content, add new sections)
4. Show diff
5. Skip for now
Choose (1-5): _
```
**Smart merge strategy**:
- Parse markdown by headers (## sections)
- Keep user-added content in existing sections
- Add new template sections that don't exist
- Preserve YAML frontmatter customizations
### 4. Handle Generated Project Docs
**For docs/project/ files (architecture-overview.md, design-overview.md, writing-style.md)**:
- If file exists and is customized → Keep (these are user content)
- If file is missing → Offer to generate from template
- If template changed significantly → Notify user (don't auto-update)
### 5. Apply Updates
```bash
# Execute user choices
# Track results: UPDATED=(), KEPT=(), MERGED=(), ADDED=()
```
**Summary output**:
```
✅ Updated (3): spike-workflow.md, new-feature.md, agent-coordination.md
🔀 Merged (1): CLAUDE.md
⏭️ Kept (4): README.md, testing-standards.md, git-workflow.md, project-brief.md
➕ Added (1): docs/development/misc/new-feature.md
```
### 6. Update Version Tracking
```bash
# Update CLAUDE.md with new plugin version
sed -i "s/Plugin Version\*\*: .*/Plugin Version**: $PLUGIN_VERSION/" CLAUDE.md
sed -i "s/Last Updated\*\*: .*/Last Updated**: $(date '+%Y-%m-%d')/" CLAUDE.md
```
## Error Handling
| Error | Message | Resolution |
|-------|---------|------------|
| Template not found | "Cannot find template at {path}" | Reinstall plugin |
| Copy fails | "Failed to copy templates" | Check permissions |
| Diff unavailable | - | Treat as customized, prompt for review |
| Merge conflict | - | Show both versions, ask user to choose |
## Integration
**Workflow position**:
```
/toolkit-init → /project-brief → /spec → /plan → /implement
```
**Update cycle**:
```
/plugin update ai-toolkit → /toolkit-init (sync) → Review changes
```
**When to run update/sync**:
- After plugin updates
- Before major releases (ensure template alignment)
- Periodically to detect drift
## Notes
- **54 files total**: 51 template files + 3 generated from templates
- **2 questions only**: App name + description
- **Smart merge**: Preserves user customizations while adding new content
- **Dry run**: Use `--dry-run` to preview all changes safely
- **Force mode**: Use `--force` only for complete reset (loses customizations)
- **Version tracking**: CLAUDE.md automatically tracks plugin version

110
commands/troubleshoot.md Normal file
View File

@@ -0,0 +1,110 @@
---
tags: ["debugging", "investigation", "problem-solving"]
description: "5-step debugging loop for unexpected issues during implementation or standalone bug fixes"
argument-hint: "[BUG-### | TASK-### | \"description\"]"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebSearch", "WebFetch", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/bug-workflow.md # 5-step debugging loop, reproduction-first approach
- docs/development/workflows/worklog-format.md # WORKLOG entry formats
---
# /troubleshoot Command
**WHAT**: Systematic debugging using the 5-step loop from bug-workflow.md.
**WHY**: Avoid shotgun debugging. Research first, one hypothesis at a time, validate before claiming fixed.
**HOW**: Follow the 5-step debugging loop in bug-workflow.md.
## Usage
```bash
/troubleshoot "tests failing after auth changes" # During TASK - describe the issue
/troubleshoot TASK-001 # Debug issue in specific task context
/troubleshoot BUG-007 # Equivalent to /implement BUG-007
```
## When to Use
| Situation | Command |
|-----------|---------|
| Unexpected issue during TASK implementation | `/troubleshoot "description"` or `/troubleshoot TASK-###` |
| Known bug with BUG.md created | `/troubleshoot BUG-###` or `/implement BUG-###` |
| Tests failing, unclear why | `/troubleshoot` |
## Execution
### Mode 1: During TASK Implementation
When something unexpected breaks while implementing a TASK:
1. **Read context**: Current TASK.md, PLAN.md, WORKLOG.md
2. **Execute 5-step loop** from bug-workflow.md
3. **Document** in current WORKLOG.md
4. **Continue** with TASK implementation
### Mode 2: Standalone Bug (BUG-###)
Equivalent to `/implement BUG-###`:
1. **Read context**: BUG.md, PLAN.md, WORKLOG.md
2. **Execute 5-step loop** from bug-workflow.md
3. **Document** in WORKLOG.md with root cause
4. **Complete** with `/complete BUG-###`
## The 5-Step Loop
**See bug-workflow.md for complete details.**
```
Research → Hypothesize → Implement → Test → Document
↑ │
└─────────── (if not fixed) ──────────────┘
```
### Quick Reference
1. **Research** - Context7 → docs → ask user (don't guess)
2. **Hypothesize** - ONE theory with debug plan
3. **Implement** - Fix + liberal debug logging
4. **Test** - Run tests, verify logs, confirm fix
5. **Document** - WORKLOG entry with hypothesis/findings/result
### Key Rules
- Research BEFORE guessing
- ONE hypothesis at a time
- Liberal debug logging (`console.log('[Component] State:', data)`)
- NEVER claim "fixed" without tests passing
- Rollback on failure before next attempt
## WORKLOG Entry
```markdown
## 2025-11-26 - Troubleshooting Loop 1
**Hypothesis:** Query fires before auth completes
**Debug findings:**
- isLoading was true when query executed
- Auth state not propagating to component
**Implementation:** Added auth state check
**Result:** ✓ Fixed - 47/47 tests passing
```
## Error Handling
| Situation | Action |
|-----------|--------|
| Hypothesis fails | Rollback, document, return to Step 1 |
| 3+ failed loops | Pause, ask user for context |
| Tests pass but issue persists | More logging, manual verification |
## Integration
**During TASK:** Documents in current WORKLOG, returns to `/implement`
**For BUG:** Same as `/implement BUG-###`, follows bug-workflow.md

198
commands/ui-design.md Normal file
View File

@@ -0,0 +1,198 @@
---
name: ui-design
description: Create and iterate on HTML UI mockups with parallel design exploration
aliases: ["mockup", "prototype"]
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Task"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/conventions/ui-design-guidelines.md # Design tokens, breakpoints, accessibility
- docs/project/design-overview.md # Synthesis of approved designs (created by /toolkit-init)
---
# /ui-design
**WHAT**: Generate HTML mockups with parallel variant exploration, conversational iteration, and tech-specific implementations (vanilla/shadcn/chakra).
**WHY**: Version-controlled, responsive, interactive designs that integrate directly into development workflow.
**HOW**: Parse request → Load design context → Generate parallel variants → Playwright review → Present options → Conversational iteration → Approval & synthesis.
## Usage
```bash
/ui-design "login screen" # Single design, ask variant count
/ui-design "show me 4 dashboard concepts" # Parallel exploration
/ui-design "login using shadcn, 3 options" # Tech-specific (includes React code)
/ui-design "show me vanilla and shadcn versions" # Compare libraries
/ui-design list # Show all designs
/ui-design list login-screen # Show specific design versions
```
## Execution Steps
### 1. Parse Request
```bash
# Extract from user prompt:
# - Design name ("login screen", "dashboard")
# - Variant count ("show me 4", "3 options") → default: ask user
# - Technology ("using shadcn", "with chakra-ui") → vanilla if not specified
# - Changes (if iteration: "move X", "increase Y")
```
### 2. Load Context
```bash
Read: docs/development/conventions/ui-design-guidelines.md # Tokens, breakpoints, a11y
Read: docs/project/ui-designs/design-overview.md # Existing patterns
Glob: docs/project/ui-designs/{name}-v*.html # Determine next version
```
**Check for tech-specific MCPs** (shadcn MCP if "shadcn" mentioned).
### 3. Generate Variants (Parallel)
```bash
# If variants > 1: Spawn N ui-ux-designer agents via Task tool (PARALLEL)
# Each agent explores different approach (layout/density/style)
# Share: base requirements + design tokens
# Unique: variant-specific prompt
```
### 4. Playwright Review (CRITICAL)
**Before presenting to user**:
```bash
# Load each generated HTML in Playwright
# Check: broken layouts, missing styles, JS errors, console warnings
# Verify: responsive at 320px, 768px, 1280px breakpoints
# Validate: interactive elements work (buttons, forms, dropdowns)
# Fix issues before presentation
```
### 5. Present & Iterate
**Present options**: Show files + brief descriptions + view instructions.
**Conversational iteration**:
- User selects: "I like option B", "v2b works"
- User changes: "move OAuth below", "increase spacing"
- User approves: "approve v2b", "that's the one"
- **After each iteration**: Playwright review again
### 6. Approval & Synthesis
```bash
# Update HTML metadata: Status: APPROVED
# Update design-overview.md: Add to Approved Designs section
# Extract patterns: Colors, spacing, components → design-overview
# Mark superseded: Note v1{a,b,c} replaced by v2b
```
## File Organization
```
docs/project/ui-designs/
├── design-overview.md # Approved designs + patterns
├── login-screen-v1a.html # Parallel variants
├── login-screen-v1b.html # (user chose this)
├── login-screen-v2b.html # ← APPROVED
├── dashboard-v1-shadcn.html # Tech-specific
└── components/buttons-v1.html # Reusable patterns
```
**Naming**:
- Single: `{name}-v{N}.html`
- Variants: `{name}-v{N}{letter}.html`
- Tech-specific: `{name}-v{N}-{tech}.html`
- Components: `components/{name}-v{N}.html`
## HTML Structure
**Vanilla HTML**:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<title>{design-name} - v{N}</title>
<style>
:root {
--primary: #3b82f6; /* From ui-design-guidelines.md */
}
/* Responsive styles, component styles */
</style>
</head>
<body>
<!-- UI Design -->
<script>/* Interactive behaviors */</script>
</body>
</html>
<!-- METADATA: Design, Version, Status: APPROVED, Design Decisions -->
```
**Tech-specific (e.g., shadcn)**:
```html
<!-- Visual preview with shadcn-matching styles -->
<!-- METADATA includes IMPLEMENTATION CODE section with copy-paste React components -->
```
**Reference**: See ui-design-guidelines.md for design tokens, breakpoints, a11y requirements.
## Technology Support
**Supported techs**:
- `"using shadcn"` → shadcn MCP, React code in HTML comments
- `"with chakra-ui"` → Chakra UI patterns
- `"material-ui"` → Material UI components
- No tech → Vanilla HTML/CSS
**Compare libraries**:
```bash
/ui-design "login, show me vanilla and shadcn versions"
→ login-screen-v1.html, login-screen-v1-shadcn.html
```
## Natural Language Parsing
**Command understands**:
- Selection: "option B", "v1b", "split screen"
- Approval: "approve v2b", "that's the one"
- Iteration: "move X below", "increase spacing", "try 3 more"
- Variant count: "show me 4", "3 options"
- Technology: "using shadcn", "with chakra"
## Asset Handling
**Images/logos**: Read file → base64 data URL → inline embed → self-contained HTML.
## Integration
**TASK.md reference**:
```markdown
Design Reference: docs/project/ui-designs/login-screen-v2b.html (approved)
Acceptance: Implement matching design, responsive 320px-1920px
```
**During /implement**:
- frontend-specialist reads approved HTML
- Tech-specific mockup: Copy React code from HTML comments
- Vanilla mockup: Implement in project's tech stack
- WORKLOG: "Implemented UI per login-screen-v2b"
## Agent Coordination
**Primary**: ui-ux-designer (creates mockups)
**Supporting**: frontend-specialist (feasibility and existing patterns)
**Approval**: User (visual review)
## Error Handling
- **No guidelines**: Create minimal HTML with standard tokens
- **Playwright errors**: Fix before presenting to user
- **Asset not found**: Skip asset, note in metadata
## Notes
**Best for**: Developer-designers, small teams, rapid exploration, design-in-code workflows
**Use Figma when**: Pixel-perfect requirements, non-technical stakeholders, professional handoff

132
commands/worklog.md Normal file
View File

@@ -0,0 +1,132 @@
---
tags: ["workflow", "collaboration", "documentation"]
description: "Add timestamped work log entries to track manual changes and communicate with AI"
argument-hint: "\"your comment text\""
allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
- docs/development/workflows/worklog-format.md # WORKLOG format and work documentation standards
---
# /worklog Command
**WHAT**: Add timestamped work log entries to track manual changes and communicate with AI.
**WHY**: Enable AI to understand manual work, avoid duplicating human effort, and maintain shared context.
**HOW**: See worklog-format.md for format standards. AI timestamps entry, finds WORKLOG, prepends in reverse chronological order.
## Usage
```bash
/worklog "Added login button to header"
/worklog "Fixed dark mode - using --color-grey-dark (#2d2d2d)"
/worklog "Don't use jsonwebtoken - jose has better TS support"
```
## How It Works
AI executes this workflow:
1. **Get timestamp**: Run `date '+%Y-%m-%d %H:%M'` (NEVER guess/estimate)
2. **Get username**: Run `git config user.name`
3. **Find WORKLOG**: Locate current task's WORKLOG.md in `pm/issues/TASK-###-*/`
4. **Prepend entry** (reverse chronological):
```markdown
## 2025-10-22 15:30 - @username
Added login button to header
```
5. **Analyze impact**: Read TASK.md and check if comment relates to existing phases
6. **Offer update** (interactive): Ask if task plan needs updating based on comment
7. **Update if confirmed**: Modify TASK.md and log the change in WORKLOG.md
## When to Use
✅ **Use when:**
- Making manual code changes outside `/implement`
- Documenting gotchas or lessons learned
- Communicating constraints to AI ("must use library X")
❌ **Don't use when:**
- AI agents did the work (they auto-log)
- No changes made (just reading code)
- Already documented in commit message
## WORKLOG Format
```markdown
# Work Log - TASK-001: User Authentication
## 2025-10-22 15:30 - @taylor
Added login button with dark mode support.
Files: src/components/Header.tsx
## 2025-10-22 14:30 - backend-specialist
Implemented JWT middleware with refresh logic.
Gotcha: Token expiry configurable via TOKEN_EXPIRY_HOURS.
Files: src/middleware/auth.js
```
**Reverse chronological** (newest first) for quick context scanning.
## Interactive Plan Updates
After adding comment, AI analyzes task plan:
```
Your comment mentions login button. This might relate to:
- [ ] 2.1 Implement login UI components
Update task plan?
1. Mark phase 2.1 complete
2. Add new phase for login work
3. No update needed
Choose (1/2/3): _
```
## Examples
**Styling work:**
```bash
/worklog "Tweaked button padding to 12px/24px for mobile"
# → Added to WORKLOG, no plan updates needed
```
**Feature addition:**
```bash
/worklog "Added email validation to login form"
# → Added to WORKLOG, AI asks: "Mark phase 1.3 complete? (y/n)"
```
**Gotcha documentation:**
```bash
/worklog "Don't use setTimeout for token refresh - use setInterval"
# → Added to WORKLOG, documented for future reference
```
**API change:**
```bash
/worklog "API changed - login endpoint now /api/v2/auth/login"
# → Added to WORKLOG, AI asks: "Update phase 3.1 description? (y/n)"
```
## Error Handling
**No active task**: AI lists available tasks and asks which one to associate comment with
**No WORKLOG.md**: AI creates it automatically with proper header
## Benefits
**For AI**: Understands manual changes, avoids duplicating human work, respects decisions
**For Humans**: Quick documentation, no context switching, AI keeps plan synchronized
**For Teams**: Shared history, captured gotchas, implementation timeline
## Philosophy
Human-AI collaboration through shared work log:
- Humans add comments for manual work
- AI agents add entries for automated work
- Both contribute to narrative history
- Result: AI remembers context, avoids breaking existing features